139 lines
6.2 KiB
Markdown
139 lines
6.2 KiB
Markdown
Device Discovery Protocol v2
|
|
==========================
|
|
|
|
Mode of Operation
|
|
-----------------
|
|
|
|
There are two distinct modes: "local discovery", performed on a LAN
|
|
segment (broadcast domain) and "global discovery" performed over the
|
|
Internet in general with the support of a well known server.
|
|
|
|
Local discovery does not use Query packets. Instead Announcement packets
|
|
are sent periodically and each participating device keeps a table of the
|
|
announcements it has seen. On multihomed hosts the announcement packets
|
|
should be sent on each interface that syncthing will accept connections.
|
|
|
|
It is recommended that local discovery Announcement packets are sent on
|
|
a 30 to 60 second interval, possibly with forced transmissions when a
|
|
previously unknown device is discovered.
|
|
|
|
Global discovery is made possible by periodically updating a global server
|
|
using Announcement packets indentical to those transmitted for local
|
|
discovery. The device performing discovery will transmit a Query packet to
|
|
the global server and expect an Announcement packet in response. In case
|
|
the global server has no knowledge of the queried device ID, there will be
|
|
no response. A timeout is to be used to determine lookup failure.
|
|
|
|
There is no message to unregister from the global server; instead
|
|
registrations are forgotten after 60 minutes. It is recommended to
|
|
send Announcement packets to the global server on a 30 minute interval.
|
|
|
|
Packet Formats
|
|
--------------
|
|
|
|
The Announcement packet has the following 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 (0x9D79BC39) |
|
|
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
|
/ /
|
|
\ Device Structure \
|
|
/ /
|
|
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
|
| Number of Extra Devices |
|
|
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
|
/ /
|
|
\ 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 \
|
|
/ /
|
|
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
|
|
|
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 IP |
|
|
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
|
/ /
|
|
\ IP (variable length) \
|
|
/ /
|
|
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
|
| Port | 0x0000 |
|
|
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
|
|
|
This is the XDR encoding of:
|
|
|
|
struct Announcement {
|
|
unsigned int Magic;
|
|
Device This;
|
|
Device Extra<>;
|
|
}
|
|
|
|
struct Device {
|
|
string ID<>;
|
|
Address Addresses<>;
|
|
}
|
|
|
|
struct Address {
|
|
opaque IP<>;
|
|
unsigned short Port;
|
|
}
|
|
|
|
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 Address structure, the IP field can be of three differnt kinds;
|
|
|
|
- A zero length indicates that the IP address should be taken from the
|
|
source address of the announcement packet, be it IPv4 or IPv6. The
|
|
source address must be a valid unicast address. This is only valid
|
|
in the first device structure, not in the list of extras.
|
|
|
|
- A four byte length indicates that the address is an IPv4 unicast
|
|
address.
|
|
|
|
- A sixteen byte length indicates that the address is an IPv6 unicast
|
|
address.
|
|
|
|
The Query packet has the following 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 Number (0x2CA856F5) |
|
|
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
|
| Length of Device ID |
|
|
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
|
/ /
|
|
\ Device ID (variable length) \
|
|
/ /
|
|
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
|
|
|
This is the XDR encoding of:
|
|
|
|
struct Announcement {
|
|
unsigned int MagicNumber;
|
|
string DeviceID<>;
|
|
}
|