specs: Update specs for protocol buffer formats
GitHub-Pull-Request: https://github.com/syncthing/docs/pull/190
This commit is contained in:
Jakob Borg
committed by
Audrius Butkevicius
Audrius Butkevicius
parent
3b76ff6329
commit
a9b3fef697
+431
-901
File diff suppressed because it is too large
Load Diff
@@ -1,120 +0,0 @@
|
||||
.. _localdisco-v3:
|
||||
|
||||
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 broadcast 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 multicast 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 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 URL |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
/ /
|
||||
\ URL (variable length) \
|
||||
/ /
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
|
||||
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>;
|
||||
}
|
||||
|
||||
struct Address {
|
||||
string URL<2083>;
|
||||
}
|
||||
|
||||
|
||||
In the ``Announce`` structure field ``Magic`` is used to ensure
|
||||
a correct datagram was received and MUST be equal to ``0x7D79BC40``.
|
||||
|
||||
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`` the ``URL`` field contains the actual target address.
|
||||
Direct connections will typically have the ``tcp://`` scheme. Relay connections
|
||||
will typically use the ``relay://`` scheme.
|
||||
@@ -0,0 +1,77 @@
|
||||
.. _localdisco-v3:
|
||||
|
||||
Local Discovery Protocol v4
|
||||
===========================
|
||||
|
||||
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.
|
||||
|
||||
The announcement packet is sent over UDP.
|
||||
|
||||
For IPv4, the Announcement packet is broadcast 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 multicast 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:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
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 |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
/ /
|
||||
\ Announce Message \
|
||||
/ /
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
|
||||
There is no explicit length field as the length is given by the length of
|
||||
the discovery announcement packet itself.
|
||||
|
||||
The Magic field is a 32 bit word representing 0x2EA7D90B in network (big
|
||||
endian) byte order. It identifies the packet as being a Syncthing discovery
|
||||
protocol packet.
|
||||
|
||||
The Announce Message contents are in protocol buffer format using the
|
||||
following schema:
|
||||
|
||||
.. code-block:: proto
|
||||
|
||||
message Announce {
|
||||
bytes id = 1;
|
||||
repeated string addresses = 2;
|
||||
}
|
||||
|
||||
The ``id`` field contains the Device ID of the sending device.
|
||||
|
||||
The ``addresses`` field contains a list of addresses where the device can be
|
||||
contacted. Direct connections will typically have the ``tcp://`` scheme.
|
||||
Relay connections will typically use the ``relay://`` scheme.
|
||||
|
||||
When interpreting addresses with an unspecified address, e.g.,
|
||||
``tcp://0.0.0.0:22000`` or ``tcp://:42424``, the source address of the
|
||||
discovery announcement is to be used.
|
||||
Reference in New Issue
Block a user