127 lines
4.7 KiB
Groff
127 lines
4.7 KiB
Groff
.\" Man page generated from reStructuredText.
|
||
.
|
||
.TH "SYNCTHING-GLOBALDISCO" "7" "Mar 01, 2021" "v1" "Syncthing"
|
||
.SH NAME
|
||
syncthing-globaldisco \- Global Discovery Protocol v3
|
||
.
|
||
.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
|
||
..
|
||
.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
|
||
.nf
|
||
.ft C
|
||
{
|
||
addresses: ["tcp://192.0.2.45:22000", "tcp://:22202", "relay://192.0.2.99:22028"],
|
||
}
|
||
.ft P
|
||
.fi
|
||
.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.
|
||
.
|