perso/syncthing-arm
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

gui, man: Update docs & translations

Browse Source
This commit is contained in:
Jakob Borg
2016-07-26 10:53:00 +02:00
parent 7aaa1dd8a3
commit 25a7b0a6f8
19 changed files with 208 additions and 147 deletions
Download Patch File Download Diff File Expand all files Collapse all files

68
man/syncthing-bep.7
View File

@@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH "SYNCTHING-BEP" "7" "July 17, 2016" "v0.14" "Syncthing"
.TH "SYNCTHING-BEP" "7" "July 24, 2016" "v0.14" "Syncthing"
.SH NAME
syncthing-bep \- Block Exchange Protocol v1
.
@@ -297,6 +297,7 @@ message Device {
string cert_name = 5;
int64 max_local_version = 6;
bool introducer = 7;
uint64 index_id = 8;
}
enum Compression {
@@ -364,16 +365,15 @@ Compress always. Metadata messages as well as Response messages are compressed.
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.
The \fBmax local version\fP field contains the highest local file version
number of the files in the index. See \fI\%Delta Index Exchange\fP for the usage of this
field.
.sp
The \fBintroducer\fP field is set for devices that are trusted as cluster
introducers.
.sp
The \fBindex id\fP field contains the unique identifier for the current set of
index data. See \fI\%Delta Index Exchange\fP for the usage of this field.
.SS Index and Index Update
.sp
The Index and Index Update messages define the contents of the senders
@@ -757,6 +757,56 @@ of other cluster devices.
.fi
.UNINDENT
.UNINDENT
.SH DELTA INDEX EXCHANGE
.sp
Index data must be exchanged whenever two devices connect so that one knows
the files available on the other. In the most basic case this happens by way
of sending an \fBIndex\fP message followed by one or more \fBIndex Update\fP
messages. Any previous index data known for a remote device is removed and
replaced with the new index data received in an \fBIndex\fP message, while the
contents of an \fBIndex Update\fP message is simply added to the existing
index data.
.sp
For situations with large indexes or frequent reconnects this can be quite
inefficient. A mechanism can then be used to retain index data between
connections and only transmit any changes since that data on connection
start. This is called "delta indexes". To enable this mechanism the \fBlocal
version\fP and \fBindex ID\fP fields are used.
.INDENT 0.0
.TP
.B Local Version:
Each index item (i.e., file, directory or symlink) has a local version
field. It contains the value of a counter at the time the index item was
updated. The counter increments by one for each change. That is, as files
are scanned and added to the index they get assigned local version numbers
1, 2, 3 and so on. The next file to be changed or detected gets local
version number 4, and future updates continue in the same fashion.
.TP
.B Index ID:
Each folder has an Index ID. This is a 64 bit random identifier set at
index creation time.
.UNINDENT
.sp
Given the above, we know that the tuple {index ID, maximum local version}
uniquely identifies a point in time of a given index. Any further changes
will increase the local version of some item, and thus the maximum local
version for the index itself. Should the index be reset or removed (i.e.,
the local version number reset to zero), a new index ID must be generated.
.sp
By letting a device know the {index ID, maximum local version} we have for
their index data, that device can arrange to only transmit \fBIndex Update\fP
messages for items with a higher local version number. This is the delta
index mechanism.
.sp
The index ID and maximum local version known for each device is transmitted
in the \fBCluster Config\fP message at connection start.
.sp
For this mechanism to be reliable it is essential that outgoing index
information is ordered by increasing local version number. Devices
announcing a non\-zero index ID in the \fBCluster Config\fP message MUST send
all index data ordered by increasing local version number. Devices not
intending to participate in delta index exchange MUST send a zero index ID
or, equivalently, not send the \fBindex_id\fP attribute at all.
.SH MESSAGE LIMITS
.sp
An implementation MAY impose reasonable limits on the length of messages and
@@ -768,7 +818,7 @@ Update messages rather than sending a very large Index message.
.sp
The Syncthing implementation imposes a hard limit of 500,000,000 bytes on
all messages. Attempting to send or receive a larger message will result in
a connection close. This size was chosen to accomodate Index messages
a connection close. This size was chosen to accommodate Index messages
containing a large block list. It\(aqs intended that the limit may be further
reduced in a future protocol update supporting variable block sizes (and
thus shorter block lists for large files).