|
|
@@ -1,6 +1,6 @@
|
|
|
.\" Man page generated from reStructuredText.
|
|
|
.
|
|
|
-.TH "SYNCTHING-BEP" "7" "Apr 18, 2018" "v0.14" "Syncthing"
|
|
|
+.TH "SYNCTHING-BEP" "7" "May 05, 2018" "v0.14" "Syncthing"
|
|
|
.SH NAME
|
|
|
syncthing-bep \- Block Exchange Protocol v1
|
|
|
.
|
|
|
@@ -41,8 +41,10 @@ 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.
|
|
|
+File data is described and transferred in units of \fIblocks\fP, each being from
|
|
|
+128 KiB (131072 bytes) to 16 MiB in size, in steps of powers of two. The
|
|
|
+block size may vary between files but is constant in any given file, except
|
|
|
+for the last block which may be smaller.
|
|
|
.sp
|
|
|
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”,
|
|
|
“SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this
|
|
|
@@ -421,7 +423,8 @@ message FileInfo {
|
|
|
bool invalid = 7;
|
|
|
bool no_permissions = 8;
|
|
|
Vector version = 9;
|
|
|
- int64 sequence = 10;
|
|
|
+ int64 sequence = 10;
|
|
|
+ int32 block_size = 13;
|
|
|
|
|
|
repeated BlockInfo Blocks = 16;
|
|
|
string symlink_target = 17;
|
|
|
@@ -513,10 +516,16 @@ The \fBsequence\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, thus forming a sequence number over database updates.
|
|
|
.sp
|
|
|
+The \fBblock_size\fP field is the size, in bytes, of each individual block in
|
|
|
+the block list (except, possibly, the last block). If this field is missing
|
|
|
+or zero, the block size is assumed to be 128 KiB (131072 bytes). Valid
|
|
|
+values of this field are the powers of two from 128 KiB through 16 MiB. See
|
|
|
+also \fI\%Selection of Block Size\fP\&.
|
|
|
+.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. The block list is empty for
|
|
|
-directories and symlinks.
|
|
|
+Each block represents a \fBblock_size\fP\-sized slice of the file, except for
|
|
|
+the last block which may represent a smaller amount of data. The block list
|
|
|
+is empty for directories and symlinks.
|
|
|
.sp
|
|
|
The \fBsymlink_target\fP field contains the symlink target, for entries of
|
|
|
symlink type. It is empty for all other entry types.
|
|
|
@@ -839,6 +848,83 @@ a connection close. This size was chosen to accommodate Index messages
|
|
|
containing a large block list. It’s 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).
|
|
|
+.SH SELECTION OF BLOCK SIZE
|
|
|
+.sp
|
|
|
+The desired block size for any given file is the smallest block size that
|
|
|
+results in fewer than 2000 blocks, or the maximum block size for larger
|
|
|
+files. This rule results in the following table of block sizes per file
|
|
|
+size:
|
|
|
+.TS
|
|
|
+center;
|
|
|
+|l|l|.
|
|
|
+_
|
|
|
+T{
|
|
|
+File Size
|
|
|
+T} T{
|
|
|
+Block Size
|
|
|
+T}
|
|
|
+_
|
|
|
+T{
|
|
|
+0 \- 250 MiB
|
|
|
+T} T{
|
|
|
+128 KiB
|
|
|
+T}
|
|
|
+_
|
|
|
+T{
|
|
|
+250 MiB \- 500 MiB
|
|
|
+T} T{
|
|
|
+256 KiB
|
|
|
+T}
|
|
|
+_
|
|
|
+T{
|
|
|
+500 MiB \- 1 GiB
|
|
|
+T} T{
|
|
|
+512 KiB
|
|
|
+T}
|
|
|
+_
|
|
|
+T{
|
|
|
+1 GiB \- 2 GiB
|
|
|
+T} T{
|
|
|
+1 MiB
|
|
|
+T}
|
|
|
+_
|
|
|
+T{
|
|
|
+2 GiB \- 4 GiB
|
|
|
+T} T{
|
|
|
+2 MiB
|
|
|
+T}
|
|
|
+_
|
|
|
+T{
|
|
|
+4 GiB \- 8 GiB
|
|
|
+T} T{
|
|
|
+4 MiB
|
|
|
+T}
|
|
|
+_
|
|
|
+T{
|
|
|
+8 GiB \- 16 GiB
|
|
|
+T} T{
|
|
|
+8 MiB
|
|
|
+T}
|
|
|
+_
|
|
|
+T{
|
|
|
+16 GiB \- up
|
|
|
+T} T{
|
|
|
+16 MiB
|
|
|
+T}
|
|
|
+_
|
|
|
+.TE
|
|
|
+.sp
|
|
|
+An implementation MAY deviate from the block size rule when there is good
|
|
|
+reason to do so. For example, if a file has been indexed at a certain block
|
|
|
+size and grows beyond 2000 blocks it may be retained at the current block
|
|
|
+size for practical reasons. When there is no overriding reason to the
|
|
|
+contrary, such as when indexing a new file for the first time, the block
|
|
|
+size rule above SHOULD be followed.
|
|
|
+.sp
|
|
|
+An implementation MUST therefore accept files with a block size differing
|
|
|
+from the above rule. This does not mean that arbitrary block sizes are
|
|
|
+allowed. The block size used MUST be exactly one of the power\-of\-two block
|
|
|
+sizes listed in the table above.
|
|
|
.SH EXAMPLE EXCHANGE
|
|
|
.TS
|
|
|
center;
|