SYNCTHING-GLOBALDISCO(7)           Syncthing          SYNCTHING-GLOBALDISCO(7)



NNAAMMEE
       syncthing-globaldisco - Global Discovery Protocol v3

AANNNNOOUUNNCCEEMMEENNTTSS
       A  device  should  announce itself at startup. It does this by an HTTPS
       POST to the announce server URL. Standard discovery currently  requires
       the  path to be â/v2/â, yet this can be up to the discovery server. The
       POST has a JSON payload listing connection addresses (if any):

          {
                  addresses: ["tcp://192.0.2.45:22000", "tcp://:22202", "relay://192.0.2.99:22028"],
          }

       Itâs OK for the âaddressesâ field to be either  the  empty  list  ([[]]),
       nnuullll,  or  missing  entirely. An announcement with the field missing or
       empty is however not usefulâ¦

       Any  empty  or  unspecified   IP   addresses   (i.e.   addresses   like
       ttccpp::////::2222000000, ttccpp::////00..00..00..00::2222000000, ttccpp::////[[::::]]::2222000000) are interpreted as
       referring to the source IP address of the announcement.

       The device ID of the announcing device is not part of the announcement.
       Instead,  the  server  requires  that  the  client  perform certificate
       authentication. The device ID is deduced from  the  presented  certifi‐
       cate.

       The server response is empty, with code 220044 (No Content) on success. If
       no certificate was presented, status 440033 (Forbidden)  is  returned.  If
       the  posted  data  doesnât  conform  to  the  expected format, 440000 (Bad
       Request) is returned.

       In successful responses,  the  server  may  return  a  RReeaannnnoouunnccee--AAfftteerr
       header  containing  the number of seconds after which the client should
       perform a new announcement.

       In error responses, the server may return a RReettrryy--AAfftteerr header contain‐
       ing the number of seconds after which the client should retry.

       Performing announcements significantly more often than indicated by the
       RReeaannnnoouunnccee--AAfftteerr or RReettrryy--AAfftteerr headers may result in the client  being
       throttled.  In  such  cases the server may respond with status code 442299
       (Too Many Requests).

QQUUEERRIIEESS
       Queries are performed as HTTPS GET requests to the announce server URL.
       The  requested  device ID is passed as the query parameter âdeviceâ, in
       canonical      string      form,      i.e.      hhttttppss::////ddiissccoovveerryy..ssyynncc‐‐
       tthhiinngg..nneett//??ddeevviiccee==AABBCC1122334455--........

       Successful  responses  will  have status code 220000 (OK) and carry a JSON
       payload of the same format as the announcement above. The response will
       not contain empty or unspecified addresses.

       If  the  âdeviceâ  query  parameter is missing or malformed, the status
       code 400 (Bad Request) is returned.

       If the device ID is of a valid format but not found  in  the  registry,
       404 (Not Found) is returned.

       If  the  client  has exceeded a rate limit, the server may respond with
       429 (Too Many Requests).

AAUUTTHHEENNTTIICCAATTIIOONN
       Global discovery is spoken over HTTPS and is protected against  attack‐
       ers in the same manner as other HTTPS traffic. However, there are a few
       Syncthing specific considerations on top of this. As  mentioned  above,
       for announcements the client must provide a certificate to prove owner‐
       ship of the announced device ID.

       In addition, Syncthing has a mechanism to verify the  identity  of  the
       discovery server.  While this would normally be accomplished by using a
       CA signed certificate, Syncthing often runs in environments  with  out‐
       dated  or  simply  nonexistent  root CA bundles. Instead, Syncthing can
       verify the discovery server certificate fingerprint using the device ID
       mechanism.  This  is  certificate pinning and conveyed in the Syncthing
       configuration as a synthetic âidâ parameter  on  the  discovery  server
       URL:  hhttttppss::////ddiissccoovveerryy..ssyynncctthhiinngg..nneett//??iidd==.......  The  âidâ  parameter is
       not, in fact, sent to the discovery server -  itâs  used  by  Syncthing
       itself to know which certificate to expect on the server side.

       The public discovery network uses this authentication mechanism instead
       of CA signed certificates.

       The discovery server prints  its  certificate  ID  in  this  manner  on
       startup.

AAUUTTHHOORR
       The Syncthing Authors

CCOOPPYYRRIIGGHHTT
       2014-2019, The Syncthing Authors



v1.19.2                          Apr 05, 2022         SYNCTHING-GLOBALDISCO(7)
