1STDISCOSRV(1) Syncthing STDISCOSRV(1)
2
3
4
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
23 -db-dir=<string>
24 Database directory, where data is stored (default “./discov‐
25 ery.db”).
26
27 -debug Enable debug output.
28
29 -http Listen on HTTP (behind an HTTPS proxy).
30
31 -key=<file>
32 Key file (default “./key.pem”).
33
34 -listen=<address>
35 Listen address (default “:8443”).
36
37 -metrics-listen=<address>
38 Prometheus compatible metrics endpoint listen address (default
39 disabled).
40
41 -replicate=<peers>
42 Replication peers, id@address <id@address>, comma separated
43
44 -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
58 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
61
62 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
70 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
77 directory unless given flags to the contrary.
78
79 The discovery server can also be obtained through apt, the
80 Debian/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
84 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
91 Certificates
92 The discovery server provides service over HTTPS. To ensure secure con‐
93 nections from clients there are three options:
94
95 · 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
100 · 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
105 · Pass the -http flag if the discovery server is behind an SSL-secured
106 reverse proxy. See below for configuration.
107
108 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
112 $ 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
115 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
119 https://disco.example.com:8443/?id=7DDRT7J-UICR4PM-PBIZYL3-MZOJ7X7-EX56JP6-IK6HHMW-S7EK32W-G3EUPQA
120
121 Otherwise, the URL will be:
122
123 https://disco.example.com:8443/
124
125 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
131 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
137 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
142 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
147 As an example, lets assume two discovery servers:
148
149 · Server one is on 192.0.2.20 and has certificate ID I6K…H76
150
151 · Server two is on 192.0.2.55 and has certificate ID MRI…7OK
152
153 In order for both to replicate to the other and thus form a redundant
154 pair, use the following commands.
155
156 On server one:
157
158 $ stdiscosrv -replicate=MRI...7OK@192.0.2.55:19200 <other options>
159
160 On server two:
161
162 $ stdiscosrv -replicate=I6K...H76@192.0.2.20:19200 <other options>
163
164 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
169 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
173 $ stdiscosrv -replicate=I6K...H76 <other options>
174
175 Discosrv will listen on the replication port only when -replicate is
176 given. The default replication listen address is “:19200”.
177
178 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
183 Reverse Proxy Setup
184 New in version 1.8.0: A new “X-Client-Port” HTTP header was added.
185
186
187 The discovery server can be run behind an SSL-secured reverse proxy.
188 This allows:
189
190 · Use of a subdomain name without requiring a port number added to the
191 URL
192
193 · Sharing an SSL certificate with multiple services on the same server
194
195 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
205 Requirements
206 · Run the discovery server using the -http flag: stdiscosrv -http.
207
208 · SSL certificate/key configured for the reverse proxy.
209
210 · The “X-Forwarded-For” HTTP header must be passed through with the
211 client’s real IP address.
212
213 · The “X-Client-Port” HTTP header should be passed through, containing
214 the client’s real connection port.
215
216 · The “X-SSL-Cert” HTTP header must be passed through with the
217 PEM-encoded client SSL certificate. This will be present in POST
218 requests and may be empty in GET requests from clients. If you see
219 syncthing-discosrv outputting no certificates when receiving POST
220 requests, that’s because the proxy is not passing this header
221 through.
222
223 · The proxy must request the client SSL certificate but not require it
224 to be signed by a trusted CA.
225
226 Nginx
227 These lines in the configuration take care of the last four require‐
228 ments listed above:
229
230 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
231 proxy_set_header X-Client-Port $remote_port;
232 proxy_set_header X-SSL-Cert $ssl_client_cert;
233 ssl_verify_client optional_no_ca;
234
235 The following is a complete example Nginx configuration file. With this
236 setup, clients can use https://discovery.example.com as the discovery
237 server URL in the Syncthing settings.
238
239 # HTTP 1.1 support
240 proxy_http_version 1.1;
241 proxy_buffering off;
242 proxy_set_header Host $http_host;
243 proxy_set_header Upgrade $http_upgrade;
244 proxy_set_header Connection $http_connection;
245 proxy_set_header X-Real-IP $remote_addr;
246 proxy_set_header X-Client-Port $remote_port;
247 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
248 proxy_set_header X-Forwarded-Proto $http_x_forwarded_proto;
249 proxy_set_header X-SSL-Cert $ssl_client_cert;
250 upstream discovery.example.com {
251 # Local IP address:port for discovery server
252 server 192.0.2.1:8443;
253 }
254 server {
255 server_name discovery.example.com;
256 listen 80;
257 access_log /var/log/nginx/access.log vhost;
258 return 301 https://$host$request_uri;
259 }
260 server {
261 server_name discovery.example.com;
262
263 listen 443 ssl http2;
264 access_log /var/log/nginx/access.log vhost;
265
266 # Mozilla Intermediate configuration (https://wiki.mozilla.org/Security/Server_Side_TLS)
267 ssl_protocols TLSv1.2 TLSv1.3;
268 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;
269 ssl_prefer_server_ciphers off;
270 ssl_session_tickets off;
271 ssl_session_timeout 5m;
272 ssl_session_cache shared:SSL:50m;
273 ssl_verify_client optional_no_ca;
274
275 # OCSP stapling
276 ssl_stapling on;
277 ssl_stapling_verify on;
278
279 # Certificates
280 ssl_certificate /etc/nginx/certs/discovery.example.com.crt;
281 ssl_certificate_key /etc/nginx/certs/discovery.example.com.key;
282
283 # curl https://ssl-config.mozilla.org/ffdhe2048.txt > /path/to/dhparam
284 ssl_dhparam /path/to/dhparam;
285
286 # HSTS (ngx_http_headers_module is required) (63072000 seconds)
287 add_header Strict-Transport-Security "max-age=63072000" always;
288
289 location / {
290 proxy_pass http://discovery.example.com;
291 }
292 }
293
294 An example of automating the SSL certificates and reverse-proxying the
295 Discovery Server and Syncthing using Nginx, Let’s Encrypt
296 <https://letsencrypt.org/> and Docker can be found here
297 <https://forum.syncthing.net/t/docker-syncthing-and-syncthing-discov‐
298 ery-behind-nginx-reverse-proxy-with-lets-encrypt/6880>.
299
300 Apache
301 The following lines must be added to the configuration:
302
303 SSLProxyEngine On
304 SSLVerifyClient optional_no_ca
305 RequestHeader set X-SSL-Cert "%{SSL_CLIENT_CERT}s"
306
307 The following was observed to not be required at least under Apache
308 httpd 2.4.38, as the proxy module adds the needed header by default.
309 If you need to explicitly add the following directive, make sure to
310 issue a2enmod remoteip first. Then, add the following to your Apache
311 httpd configuration:
312
313 RemoteIPHeader X-Forwarded-For
314
315 For more details, see also the recommendations in the Reverse Proxy
316 Setup <https://docs.syncthing.net/users/reverseproxy.html> page. Note
317 that that page is directed at setting up a proxy for the Syncthing web
318 UI. You should do the proper path and port adjustments to proxying the
319 discovery server and your particular setup.
320
322 syncthing-networking(7), syncthing-faq(7)
323
325 The Syncthing Authors
326
328 2014-2019, The Syncthing Authors
329
330
331
332
333v1 Feb 17, 2021 STDISCOSRV(1)