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

gui, man: Update docs & translations

Browse Source 
GitHub-Pull-Request: https://github.com/syncthing/syncthing/pull/3034
This commit is contained in:
Jakob Borg
2016-05-04 19:47:08 +00:00
parent 674fc566bb
commit 459930df09
48 changed files with 596 additions and 214 deletions
Download Patch File Download Diff File Expand all files Collapse all files

361
man/syncthing-bep.7
View File

@@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH "SYNCTHING-BEP" "7" "April 14, 2016" "v0.12" "Syncthing"
.TH "SYNCTHING-BEP" "7" "May 01, 2016" "v0.12" "Syncthing"
.SH NAME
syncthing-bep \- Block Exchange Protocol v1
.
@@ -90,8 +90,91 @@ 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
The underlying transport protocol MUST guarantee reliable packet delivery.
.SH PRE-AUTHENTICATION MESSAGES
.sp
AFTER establishing a connection, but BEFORE performing any authentication,
\fIdevices\fP MUST exchange Hello messages.
.sp
Hello messages are used to carry additional information about the peer, which
might be of interest to the user even if the peer is not permitted to
communicate due to failing authentication.
.sp
Hello messages MUST be prefixed with a magic number \fB0x9F79BC40\fP
represented in network byte order (BE), followed by 4 bytes representing the
size of the message in network byte order (BE), followed by the content of
the Hello message itself. The size of the contents of Hello message MUST be
less or equal to 1024 bytes.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
Prefix 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 |
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
| Length |
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
/ /
\e Content of HelloMessage \e
/ /
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
HelloMessage 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
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
/ /
\e Device Name (length + padded data) \e
/ /
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
/ /
\e Client Name (length + padded data) \e
/ /
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
/ /
\e Client Version (length + padded data) \e
/ /
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Fields (HelloMessage)
.sp
The \fBDevice Name\fP is a human readable (configured or auto detected) device
name or host name, for the remote 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.
.SS XDR
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
struct HelloMessage {
string DeviceName<64>;
string ClientName<64>;
string ClientVersion<64>;
};
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Immediately after exchanging Hello messages, the connection should be
dropped if device does not pass authentication.
.SH POST-AUTHENTICATION 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
@@ -199,24 +282,6 @@ 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 |
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
/ /
@@ -329,16 +394,6 @@ Option Structure:
.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
@@ -372,7 +427,7 @@ folder Flags field contains the following single bit flags:
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|
| Reserved |T|D|P|R|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
.ft P
.fi
@@ -390,6 +445,15 @@ permissions for.
.TP
.B Bit 29 ("D", Ignore Deletes)
is set for folders that the device will ignore deletes for.
.TP
.B Bit 28 ("T", Disable Temporary Indexes)
is set for folders that will not dispatch and do not wish to receive
progress updates about partially downloaded files via DownloadProgress
.INDENT 7.0
.INDENT 3.5
messages.
.UNINDENT
.UNINDENT
.UNINDENT
.sp
The \fBOptions\fP field contains a list of options that apply to the folder.
@@ -464,7 +528,7 @@ cluster introducers.
.B Bits 16 through 28
are reserved and MUST be set to zero.
.TP
.B Bits 14\-15 ("Pri)
.B Bits 14\-15 ("Pri", Priority)
indicate the device\(aqs upload priority for this
folder. Possible values are:
.INDENT 7.0
@@ -499,9 +563,6 @@ The \fBOptions\fP field contains a list of options that apply to the device.
.nf
.ft C
struct ClusterConfigMessage {
string DeviceName<64>;
string ClientName<64>;
string ClientVersion<64>;
Folder Folders<1000000>;
Option Options<64>;
};
@@ -852,8 +913,35 @@ 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
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 |T|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B Bit 31 ("T", Temporary)
is set to indicate that the read should be performed
from the temporary file (converting Name to it\(aqs temporary form) and falling
back to the non temporary file if any error occurs. Knowledge of content
.INDENT 7.0
.INDENT 3.5
inside temporary files comes from DownloadProgress messages.
.UNINDENT
.UNINDENT
.UNINDENT
.sp
The Options list is implementation defined and as described in the
ClusterConfig message section.
.SS XDR
.INDENT 0.0
@@ -939,6 +1027,159 @@ struct ResponseMessage {
.fi
.UNINDENT
.UNINDENT
.SS DownloadProgress (Type = 8)
.sp
The DownloadProgress message is used to notify remote devices about partial
availability of files. By default, these messages are sent every 5 seconds,
and only in the cases where progress or state changes have been detected.
Each DownloadProgress message is addressed to a specific folder and MUST
contain zero or more FileDownloadProgressUpdate structures.
.SS Graphical Representation
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
DownloadProgressMessage 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
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
/ /
\e Folder (length + padded data) \e
/ /
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
| Number of Updates |
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
/ /
\e Zero or more FileDownloadProgressUpdate Structures \e
/ /
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
| Flags |
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
| Number of Options |
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
/ /
\e Zero or more Option Structures \e
/ /
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
FileDownloadProgressUpdate 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
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
| Update Type |
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
/ /
\e Name (length + padded data) \e
/ /
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
/ /
\e Version Structure \e
/ /
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
| Number of Block Indexes |
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
/ /
| Block Indexes (n items) |
/ /
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Each
.SS Fields (DownloadProgress Message)
.sp
\fBFolder\fP represents the ID of the folder for which the update is being
provided.
.sp
The \fBFlags\fP field is reserved for future use and MUST currently be set to
zero. The \fBOptions\fP field contains a list of options that apply to the update.
.SS Fields (FileDownloadProgressUpdate Structure)
.sp
The \fBUpdate Type\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 |F|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B Bit 31 ("F", Forget)
is set to notify that the file that was previously
advertised is no longer available (at least as a temporary file).
.UNINDENT
.sp
The \fBName\fP field defines the file name from the global index for which this
update is being sent.
.sp
The \fBVersion\fP structure defines the version of the file for which this update
is being sent.
.sp
\fBBlock Indexes\fP is a list of positive integers, where each integer represents
the index of the block in the FileInfo structure Blocks array that has become
available for download.
For example an integer with with value 3 represents that the data defined in the
fourth BlockInfo structure of the FileInfo structure of that file is now available.
Please note that matching should be done on \fBName\fP AND \fBVersion\fP\&.
Furthermore, each update received is incremental, for example the initial update
structure might contain indexes 0, 1, 2, an update 5 seconds later might contain
indexes 3, 4, 5 which should be appended to the original list, which implies
that blocks 0\-5 are currently available.
.sp
Block indexes MAY be added in any order.
An implementation MUST NOT assume that block indexes are added in any specific
order.
.sp
\fBForget\fP bit being set implies that the file that was previously advertised
is no longer available, therefore the list of block indexes should be truncated.
.sp
Messages with \fBForget\fP bit set MUST NOT have any block indexes.
.sp
Any update message which is being sent for a different \fBVersion\fP of the same
file name must be preceeded with an update message for the old version of that
file with the \fBForget\fP bit set.
.sp
As a safeguard on the receiving side, value of \fBVersion\fP changing between
update messages implies that the file has changed, and that any indexes
previously advertised are no longer available. The list of available block
indexes MUST be replaced (rather than appended) with the indexes specified in
this message.
.SS XDR
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
struct DownloadProgressMessage {
string Folder<64>;
FileDownloadProgressUpdate Updates<1000000>;
unsigned int Flags;
Option Options<64>;
}
struct FileDownloadProgressUpdate {
unsigned int UpdateType;
string Name<8192>;
Vector Version;
int BlockIndexes<1000000>;
}
.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
@@ -1224,6 +1465,50 @@ T} T{
1024 bytes
T}
_
T{
\fBDownload Progress Messages\fP
T}
_
T{
.nf
.fi
T} T{
Folder
T} T{
64 bytes
T}
_
T{
.nf
.fi
T} T{
Number of Updates
T} T{
1.000.000
T}
_
T{
.nf
.fi
T} T{
Name
T} T{
8192 bytes
T}
_
T{
.nf
.fi
T} T{
Number of Indexes
T} T{
1.000.000
T}
_
.TE
.sp
The currently defined values allow maximum file size of 1220 GiB