STDISCOSRV(1)                      Syncthing                     STDISCOSRV(1)



NNAAMMEE
       stdiscosrv - Syncthing Discovery Server

SSYYNNOOPPSSIISS
          stdiscosrv [-cert=<file>] [-db-dir=<string>] [-debug] [-http] [-key=<string>]
                     [-listen=<address>] [-metrics-listen=<address>]
                     [-replicate=<peers>] [-replication-listen=<address>]

DDEESSCCRRIIPPTTIIOONN
       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.

OOPPTTIIOONNSS
       --cceerrtt==<<ffiillee>>
              Certificate file (default â./cert.pemâ).

       --ddbb--ddiirr==<<ssttrriinngg>>
              Database directory, where data  is  stored  (default  â./discov‐
              ery.dbâ).

       --ddeebbuugg Enable debug output.

       --hhttttpp  Listen on HTTP (behind an HTTPS proxy).

       --kkeeyy==<<ffiillee>>
              Key file (default â./key.pemâ).

       --lliisstteenn==<<aaddddrreessss>>
              Listen address (default â:8443â).

       --mmeettrriiccss--lliisstteenn==<<aaddddrreessss>>
              Prometheus  compatible  metrics endpoint listen address (default
              disabled).

       --rreepplliiccaattee==<<ppeeeerrss>>
              Replication peers, _i_d_@_a_d_d_r_e_s_s <iidd@@aaddddrreessss>, comma separated

       --rreepplliiccaattiioonn--lliisstteenn==<<aaddddrreessss>>
              Listen address for  incoming  replication  connections  (default
              â:19200â).

PPOOIINNTTIINNGG SSYYNNCCTTHHIINNGG AATT YYOOUURR DDIISSCCOOVVEERRYY SSEERRVVEERR
       By default, Syncthing uses a number of global discovery servers, signi‐
       fied by the entry ddeeffaauulltt 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.  hhttttppss::////ddiissccoo..eexxaamm‐‐
       ppllee..ccoomm::88444433//. 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 //vv22// appended to
       the discovery server address, e.g. hhttttppss::////ddiissccoo..eexxaammppllee..ccoomm::88444433//vv22//.


       If  you  wish to use _o_n_l_y your own discovery server, remove the ddeeffaauulltt
       entry from the list.

SSEETTTTIINNGG UUPP
   DDeessccrriippttiioonn
       This guide assumes that you have  already  set  up  Syncthing.  If  you
       havenât yet, head over to getting-started first.

   IInnssttaalllliinngg
       Go  to  _r_e_l_e_a_s_e_s  <hhttttppss::////ggiitthhuubb..ccoomm//ssyynncctthhiinngg//ddiissccoossrrvv//rreelleeaasseess>  and
       download the file appropriate for your operating system.  Unpacking  it
       will  yield  a binary called ssttddiissccoossrrvv (or ssttddiissccoossrrvv..eexxee 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  <hhttttppss::////aapptt..ssyynncctthhiinngg..nneett//>. The name of the
       package is syncthing-discosrv.

   CCoonnffiigguurriinngg
       NNOOTTEE::
          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.

   CCeerrttiiffiiccaatteess
       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 --hhttttpp 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
       hhttttpp 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/

   RReepplliiccaattiioonn
       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  --cceerrtt  and --kkeeyy options and is thus
       shared with the main discovery API. If the --hhttttpp 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 <hhttttppss::////ddooccss..ssyynncctthhiinngg..nneett//ddeevv//ddeevviiccee--iiddss..hhttmmll##iidd11> 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 sseennddeerr to a lliisstteenneerr. 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  --rreepplliiccaattee 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  --rreepplliiccaattee  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.

   RReevveerrssee PPrrooxxyy SSeettuupp
       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, cclliieennttss sshhoouulldd oommiitt tthhee ??iidd==...... ppaarraammeetteerr ffrroomm tthhee ddiissccoovv‐‐
       eerryy sseerrvveerr UURRLL oonn tthheeiirr ccoonnffiigguurraattiioonn. 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 ??iidd==...... 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.

   RReeqquuiirreemmeennttss
       · Run the discovery server using the -http flag: ssttddiissccoossrrvv --hhttttpp.

       · 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  nnoo  cceerrttiiffiiccaatteess  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.

   NNggiinnxx
       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
       <hhttttppss::////lleettsseennccrryypptt..oorrgg//>    and    Docker    can    be   found   _h_e_r_e
       <hhttttppss::////ffoorruumm..ssyynncctthhiinngg..nneett//tt//ddoocckkeerr--ssyynncctthhiinngg--aanndd--ssyynncctthhiinngg--ddiissccoovv‐‐
       eerryy--bbeehhiinndd--nnggiinnxx--rreevveerrssee--pprrooxxyy--wwiitthh--lleettss--eennccrryypptt//66888800>.

   AAppaacchhee
       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 aa22eennmmoodd rreemmootteeiipp 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 <hhttttppss::////ddooccss..ssyynncctthhiinngg..nneett//uusseerrss//rreevveerrsseepprrooxxyy..hhttmmll>  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.

SSEEEE AALLSSOO
       ssyynncctthhiinngg--nneettwwoorrkkiinngg((77)), ssyynncctthhiinngg--ffaaqq((77))

AAUUTTHHOORR
       The Syncthing Authors

CCOOPPYYRRIIGGHHTT
       2014-2019, The Syncthing Authors



v1.19.2                          Apr 05, 2022                    STDISCOSRV(1)
