1STDISCOSRV(1) Syncthing STDISCOSRV(1)
2
6 stdiscosrv - Syncthing Discovery Server
7
9 stdiscosrv [-cert=<file>] [-db-dir=<string>] [-debug] [-http] [-key=<string>]
10 [-listen=<address>] [-metrics-listen=<address>]
11 [-replicate=<peers>] [-replication-listen=<address>]
12
14 Syncthing relies on a discovery server to find peers on the internet.
15 Anyone can run a discovery server and point Syncthing installations to
16 it. The Syncthing project also maintains a global cluster for public
17 use.
18
20 -cert=<file>
21 Certificate file (default “./cert.pem”).
22 -db-dir=<string>
24 Database directory, where data is stored (default “./discov‐
25 ery.db”).
26 -debug Enable debug output.
28 -http Listen on HTTP (behind an HTTPS proxy).
30 -key=<file>
32 Key file (default “./key.pem”).
33 -listen=<address>
35 Listen address (default “:8443”).
36 -metrics-listen=<address>
38 Prometheus compatible metrics endpoint listen address (default
39 disabled).
40 -replicate=<peers>
42 Replication peers, id@address <id@address>, comma separated
43 -replication-listen=<address>
45 Listen address for incoming replication connections (default
46 “:19200”).
47
49 By default, Syncthing uses a number of global discovery servers, signi‐
50 fied by the entry default in the list of discovery servers. To make
51 Syncthing use your own instance of stdiscosrv, open up Syncthing’s web
52 GUI. Go to settings, Global Discovery Server and add stdiscosrv’s host
53 address to the comma-separated list, e.g. https://disco.exam‐
54 ple.com:8443/. Note that stdiscosrv uses port 8443 by default. For
55 stdiscosrv to be available over the internet with a dynamic IP address,
56 you will need a dynamic DNS service.
57 Deprecated since version v0.14.44: Prior versions need /v2/ appended to
59 the discovery server address, e.g. https://disco.example.com:8443/v2/.
60 If you wish to use only your own discovery server, remove the default
63 entry from the list.
64
66 Description
67 This guide assumes that you have already set up Syncthing. If you
68 haven’t yet, head over to getting-started first.
69 Installing
71 Go to releases <https://github.com/syncthing/discosrv/releases> and
72 download the file appropriate for your operating system. Unpacking it
73 will yield a binary called stdiscosrv (or stdiscosrv.exe on Windows).
74 Start this in whatever way you are most comfortable with; double click‐
75 ing should work in any graphical environment. At first start, stdis‐
76 cosrv will generate certificate files and database in the current di‐
77 rectory unless given flags to the contrary.
78 The discovery server can also be obtained through apt, the De‐
80 bian/Ubuntu package manager. Recent releases can be found at sync‐
81 thing’s apt repository <https://apt.syncthing.net/>. The name of the
82 package is syncthing-discosrv.
83 Configuring
85 NOTE:
86 If you are running an instance of Syncthing on the discovery server,
87 you must either add that instance to other devices using a static
88 address or bind the discovery server and Syncthing instances to dif‐
89 ferent IP addresses.
90 Certificates
92 The discovery server provides service over HTTPS. To ensure secure con‐
93 nections from clients there are three options:
94 • Use a CA-signed certificate pair for the domain name you will use for
96 the discovery server. This is like any other HTTPS website; clients
97 will authenticate the server based on its certificate and domain
98 name.
99 • Use any certificate pair and let clients authenticate the server
101 based on its “device ID” (similar to Syncthing-to-Syncthing authenti‐
102 cation). This option can be used with the certificate automatically
103 generated by the discovery server.
104 • Pass the -http flag if the discovery server is behind an SSL-secured
106 reverse proxy. See below for configuration.
107 For the first two options, the discovery server must be given the paths
109 to the certificate and key at startup. This isn’t necessary with the
110 http flag:
111 $ stdiscosrv -cert=/path/to/cert.pem -key=/path/to/key.pem
113 Server device ID is 7DDRT7J-UICR4PM-PBIZYL3-MZOJ7X7-EX56JP6-IK6HHMW-S7EK32W-G3EUPQA
114 The discovery server prints its device ID at startup. In case you are
116 using a non CA signed certificate, this device ID (fingerprint) must be
117 given to the clients in the discovery server URL:
118 https://disco.example.com:8443/?id=7DDRT7J-UICR4PM-PBIZYL3-MZOJ7X7-EX56JP6-IK6HHMW-S7EK32W-G3EUPQA
120 Otherwise, the URL will be:
122 https://disco.example.com:8443/
124 Replication
126 The discovery server can be deployed in a redundant, load sharing fash‐
127 ion. In this mode announcements are replicated from the server that
128 receives them to other peer servers and queries can be answered equally
129 by all servers.
130 Replication connections are encrypted and authenticated using TLS. The
132 certificate is selected by the -cert and -key options and is thus
133 shared with the main discovery API. If the -http mode is used the cer‐
134 tificate is not used for client requests but only for replication con‐
135 nections.
136 Authentication of replication connections is done using Syncthing-style
138 device IDs <https://docs.syncthing.net/dev/device-ids.html#id1> only -
139 CA verification is not available. The device IDs in question are those
140 printed by the discovery server on startup.
141 Replication connections are unidirectional - announcements are replica‐
143 tion from the sender to a listener. In order to have a bidirectional
144 replication relationship between two servers both need to be configured
145 as sender and listener.
146 As an example, lets assume two discovery servers:
148 • Server one is on 192.0.2.20 and has certificate ID I6K…H76
150 • Server two is on 192.0.2.55 and has certificate ID MRI…7OK
152 In order for both to replicate to the other and thus form a redundant
154 pair, use the following commands.
155 On server one:
157 $ stdiscosrv -replicate=MRI...7OK@192.0.2.55:19200 <other options>
159 On server two:
161 $ stdiscosrv -replicate=I6K...H76@192.0.2.20:19200 <other options>
163 The -replicate directive sets which remote device IDs are expected and
165 allowed for both outgoing (sending) and incoming (listening) connec‐
166 tions, and which addresses to use when connecting out to those peers.
167 Both IP and port must be specified in peer addresses.
168 It is possible to only allow incoming connections from a peer without
170 establishing an outgoing replication connection. To do so, give only
171 the device ID without “@ip:port” address:
172 $ stdiscosrv -replicate=I6K...H76 <other options>
174 Discosrv will listen on the replication port only when -replicate is
176 given. The default replication listen address is “:19200”.
177 To achieve load balancing over two mutually replicating discovery
179 server instances, add multiple A / AAAA DNS records for a given name
180 and point Syncthing towards this name. The same certificate must be
181 used on both discovery servers.
182 Reverse Proxy Setup
184 New in version 1.8.0: A new “X-Client-Port” HTTP header was added.
185 The discovery server can be run behind an SSL-secured reverse proxy.
188 This allows:
189 • Use of a subdomain name without requiring a port number added to the
191 URL
192 • Sharing an SSL certificate with multiple services on the same server
194 Note that after this configuration, if the proxy uses a valid HTTPS
196 certificate, clients should omit the ?id=... parameter from the discov‐
197 ery server URL on their configuration. Client-side validation will be
198 done by checking the visible proxy server’s HTTPS certificate. If, how‐
199 ever, the proxy uses a self-signed or somehow invalid certificate,
200 clients must still set the ?id=... parameter with the computed hash of
201 the proxy’s certificate. Using such setup is discouraged and is not
202 covered in this page. Always favour using valid and widely recognised
203 certificates.
204 Requirements
206 • Run the discovery server using the -http flag: stdiscosrv -http.
207 • SSL certificate/key configured for the reverse proxy.
209 • The “X-Forwarded-For” HTTP header must be passed through with the
211 client’s real IP address.
212 • The “X-Client-Port” HTTP header should be passed through, containing
214 the client’s real connection port.
215 • The “X-SSL-Cert” HTTP header must be passed through with the PEM-en‐
217 coded client SSL certificate. This will be present in POST requests
218 and may be empty in GET requests from clients. If you see sync‐
219 thing-discosrv outputting no certificates when receiving POST re‐
220 quests, that’s because the proxy is not passing this header through.
221 • The proxy must request the client SSL certificate but not require it
223 to be signed by a trusted CA.
224 Nginx
226 These lines in the configuration take care of the last four require‐
227 ments listed above:
228 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
230 proxy_set_header X-Client-Port $remote_port;
231 proxy_set_header X-SSL-Cert $ssl_client_cert;
232 ssl_verify_client optional_no_ca;
233 The following is a complete example Nginx configuration file. With this
235 setup, clients can use https://discovery.example.com as the discovery
236 server URL in the Syncthing settings.
237 # HTTP 1.1 support
239 proxy_http_version 1.1;
240 proxy_buffering off;
241 proxy_set_header Host $http_host;
242 proxy_set_header Upgrade $http_upgrade;
243 proxy_set_header Connection $http_connection;
244 proxy_set_header X-Real-IP $remote_addr;
245 proxy_set_header X-Client-Port $remote_port;
246 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
247 proxy_set_header X-Forwarded-Proto $http_x_forwarded_proto;
248 proxy_set_header X-SSL-Cert $ssl_client_cert;
249 upstream discovery.example.com {
250 # Local IP address:port for discovery server
251 server 192.0.2.1:8443;
252 }
253 server {
254 server_name discovery.example.com;
255 listen 80;
256 access_log /var/log/nginx/access.log vhost;
257 return 301 https://$host$request_uri;
258 }
259 server {
260 server_name discovery.example.com;
261 listen 443 ssl http2;
263 access_log /var/log/nginx/access.log vhost;
264 # Mozilla Intermediate configuration (https://wiki.mozilla.org/Security/Server_Side_TLS)
266 ssl_protocols TLSv1.2 TLSv1.3;
267 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;
268 ssl_prefer_server_ciphers off;
269 ssl_session_tickets off;
270 ssl_session_timeout 5m;
271 ssl_session_cache shared:SSL:50m;
272 ssl_verify_client optional_no_ca;
273 # OCSP stapling
275 ssl_stapling on;
276 ssl_stapling_verify on;
277 # Certificates
279 ssl_certificate /etc/nginx/certs/discovery.example.com.crt;
280 ssl_certificate_key /etc/nginx/certs/discovery.example.com.key;
281 # curl https://ssl-config.mozilla.org/ffdhe2048.txt > /path/to/dhparam
283 ssl_dhparam /path/to/dhparam;
284 # HSTS (ngx_http_headers_module is required) (63072000 seconds)
286 add_header Strict-Transport-Security "max-age=63072000" always;
287 location / {
289 proxy_pass http://discovery.example.com;
290 }
291 }
292 An example of automating the SSL certificates and reverse-proxying the
294 Discovery Server and Syncthing using Nginx, Let’s Encrypt
295 <https://letsencrypt.org/> and Docker can be found here <https://fo‐
296 rum.syncthing.net/t/docker-syncthing-and-syncthing-discovery-behind-ng‐
297 inx-reverse-proxy-with-lets-encrypt/6880>.
298 Apache
300 The following lines must be added to the configuration:
301 SSLProxyEngine On
303 SSLVerifyClient optional_no_ca
304 RequestHeader set X-SSL-Cert "%{SSL_CLIENT_CERT}s"
305 The following was observed to not be required at least under Apache
307 httpd 2.4.38, as the proxy module adds the needed header by default.
308 If you need to explicitly add the following directive, make sure to is‐
309 sue a2enmod remoteip first. Then, add the following to your Apache
310 httpd configuration:
311 RemoteIPHeader X-Forwarded-For
313 For more details, see also the recommendations in the Reverse Proxy
315 Setup <https://docs.syncthing.net/users/reverseproxy.html> page. Note
316 that that page is directed at setting up a proxy for the Syncthing web
317 UI. You should do the proper path and port adjustments to proxying the
318 discovery server and your particular setup.
319
321 syncthing-networking(7), syncthing-faq(7)
322
324 The Syncthing Authors
325
327 2014-2019, The Syncthing Authors
328v1 Oct 17, 2021 STDISCOSRV(1)