STDISCOSRV(1)                      Syncthing                     STDISCOSRV(1)



NNAAMMEE
       stdiscosrv - Syncthing Discovery Server

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

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

OOPPTTIIOONNSS
       --cceerrtt==<<ffiillee>>
              Certificate file (default â./cert.pemâ).

       --ddbb--ddiirr==<<ssttrriinngg>>
              Database directory, where data  is  stored  (default  â./discov‐
              ery.dbâ).

       --ddeebbuugg Enable debug output.

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

       --kkeeyy==<<ffiillee>>
              Key file (default â./key.pemâ).

       --lliisstteenn==<<aaddddrreessss>>
              Listen address (default â:8443â).

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

       --rreepplliiccaattee==<<ppeeeerrss>>
              Replication peers, _i_d_@_a_d_d_r_e_s_s <iidd@@aaddddrreessss>, comma separated

       --rreepplliiccaattiioonn--lliisstteenn==<<aaddddrreessss>>
              Listen address for  incoming  replication  connections  (default
              â:19200â).

PPOOIINNTTIINNGG SSYYNNCCTTHHIINNGG AATT YYOOUURR DDIISSCCOOVVEERRYY SSEERRVVEERR
       By default, Syncthing uses a number of global discovery servers, signi‐
       fied by the entry ddeeffaauulltt 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.  hhttttppss::////ddiissccoo..eexxaamm‐‐
       ppllee..ccoomm::88444433//. 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 //vv22// appended to
       the discovery server address, e.g. hhttttppss::////ddiissccoo..eexxaammppllee..ccoomm::88444433//vv22//.


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

SSEETTTTIINNGG UUPP
   DDeessccrriippttiioonn
       This guide assumes that you have  already  set  up  Syncthing.  If  you
       havenât yet, head over to getting-started first.

   IInnssttaalllliinngg
       Go  to  _r_e_l_e_a_s_e_s  <hhttttppss::////ggiitthhuubb..ccoomm//ssyynncctthhiinngg//ddiissccoossrrvv//rreelleeaasseess>  and
       download the file appropriate for your operating system.  Unpacking  it
       will  yield  a binary called ssttddiissccoossrrvv (or ssttddiissccoossrrvv..eexxee on Windows).
       Start this in whatever way you are most comfortable with; double click‐
       ing  should  work  in any graphical environment. At first start, stdis‐
       cosrv 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  sync‐
       thingâs  _a_p_t  _r_e_p_o_s_i_t_o_r_y  <hhttttppss::////aapptt..ssyynncctthhiinngg..nneett//>. The name of the
       package is syncthing-discosrv.

   CCoonnffiigguurriinngg
       NNOOTTEE::
          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 dif‐
          ferent IP addresses.

   CCeerrttiiffiiccaatteess
       The discovery server provides service over HTTPS. To ensure secure con‐
       nections 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 authenti‐
         cation).  This  option can be used with the certificate automatically
         generated by the discovery server.

       · Pass the --hhttttpp 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
       hhttttpp 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/

   RReepplliiccaattiioonn
       The discovery server can be deployed in a redundant, load sharing fash‐
       ion.  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  --cceerrtt  and --kkeeyy options and is thus
       shared with the main discovery API. If the --hhttttpp mode is used the  cer‐
       tificate  is not used for client requests but only for replication con‐
       nections.

       Authentication of replication connections is done using _S_y_n_c_t_h_i_n_g_-_s_t_y_l_e
       _d_e_v_i_c_e  _I_D_s <hhttttppss::////ddooccss..ssyynncctthhiinngg..nneett//ddeevv//ddeevviiccee--iiddss..hhttmmll##iidd11> 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 replica‐
       tion from the sseennddeerr to a lliisstteenneerr. 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  --rreepplliiccaattee directive sets which remote device IDs are expected and
       allowed for both outgoing (sending) and  incoming  (listening)  connec‐
       tions,  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  --rreepplliiccaattee  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.

   RReevveerrssee PPrrooxxyy SSeettuupp
       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, cclliieennttss sshhoouulldd oommiitt tthhee ??iidd==...... ppaarraammeetteerr ffrroomm tthhee ddiissccoovv‐‐
       eerryy sseerrvveerr UURRLL oonn tthheeiirr ccoonnffiigguurraattiioonn. Client-side validation  will  be
       done by checking the visible proxy serverâs HTTPS certificate. If, how‐
       ever, the proxy uses a  self-signed  or  somehow  invalid  certificate,
       clients  must still set the ??iidd==...... 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.

   RReeqquuiirreemmeennttss
       · Run the discovery server using the -http flag: ssttddiissccoossrrvv --hhttttpp.

       · 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  nnoo  cceerrttiiffiiccaatteess  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.

   NNggiinnxx
       These lines in the configuration take care of the  last  four  require‐
       ments 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 _h_t_t_p_s_:_/_/_d_i_s_c_o_v_e_r_y_._e_x_a_m_p_l_e_._c_o_m 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,   _L_e_t_â_s   _E_n_c_r_y_p_t
       <hhttttppss::////lleettsseennccrryypptt..oorrgg//>    and    Docker    can    be   found   _h_e_r_e
       <hhttttppss::////ffoorruumm..ssyynncctthhiinngg..nneett//tt//ddoocckkeerr--ssyynncctthhiinngg--aanndd--ssyynncctthhiinngg--ddiissccoovv‐‐
       eerryy--bbeehhiinndd--nnggiinnxx--rreevveerrssee--pprrooxxyy--wwiitthh--lleettss--eennccrryypptt//66888800>.

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

          RemoteIPHeader X-Forwarded-For

       For  more  details,  see  also the recommendations in the _R_e_v_e_r_s_e _P_r_o_x_y
       _S_e_t_u_p <hhttttppss::////ddooccss..ssyynncctthhiinngg..nneett//uusseerrss//rreevveerrsseepprrooxxyy..hhttmmll>  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.

SSEEEE AALLSSOO
       ssyynncctthhiinngg--nneettwwoorrkkiinngg((77)), ssyynncctthhiinngg--ffaaqq((77))

AAUUTTHHOORR
       The Syncthing Authors

CCOOPPYYRRIIGGHHTT
       2014-2019, The Syncthing Authors



v1.19.2                          Apr 05, 2022                    STDISCOSRV(1)
