Provided by: syncthing-discosrv_1.19.2~ds1-3ubuntu0.1_amd64 bug

NAME

       stdiscosrv - Syncthing Discovery Server

SYNOPSIS

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

DESCRIPTION

       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.

OPTIONS

       -cert=<file>
              Certificate file (default “./cert.pem”).

       -db-dir=<string>
              Database directory, where data is stored (default “./discovery.db”).

       -debug Enable debug output.

       -http  Listen on HTTP (behind an HTTPS proxy).

       -key=<file>
              Key file (default “./key.pem”).

       -listen=<address>
              Listen address (default “:8443”).

       -metrics-listen=<address>
              Prometheus compatible metrics endpoint listen address (default disabled).

       -replicate=<peers>
              Replication peers, id@address <id@address>, comma separated

       -replication-listen=<address>
              Listen address for incoming replication connections (default “:19200”).

POINTING SYNCTHING AT YOUR DISCOVERY SERVER

       By  default,  Syncthing  uses a number of global discovery servers, signified by the entry
       default 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.
       https://disco.example.com:8443/.  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.

       Deprecated  since  version  v0.14.44:  Prior  versions need /v2/ appended to the discovery
       server address, e.g. https://disco.example.com:8443/v2/.

       If you wish to use only your own discovery server, remove the default entry from the list.

SETTING UP

   Description
       This guide assumes that you have already set up Syncthing. If you haven’t yet,  head  over
       to getting-started first.

   Installing
       Go  to  releases  <https://github.com/syncthing/discosrv/releases>  and  download the file
       appropriate for your operating system. Unpacking it will yield a binary called  stdiscosrv
       (or stdiscosrv.exe 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.

       The discovery server can also be obtained through apt, the Debian/Ubuntu package  manager.
       Recent  releases  can be found at syncthing’s apt repository <https://apt.syncthing.net/>.
       The name of the package is syncthing-discosrv.

   Configuring
       NOTE:
          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.

   Certificates
       The discovery server provides service  over  HTTPS.  To  ensure  secure  connections  from
       clients there are three options:

       • 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.

       • 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.

       • Pass  the -http flag if the discovery server is behind an SSL-secured reverse proxy. See
         below for configuration.

       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 http flag:

          $ stdiscosrv -cert=/path/to/cert.pem -key=/path/to/key.pem
          Server device ID is 7DDRT7J-UICR4PM-PBIZYL3-MZOJ7X7-EX56JP6-IK6HHMW-S7EK32W-G3EUPQA

       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:

          https://disco.example.com:8443/?id=7DDRT7J-UICR4PM-PBIZYL3-MZOJ7X7-EX56JP6-IK6HHMW-S7EK32W-G3EUPQA

       Otherwise, the URL will be:

          https://disco.example.com:8443/

   Replication
       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.

       Replication  connections  are  encrypted  and  authenticated using TLS. The certificate is
       selected by the -cert and -key options and is thus shared with the main discovery API.  If
       the  -http  mode  is  used  the  certificate  is not used for client requests but only for
       replication connections.

       Authentication of  replication  connections  is  done  using  Syncthing-style  device  IDs
       <https://docs.syncthing.net/dev/device-ids.html#id1>   only   -  CA  verification  is  not
       available. The device IDs in question  are  those  printed  by  the  discovery  server  on
       startup.

       Replication connections are unidirectional - announcements are replication from the sender
       to a listener. In order to have  a  bidirectional  replication  relationship  between  two
       servers both need to be configured as sender and listener.

       As an example, lets assume two discovery servers:

       • Server one is on 192.0.2.20 and has certificate ID I6K…H76

       • Server two is on 192.0.2.55 and has certificate ID MRI…7OK

       In  order  for  both  to  replicate  to  the other and thus form a redundant pair, use the
       following commands.

       On server one:

          $ stdiscosrv -replicate=MRI...7OK@192.0.2.55:19200 <other options>

       On server two:

          $ stdiscosrv -replicate=I6K...H76@192.0.2.20:19200 <other options>

       The -replicate 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.

       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:

          $ stdiscosrv -replicate=I6K...H76 <other options>

       Discosrv will listen on the replication port only when -replicate is  given.  The  default
       replication listen address is “:19200”.

       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.

   Reverse Proxy Setup
       New in version 1.8.0: A new “X-Client-Port” HTTP header was added.

       The discovery server can be run behind an SSL-secured reverse proxy. This allows:

       • Use of a subdomain name without requiring a port number added to the URL

       • Sharing an SSL certificate with multiple services on the same server

       Note  that  after this configuration, if the proxy uses a valid HTTPS certificate, clients
       should omit the ?id=... parameter from the discovery server URL  on  their  configuration.
       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  ?id=...  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.

   Requirements
       • Run the discovery server using the -http flag: stdiscosrv -http.

       • SSL certificate/key configured for the reverse proxy.

       • The  “X-Forwarded-For”  HTTP  header  must  be  passed through with the client’s real IP
         address.

       • The “X-Client-Port” HTTP header should be passed through, containing the  client’s  real
         connection port.

       • 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 no certificates when receiving POST
         requests, that’s because the proxy is not passing this header through.

       • The proxy must request the client SSL certificate but not require it to be signed  by  a
         trusted CA.

   Nginx
       These lines in the configuration take care of the last four requirements listed above:

          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;

       The following is a complete example Nginx configuration file. With this setup, clients can
       use https://discovery.example.com as the discovery server URL in the Syncthing settings.

          # 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;
                  }
          }

       An example of automating the SSL certificates and reverse-proxying  the  Discovery  Server
       and  Syncthing  using  Nginx,  Let’s  Encrypt <https://letsencrypt.org/> and Docker can be
       found here <https://forum.syncthing.net/t/docker-syncthing-and-syncthing-discovery-behind-
       nginx-reverse-proxy-with-lets-encrypt/6880>.

   Apache
       The following lines must be added to the configuration:

          SSLProxyEngine On
          SSLVerifyClient optional_no_ca
          RequestHeader set X-SSL-Cert "%{SSL_CLIENT_CERT}s"

       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 a2enmod remoteip first. Then, add the following to
       your Apache httpd configuration:

          RemoteIPHeader X-Forwarded-For

       For  more  details,  see  also  the   recommendations   in   the   Reverse   Proxy   Setup
       <https://docs.syncthing.net/users/reverseproxy.html> 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.

SEE ALSO

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

AUTHOR

       The Syncthing Authors

COPYRIGHT

       2014-2019, The Syncthing Authors