syncthing-bep - Man Page

The device_name is a human readable (configured or auto detected) device name or host name, for the remote device.

The client_name and client_version 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 Semantic Versioning <https://semver.org/> standard.

Immediately after exchanging Hello messages, the connection MUST be dropped if the remote device does not pass authentication.

This informational message provides information about the cluster configuration as it pertains to the current connection. A Cluster Config message MUST be the first post authentication message sent on a BEP connection. Additional Cluster Config messages MUST NOT be sent after the initial exchange.

message ClusterConfig {
    repeated Folder folders = 1;
}

message Folder {
    string id                   = 1;
    string label                = 2;
    bool   read_only            = 3;
    bool   ignore_permissions   = 4;
    bool   ignore_delete        = 5;
    bool   disable_temp_indexes = 6;
    bool   paused               = 7;

    repeated Device devices = 16;
}

message Device {
    bytes           id                         = 1;
    string          name                       = 2;
    repeated string addresses                  = 3;
    Compression     compression                = 4;
    string          cert_name                  = 5;
    int64           max_sequence               = 6;
    bool            introducer                 = 7;
    uint64          index_id                   = 8;
    bool            skip_introduction_removals = 9;
    bytes           encryption_password_token  = 10;
}

enum Compression {
    METADATA = 0;
    NEVER    = 1;
    ALWAYS   = 2;
}

The folders field contains the list of folders that will be synchronized over the current connection.

The id field contains the folder ID, which is the unique identifier of the folder.

The label field contains the folder label, the human readable name of the folder.

The read_only field is set for folders that the device will accept no updates from the network for.

The ignore_permissions field is set for folders that the device will not accept or announce file permissions for.

The ignore_delete field is set for folders that the device will ignore deletes for.

The disable_temp_indexes field is set for folders that will not dispatch and do not wish to receive progress updates about partially downloaded files via Download Progress messages.

The paused field is set for folders that are currently paused.

The devices field is a list of devices participating in sharing this folder.

The device id 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.

The name 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.

The list of addresses is that used by the sending device to connect to the described device.

The compression field indicates the compression mode in use for this device and folder. The following values are valid:

0

Compress metadata. This enables compression of metadata messages such as Index.

1

Compression disabled. No compression is used on any message.

2

Compress always. Metadata messages as well as Response messages are compressed.

The cert_name field indicates the expected certificate name for this device. It is commonly blank, indicating to use the implementation default.

The max_sequence field contains the highest sequence number of the files in the index. See Delta Index Exchange for the usage of this field.

The introducer field is set for devices that are trusted as cluster introducers.

The index_id field contains the unique identifier for the current set of index data. See Delta Index Exchange for the usage of this field.

The skip_introduction_removals field signifies if the remote device has opted to ignore introduction removals for the given device. This setting is copied across as we are being introduced to a new device.

The encryption_password_token field contains a token derived from the password, that is used to encrypt data sent to this device. If the device is the same as the device sending the message, it signifies that the device itself has encrypted data that was encrypted with the given token. It is empty or missing if there is no encryption. See Untrusted Device Encryption for details on the encryption scheme.

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 Sequence has been announced for the given folder by the peer device.

The Index and Index Update messages are currently identical in format, although this is not guaranteed to be the case in the future.

message Index {
    string            folder = 1;
    repeated FileInfo files  = 2;
}

message IndexUpdate {
    string            folder = 1;
    repeated FileInfo files  = 2;
}

message FileInfo {
    string       name           = 1;
    FileInfoType type           = 2;
    int64        size           = 3;
    uint32       permissions    = 4;
    int64        modified_s     = 5;
    int32        modified_ns    = 11;
    uint64       modified_by    = 12;
    bool         deleted        = 6;
    bool         invalid        = 7;
    bool         no_permissions = 8;
    Vector       version        = 9;
    int64        sequence       = 10;
    int32        block_size     = 13;

    repeated BlockInfo Blocks         = 16;
    string             symlink_target = 17;
}

enum FileInfoType {
    FILE              = 0;
    DIRECTORY         = 1;
    SYMLINK_FILE      = 2 [deprecated = true];
    SYMLINK_DIRECTORY = 3 [deprecated = true];
    SYMLINK           = 4;
}

message BlockInfo {
    int64 offset     = 1;
    int32 size       = 2;
    bytes hash       = 3;
    uint32 weak_hash = 4;
}

message Vector {
    repeated Counter counters = 1;
}

message Counter {
    uint64 id    = 1;
    uint64 value = 2;
}

The folder field identifies the folder that the index message pertains to.

The files field is a list of files making up the index information.

The name 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’s operating system conventions. The combination of folder and name uniquely identifies each file in a cluster.

The type field contains the type of the described item. The type is one of file (0), directory (1), or symlink (4).

The size field contains the size of the file, in bytes. For directories and symlinks the size is zero.

The permissions field holds the common Unix permission bits. An implementation MAY ignore or interpret these as is suitable on the host operating system.

The modified_s time is expressed as the number of seconds since the Unix Epoch (1970-01-01 00:00:00 UTC). The modified_ns field holds the nanosecond part of the modification time.

The modified_by field holds the short id of the client that last made any modification to the file whether add, change or delete.  This will be overwritten every time a change is made to the file by the last client to do so and so does not hold history.

The deleted field 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.

The invalid field 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.

The no_permissions field 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.

The version 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 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.

The sequence 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.

The block_size 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 Selection of Block Size.

The blocks list contains the size and hash for each block in the file. Each block represents a block_size-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.

The symlink_target field contains the symlink target, for entries of symlink type. It is empty for all other entry types.

The Request message expresses the desire to receive a data block corresponding to a part of a certain file in the peer’s folder.

message Request {
    int32  id             = 1;
    string folder         = 2;
    string name           = 3;
    int64  offset         = 4;
    int32  size           = 5;
    bytes  hash           = 6;
    bool   from_temporary = 7;
}

The id is the request identifier. It will be matched in the corresponding Response message. Each outstanding request must have a unique ID.

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.

The hash field MAY be set to the expected hash value of the block. 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.

The from_temporary field is set to indicate that the read should be performed from the temporary file (converting name to it’s temporary form) and falling back to the non temporary file if any error occurs. Knowledge of contents of temporary files comes from DownloadProgress messages.

The Response message is sent in response to a Request message.

message Response {
    int32     id   = 1;
    bytes     data = 2;
    ErrorCode code = 3;
}

enum ErrorCode {
    NO_ERROR     = 0;
    GENERIC      = 1;
    NO_SUCH_FILE = 2;
    INVALID_FILE = 3;
}

The id field is the request identifier. It must match the ID of the Request that is being responded to.

The data field contains either the requested data block or is empty if the requested block is not available.

The code field contains an error code describing the reason a Request could not be fulfilled, in the case where zero length data was returned. The following values are defined:

0

No Error (data should be present)

1

Generic Error

2

No Such File (the requested file does not exist, or the offset is outside the acceptable range for the file)

3

Invalid (file exists but has invalid bit set or is otherwise unavailable)

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 messages.

message DownloadProgress {
    string                              folder  = 1;
    repeated FileDownloadProgressUpdate updates = 2;
}

message FileDownloadProgressUpdate {
    FileDownloadProgressUpdateType update_type   = 1;
    string                         name          = 2;
    Vector                         version       = 3;
    repeated int32                 block_indexes = 4;
}

enum FileDownloadProgressUpdateType {
    APPEND = 0;
    FORGET = 1;
}

The folder field represents the ID of the folder for which the update is being provided.

The updates field is a list of progress update messages.

The update_type indicates whether the update is of type append (0) (new blocks are available) or forget (1) (the file transfer has completed or failed).

The name field defines the file name from the global index for which this update is being sent.

The version message defines the version of the file for which this update is being sent.

The block_indexes field is a list of positive integers, where each integer represents the index of the block in the FileInfo message Blocks array that has become available for download.

For example an integer with value 3 represents that the data defined in the fourth BlockInfo message of the FileInfo message of that file is now available. Please note that matching should be done on name AND version. Furthermore, each update received is incremental, for example the initial update message 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.

Block indexes MAY be added in any order. An implementation MUST NOT assume that block indexes are added in any specific order.

The forget field being set implies that previously advertised file is no longer available, therefore the list of block indexes should be truncated.

Messages with the forget field set MUST NOT have any block indexes.

Any update message which is being sent for a different version of the same file name must be preceded with an update message for the old version of that file with the forget field set.

As a safeguard on the receiving side, the value of version 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.

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. A Ping message is sent every 90 seconds, if no other message has been sent in the preceding 90 seconds.

message Ping {
}

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.

message Close {
    string reason = 1;
}

The reason field contains a human readable description of the error condition.

Trusted mode is the default sharing mode. Updates are exchanged in both directions.

+------------+     Updates      /---------\
|            |  ----------->   /           \
|   Device   |                 |  Cluster  |
|            |  <-----------   \           /
+------------+     Updates      \---------/

In send only mode, a device does not apply any updates from the cluster, but publishes changes of its local folder to the cluster as usual.

+------------+     Updates      /---------\
|            |  ----------->   /           \
|   Device   |                 |  Cluster  |
|            |                 \           /
+------------+                  \---------/

In receive only mode, a device does not send any updates to the cluster, but accepts changes to its local folder from the cluster as usual.

+------------+     Updates      /---------\
|            |  <-----------   /           \
|   Device   |                 |  Cluster  |
|            |                 \           /
+------------+                  \---------/