1440 lines
46 KiB
Groff
1440 lines
46 KiB
Groff
.\" Man page generated from reStructuredText.
|
|
.
|
|
.TH "SYNCTHING-BEP" "7" "October 20, 2015" "v0.11" "Syncthing"
|
|
.SH NAME
|
|
syncthing-bep \- Block Exchange Protocol v1
|
|
.
|
|
.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 INTRODUCTION AND DEFINITIONS
|
|
.sp
|
|
BEP is used between two or more \fIdevices\fP thus forming a \fIcluster\fP\&. Each
|
|
device has one or more \fIfolders\fP of files described by the \fIlocal
|
|
model\fP, containing metadata and block hashes. The local model is sent to
|
|
the other devices in the cluster. The union of all files in the local
|
|
models, with files selected for highest change version, forms the
|
|
\fIglobal model\fP\&. Each device strives to get its folders in sync with the
|
|
global model by requesting missing or outdated blocks from the other
|
|
devices in the cluster.
|
|
.sp
|
|
File data is described and transferred in units of \fIblocks\fP, each being
|
|
128 KiB (131072 bytes) in size.
|
|
.sp
|
|
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
|
|
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
|
|
document are to be interpreted as described in RFC 2119.
|
|
.SH TRANSPORT AND AUTHENTICATION
|
|
.sp
|
|
BEP is deployed as the highest level in a protocol stack, with the lower
|
|
level protocols providing encryption and authentication.
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-|
|
|
| Block Exchange Protocol |
|
|
|\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-|
|
|
| Encryption & Auth (TLS 1.2) |
|
|
|\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-|
|
|
| TCP |
|
|
|\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-|
|
|
v ... v
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
The encryption and authentication layer SHALL use TLS 1.2 or a higher
|
|
revision. A strong cipher suite SHALL be used, with "strong cipher
|
|
suite" being defined as being without known weaknesses and providing
|
|
Perfect Forward Secrecy (PFS). Examples of strong cipher suites are
|
|
given at the end of this document. This is not to be taken as an
|
|
exhaustive list of allowed cipher suites but represents best practices
|
|
at the time of writing.
|
|
.sp
|
|
The exact nature of the authentication is up to the application, however
|
|
it SHALL be based on the TLS certificate presented at the start of the
|
|
connection. Possibilities include certificates signed by a common
|
|
trusted CA, preshared certificates, preshared certificate fingerprints
|
|
or certificate pinning combined with some out of band first
|
|
verification. The reference implementation uses preshared certificate
|
|
fingerprints (SHA\-256) referred to as "Device IDs".
|
|
.sp
|
|
There is no required order or synchronization among BEP messages except
|
|
as noted per message type \- any message type may be sent at any time and
|
|
the sender need not await a response to one message before sending
|
|
another.
|
|
.sp
|
|
The underlying transport protocol MUST be TCP.
|
|
.SH MESSAGES
|
|
.sp
|
|
Every message starts with one 32 bit word indicating the message version, type
|
|
and ID, followed by the length of the message. The header is in network byte
|
|
order, i.e. big endian. In this document, in diagrams and text, "bit 0" refers
|
|
to the \fImost significant\fP bit of a word; "bit 31" is thus the least
|
|
significant bit of a 32 bit word.
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
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
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
| Ver | Message ID | Type | Reserved |C|
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
| Length |
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
For BEP v1 the \fBVersion\fP field is set to zero. Future versions with
|
|
incompatible message formats will increment the Version field. A message
|
|
with an unknown version is a protocol error and MUST result in the
|
|
connection being terminated. A client supporting multiple versions MAY
|
|
retry with a different protocol version upon disconnection.
|
|
.sp
|
|
The \fBMessage ID\fP is set to a unique value for each transmitted Request
|
|
message. In Response messages it is set to the Message ID of the corresponding
|
|
Request message. The uniqueness requirement implies that no more than 4096
|
|
request messages may be outstanding at any given moment. For message types
|
|
that do not have a corresponding response (Cluster Configuration, Index, etc.)
|
|
the Message ID field is irrelevant and SHOULD be set to zero.
|
|
.sp
|
|
The \fBType\fP field indicates the type of data following the message header
|
|
and is one of the integers defined below. A message of an unknown type
|
|
is a protocol error and MUST result in the connection being terminated.
|
|
.sp
|
|
The \fBCompression\fP bit "C" indicates the compression used for the message.
|
|
.sp
|
|
For C=0:
|
|
.INDENT 0.0
|
|
.IP \(bu 2
|
|
The Length field contains the length, in bytes, of the uncompressed
|
|
message data.
|
|
.IP \(bu 2
|
|
The message is not compressed.
|
|
.UNINDENT
|
|
.sp
|
|
For C=1:
|
|
.INDENT 0.0
|
|
.IP \(bu 2
|
|
The Length field contains the length, in bytes, of the compressed
|
|
message data plus a four byte uncompressed length field.
|
|
.IP \(bu 2
|
|
The compressed message data is preceeded by a 32 bit field denoting
|
|
the length of the uncompressed message.
|
|
.IP \(bu 2
|
|
The message data is compressed using the LZ4 format and algorithm
|
|
described in \fI\%http://www.lz4.org/\fP\&.
|
|
.UNINDENT
|
|
.sp
|
|
All data within the message (post decompression, if compression is in
|
|
use) MUST be in XDR (RFC 1014) encoding. All fields shorter than 32 bits
|
|
and all variable length data MUST be padded to a multiple of 32 bits.
|
|
The actual data types in use by BEP, in XDR naming convention, are the
|
|
following:
|
|
.INDENT 0.0
|
|
.TP
|
|
.B (unsigned) int:
|
|
(unsigned) 32 bit integer
|
|
.TP
|
|
.B (unsigned) hyper:
|
|
(unsigned) 64 bit integer
|
|
.TP
|
|
.B opaque<>
|
|
variable length opaque data
|
|
.TP
|
|
.B string<>
|
|
variable length string
|
|
.UNINDENT
|
|
.sp
|
|
The transmitted length of string and opaque data is the length of actual
|
|
data, excluding any added padding. The encoding of opaque<> and string<>
|
|
are identical, the distinction being solely one of interpretation.
|
|
Opaque data should not be interpreted but can be compared bytewise to
|
|
other opaque data. All strings MUST use the Unicode UTF\-8 encoding,
|
|
normalization form C.
|
|
.SS Cluster Config (Type = 0)
|
|
.sp
|
|
This informational message provides information about the cluster
|
|
configuration as it pertains to the current connection. A Cluster Config
|
|
message MUST be the first message sent on a BEP connection. Additional
|
|
Cluster Config messages MUST NOT be sent after the initial exchange.
|
|
.SS Graphical Representation
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
ClusterConfigMessage 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 Device Name |
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
/ /
|
|
\e Device Name (variable length) \e
|
|
/ /
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
| Length of Client Name |
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
/ /
|
|
\e Client Name (variable length) \e
|
|
/ /
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
| Length of Client Version |
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
/ /
|
|
\e Client Version (variable length) \e
|
|
/ /
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
| Number of Folders |
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
/ /
|
|
\e Zero or more Folder Structures \e
|
|
/ /
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
| Number of Options |
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
/ /
|
|
\e Zero or more Option Structures \e
|
|
/ /
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
|
|
Folder 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 Devices |
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
/ /
|
|
\e Zero or more Device Structures \e
|
|
/ /
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
| Flags |
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
| Number of Options |
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
/ /
|
|
\e Zero or more Option 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
|
|
/ /
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
| Length of Name |
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
/ /
|
|
\e Name (variable length) \e
|
|
/ /
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
| Number of Addresses |
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
| Length of Address |
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
/ /
|
|
\e Address (variable length) \e
|
|
/ /
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
| Compression |
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
| Length of Cert Name |
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
/ /
|
|
\e Cert Name (variable length) \e
|
|
/ /
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
| |
|
|
+ Max Local Version (64 bits) +
|
|
| |
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
| Flags |
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
| Number of Options |
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
/ /
|
|
\e Zero or more Option Structures \e
|
|
/ /
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
|
|
Option 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 Key |
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
/ /
|
|
\e Key (variable length) \e
|
|
/ /
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
| Length of Value |
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
/ /
|
|
\e Value (variable length) \e
|
|
/ /
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SS Fields (ClusterConfigMessage)
|
|
.sp
|
|
The \fBDevice Name\fP is a human readable (configured or auto detected) device
|
|
name or host name, for the sending device.
|
|
.sp
|
|
The \fBClient Name\fP and \fBClient Version\fP identifies the implementation. The
|
|
values SHOULD be simple strings identifying the implementation name, as a
|
|
user would expect to see it, and the version string in the same manner. An
|
|
example Client Name is "syncthing" and an example Client Version is "v0.7.2".
|
|
The Client Version field SHOULD follow the patterns laid out in the \fI\%Semantic
|
|
Versioning\fP <\fBhttp://semver.org/\fP> standard.
|
|
.sp
|
|
The \fBFolders\fP field contains the list of folders that will be synchronized
|
|
over the current connection.
|
|
.sp
|
|
The \fBOptions\fP field is a list of options that apply to the current
|
|
connection. The options are used in an implementation specific manner. The
|
|
options list is conceptually a map of keys to values, although it is
|
|
transmitted in the form of a list of key and value pairs, both of string type.
|
|
Key ID:s are implementation specific. An implementation MUST ignore unknown
|
|
keys. An implementation MAY impose limits on the length keys and values. The
|
|
options list may be used to inform devices of relevant local configuration
|
|
options such as rate limiting or make recommendations about request
|
|
parallelism, device priorities, etc. An empty options list is valid for
|
|
devices not having any such information to share. Devices MAY NOT make any
|
|
assumptions about peers acting in a specific manner as a result of sent
|
|
options.
|
|
.SS Fields (Folder Structure)
|
|
.sp
|
|
The \fBID\fP field contains the folder ID, as a human readable string.
|
|
.sp
|
|
The \fBDevices\fP field is list of devices participating in sharing this folder.
|
|
.sp
|
|
The \fBFlags\fP field contains flags that affect the behavior of the folder. The
|
|
folder Flags field contains the following single bit flags:
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
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
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
| Reserved |D|P|R|
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B Bit 31 ("R", Read Only)
|
|
is set for folders that the device will accept no updates from the network
|
|
for.
|
|
.TP
|
|
.B Bit 30 ("P", Ignore Permissions)
|
|
is set for folders that the device will not accept or announce file
|
|
permissions for.
|
|
.TP
|
|
.B Bit 29 ("D", Ignore Deletes)
|
|
is set for folders that the device will ignore deletes for.
|
|
.UNINDENT
|
|
.sp
|
|
The \fBOptions\fP field contains a list of options that apply to the folder.
|
|
.SS Fields (Device Structure)
|
|
.sp
|
|
The device \fBID\fP field is a 32 byte number that uniquely identifies the
|
|
device. For instance, the reference implementation uses the SHA\-256 of the
|
|
device X.509 certificate.
|
|
.sp
|
|
The \fBName\fP field is a human readable name assigned to the described device
|
|
by the sending device. It MAY be empty and it need not be unique.
|
|
.sp
|
|
The list of \fBAddressess\fP is that used by the sending device to connect to
|
|
the described device.
|
|
.sp
|
|
The \fBCompression\fP field indicates the compression mode in use for this
|
|
device and folder. The following values are valid:
|
|
.INDENT 0.0
|
|
.TP
|
|
.B 0
|
|
Compress metadata. This enables compression of metadata messages such as Index.
|
|
.TP
|
|
.B 1
|
|
Compression disabled. No compression is used on any message.
|
|
.TP
|
|
.B 2
|
|
Compress always. Metadata messages as well as Response messages are compressed.
|
|
.UNINDENT
|
|
.sp
|
|
The \fBCert Name\fP field indicates the expected certificate name for this
|
|
device. It is commonly blank, indicating to use the implementation default.
|
|
.sp
|
|
The \fBMax Local Version\fP field contains the highest local file
|
|
version number of the files already known to be in the index sent by
|
|
this device. If nothing is known about the index of a given device, this
|
|
field MUST be set to zero. When receiving a Cluster Config message with
|
|
a non\-zero Max Local Version for the local device ID, a device MAY elect
|
|
to send an Index Update message containing only files with higher local
|
|
version numbers in place of the initial Index message.
|
|
.sp
|
|
The \fBFlags\fP field indicates the sharing mode of the folder and other device
|
|
& folder specific settings. See the discussion on Sharing Modes. The Device
|
|
Flags field contains the following single bit flags:
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
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
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
| Reserved |Pri| Reserved |I|R|T|
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B Bit 31 ("T", Trusted)
|
|
is set for devices that participate in trusted
|
|
mode.
|
|
.TP
|
|
.B Bit 30 ("R", Read Only)
|
|
is set for devices that participate in read
|
|
only mode.
|
|
.TP
|
|
.B Bit 29 ("I", Introducer)
|
|
is set for devices that are trusted as
|
|
cluster introducers.
|
|
.TP
|
|
.B Bits 16 through 28
|
|
are reserved and MUST be set to zero.
|
|
.TP
|
|
.B Bits 14\-15 ("Pri)
|
|
indicate the device\(aqs upload priority for this
|
|
folder. Possible values are:
|
|
.INDENT 7.0
|
|
.TP
|
|
.B 00
|
|
The default. Normal priority.
|
|
.TP
|
|
.B 01
|
|
High priority. Other devices SHOULD favour requesting files
|
|
from this device over devices with normal or low priority.
|
|
.TP
|
|
.B 10
|
|
Low priority. Other devices SHOULD avoid requesting files from
|
|
this device when they are available from other devices.
|
|
.TP
|
|
.B 11
|
|
Sharing disabled. Other devices SHOULD NOT request files from
|
|
this device.
|
|
.UNINDENT
|
|
.TP
|
|
.B Bits 0 through 14
|
|
are reserved and MUST be set to zero.
|
|
.UNINDENT
|
|
.sp
|
|
Exactly one of the T and R bits MUST be set.
|
|
.sp
|
|
The \fBOptions\fP field contains a list of options that apply to the device.
|
|
.SS XDR
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
struct ClusterConfigMessage {
|
|
string DeviceName<64>;
|
|
string ClientName<64>;
|
|
string ClientVersion<64>;
|
|
Folder Folders<1000000>;
|
|
Option Options<64>;
|
|
}
|
|
|
|
struct Folder {
|
|
string ID<256>;
|
|
Device Devices<1000000>;
|
|
unsigned int Flags;
|
|
Option Options<64>;
|
|
}
|
|
|
|
struct Device {
|
|
opaque ID<32>;
|
|
string Name<64>;
|
|
string Addresses<64>;
|
|
unsigned int Compression;
|
|
string CertName<64>;
|
|
hyper MaxLocalVersion;
|
|
unsigned int Flags;
|
|
Option Options<64>;
|
|
}
|
|
|
|
struct Option {
|
|
string Key<64>;
|
|
string Value<1024>;
|
|
}
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SS Index (Type = 1) and Index Update (Type = 6)
|
|
.sp
|
|
The Index and Index Update messages define the contents of the senders
|
|
folder. An Index message represents the full contents of the folder and
|
|
thus supersedes any previous index. An Index Update amends an existing
|
|
index with new information, not affecting any entries not included in
|
|
the message. An Index Update MAY NOT be sent unless preceded by an
|
|
Index, unless a non\-zero Max Local Version has been announced for the
|
|
given folder by the peer device.
|
|
.SS Graphical Representation
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
IndexMessage 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 Folder |
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
/ /
|
|
\e Folder (variable length) \e
|
|
/ /
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
| Number of Files |
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
/ /
|
|
\e Zero or more FileInfo Structures \e
|
|
/ /
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
| Flags |
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
| Number of Options |
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
/ /
|
|
\e Zero or more Option Structures \e
|
|
/ /
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
|
|
FileInfo 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 Name |
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
/ /
|
|
\e Name (variable length) \e
|
|
/ /
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
| Flags |
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
| |
|
|
+ Modified (64 bits) +
|
|
| |
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
/ /
|
|
\e Version (variable length) \e
|
|
/ /
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
| |
|
|
+ Local Version (64 bits) +
|
|
| |
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
| Number of Blocks |
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
/ /
|
|
\e Zero or more BlockInfo Structures \e
|
|
/ /
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
|
|
Vector 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
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
| Number of Counters |
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
/ /
|
|
\e Zero or more Counter Structures \e
|
|
/ /
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
|
|
Counter 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
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
| |
|
|
+ ID (64 bits) +
|
|
| |
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
| |
|
|
+ Value (64 bits) +
|
|
| |
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
|
|
|
|
BlockInfo 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
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
| Size |
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
| Length of Hash |
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
/ /
|
|
\e Hash (variable length) \e
|
|
/ /
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SS Fields (Index Message)
|
|
.sp
|
|
The \fBFolder\fP field identifies the folder that the index message pertains to.
|
|
.sp
|
|
\fBFiles\fP
|
|
.sp
|
|
The \fBFlags\fP field is reserved for future use and MUST currently be set to
|
|
zero.
|
|
.sp
|
|
The \fBOptions\fP list is implementation defined and as described in the
|
|
ClusterConfig message section.
|
|
.SS Fields (FileInfo Structure)
|
|
.sp
|
|
The \fBName\fP is the file name path relative to the folder root. Like all
|
|
strings in BEP, the Name is always in UTF\-8 NFC regardless of operating
|
|
system or file system specific conventions. The Name field uses the
|
|
slash character ("/") as path separator, regardless of the
|
|
implementation\(aqs operating system conventions. The combination of Folder
|
|
and Name uniquely identifies each file in a cluster.
|
|
.sp
|
|
The \fBFlags\fP field is made up of the following single bit flags:
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
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
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
| Reserved |U|S|P|I|D| Unix Perm. & Mode |
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B The lower 12 bits
|
|
hold the common Unix permission and mode bits. An
|
|
implementation MAY ignore or interpret these as is suitable on the
|
|
host operating system.
|
|
.TP
|
|
.B Bit 19 ("D")
|
|
is set when the file has been deleted. The block list
|
|
SHALL be of length zero and the modification time indicates the time
|
|
of deletion or, if the time of deletion is not reliably determinable,
|
|
the last known modification time.
|
|
.TP
|
|
.B Bit 18 ("I")
|
|
is set when the file is invalid and unavailable for
|
|
synchronization. A peer MAY set this bit to indicate that it can
|
|
temporarily not serve data for the file.
|
|
.TP
|
|
.B Bit 17 ("P")
|
|
is set when there is no permission information for the
|
|
file. This is the case when it originates on a file system which
|
|
does not support permissions. Changes to only permission bits SHOULD
|
|
be disregarded on files with this bit set. The permissions bits MUST
|
|
be set to the octal value 0666.
|
|
.TP
|
|
.B Bit 16 ("S")
|
|
is set when the file is a symbolic link. The block list
|
|
SHALL be of one or more blocks since the target of the symlink is
|
|
stored within the blocks of the file.
|
|
.TP
|
|
.B Bit 15 ("U")
|
|
is set when the symbolic links target does not exist. On
|
|
systems where symbolic links have types, this bit being means that
|
|
the default file symlink SHALL be used. If this bit is unset bit 19
|
|
will decide the type of symlink to be created.
|
|
.TP
|
|
.B Bit 0 through 14
|
|
are reserved for future use and SHALL be set to
|
|
zero.
|
|
.UNINDENT
|
|
.sp
|
|
The \fBModified\fP time is expressed as the number of seconds since the Unix
|
|
Epoch (1970\-01\-01 00:00:00 UTC).
|
|
.sp
|
|
The \fBVersion\fP field is a version vector describing the updates performed
|
|
to a file by all members in the cluster. Each counter in the version
|
|
vector is an ID\-Value tuple. The ID is used the first 64 bits of the
|
|
device ID. The Value is a simple incrementing counter, starting at zero.
|
|
The combination of Folder, Name and Version uniquely identifies the
|
|
contents of a file at a given point in time.
|
|
.sp
|
|
The \fBLocal Version\fP field is the value of a device local monotonic clock
|
|
at the time of last local database update to a file. The clock ticks on
|
|
every local database update.
|
|
.sp
|
|
The \fBBlocks\fP list contains the size and hash for each block in the file.
|
|
Each block represents a 128 KiB slice of the file, except for the last
|
|
block which may represent a smaller amount of data.
|
|
.sp
|
|
The hash algorithm is implied by the \fBHash\fP length. Currently, the hash
|
|
MUST be 32 bytes long and computed by SHA256.
|
|
.SS XDR
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
struct IndexMessage {
|
|
string Folder<256>;
|
|
FileInfo Files<1000000>;
|
|
unsigned int Flags;
|
|
Option Options<64>;
|
|
}
|
|
|
|
struct FileInfo {
|
|
string Name<8192>;
|
|
unsigned int Flags;
|
|
hyper Modified;
|
|
Vector Version;
|
|
hyper LocalVersion;
|
|
BlockInfo Blocks<1000000>;
|
|
}
|
|
|
|
struct Vector {
|
|
Counter Counters<>
|
|
}
|
|
|
|
struct Counter {
|
|
unsigned hyper ID
|
|
unsigned hyper Value
|
|
}
|
|
|
|
struct BlockInfo {
|
|
unsigned int Size;
|
|
opaque Hash<64>;
|
|
}
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SS Request (Type = 2)
|
|
.sp
|
|
The Request message expresses the desire to receive a data block
|
|
corresponding to a part of a certain file in the peer\(aqs folder.
|
|
.SS Graphical Representation
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
RequestMessage 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 Folder |
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
/ /
|
|
\e Folder (variable length) \e
|
|
/ /
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
| Length of Name |
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
/ /
|
|
\e Name (variable length) \e
|
|
/ /
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
| |
|
|
+ Offset (64 bits) +
|
|
| |
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
| Size |
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
| Length of Hash |
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
/ /
|
|
\e Hash (variable length) \e
|
|
/ /
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
| Flags |
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
| Number of Options |
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
/ /
|
|
\e Zero or more Option Structures \e
|
|
/ /
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SS Fields
|
|
.sp
|
|
The Folder and Name fields are as documented for the Index message. The
|
|
Offset and Size fields specify the region of the file to be transferred.
|
|
This SHOULD equate to exactly one block as seen in an Index message.
|
|
.sp
|
|
The Hash field MAY be set to the expected hash value of the block, or
|
|
may be left empty (zero length). If set, the other device SHOULD ensure
|
|
that the transmitted block matches the requested hash. The other device
|
|
MAY reuse a block from a different file and offset having the same size
|
|
and hash, if one exists.
|
|
.sp
|
|
The Flags field is reserved for future use and MUST currently be set to
|
|
zero. The Options list is implementation defined and as described in the
|
|
ClusterConfig message section.
|
|
.SS XDR
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
struct RequestMessage {
|
|
string Folder<64>;
|
|
string Name<8192>;
|
|
hyper Offset;
|
|
int Size;
|
|
opaque Hash<64>;
|
|
unsigned int Flags;
|
|
Option Options<64>;
|
|
}
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SS Response (Type = 3)
|
|
.sp
|
|
The Response message is sent in response to a Request message.
|
|
.SS Graphical Representation
|
|
.sp
|
|
ResponseMessage Structure:
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
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 Data |
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
/ /
|
|
\e Data (variable length) \e
|
|
/ /
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
| Code |
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SS Fields
|
|
.sp
|
|
The \fBData\fP field contains either a full 128 KiB block, a shorter block in
|
|
the case of the last block in a file, or is empty (zero length) if the
|
|
requested block is not available.
|
|
.sp
|
|
The \fBCode\fP field contains an error code describing the reason a Request
|
|
could not be fulfilled, in the case where a zero length Data was
|
|
returned. The following values are defined:
|
|
.INDENT 0.0
|
|
.TP
|
|
.B 0
|
|
No Error (Data should be present)
|
|
.TP
|
|
.B 1
|
|
Generic Error
|
|
.TP
|
|
.B 2
|
|
No Such File (the requested file does not exist, or the offset is
|
|
outside the acceptable range for the file)
|
|
.TP
|
|
.B 3
|
|
Invalid (file exists but has invalid bit set or is otherwise
|
|
unavailable)
|
|
.UNINDENT
|
|
.SS XDR
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
struct ResponseMessage {
|
|
opaque Data<>;
|
|
int Code;
|
|
}
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SS Ping (Type = 4)
|
|
.sp
|
|
The Ping message is used to determine that a connection is alive, and to keep
|
|
connections alive through state tracking network elements such as firewalls
|
|
and NAT gateways. The Ping message has no contents. A Ping message is sent
|
|
every 90 seconds, if no other message has been sent in the preceding 90
|
|
seconds.
|
|
.SS Close (Type = 7)
|
|
.sp
|
|
The Close message MAY be sent to indicate that the connection will be
|
|
torn down due to an error condition. A Close message MUST NOT be
|
|
followed by further messages.
|
|
.SS Graphical Representation
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
CloseMessage 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 Reason |
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
/ /
|
|
\e Reason (variable length) \e
|
|
/ /
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
| Code |
|
|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SS Fields
|
|
.sp
|
|
The \fBReason\fP field contains a human description of the error condition,
|
|
suitable for consumption by a human. The \fBCode\fP field is for a machine
|
|
readable error code. Codes are reserved for future use and MUST
|
|
currently be set to zero.
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
struct CloseMessage {
|
|
string Reason<1024>;
|
|
int Code;
|
|
}
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SH SHARING MODES
|
|
.SS Trusted
|
|
.sp
|
|
Trusted mode is the default sharing mode. Updates are exchanged in both
|
|
directions.
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
+\-\-\-\-\-\-\-\-\-\-\-\-+ Updates /\-\-\-\-\-\-\-\-\-\e
|
|
| | \-\-\-\-\-\-\-\-\-\-\-> / \e
|
|
| Device | | Cluster |
|
|
| | <\-\-\-\-\-\-\-\-\-\-\- \e /
|
|
+\-\-\-\-\-\-\-\-\-\-\-\-+ Updates \e\-\-\-\-\-\-\-\-\-/
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SS Read Only
|
|
.sp
|
|
In read only mode, a device does not synchronize the local folder to the
|
|
cluster, but publishes changes to its local folder contents as usual.
|
|
The local folder can be seen as a "master copy" that is never affected
|
|
by the actions of other cluster devices.
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
+\-\-\-\-\-\-\-\-\-\-\-\-+ Updates /\-\-\-\-\-\-\-\-\-\e
|
|
| | \-\-\-\-\-\-\-\-\-\-\-> / \e
|
|
| Device | | Cluster |
|
|
| | \e /
|
|
+\-\-\-\-\-\-\-\-\-\-\-\-+ \e\-\-\-\-\-\-\-\-\-/
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SH MESSAGE LIMITS
|
|
.sp
|
|
An implementation MAY impose reasonable limits on the length of messages
|
|
and message fields to aid robustness in the face of corruption or broken
|
|
implementations. These limits, if imposed, SHOULD NOT be more
|
|
restrictive than the following. An implementation should strive to keep
|
|
messages short and to the point, favouring more and smaller messages
|
|
over fewer and larger. For example, favour a smaller Index message
|
|
followed by one or more Index Update messages rather than sending a very
|
|
large Index message.
|
|
.TS
|
|
center;
|
|
|l|l|l|.
|
|
_
|
|
T{
|
|
Message Type
|
|
T} T{
|
|
Field
|
|
T} T{
|
|
Limit
|
|
T}
|
|
_
|
|
T{
|
|
\fBAll Messages\fP
|
|
T}
|
|
_
|
|
T{
|
|
.nf
|
|
|
|
.fi
|
|
T} T{
|
|
Total length
|
|
T} T{
|
|
64 MiB
|
|
T}
|
|
_
|
|
T{
|
|
\fBIndex and Index Update Messages\fP
|
|
T}
|
|
_
|
|
T{
|
|
.nf
|
|
|
|
.fi
|
|
T} T{
|
|
Folder
|
|
T} T{
|
|
64 bytes
|
|
T}
|
|
_
|
|
T{
|
|
.nf
|
|
|
|
.fi
|
|
T} T{
|
|
Number of Files
|
|
T} T{
|
|
1.000.000
|
|
T}
|
|
_
|
|
T{
|
|
.nf
|
|
|
|
.fi
|
|
T} T{
|
|
Name
|
|
T} T{
|
|
8192 bytes
|
|
T}
|
|
_
|
|
T{
|
|
.nf
|
|
|
|
.fi
|
|
T} T{
|
|
Number of Blocks
|
|
T} T{
|
|
1.000.000
|
|
T}
|
|
_
|
|
T{
|
|
.nf
|
|
|
|
.fi
|
|
T} T{
|
|
Hash
|
|
T} T{
|
|
64 bytes
|
|
T}
|
|
_
|
|
T{
|
|
.nf
|
|
|
|
.fi
|
|
T} T{
|
|
Number of Counters
|
|
T} T{
|
|
1.000.000
|
|
T}
|
|
_
|
|
T{
|
|
\fBRequest Messages\fP
|
|
T}
|
|
_
|
|
T{
|
|
.nf
|
|
|
|
.fi
|
|
T} T{
|
|
Folder
|
|
T} T{
|
|
64 bytes
|
|
T}
|
|
_
|
|
T{
|
|
.nf
|
|
|
|
.fi
|
|
T} T{
|
|
Name
|
|
T} T{
|
|
8192 bytes
|
|
T}
|
|
_
|
|
T{
|
|
\fBResponse Messages\fP
|
|
T}
|
|
_
|
|
T{
|
|
.nf
|
|
|
|
.fi
|
|
T} T{
|
|
Data
|
|
T} T{
|
|
256 KiB
|
|
T}
|
|
_
|
|
T{
|
|
\fBCluster Config Message\fP
|
|
T}
|
|
_
|
|
T{
|
|
.nf
|
|
|
|
.fi
|
|
T} T{
|
|
Number of Folders
|
|
T} T{
|
|
1.000.000
|
|
T}
|
|
_
|
|
T{
|
|
.nf
|
|
|
|
.fi
|
|
T} T{
|
|
Number of Devices
|
|
T} T{
|
|
1.000.000
|
|
T}
|
|
_
|
|
T{
|
|
.nf
|
|
|
|
.fi
|
|
T} T{
|
|
Number of Options
|
|
T} T{
|
|
64
|
|
T}
|
|
_
|
|
T{
|
|
.nf
|
|
|
|
.fi
|
|
T} T{
|
|
Key
|
|
T} T{
|
|
64 bytes
|
|
T}
|
|
_
|
|
T{
|
|
.nf
|
|
|
|
.fi
|
|
T} T{
|
|
Value
|
|
T} T{
|
|
1024 bytes
|
|
T}
|
|
_
|
|
.TE
|
|
.SH EXAMPLE EXCHANGE
|
|
.TS
|
|
center;
|
|
|l|l|l|.
|
|
_
|
|
T{
|
|
#
|
|
T} T{
|
|
A
|
|
T} T{
|
|
B
|
|
T}
|
|
_
|
|
T{
|
|
1
|
|
T} T{
|
|
ClusterConfiguration\->
|
|
T} T{
|
|
<\-ClusterConfiguration
|
|
T}
|
|
_
|
|
T{
|
|
2
|
|
T} T{
|
|
Index\->
|
|
T} T{
|
|
<\-Index
|
|
T}
|
|
_
|
|
T{
|
|
3
|
|
T} T{
|
|
IndexUpdate\->
|
|
T} T{
|
|
<\-IndexUpdate
|
|
T}
|
|
_
|
|
T{
|
|
4
|
|
T} T{
|
|
IndexUpdate\->
|
|
T} T{
|
|
T}
|
|
_
|
|
T{
|
|
5
|
|
T} T{
|
|
Request\->
|
|
T} T{
|
|
T}
|
|
_
|
|
T{
|
|
6
|
|
T} T{
|
|
Request\->
|
|
T} T{
|
|
T}
|
|
_
|
|
T{
|
|
7
|
|
T} T{
|
|
Request\->
|
|
T} T{
|
|
T}
|
|
_
|
|
T{
|
|
8
|
|
T} T{
|
|
Request\->
|
|
T} T{
|
|
T}
|
|
_
|
|
T{
|
|
9
|
|
T} T{
|
|
T} T{
|
|
<\-Response
|
|
T}
|
|
_
|
|
T{
|
|
10
|
|
T} T{
|
|
T} T{
|
|
<\-Response
|
|
T}
|
|
_
|
|
T{
|
|
11
|
|
T} T{
|
|
T} T{
|
|
<\-Response
|
|
T}
|
|
_
|
|
T{
|
|
12
|
|
T} T{
|
|
T} T{
|
|
<\-Response
|
|
T}
|
|
_
|
|
T{
|
|
13
|
|
T} T{
|
|
Index Update\->
|
|
T} T{
|
|
T}
|
|
_
|
|
T{
|
|
\&...
|
|
T} T{
|
|
T} T{
|
|
T}
|
|
_
|
|
T{
|
|
14
|
|
T} T{
|
|
T} T{
|
|
<\-Ping
|
|
T}
|
|
_
|
|
T{
|
|
15
|
|
T} T{
|
|
Ping\->
|
|
T} T{
|
|
T}
|
|
_
|
|
.TE
|
|
.sp
|
|
The connection is established and at 1. both peers send ClusterConfiguration
|
|
messages and then Index records. The Index records are received and both peers
|
|
recompute their knowledge of the data in the cluster. In this example, peer A
|
|
has four missing or outdated blocks. At 5 through 8 peer A sends requests for
|
|
these blocks. The requests are received by peer B, who retrieves the data from
|
|
the folder and transmits Response records (9 through 12). Device A updates
|
|
their folder contents and transmits an Index Update message (13). Both peers
|
|
enter idle state after 13. At some later time 14, the ping timer on device B
|
|
expires and a Ping message is sent. The same process occurs for device A at
|
|
15.
|
|
.SH EXAMPLES OF STRONG CIPHER SUITES
|
|
.TS
|
|
center;
|
|
|l|l|l|.
|
|
_
|
|
T{
|
|
ID
|
|
T} T{
|
|
Name
|
|
T} T{
|
|
Description
|
|
T}
|
|
_
|
|
T{
|
|
0x009F
|
|
T} T{
|
|
DHE\-RSA\-AES256\-GCM\-SHA384
|
|
T} T{
|
|
TLSv1.2 DH RSA AESGCM(256) AEAD
|
|
T}
|
|
_
|
|
T{
|
|
0x006B
|
|
T} T{
|
|
DHE\-RSA\-AES256\-SHA256
|
|
T} T{
|
|
TLSv1.2 DH RSA AES(256) SHA256
|
|
T}
|
|
_
|
|
T{
|
|
0xC030
|
|
T} T{
|
|
ECDHE\-RSA\-AES256\-GCM\-SHA384
|
|
T} T{
|
|
TLSv1.2 ECDH RSA AESGCM(256) AEAD
|
|
T}
|
|
_
|
|
T{
|
|
0xC028
|
|
T} T{
|
|
ECDHE\-RSA\-AES256\-SHA384
|
|
T} T{
|
|
TLSv1.2 ECDH RSA AES(256) SHA384
|
|
T}
|
|
_
|
|
T{
|
|
0x009E
|
|
T} T{
|
|
DHE\-RSA\-AES128\-GCM\-SHA256
|
|
T} T{
|
|
TLSv1.2 DH RSA AESGCM(128) AEAD
|
|
T}
|
|
_
|
|
T{
|
|
0x0067
|
|
T} T{
|
|
DHE\-RSA\-AES128\-SHA256
|
|
T} T{
|
|
TLSv1.2 DH RSA AES(128) SHA256
|
|
T}
|
|
_
|
|
T{
|
|
0xC02F
|
|
T} T{
|
|
ECDHE\-RSA\-AES128\-GCM\-SHA256
|
|
T} T{
|
|
TLSv1.2 ECDH RSA AESGCM(128) AEAD
|
|
T}
|
|
_
|
|
T{
|
|
0xC027
|
|
T} T{
|
|
ECDHE\-RSA\-AES128\-SHA256
|
|
T} T{
|
|
TLSv1.2 ECDH RSA AES(128) SHA256
|
|
T}
|
|
_
|
|
.TE
|
|
.SH AUTHOR
|
|
The Syncthing Authors
|
|
.SH COPYRIGHT
|
|
2015, The Syncthing Authors
|
|
.\" Generated by docutils manpage writer.
|
|
.
|