1STDISCOSRV(1)                      Syncthing                     STDISCOSRV(1)
2
3
4

NAME

6       stdiscosrv - Syncthing Discovery Server
7

SYNOPSIS

9          stdiscosrv [-cert=<file>] [-db-dir=<string>] [-debug] [-http] [-key=<string>]
10                     [-listen=<address>] [-metrics-listen=<address>]
11                     [-replicate=<peers>] [-replication-listen=<address>]
12

DESCRIPTION

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

OPTIONS

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

POINTING SYNCTHING AT YOUR DISCOVERY SERVER

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

SETTING UP

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   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
86   Certificates
87       The discovery server provides service over HTTPS. To ensure secure con‐
88       nections from clients there are three options:
89
90       · 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
95       · 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
100       · Pass  the -http flag if the discovery server is behind an SSL-secured
101         reverse proxy. See below for configuration.
102
103       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
107          $ 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
110       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
114          https://disco.example.com:8443/?id=7DDRT7J-UICR4PM-PBIZYL3-MZOJ7X7-EX56JP6-IK6HHMW-S7EK32W-G3EUPQA
115
116       Otherwise, the URL will be:
117
118          https://disco.example.com:8443/
119
120   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
126       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
132       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
137       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
142       As an example, lets assume two discovery servers:
143
144       · Server one is on 192.0.2.20 and has certificate ID I6K…H76
145
146       · Server two is on 192.0.2.55 and has certificate ID MRI…7OK
147
148       In  order  for both to replicate to the other and thus form a redundant
149       pair, use the following commands.
150
151       On server one:
152
153          $ stdiscosrv -replicate=MRI...7OK@192.0.2.55:19200 <other options>
154
155       On server two:
156
157          $ stdiscosrv -replicate=I6K...H76@192.0.2.20:19200 <other options>
158
159       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
164       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
168          $ stdiscosrv -replicate=I6K...H76 <other options>
169
170       Discosrv  will  listen  on the replication port only when -replicate is
171       given. The default replication listen address is “:19200”.
172
173       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
178   Reverse Proxy Setup
179       The  discovery  server  can be run behind an SSL-secured reverse proxy.
180       This allows:
181
182       · Use of a subdomain name without requiring a port number added to  the
183         URL
184
185       · Sharing an SSL certificate with multiple services on the same server
186
187   Requirements
188       · Run the discovery server using the -http flag  stdiscosrv -http.
189
190       · SSL certificate/key configured for the reverse proxy
191
192       · The  “X-Forwarded-For”  http  header  must be passed through with the
193         client’s real IP address
194
195       · The “X-SSL-Cert” must be passed through with the  PEM-encoded  client
196         SSL certificate
197
198       · The  proxy must request the client SSL certificate but not require it
199         to be signed by a trusted CA.
200
201   Nginx
202       These three lines in the configuration take  care  of  the  last  three
203       requirements listed above:
204
205          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
209       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
213          # 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 $proxy_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 $proxy_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
252       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

SEE ALSO

259       syncthing-networking(7), syncthing-faq(7)
260

AUTHOR

262       The Syncthing Authors
263
265       2014-2019, The Syncthing Authors
266
267
268
269
270v1                               Apr 13, 2019                    STDISCOSRV(1)
Impressum