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
77 directory unless given flags to the contrary.
78 Configuring
80 NOTE:
81 If you are running an instance of Syncthing on the discovery server,
82 you must either add that instance to other devices using a static
83 address or bind the discovery server and Syncthing instances to dif‐
84 ferent IP addresses.
85 Certificates
87 The discovery server provides service over HTTPS. To ensure secure con‐
88 nections from clients there are three options:
89 · Use a CA-signed certificate pair for the domain name you will use for
91 the discovery server. This is like any other HTTPS website; clients
92 will authenticate the server based on its certificate and domain
93 name.
94 · Use any certificate pair and let clients authenticate the server
96 based on its “device ID” (similar to Syncthing-to-Syncthing authenti‐
97 cation). This option can be used with the certificate automatically
98 generated by the discovery server.
99 · Pass the -http flag if the discovery server is behind an SSL-secured
101 reverse proxy. See below for configuration.
102 For the first two options, the discovery server must be given the paths
104 to the certificate and key at startup. This isn’t necessary with the
105 http flag:
106 $ stdiscosrv -cert=/path/to/cert.pem -key=/path/to/key.pem
108 Server device ID is 7DDRT7J-UICR4PM-PBIZYL3-MZOJ7X7-EX56JP6-IK6HHMW-S7EK32W-G3EUPQA
109 The discovery server prints its device ID at startup. In case you are
111 using a non CA signed certificate, this device ID (fingerprint) must be
112 given to the clients in the discovery server URL:
113 https://disco.example.com:8443/?id=7DDRT7J-UICR4PM-PBIZYL3-MZOJ7X7-EX56JP6-IK6HHMW-S7EK32W-G3EUPQA
115 Otherwise, the URL will be:
117 https://disco.example.com:8443/
119 Replication
121 The discovery server can be deployed in a redundant, load sharing fash‐
122 ion. In this mode announcements are replicated from the server that
123 receives them to other peer servers and queries can be answered equally
124 by all servers.
125 Replication connections are encrypted and authenticated using TLS. The
127 certificate is selected by the -cert and -key options and is thus
128 shared with the main discovery API. If the -http mode is used the cer‐
129 tificate is not used for client requests but only for replication con‐
130 nections.
131 Authentication of replication connections is done using Syncthing-style
133 device IDs <https://docs.syncthing.net/dev/device-ids.html#id1> only -
134 CA verification is not available. The device IDs in question are those
135 printed by the discovery server on startup.
136 Replication connections are unidirectional - announcements are replica‐
138 tion from the sender to a listener. In order to have a bidirectional
139 replication relationship between two servers both need to be configured
140 as sender and listener.
141 As an example, lets assume two discovery servers:
143 · Server one is on 192.0.2.20 and has certificate ID I6K…H76
145 · Server two is on 192.0.2.55 and has certificate ID MRI…7OK
147 In order for both to replicate to the other and thus form a redundant
149 pair, use the following commands.
150 On server one:
152 $ stdiscosrv -replicate=MRI...7OK@192.0.2.55:19200 <other options>
154 On server two:
156 $ stdiscosrv -replicate=I6K...H76@192.0.2.20:19200 <other options>
158 The -replicate directive sets which remote device IDs are expected and
160 allowed for both outgoing (sending) and incoming (listening) connec‐
161 tions, and which addresses to use when connecting out to those peers.
162 Both IP and port must be specified in peer addresses.
163 It is possible to only allow incoming connections from a peer without
165 establishing an outgoing replication connection. To do so, give only
166 the device ID without “@ip:port” address:
167 $ stdiscosrv -replicate=I6K...H76 <other options>
169 Discosrv will listen on the replication port only when -replicate is
171 given. The default replication listen address is “:19200”.
172 To achieve load balancing over two mutually replicating discovery
174 server instances, add multiple A / AAAA DNS records for a given name
175 and point Syncthing towards this name. The same certificate must be
176 used on both discovery servers.
177 Reverse Proxy Setup
179 The discovery server can be run behind an SSL-secured reverse proxy.
180 This allows:
181 · Use of a subdomain name without requiring a port number added to the
183 URL
184 · Sharing an SSL certificate with multiple services on the same server
186 Requirements
188 · Run the discovery server using the -http flag stdiscosrv -http.
189 · SSL certificate/key configured for the reverse proxy
191 · The “X-Forwarded-For” http header must be passed through with the
193 client’s real IP address
194 · The “X-SSL-Cert” must be passed through with the PEM-encoded client
196 SSL certificate
197 · The proxy must request the client SSL certificate but not require it
199 to be signed by a trusted CA.
200 Nginx
202 These three lines in the configuration take care of the last three
203 requirements listed above:
204 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
206 proxy_set_header X-SSL-Cert $ssl_client_cert;
207 ssl_verify_client optional_no_ca;
208 The following is a complete example Nginx configuration file. With this
210 setup, clients can use https://discovery.example.com as the discovery
211 server URL in the Syncthing settings.
212 # HTTP 1.1 support
214 proxy_http_version 1.1;
215 proxy_buffering off;
216 proxy_set_header Host $http_host;
217 proxy_set_header Upgrade $http_upgrade;
218 proxy_set_header Connection $http_connection;
219 proxy_set_header X-Real-IP $remote_addr;
220 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
221 proxy_set_header X-Forwarded-Proto $http_x_forwarded_proto;
222 proxy_set_header X-SSL-Cert $ssl_client_cert;
223 upstream discovery.example.com {
224 # Local IP address:port for discovery server
225 server 192.0.2.1:8443;
226 }
227 server {
228 server_name discovery.example.com;
229 listen 80;
230 access_log /var/log/nginx/access.log vhost;
231 return 301 https://$host$request_uri;
232 }
233 server {
234 server_name discovery.example.com;
235 listen 443 ssl http2;
236 access_log /var/log/nginx/access.log vhost;
237 ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
238 ssl_ciphers ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES256-GCM-SHA384: DHE-RSA-AES128-GCM-SHA256:DHE-DSS-AES128-GCM-SHA256:kEDH+AESGCM:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA:E CDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA:ECDHE-ECDSA-AES256-SHA:DHE-RSA-AES128-SHA25 6:DHE-RSA-AES128-SHA:DHE-DSS-AES128-SHA256:DHE-RSA-AES256-SHA256:DHE-DSS-AES256-SHA:DHE-RSA-AES256-SHA:AES128-GCM-SHA256:AES256-GCM-SHA3 84:AES128-SHA256:AES256-SHA256:AES128-SHA:AES256-SHA:AES:CAMELLIA:DES-CBC3-SHA:!aNULL:!eNULL:!EXPORT:!DES:!RC4:!MD5:!PSK:!aECDH:!EDH-DSS -DES-CBC3-SHA:!EDH-RSA-DES-CBC3-SHA:!KRB5-DES-CBC3-SHA;
239 ssl_prefer_server_ciphers on;
240 ssl_session_timeout 5m;
241 ssl_session_cache shared:SSL:50m;
242 ssl_certificate /etc/nginx/certs/discovery.example.com.crt;
243 ssl_certificate_key /etc/nginx/certs/discovery.example.com.key;
244 ssl_dhparam /etc/nginx/certs/discovery.example.com.dhparam.pem;
245 add_header Strict-Transport-Security "max-age=31536000";
246 ssl_verify_client optional_no_ca;
247 location / {
248 proxy_pass http://discovery.example.com;
249 }
250 }
251 An example of automating the SSL certificates and reverse-proxying the
253 Discovery Server and Syncthing using Nginx, Let’s Encrypt
254 <https://letsencrypt.org/> and Docker can be found here
255 <https://forum.syncthing.net/t/docker-syncthing-and-syncthing-discov‐
256 ery-behind-nginx-reverse-proxy-with-lets-encrypt/6880>.
257
259 syncthing-networking(7), syncthing-faq(7)
260
262 The Syncthing Authors
263
265 2014-2019, The Syncthing Authors
266v1 Mar 17, 2020 STDISCOSRV(1)