syncthing/man/syncthing-globaldisco.7

.\" Man page generated from reStructuredText.
.
.TH "SYNCTHING-GLOBALDISCO" "7" "Mar 05, 2019" "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\(aqs 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\(aqt 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\(aqs 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.
.