felixfoertsch/syncthing
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 10 Wiki Activity

Add BEP & discovery protocols

Browse Source
This commit is contained in:
Jakob Borg
2015-09-22 23:30:39 +02:00
parent afce1b8cd3
commit ebb98a13e2
4 changed files with 1080 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files
specs/localdisco-v3.rst
+145
View File
@@ -0,0 +1,145 @@
Local Discovery Protocol v3
===========================
Mode of Operation
-----------------
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.
On multihomed hosts the announcement packets should be sent on each interface
on which Syncthing will accept connections.
For IPv4, the Announcement packet is broadcasted either to the link-specific
broadcast address, or to the generic link-local broadcast address
``255.255.255.255``, with destination port 21027.
For IPv6, the Announcement packet is multicasted to the transient link-local
multicast address ``[ff12::8384]``, with destination port 21027.
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.
Device ID
---------
The device ID is the SHA-256 (32 bytes) of the device X.509 certificate. See
:ref:`device-ids` in the Syncthing documentation.
Announcement packet
-------------------
The Announcement packet has the following structure::
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 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
/ /
\ Device Structure \
/ /
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Number of Extra |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
/ /
\ Zero or more Device Structures \
/ /
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
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 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
/ /
\ ID (variable length) \
/ /
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Number of Addresses |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
/ /
\ Zero or more Address Structures \
/ /
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Number of Relays |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
/ /
\ Zero or more Relay Structures \
/ /
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
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 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
/ /
\ URL (variable length) \
/ /
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
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 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
/ /
\ URL (variable length) \
/ /
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Latency |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
The corresponding XDR representation is as follows (see
`RFC4506 <http://tools.ietf.org/html/rfc4506>`__ for the XDR format):
::
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;
}
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.
In the ``Device`` structure, field ``DeviceID`` is the SHA-256 (32
bytes) of the device X.509 certificate, as explained in section *Device
ID*.
For each ``Address`` and ``Relay`` the ``URL`` field contains the actual
target address. For direction connections (the ``Address`` list) these will
typically have the ``tcp://`` scheme. Relay connections will typically use the
``relay://`` scheme.
The ``Latency`` field contains the approximate latency for a TCP handshake
(i.e. three packet round trips) between the other device and the relay, in
milliseconds.