.\" Man page generated from reStructuredText. . . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .TH "STDISCOSRV" "1" "Oct 23, 2024" "v1.28.0" "Syncthing" .SH NAME stdiscosrv \- Syncthing Discovery Server .SH SYNOPSIS .INDENT 0.0 .INDENT 3.5 .sp .EX stdiscosrv [\-\-debug] [\-\-http] [\-\-compression] [\-\-version] [\-\-cert=] [\-\-key=] [\-\-listen=
] [\-\-metrics\-listen=
] [\-\-db\-dir=] [\-\-db\-flush\-interval=] .EE .UNINDENT .UNINDENT .SH DESCRIPTION .sp Syncthing relies on a discovery server to find peers on the internet. Anyone can run a discovery server and point Syncthing installations to it. The Syncthing project also maintains a global cluster for public use. .SH OPTIONS .INDENT 0.0 .TP .B \-\-debug Enable debug output. .UNINDENT .INDENT 0.0 .TP .B \-\-http Listen on HTTP (behind an HTTPS proxy). .UNINDENT .INDENT 0.0 .TP .B \-\-version Print the current version number and exit. .UNINDENT .INDENT 0.0 .TP .B \-\-compression Enable GZIP compression of HTTP responses. .UNINDENT .INDENT 0.0 .TP .B \-\-cert= Certificate file (default “./cert.pem”). Unused in –http mode. .UNINDENT .INDENT 0.0 .TP .B \-\-key= Key file (default “./key.pem”). Unused in –http mode. .UNINDENT .INDENT 0.0 .TP .B \-\-listen=
Listen address (default “:8443”). .UNINDENT .INDENT 0.0 .TP .B \-\-metrics\-listen=
Prometheus compatible metrics endpoint listen address (default disabled). .UNINDENT .INDENT 0.0 .TP .B \-\-db\-dir= Database directory, where data is stored (default “.”). .UNINDENT .INDENT 0.0 .TP .B \-\-db\-flush\-interval= Interval at which the in\-memory database is flushed to disk (default “5m”). .UNINDENT .SH POINTING SYNCTHING AT YOUR DISCOVERY SERVER .sp By default, Syncthing uses a number of global discovery servers, signified by the entry \fBdefault\fP in the list of discovery servers. To make Syncthing use your own instance of stdiscosrv, open up Syncthing’s web GUI. Go to settings, Global Discovery Server and add stdiscosrv’s host address to the comma\-separated list, e.g. \fBhttps://disco.example.com:8443/\fP\&. Note that stdiscosrv uses port 8443 by default. For stdiscosrv to be available over the internet with a dynamic IP address, you will need a dynamic DNS service. .sp Deprecated since version v0.14.44: Prior versions need \fB/v2/\fP appended to the discovery server address, e.g. \fBhttps://disco.example.com:8443/v2/\fP\&. .sp If you wish to use \fIonly\fP your own discovery server, remove the \fBdefault\fP entry from the list. .SH SETTING UP .SS Description .sp This guide assumes that you have already set up Syncthing. If you haven’t yet, head over to \fI\%Getting Started\fP first. .SS Installing .sp Go to \X'tty: link https://github.com/syncthing/discosrv/releases'\fI\%releases\fP <\fBhttps://github.com/syncthing/discosrv/releases\fP>\X'tty: link' and download the file appropriate for your operating system. Unpacking it will yield a binary called \fBstdiscosrv\fP (or \fBstdiscosrv.exe\fP on Windows). Start this in whatever way you are most comfortable with; double clicking should work in any graphical environment. At first start, stdiscosrv will generate certificate files and database in the current directory unless given flags to the contrary. .sp The discovery server can also be obtained through apt, the Debian/Ubuntu package manager. Recent releases can be found at syncthing’s \X'tty: link https://apt.syncthing.net/'\fI\%apt repository\fP <\fBhttps://apt.syncthing.net/\fP>\X'tty: link'\&. The name of the package is syncthing\-discosrv. .SS Configuring .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 If you are running an instance of Syncthing on the discovery server, you must either add that instance to other devices using a static address or bind the discovery server and Syncthing instances to different IP addresses. .UNINDENT .UNINDENT .SS Certificates .sp The discovery server provides service over HTTPS. To ensure secure connections from clients there are three options: .INDENT 0.0 .IP \(bu 2 Use a CA\-signed certificate pair for the domain name you will use for the discovery server. This is like any other HTTPS website; clients will authenticate the server based on its certificate and domain name. .IP \(bu 2 Use any certificate pair and let clients authenticate the server based on its “device ID” (similar to Syncthing\-to\-Syncthing authentication). This option can be used with the certificate automatically generated by the discovery server. .IP \(bu 2 Pass the \fB\-\-http\fP flag if the discovery server is behind an SSL\-secured reverse proxy. See below for configuration. .UNINDENT .sp For the first two options, the discovery server must be given the paths to the certificate and key at startup. This isn’t necessary with the \fBhttp\fP flag: .INDENT 0.0 .INDENT 3.5 .sp .EX $ stdiscosrv \-\-cert=/path/to/cert.pem \-\-key=/path/to/key.pem Server device ID is 7DDRT7J\-UICR4PM\-PBIZYL3\-MZOJ7X7\-EX56JP6\-IK6HHMW\-S7EK32W\-G3EUPQA .EE .UNINDENT .UNINDENT .sp The discovery server prints its device ID at startup. In case you are using a non CA signed certificate, this device ID (fingerprint) must be given to the clients in the discovery server URL: .INDENT 0.0 .INDENT 3.5 .sp .EX https://disco.example.com:8443/?id=7DDRT7J\-UICR4PM\-PBIZYL3\-MZOJ7X7\-EX56JP6\-IK6HHMW\-S7EK32W\-G3EUPQA .EE .UNINDENT .UNINDENT .sp Otherwise, the URL will be: .INDENT 0.0 .INDENT 3.5 .sp .EX https://disco.example.com:8443/ .EE .UNINDENT .UNINDENT .SS Reverse Proxy Setup .sp Added in version 1.8.0: A new “X\-Client\-Port” HTTP header was added. .sp The discovery server can be run behind an SSL\-secured reverse proxy. This allows: .INDENT 0.0 .IP \(bu 2 Use of a subdomain name without requiring a port number added to the URL .IP \(bu 2 Sharing an SSL certificate with multiple services on the same server .UNINDENT .sp Note that after this configuration, if the proxy uses a valid HTTPS certificate, \fBclients should omit the\fP \fB?id=...\fP \fBparameter from the discovery server URL on their configuration\fP\&. Client\-side validation will be done by checking the visible proxy server’s HTTPS certificate. If, however, the proxy uses a self\-signed or somehow invalid certificate, clients must still set the \fB?id=...\fP parameter with the computed hash of the proxy’s certificate. Using such setup is discouraged and is not covered in this page. Always favour using valid and widely recognised certificates. .SS Requirements .INDENT 0.0 .IP \(bu 2 Run the discovery server using the \-http flag: \fBstdiscosrv \-http\fP\&. .IP \(bu 2 SSL certificate/key configured for the reverse proxy. .IP \(bu 2 The “X\-Forwarded\-For” HTTP header must be passed through with the client’s real IP address. .IP \(bu 2 The “X\-Client\-Port” HTTP header should be passed through, containing the client’s real connection port. .IP \(bu 2 The “X\-SSL\-Cert” HTTP header must be passed through with the PEM\-encoded client SSL certificate. This will be present in POST requests and may be empty in GET requests from clients. If you see syncthing\-discosrv outputting \fBno certificates\fP when receiving POST requests, that’s because the proxy is not passing this header through. .IP \(bu 2 The proxy must request the client SSL certificate but not require it to be signed by a trusted CA. .UNINDENT .SS Nginx .sp These lines in the configuration take care of the last four requirements listed above: .INDENT 0.0 .INDENT 3.5 .sp .EX proxy_set_header X\-Forwarded\-For $proxy_add_x_forwarded_for; proxy_set_header X\-Client\-Port $remote_port; proxy_set_header X\-SSL\-Cert $ssl_client_cert; ssl_verify_client optional_no_ca; .EE .UNINDENT .UNINDENT .sp The following is a complete example Nginx configuration file. With this setup, clients can use \X'tty: link https://discovery.example.com'\fI\%https://discovery.example.com\fP\X'tty: link' as the discovery server URL in the Syncthing settings. .INDENT 0.0 .INDENT 3.5 .sp .EX # HTTP 1.1 support proxy_http_version 1.1; proxy_buffering off; proxy_set_header Host $http_host; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection $http_connection; proxy_set_header X\-Real\-IP $remote_addr; proxy_set_header X\-Client\-Port $remote_port; proxy_set_header X\-Forwarded\-For $proxy_add_x_forwarded_for; proxy_set_header X\-Forwarded\-Proto $http_x_forwarded_proto; proxy_set_header X\-SSL\-Cert $ssl_client_cert; upstream discovery.example.com { # Local IP address:port for discovery server server 192.0.2.1:8443; } server { server_name discovery.example.com; listen 80; access_log /var/log/nginx/access.log vhost; return 301 https://$host$request_uri; } server { server_name discovery.example.com; listen 443 ssl http2; access_log /var/log/nginx/access.log vhost; # Mozilla Intermediate configuration (https://wiki.mozilla.org/Security/Server_Side_TLS) ssl_protocols TLSv1.2 TLSv1.3; ssl_ciphers ECDHE\-ECDSA\-AES128\-GCM\-SHA256:ECDHE\-RSA\-AES128\-GCM\-SHA256:ECDHE\-ECDSA\-AES256\-GCM\-SHA384:ECDHE\-RSA\-AES256\-GCM\-SHA384:ECDHE\-ECDSA\-CHACHA20\-POLY1305:ECDHE\-RSA\-CHACHA20\-POLY1305:DHE\-RSA\-AES128\-GCM\-SHA256:DHE\-RSA\-AES256\-GCM\-SHA384; ssl_prefer_server_ciphers off; ssl_session_tickets off; ssl_session_timeout 5m; ssl_session_cache shared:SSL:50m; ssl_verify_client optional_no_ca; # OCSP stapling ssl_stapling on; ssl_stapling_verify on; # Certificates ssl_certificate /etc/nginx/certs/discovery.example.com.crt; ssl_certificate_key /etc/nginx/certs/discovery.example.com.key; # curl https://ssl\-config.mozilla.org/ffdhe2048.txt > /path/to/dhparam ssl_dhparam /path/to/dhparam; # HSTS (ngx_http_headers_module is required) (63072000 seconds) add_header Strict\-Transport\-Security \(dqmax\-age=63072000\(dq always; location / { proxy_pass http://discovery.example.com; } } .EE .UNINDENT .UNINDENT .sp An example of automating the SSL certificates and reverse\-proxying the Discovery Server and Syncthing using Nginx, \X'tty: link https://letsencrypt.org/'\fI\%Let’s Encrypt\fP <\fBhttps://letsencrypt.org/\fP>\X'tty: link' and Docker can be found \X'tty: link https://forum.syncthing.net/t/docker-syncthing-and-syncthing-discovery-behind-nginx-reverse-proxy-with-lets-encrypt/6880'\fI\%here\fP <\fBhttps://forum.syncthing.net/t/docker-syncthing-and-syncthing-discovery-behind-nginx-reverse-proxy-with-lets-encrypt/6880\fP>\X'tty: link'\&. .SS Apache .sp The following lines must be added to the configuration: .INDENT 0.0 .INDENT 3.5 .sp .EX SSLProxyEngine On SSLVerifyClient optional_no_ca RequestHeader set X\-SSL\-Cert \(dq%{SSL_CLIENT_CERT}s\(dq .EE .UNINDENT .UNINDENT .sp The following was observed to not be required at least under Apache httpd 2.4.38, as the proxy module adds the needed header by default. If you need to explicitly add the following directive, make sure to issue \fBa2enmod remoteip\fP first. Then, add the following to your Apache httpd configuration: .INDENT 0.0 .INDENT 3.5 .sp .EX RemoteIPHeader X\-Forwarded\-For .EE .UNINDENT .UNINDENT .SS Caddy .sp The following lines must be added to the Caddyfile: .INDENT 0.0 .INDENT 3.5 .sp .EX discovery.example.com { reverse_proxy 192.0.2.1:8443 { header_up X\-Forwarded\-For {http.request.remote.host} header_up X\-Client\-Port {http.request.remote.port} header_up X\-Tls\-Client\-Cert\-Der\-Base64 {http.request.tls.client.certificate_der_base64} } tls { client_auth { mode request } } } .EE .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .EX .EE .UNINDENT .UNINDENT .sp For more details, see also the recommendations in the \X'tty: link https://docs.syncthing.net/users/reverseproxy.html'\fI\%Reverse Proxy Setup\fP <\fBhttps://docs.syncthing.net/users/reverseproxy.html\fP>\X'tty: link' page. Note that that page is directed at setting up a proxy for the Syncthing web UI. You should do the proper path and port adjustments to proxying the discovery server and your particular setup. .SH SEE ALSO .sp \fBsyncthing\-networking(7)\fP, \fBsyncthing\-faq(7)\fP .SH AUTHOR The Syncthing Authors .SH COPYRIGHT 2014-2019, The Syncthing Authors .\" Generated by docutils manpage writer. .