1SYNCTHING-GLOBALDISCO(7) Syncthing SYNCTHING-GLOBALDISCO(7)
2
6 syncthing-globaldisco - Global Discovery Protocol v3
7
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 {
15 addresses: ["tcp://192.0.2.45:22000", "tcp://:22202", "relay://192.0.2.99:22028"],
16 }
17 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 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 The device ID of the announcing device is not part of the announcement.
27 Instead, the server requires that the client perform certificate au‐
28 thentication. The device ID is deduced from the presented certificate.
29 The server response is empty, with code 204 (No Content) on success. If
31 no certificate was presented, status 403 (Forbidden) is returned. If
32 the posted data doesn’t conform to the expected format, 400 (Bad Re‐
33 quest) is returned.
34 In successful responses, the server may return a Reannounce-After
36 header containing the number of seconds after which the client should
37 perform a new announcement.
38 In error responses, the server may return a Retry-After header contain‐
40 ing the number of seconds after which the client should retry.
41 Performing announcements significantly more often than indicated by the
43 Reannounce-After or Retry-After headers may result in the client being
44 throttled. In such cases the server may respond with status code 429
45 (Too Many Requests).
46
48 Queries are performed as HTTPS GET requests to the announce server URL.
49 The requested device ID is passed as the query parameter “device”, in
50 canonical string form, i.e. https://discovery.syncthing.net/?de‐
51 vice=ABC12345-....
52 Successful responses will have status code 200 (OK) and carry a JSON
54 payload of the same format as the announcement above. The response will
55 not contain empty or unspecified addresses.
56 If the “device” query parameter is missing or malformed, the status
58 code 400 (Bad Request) is returned.
59 If the device ID is of a valid format but not found in the registry,
61 404 (Not Found) is returned.
62 If the client has exceeded a rate limit, the server may respond with
64 429 (Too Many Requests).
65
67 Global discovery is spoken over HTTPS and is protected against attack‐
68 ers in the same manner as other HTTPS traffic. However, there are a few
69 Syncthing specific considerations on top of this. As mentioned above,
70 for announcements the client must provide a certificate to prove owner‐
71 ship of the announced device ID.
72 In addition, Syncthing has a mechanism to verify the identity of the
74 discovery server. While this would normally be accomplished by using a
75 CA signed certificate, Syncthing often runs in environments with out‐
76 dated or simply nonexistent root CA bundles. Instead, Syncthing can
77 verify the discovery server certificate fingerprint using the device ID
78 mechanism. This is certificate pinning and conveyed in the Syncthing
79 configuration as a synthetic “id” parameter on the discovery server
80 URL: https://discovery.syncthing.net/?id=.... The “id” parameter is
81 not, in fact, sent to the discovery server - it’s used by Syncthing it‐
82 self to know which certificate to expect on the server side.
83 The public discovery network uses this authentication mechanism instead
85 of CA signed certificates.
86 The discovery server prints its certificate ID in this manner on
88 startup.
89
91 The Syncthing Authors
92
94 2014-2019, The Syncthing Authors
95v1.22.2 Dec 29, 2022 SYNCTHING-GLOBALDISCO(7)