.\" Man page generated from reStructuredText. . .TH "SYNCTHING-GLOBALDISCO" "7" "January 01, 2016" "v0.12" "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 (with the path usually being "/", but this is of course up to the discovery server). The POST has a JSON payload listing direct connection addresses (if any) and relay addresses (if any): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { direct: ["tcp://192.0.2.45:22000", "tcp://:22202"], relays: [{"url": "relay://192.0.2.99:22028", "latency": 142}] } .ft P .fi .UNINDENT .UNINDENT .sp It\(aqs OK for either of the "direct" or "relays" fields to be either the empty list (\fB[]\fP), \fBnull\fP, or missing entirely. An announcment with both fields 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 successfull 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://announce.syncthing.net/?device=ABC12345\-....\fP .sp Successfull 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 AUTHOR The Syncthing Authors .SH COPYRIGHT 2015, The Syncthing Authors .\" Generated by docutils manpage writer. .