NAME

       syncthing-globaldisco - Global Discovery Protocol v3

ANNOUNCEMENTS

       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  ([]),  null,  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   tcp://:22000,
       tcp://0.0.0.0:22000, tcp://[::]:22000) 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 certificate.

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

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

       In error responses, the server may return a Retry-After header containing  the  number  of
       seconds after which the client should retry.

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

QUERIES

       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.
       https://discovery.syncthing.net/?device=ABC12345-....

       Successful  responses  will have status code 200 (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).

AUTHENTICATION

       Global discovery is spoken over HTTPS and is  protected  against  attackers  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 ownership 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 outdated 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:
       https://discovery.syncthing.net/?id=....  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.

AUTHOR

       The Syncthing Authors

COPYRIGHT

       2014-2019, The Syncthing Authors