Synology DSM Reverse Proxy

:warning: This guide has been migrated from our website and might be outdated. Feel free to edit this guide to update it, and to remove this message after that.

Synology NAS is the perfect companion to running Home Assistant. But by default, the DSM Reverse Proxy does not configure its NGINX settings to allow WebSocket, and some extra configuration will be required to get the Home Assistant frontend working with the DSM.

Setup headers

Starting with DSM 6.2.1+, you can create “custom headers” in the Application Portal:

  • Go to Application Portal and edit your entry
  • Click on “custom headers” tab and click the dropdown on the “Create” button
  • Select “Websocket”. This will automatically add the required headers for WebSocket to this reverse proxy.
  • Click “OK”. Home Assistant should work now with the reverse proxy.

It’s not necessary anymore to change the template anymore since Version DSM 6.2.1. Changing the Portal.mustache is not recommended! You should use the following part only if you’re using a Version before DSM 6.2.1. on your Synology.

Template change

To allow WebSocket by default for all service exposed by NGINX, you can enable it in the template file located in /usr/syno/share/nginx/Portal.mustache. Please be really careful in editing this file since you may break access to the DSM UI. Please backup this file before any edition.

Open /usr/syno/share/nginx/Portal.mustache and add the followings in the Location section:

        proxy_set_header        Upgrade             $http_upgrade;
        proxy_set_header        Connection          "upgrade";
        proxy_read_timeout      86400;

Then restart the NGINX daemon:

sudo synoservicecfg --restart nginx

This will restart the running HTTP service, not only reverse proxy, as a single instance of NGINX runs everything.

You can find more information here.

HTTP Configuration

  • Copy the Home Assistant specific Reverse Proxy settings from the existing /etc/nginx/app.d/server.ReverseProxy.conf file to /usr/local/etc/nginx/conf.d/http.HomeAssistant.conf.
  • Include these lines in the location declaration:
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";

Thank you so much! You rock!

I had been reading like over 20 other posts with so complicated conf file edits, and you did it with just a couple of clicks on reverse proxy GUI.


Wonderful, I looked for several hours before I found this right solution
Thank you

Thanks also from my side - this was the missing puzzle piece to get the reverse-proxy to work. Before that I always got a page with the home assistant logo and the message ‘Retry’.

If the source and destination are both http, it works. But if the source is https, it seems not work.(tested on DSM7.0 beta) Even if I selected WebSocket in custom headers in reverse proxy, the page always showed “Retry”, with the console said:

[Error] WebSocket network error: The operation couldn’t be completed. (OSStatus error -9836.) (x2)
[Error] Unhandled Promise Rejection: 1

When pressing OK I get an error that the domain is already used … I used my synology dn.
Even if i change to a random name … I get the same error …
Any hints ?

Thank you!

I stumbled for a while until I setup my certificates and proxy correctly. I don’t worry too much about a custom domain name - Synology provide wildcard certificates for their DDNS service and it’s all in the UI.

I wrote this response for someone else and it’s helped a few people - might help you too.

been running reverse proxy without issues. However i have one challange on caching a snapshot jpg. when i have motion triggered, i get a new snapshot stored on www local folder and is accesible from internet because of reverse proxy. However , browser caches the image and dont show the new image, only after 2 refreshes, new image appears.
Should it be possible to tell the reverse proxy to have no caching to the browsers? Or is is HA webserver causing this?

nevermind… solved it by having dynamic file name on the captures… no cache possible ever :slight_smile:

I don’t know why, but I have a 400: Bad request response. :thinking:
Somebody had like that?
DSM 7.0-41890

Record in HA log is:
ERROR (MainThread) [homeassistant.components.http.forwarded] A request from a reverse proxy was received from, but your HTTP integration is not set-up for reverse proxies

I found an answer! I have to add to config.yaml

  use_x_forwarded_for: true

Even with the correct config.yaml
Reverse proxy is working for the syno itself and for photo and bitwarden. Only HA doesn’t work. Does anyone have an idea?

Found one strange thing. For me this is working, but partly.
So we need to create Websocket in the synology NAS, as it is described in the first message, but then change “Connection” parametr from “$connection_upgrade” to “upgage” and everything is starting to work fine.

Stupid question…is the DSM Proxy reverse Limited to 10MB Upload?