1SYNCTHING-GLOBALDISCO(7)           Syncthing          SYNCTHING-GLOBALDISCO(7)
2
3
4

NAME

6       syncthing-globaldisco - Global Discovery Protocol v3
7

ANNOUNCEMENTS

9       A  device  should  announce itself at startup. It does this by an HTTPS
10       POST to the announce server URL. Standard discovery currently  requires
11       the  path to be “/v2/”, yet this can be up to the discovery server. The
12       POST has a JSON payload listing connection addresses (if any):
13
14          {
15                  addresses: ["tcp://192.0.2.45:22000", "tcp://:22202", "relay://192.0.2.99:22028"],
16          }
17
18       It’s OK for the “addresses” field to be either  the  empty  list  ([]),
19       null,  or  missing  entirely. An announcement with the field missing or
20       empty is however not useful…
21
22       Any  empty  or  unspecified   IP   addresses   (i.e.   addresses   like
23       tcp://:22000, tcp://0.0.0.0:22000, tcp://[::]:22000) are interpreted as
24       referring to the source IP address of the announcement.
25
26       The device ID of the announcing device is not part of the announcement.
27       Instead,  the  server  requires  that  the  client  perform certificate
28       authentication. The device ID is deduced from  the  presented  certifi‐
29       cate.
30
31       The server response is empty, with code 204 (No Content) on success. If
32       no certificate was presented, status 403 (Forbidden)  is  returned.  If
33       the  posted  data  doesn’t  conform  to  the  expected format, 400 (Bad
34       Request) is returned.
35
36       In successful responses,  the  server  may  return  a  Reannounce-After
37       header  containing  the number of seconds after which the client should
38       perform a new announcement.
39
40       In error responses, the server may return a Retry-After header contain‐
41       ing the number of seconds after which the client should retry.
42
43       Performing announcements significantly more often than indicated by the
44       Reannounce-After or Retry-After headers may result in the client  being
45       throttled.  In  such  cases the server may respond with status code 429
46       (Too Many Requests).
47

QUERIES

49       Queries are performed as HTTPS GET requests to the announce server URL.
50       The  requested  device ID is passed as the query parameter “device”, in
51       canonical      string      form,      i.e.      https://discovery.sync
52       thing.net/?device=ABC12345-....
53
54       Successful  responses  will  have status code 200 (OK) and carry a JSON
55       payload of the same format as the announcement above. The response will
56       not contain empty or unspecified addresses.
57
58       If  the  “device”  query  parameter is missing or malformed, the status
59       code 400 (Bad Request) is returned.
60
61       If the device ID is of a valid format but not found  in  the  registry,
62       404 (Not Found) is returned.
63
64       If  the  client  has exceeded a rate limit, the server may respond with
65       429 (Too Many Requests).
66

AUTHENTICATION

68       Global discovery is spoken over HTTPS and is protected against  attack‐
69       ers in the same manner as other HTTPS traffic. However, there are a few
70       Syncthing specific considerations on top of this. As  mentioned  above,
71       for announcements the client must provide a certificate to prove owner‐
72       ship of the announced device ID.
73
74       In addition, Syncthing has a mechanism to verify the  identity  of  the
75       discovery server.  While this would normally be accomplished by using a
76       CA signed certificate, Syncthing often runs in environments  with  out‐
77       dated  or  simply  nonexistent  root CA bundles. Instead, Syncthing can
78       verify the discovery server certificate fingerprint using the device ID
79       mechanism.  This  is  certificate pinning and conveyed in the Syncthing
80       configuration as a synthetic “id” parameter  on  the  discovery  server
81       URL:  https://discovery.syncthing.net/?id=....  The  “id”  parameter is
82       not, in fact, sent to the discovery server -  it’s  used  by  Syncthing
83       itself to know which certificate to expect on the server side.
84
85       The public discovery network uses this authentication mechanism instead
86       of CA signed certificates.
87
88       The discovery server prints  its  certificate  ID  in  this  manner  on
89       startup.
90

AUTHOR

92       The Syncthing Authors
93
95       2014-2019, The Syncthing Authors
96
97
98
99
100v1                               Feb 17, 2021         SYNCTHING-GLOBALDISCO(7)
Impressum