summaryrefslogtreecommitdiffstats
path: root/man/stdiscosrv.1
blob: 28012237e13638f97f649e21dc7b707d2163e7fe (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
.\" 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" "Jun 09, 2022" "v1.20.2" "Syncthing"
.SH NAME
stdiscosrv \- Syncthing Discovery Server
.SH SYNOPSIS
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
stdiscosrv [\-cert=<file>] [\-db\-dir=<string>] [\-debug] [\-http] [\-key=<string>]
           [\-listen=<address>] [\-metrics\-listen=<address>]
           [\-replicate=<peers>] [\-replication\-listen=<address>]
.ft P
.fi
.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 \-cert=<file>
Certificate file (default “./cert.pem”).
.UNINDENT
.INDENT 0.0
.TP
.B \-db\-dir=<string>
Database directory, where data is stored (default “./discovery.db”).
.UNINDENT
.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 \-key=<file>
Key file (default “./key.pem”).
.UNINDENT
.INDENT 0.0
.TP
.B \-listen=<address>
Listen address (default “:8443”).
.UNINDENT
.INDENT 0.0
.TP
.B \-metrics\-listen=<address>
Prometheus compatible metrics endpoint listen address (default disabled).
.UNINDENT
.INDENT 0.0
.TP
.B \-replicate=<peers>
Replication peers, \fI\%id@address\fP <\fBid@address\fP>, comma separated
.UNINDENT
.INDENT 0.0
.TP
.B \-replication\-listen=<address>
Listen address for incoming replication connections (default “:19200”).
.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 getting\-started first.
.SS Installing
.sp
Go to \fI\%releases\fP <\fBhttps://github.com/syncthing/discosrv/releases\fP> 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
\fI\%apt repository\fP <\fBhttps://apt.syncthing.net/\fP>\&. 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
.nf
.ft C
$ stdiscosrv \-cert=/path/to/cert.pem \-key=/path/to/key.pem
Server device ID is 7DDRT7J\-UICR4PM\-PBIZYL3\-MZOJ7X7\-EX56JP6\-IK6HHMW\-S7EK32W\-G3EUPQA
.ft P
.fi
.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
.nf
.ft C
https://disco.example.com:8443/?id=7DDRT7J\-UICR4PM\-PBIZYL3\-MZOJ7X7\-EX56JP6\-IK6HHMW\-S7EK32W\-G3EUPQA
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Otherwise, the URL will be:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
https://disco.example.com:8443/
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Replication
.sp
The discovery server can be deployed in a redundant, load sharing fashion.
In this mode announcements are replicated from the server that receives them
to other peer servers and queries can be answered equally by all servers.
.sp
Replication connections are encrypted and authenticated using TLS. The
certificate is selected by the \fB\-cert\fP and \fB\-key\fP options and is thus
shared with the main discovery API. If the \fB\-http\fP mode is used the
certificate is not used for client requests but only for replication
connections.
.sp
Authentication of replication connections is done using \fI\%Syncthing\-style
device IDs\fP <\fBhttps://docs.syncthing.net/dev/device-ids.html#id1\fP> only \- CA
verification is not available. The device IDs in question are those printed
by the discovery server on startup.
.sp
Replication connections are unidirectional \- announcements are replication
from the \fBsender\fP to a \fBlistener\fP\&. In order to have a bidirectional
replication relationship between two servers both need to be configured as
sender and listener.
.sp
As an example, lets assume two discovery servers:
.INDENT 0.0
.IP \(bu 2
Server one is on 192.0.2.20 and has certificate ID I6K…H76
.IP \(bu 2
Server two is on 192.0.2.55 and has certificate ID MRI…7OK
.UNINDENT
.sp
In order for both to replicate to the other and thus form a redundant pair,
use the following commands.
.sp
On server one:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ stdiscosrv \-replicate=MRI...7OK@192.0.2.55:19200 <other options>
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
On server two:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ stdiscosrv \-replicate=I6K...H76@192.0.2.20:19200 <other options>
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The \fB\-replicate\fP directive sets which remote device IDs are expected and
allowed for both outgoing (sending) and incoming (listening) connections,
and which addresses to use when connecting out to those peers. Both IP and
port must be specified in peer addresses.
.sp
It is possible to only allow incoming connections from a peer without
establishing an outgoing replication connection. To do so, give only the
device ID without “@ip:port” address:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ stdiscosrv \-replicate=I6K...H76 <other options>
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Discosrv will listen on the replication port only when \fB\-replicate\fP is
given. The default replication listen address is “:19200”.
.sp
To achieve load balancing over two mutually replicating discovery server
instances, add multiple A / AAAA DNS records for a given name and point
Syncthing towards this name. The same certificate must be used on both
discovery servers.
.SS Reverse Proxy Setup
.sp
New 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
.nf
.ft C
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;
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The following is a complete example Nginx configuration file. With this setup,
clients can use \fI\%https://discovery.example.com\fP as the discovery server URL in
the Syncthing settings.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# 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 "max\-age=63072000" always;

        location / {
                proxy_pass http://discovery.example.com;
        }
}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
An example of automating the SSL certificates and reverse\-proxying the Discovery
Server and Syncthing using Nginx, \fI\%Let’s Encrypt\fP <\fBhttps://letsencrypt.org/\fP> and Docker can be found \fI\%here\fP <\fBhttps://forum.syncthing.net/t/docker-syncthing-and-syncthing-discovery-behind-nginx-reverse-proxy-with-lets-encrypt/6880\fP>\&.
.SS Apache
.sp
The following lines must be added to the configuration:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
SSLProxyEngine On
SSLVerifyClient optional_no_ca
RequestHeader set X\-SSL\-Cert "%{SSL_CLIENT_CERT}s"
.ft P
.fi
.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
.nf
.ft C
RemoteIPHeader X\-Forwarded\-For
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
For more details, see also the recommendations in the
\fI\%Reverse Proxy Setup\fP <\fBhttps://docs.syncthing.net/users/reverseproxy.html\fP>
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.
.