mirror of
https://github.com/syncthing/syncthing.git
synced 2024-11-16 02:18:44 -07:00
193 lines
7.7 KiB
Groff
193 lines
7.7 KiB
Groff
.\" Man page generated from reStructuredText.
|
|
.
|
|
.TH "SYNCTHING-LOCALDISCO" "7" "January 20, 2016" "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.
|
|
.
|