syncthing/man/syncthing-localdisco.7

.\" Man page generated from reStructuredText.
.
.TH "SYNCTHING-LOCALDISCO" "7" "November 09, 2015" "v0.12" "Syncthing"
.SH NAME
syncthing-localdisco \- Local 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 MODE OF OPERATION
.sp
Each participating device periodically sends an Announcement packet. It also
keeps a table of the announcements it has seen. There is no way to solicit a
reply; the only message type is Announcement.
.sp
On multihomed hosts the announcement packets should be sent on each interface
on which Syncthing will accept connections.
.sp
For IPv4, the Announcement packet is broadcast either to the link\-specific
broadcast address, or to the generic link\-local broadcast address
\fB255.255.255.255\fP, with destination port 21027.
.sp
For IPv6, the Announcement packet is multicast to the transient link\-local
multicast address \fB[ff12::8384]\fP, with destination port 21027.
.sp
It is recommended that local discovery Announcement packets be sent on a 30 to
60 second interval, possibly with immediate transmissions when a previously
unknown device is discovered.
.SH DEVICE ID
.sp
The device ID is the SHA\-256 (32 bytes) of the device X.509 certificate. See
device\-ids in the Syncthing documentation.
.SH ANNOUNCEMENT PACKET
.sp
The Announcement packet has the following structure:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
Announce Structure:

 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|                             Magic                             |
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
/                                                               /
\e                       Device Structure                        \e
/                                                               /
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|                    Number of Extra Devices                    |
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
/                                                               /
\e                Zero or more Device Structures                 \e
/                                                               /
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+

Device Structure:

 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|                         Length of ID                          |
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
/                                                               /
\e                     ID (variable length)                      \e
/                                                               /
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|                      Number of Addresses                      |
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
/                                                               /
\e                Zero or more Address Structures                \e
/                                                               /
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|                       Number of Relays                        |
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
/                                                               /
\e                 Zero or more Relay Structures                 \e
/                                                               /
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+

Address Structure:

 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|                         Length of URL                         |
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
/                                                               /
\e                     URL (variable length)                     \e
/                                                               /
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+

Relay Structure:

 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|                         Length of URL                         |
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
/                                                               /
\e                     URL (variable length)                     \e
/                                                               /
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|                            Latency                            |
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The corresponding XDR representation is as follows (see
\fI\%RFC4506\fP <\fBhttp://tools.ietf.org/html/rfc4506\fP> for the XDR format):
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
struct Announcement {
    unsigned int Magic;
    Device This;
    Device Extra<>;
}

struct Device {
    opaque ID<32>;
    Address Addresses<16>;
    Relay Relays<16>;
}

struct Address {
    string URL<2083>;
}

struct Relay {
    string URL<2083>;
    int Latency;
}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In the \fBAnnounce\fP  structure  field \fBMagic\fP is used to ensure
a correct datagram was received and MUST be equal to \fB0x9D79BC40\fP\&.
.sp
The first Device structure contains information about the sending
device. The following zero or more Extra devices contain information
about other devices known to the sending device.
.sp
In the \fBDevice\fP structure, field \fBDeviceID\fP is the SHA\-256 (32
bytes) of the device X.509 certificate, as explained in section \fIDevice
ID\fP\&.
.sp
For each \fBAddress\fP and \fBRelay\fP the \fBURL\fP field contains the actual
target address. Direct connections (the \fBAddress\fP list) will
typically have the \fBtcp://\fP scheme. Relay connections will typically use the
\fBrelay://\fP scheme.
.sp
The \fBLatency\fP field contains the approximate latency for a TCP handshake
(i.e. three packet round trips) between the other device and the relay, in
milliseconds.
.SH AUTHOR
The Syncthing Authors
.SH COPYRIGHT
2015, The Syncthing Authors
.\" Generated by docutils manpage writer.
.