123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125 |
- .\" Man page generated from reStructuredText.
- .
- .
- .nr rst2man-indent-level 0
- .
- .de1 rstReportMargin
- \\$1 \\n[an-margin]
- level \\n[rst2man-indent-level]
- level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
- -
- \\n[rst2man-indent0]
- \\n[rst2man-indent1]
- \\n[rst2man-indent2]
- ..
- .de1 INDENT
- .\" .rstReportMargin pre:
- . RS \\$1
- . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
- . nr rst2man-indent-level +1
- .\" .rstReportMargin post:
- ..
- .de UNINDENT
- . RE
- .\" indent \\n[an-margin]
- .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
- .nr rst2man-indent-level -1
- .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
- .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
- ..
- .TH "SYNCTHING-GLOBALDISCO" "7" "Jun 02, 2024" "v1.27.7" "Syncthing"
- .SH NAME
- syncthing-globaldisco \- Global Discovery Protocol v3
- .SH ANNOUNCEMENTS
- .sp
- 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):
- .INDENT 0.0
- .INDENT 3.5
- .sp
- .EX
- {
- addresses: [\(dqtcp://192.0.2.45:22000\(dq, \(dqtcp://:22202\(dq, \(dqrelay://192.0.2.99:22028\(dq],
- }
- .EE
- .UNINDENT
- .UNINDENT
- .sp
- It’s OK for the “addresses” field to be either the empty list (\fB[]\fP),
- \fBnull\fP, or missing entirely. An announcement with the field missing
- or empty is however not useful…
- .sp
- Any empty or unspecified IP addresses (i.e. addresses like \fBtcp://:22000\fP,
- \fBtcp://0.0.0.0:22000\fP, \fBtcp://[::]:22000\fP) are interpreted as referring to
- the source IP address of the announcement.
- .sp
- 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.
- .sp
- The server response is empty, with code \fB204\fP (No Content) on success. If no
- certificate was presented, status \fB403\fP (Forbidden) is returned. If the
- posted data doesn’t conform to the expected format, \fB400\fP (Bad Request) is
- returned.
- .sp
- In successful responses, the server may return a \fBReannounce\-After\fP header
- containing the number of seconds after which the client should perform a new
- announcement.
- .sp
- In error responses, the server may return a \fBRetry\-After\fP header containing
- the number of seconds after which the client should retry.
- .sp
- Performing announcements significantly more often than indicated by the
- \fBReannounce\-After\fP or \fBRetry\-After\fP headers may result in the client being
- throttled. In such cases the server may respond with status code \fB429\fP (Too
- Many Requests).
- .SH QUERIES
- .sp
- 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. \fBhttps://discovery.syncthing.net/?device=ABC12345\-....\fP
- .sp
- Successful responses will have status code \fB200\fP (OK) and carry a JSON payload
- of the same format as the announcement above. The response will not contain
- empty or unspecified addresses.
- .sp
- If the “device” query parameter is missing or malformed, the status code 400
- (Bad Request) is returned.
- .sp
- If the device ID is of a valid format but not found in the registry, 404 (Not
- Found) is returned.
- .sp
- If the client has exceeded a rate limit, the server may respond with 429 (Too
- Many Requests).
- .SH AUTHENTICATION
- .sp
- 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.
- .sp
- 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:
- \fBhttps://discovery.syncthing.net/?id=...\fP\&. 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.
- .sp
- The public discovery network uses this authentication mechanism instead of
- CA signed certificates.
- .sp
- The discovery server prints its certificate ID in this manner on startup.
- .SH AUTHOR
- The Syncthing Authors
- .SH COPYRIGHT
- 2014-2019, The Syncthing Authors
- .\" Generated by docutils manpage writer.
- .
|