123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460 |
- .\" 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" "Oct 07, 2022" "v1.22.0" "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.
- .
|