SYNCTHING-BEP(7)                   Syncthing                  SYNCTHING-BEP(7)



NNAAMMEE
       syncthing-bep - Block Exchange Protocol v1

IINNTTRROODDUUCCTTIIOONN AANNDD DDEEFFIINNIITTIIOONNSS
       The  Block  Exchange Protocol (BEP) is used between two or more _d_e_v_i_c_e_s
       thus forming a _c_l_u_s_t_e_r. Each device has one or more  _f_o_l_d_e_r_s  of  files
       described by the _l_o_c_a_l _m_o_d_e_l, 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 _g_l_o_b_a_l _m_o_d_e_l. 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.

       File data is described and transferred in units of _b_l_o_c_k_s,  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.

       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 _R_F_C _2_1_1_9 <hhttttppss::////ddaattaa‐‐
       ttrraacckkeerr..iieettff..oorrgg//ddoocc//hhttmmll//rrffcc22111199..hhttmmll>.

TTRRAANNSSPPOORRTT AANNDD AAUUTTHHEENNTTIICCAATTIIOONN
       BEP is deployed as the highest level in  a  protocol  stack,  with  the
       lower level protocols providing encryption and authentication.

          +-----------------------------+
          |   Block Exchange Protocol   |
          |-----------------------------|
          | Encryption & Auth (TLS 1.2) |
          |-----------------------------|
          |      Reliable Transport     |
          |-----------------------------|
          v             ...             v

       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.

       The  exact  nature of the authentication is up to the application, how‐
       ever 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 verifica‐
       tion. The reference implementation uses preshared  certificate  finger‐
       prints (SHA-256) referred to as âDevice IDsâ.

       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.

       The underlying transport protocol MUST guarantee reliable packet deliv‐
       ery.

       In this document, in diagrams and text, âbit 0â refers to the _m_o_s_t _s_i_g_‐
       _n_i_f_i_c_a_n_t bit of a word; âbit 15â is thus the least significant bit of a
       16  bit  word (int16) and âbit 31â is the least significant bit of a 32
       bit word (int32). Non protocol buffer integers are  always  represented
       in  network  byte order (i.e., big endian) and are signed unless stated
       otherwise, but when describing message lengths negative values  do  not
       make sense and the most significant bit MUST be zero.

       The protocol buffer schemas in this document are in pprroottoo33 syntax. This
       means, among other things, that all fields are optional and will assume
       their default value when missing. This does not necessarily mean that a
       message is _v_a_l_i_d with all fields empty - for example,  an  index  entry
       for  a file that does not have a name is not useful and MAY be rejected
       by the implementation. However the folder label is for  human  consump‐
       tion  only  so  an  empty label should be accepted - the implementation
       will have to choose some way to represent the folder, perhaps by  using
       the ID in itâs place or automatically generating a label.

PPRREE--AAUUTTHHEENNTTIICCAATTIIOONN MMEESSSSAAGGEESS
       AFTER  establishing a connection, but BEFORE performing any authentica‐
       tion, devices MUST exchange Hello messages.

       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 permit‐
       ted to communicate due to failing authentication. Note  that  the  cer‐
       tificate  based  authentication may be considered part of the TLS hand‐
       shake that precedes the Hello message exchange, but even  in  the  case
       that  a  connection is rejected a Hello message must be sent before the
       connection is terminated.

       Hello messages MUST be prefixed with an int32 containing the magic num‐
       ber  00xx22EEAA77DD9900BB, followed by an int16 representing the size of the mes‐
       sage, followed by the contents of the Hello message itself.

           0                   1
           0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5
          +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
          |             Magic             |
          |           (32 bits)           |
          +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
          |             Length            |
          +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
          /                               /
          \             Hello             \
          /                               /
          +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

       The Hello message itself is in protocol buffer format with the  follow‐
       ing schema:

          message Hello {
              string device_name    = 1;
              string client_name    = 2;
              string client_version = 3;
          }

   FFiieellddss ((HHeelllloo mmeessssaaggee))
       The  ddeevviiccee__nnaammee  is  a  human  readable  (configured or auto detected)
       device name or host name, for the remote device.

       The cclliieenntt__nnaammee and cclliieenntt__vveerrssiioonn 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  pat‐
       terns  laid  out in the _S_e_m_a_n_t_i_c _V_e_r_s_i_o_n_i_n_g <hhttttppss::////sseemmvveerr..oorrgg//> stan‐
       dard.

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

PPOOSSTT--AAUUTTHHEENNTTIICCAATTIIOONN MMEESSSSAAGGEESS
       Every message post authentication is made up of several parts:

       · A header length word

       · A HHeeaaddeerr

       · A message length word

       · A MMeessssaaggee

           0                   1
           0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5
          +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
          |         Header Length         |
          +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
          /                               /
          \            Header             \
          /                               /
          +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
          |         Message Length        |
          |           (32 bits)           |
          +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
          /                               /
          \            Message            \
          /                               /
          +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

       The  header length word is 16 bits. It indicates the length of the fol‐
       lowing HHeeaaddeerr message. The Header is in  protocol  buffer  format.  The
       Header  describes the type and compression status of the following mes‐
       sage.

       The message is preceded by the 32 bit message length word and is one of
       the concrete BEP messages described below, identified by the ttyyppee field
       of the Header.

       As always, the length words are in network byte order (big endian).

          message Header {
              MessageType        type        = 1;
              MessageCompression compression = 2;
          }

          enum MessageType {
              CLUSTER_CONFIG    = 0;
              INDEX             = 1;
              INDEX_UPDATE      = 2;
              REQUEST           = 3;
              RESPONSE          = 4;
              DOWNLOAD_PROGRESS = 5;
              PING              = 6;
              CLOSE             = 7;
          }

          enum MessageCompression {
              NONE = 0;
              LZ4  = 1;
          }

       When the ccoommpprreessssiioonn field is NNOONNEE, the message is directly in protocol
       buffer format.

       When  the  compression  field  is LLZZ44, the message consists of a 32 bit
       integer describing the uncompressed message length followed by a single
       LZ4  block.  After decompressing the LZ4 block it should be interpreted
       as a protocol buffer message just as in the uncompressed case.

MMEESSSSAAGGEE SSUUBBTTYYPPEESS
   CClluusstteerr CCoonnffiigg
       This informational message provides information about the cluster  con‐
       figuration  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.

   PPrroottooccooll BBuuffffeerr SScchheemmaa
          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;
          }

   FFiieellddss ((CClluusstteerr CCoonnffiigg MMeessssaaggee))
       The ffoollddeerrss field contains the list of folders that  will  be  synchro‐
       nized over the current connection.

   FFiieellddss ((FFoollddeerr MMeessssaaggee))
       The  iidd field contains the folder ID, which is the unique identifier of
       the folder.

       The llaabbeell field contains the folder label, the human readable  name  of
       the folder.

       The  rreeaadd  oonnllyy field is set for folders that the device will accept no
       updates from the network for.

       The iiggnnoorree ppeerrmmiissssiioonnss field is set for folders that  the  device  will
       not accept or announce file permissions for.

       The  iiggnnoorree ddeelleettee field is set for folders that the device will ignore
       deletes for.

       The ddiissaabbllee tteemmpp iinnddeexxeess field is set for folders that  will  not  dis‐
       patch and do not wish to receive progress updates about partially down‐
       loaded files via Download Progress messages.

       The ppaauusseedd field is set for folders that are currently paused.

       The ddeevviicceess field is a list of devices participating  in  sharing  this
       folder.

   FFiieellddss ((DDeevviiccee MMeessssaaggee))
       The  device  iidd  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  nnaammee  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 aaddddrreesssseess is that used by the sending device to connect to
       the described device.

       The ccoommpprreessssiioonn field indicates the compression mode in  use  for  this
       device and folder. The following values are valid:

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

       11      Compression disabled. No compression is used on any message.

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

       The  cceerrtt  nnaammee  field indicates the expected certificate name for this
       device. It is commonly blank,  indicating  to  use  the  implementation
       default.

       The  mmaaxx  sseeqquueennccee  field  contains  the highest sequence number of the
       files in the index. See _D_e_l_t_a _I_n_d_e_x _E_x_c_h_a_n_g_e  for  the  usage  of  this
       field.

       The  iinnttrroodduucceerr  field  is  set for devices that are trusted as cluster
       introducers.

       The iinnddeexx iidd field contains the unique identifier for the  current  set
       of index data. See _D_e_l_t_a _I_n_d_e_x _E_x_c_h_a_n_g_e for the usage of this field.

       The sskkiipp iinnttrroodduuccttiioonn rreemmoovvaallss field signifies if the remote device has
       opted to ignore introduction removals for the given device.  This  set‐
       ting is copied across as we are being introduced to a new device.

       The eenncc ppww ttookkeenn 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 for details on the
       encryption scheme.

   IInnddeexx aanndd IInnddeexx UUppddaattee
       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.

   PPrroottooccooll BBuuffffeerr SScchheemmaa
          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;
          }

   FFiieellddss ((IInnddeexx MMeessssaaggee))
       The  ffoollddeerr field identifies the folder that the index message pertains
       to.

       The ffiilleess field is a list of files making up the index information.

   FFiieellddss ((FFiilleeIInnffoo MMeessssaaggee))
       The nnaammee 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 implementa‐
       tionâs operating system conventions. The combination of folder and name
       uniquely identifies each file in a cluster.

       The ttyyppee field contains the type of the described item. The type is one
       of ffiillee ((00)), ddiirreeccttoorryy ((11)), or ssyymmlliinnkk ((44)).

       The ssiizzee field contains the size of the file, in bytes. For directories
       and symlinks the size is zero.

       The  ppeerrmmiissssiioonnss field holds the common Unix permission bits. An imple‐
       mentation MAY ignore or interpret these as  is  suitable  on  the  host
       operating system.

       The  mmooddiiffiieedd__ss  time  is  expressed as the number of seconds since the
       Unix Epoch (1970-01-01 00:00:00 UTC). The mmooddiiffiieedd__nnss field  holds  the
       nanosecond part of the modification time.

       The  mmooddiiffiieedd__bbyy  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 ddeelleetteedd 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  iinnvvaalliidd  field is set when the file is invalid and unavailable for
       synchronization. A peer MAY set this bit to indicate that it can tempo‐
       rarily not serve data for the file.

       The nnoo ppeerrmmiissssiioonnss 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  vveerrssiioonn 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 con‐
       tents of a file at a given point in time.

       The sseeqquueennccee 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  data‐
       base updates.

       The bblloocckk__ssiizzee 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 _S_e_l_e_c_t_i_o_n _o_f _B_l_o_c_k _S_i_z_e.

       The  bblloocckkss list contains the size and hash for each block in the file.
       Each block represents a bblloocckk__ssiizzee-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 ssyymmlliinnkk__ttaarrggeett field contains the symlink target,  for  entries  of
       symlink type. It is empty for all other entry types.

   RReeqquueesstt
       The Request message expresses the desire to receive a data block corre‐
       sponding to a part of a certain file in the peerâs folder.

   PPrroottooccooll BBuuffffeerr SScchheemmaa
          message Request {
              int32  id             = 1;
              string folder         = 2;
              string name           = 3;
              int64  offset         = 4;
              int32  size           = 5;
              bytes  hash           = 6;
              bool   from_temporary = 7;
          }

   FFiieellddss
       The iidd is the request identifier. It will be matched in the correspond‐
       ing RReessppoonnssee message. Each outstanding request must have a unique ID.

       The  ffoollddeerr  and  nnaammee  fields are as documented for the Index message.
       The ooffffsseett and ssiizzee fields specify the region of the file to be  trans‐
       ferred.  This  SHOULD  equate  to exactly one block as seen in an Index
       message.

       The _h_a_s_h 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  ffrroomm  tteemmppoorraarryy  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.

   RReessppoonnssee
       The Response message is sent in response to a Request message.

   PPrroottooccooll BBuuffffeerr SScchheemmaa
          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;
          }

   FFiieellddss
       The  iidd  field  is  the request identifier. It must match the ID of the
       RReeqquueesstt that is being responded to.

       The ddaattaa field contains either the requested data block or is empty  if
       the requested block is not available.

       The  ccooddee  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0      No Error (data should be present)

       11      Generic Error

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

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

   DDoowwnnllooaaddPPrrooggrreessss
       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 FileDownloadProgressUp‐
       date messages.

   PPrroottooccooll BBuuffffeerr SScchheemmaa
          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;
          }

   FFiieellddss ((DDoowwnnllooaaddPPrrooggrreessss MMeessssaaggee))
       The ffoollddeerr field represents the ID of the folder for which  the  update
       is being provided.

       The uuppddaatteess field is a list of progress update messages.

   FFiieellddss ((FFiilleeDDoowwnnllooaaddPPrrooggrreessssUUppddaattee MMeessssaaggee))
       The uuppddaattee ttyyppee indicates whether the update is of type aappppeenndd ((00)) (new
       blocks are available) or ffoorrggeett ((11)) (the file transfer has completed or
       failed).

       The  nnaammee  field  defines the file name from the global index for which
       this update is being sent.

       The vveerrssiioonn message defines the version of  the  file  for  which  this
       update is being sent.

       The  bblloocckk  iinnddeexxeess  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 nnaammee AND
       vveerrssiioonn. 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 avail‐
       able.

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

       The  ffoorrggeett  field being set implies that previously advertised file is
       no longer available, therefore the list  of  block  indexes  should  be
       truncated.

       Messages with the ffoorrggeett field set MUST NOT have any block indexes.

       Any  update  message which is being sent for a different vveerrssiioonn of the
       same file name must be preceded with an update message for the old ver‐
       sion of that file with the ffoorrggeett field set.

       As  a  safeguard  on  the receiving side, the value of vveerrssiioonn 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.

   PPiinngg
       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.

   PPrroottooccooll BBuuffffeerr SScchheemmaa
          message Ping {
          }

   CClloossee
       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 fol‐
       lowed by further messages.

   PPrroottooccooll BBuuffffeerr SScchheemmaa
          message Close {
              string reason = 1;
          }

   FFiieellddss
       The rreeaassoonn field contains a human readable  description  of  the  error
       condition.

SSHHAARRIINNGG MMOODDEESS
   TTrruusstteedd
       Trusted mode is the default sharing mode. Updates are exchanged in both
       directions.

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

   SSeenndd OOnnllyy
       In send only mode, a device does not apply any updates from  the  clus‐
       ter, but publishes changes of its local folder to the cluster as usual.

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

   RReecceeiivvee OOnnllyy
       In  receive  only mode, a device does not send any updates to the clus‐
       ter, but accepts changes to its local folder from the cluster as usual.

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

DDEELLTTAA IINNDDEEXX EEXXCCHHAANNGGEE
       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 IInnddeexx message  followed  by  one  or  more
       IInnddeexx  UUppddaattee  messages.  Any  previous  index  data known for a remote
       device is removed and replaced with the new index data received  in  an
       IInnddeexx  message, while the contents of an IInnddeexx UUppddaattee message is simply
       added to the existing index data.

       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 mecha‐
       nism the sseeqquueennccee and iinnddeexx IIDD fields are used.

       SSeeqquueennccee::
              Each index  item  (i.e.,  file,  directory  or  symlink)  has  a
              sequence number 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 sequence numbers 1, 2, 3 and so on.  The
              next  file to be changed or detected gets sequence number 4, and
              future updates continue in the same fashion.

       IInnddeexx IIDD::
              Each folder has an Index ID. This is a 64 bit random  identifier
              set at index creation time.

       Given  the  above,  we  know that the tuple {index ID, maximum sequence
       number} uniquely identifies a point in time of a given index. Any  fur‐
       ther  changes  will increase the sequence number of some item, and thus
       the maximum sequence number for the index itself. Should the  index  be
       reset or removed (i.e., the sequence number reset to zero), a new index
       ID must be generated.

       By letting a device know the {index ID,  maximum  sequence  number}  we
       have  for  their  index  data, that device can arrange to only transmit
       IInnddeexx UUppddaattee messages for items with a higher sequence number. This  is
       the delta index mechanism.

       The  index  ID  and  maximum  sequence  number known for each device is
       transmitted in the CClluusstteerr CCoonnffiigg message at connection start.

       For this mechanism to be reliable it is essential that  outgoing  index
       information  is ordered by increasing sequence number. Devices announc‐
       ing a non-zero index ID in the CClluusstteerr CCoonnffiigg  message  MUST  send  all
       index data ordered by increasing sequence number. Devices not intending
       to participate in delta index exchange MUST send a zero  index  ID  or,
       equivalently, not send the iinnddeexx__iidd attribute at all.

MMEESSSSAAGGEE LLIIMMIITTSS
       An  implementation  MAY  impose reasonable limits on the length of mes‐
       sages and message fields to aid robustness in the face of corruption or
       broken  implementations.  An  implementation should strive to keep mes‐
       sages 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.

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

SSEELLEECCTTIIOONN OOFF BBLLOOCCKK SSIIZZEE
       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:

       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} _

       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 cer‐
       tain  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.

       An implementation MUST therefore accept files with a block size differ‐
       ing  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.

EEXXAAMMPPLLEE EEXXCCHHAANNGGEE
       center; |l|l|l|.  _ T{ # T}   T{ A T}   T{ B T} _ T{ 1 T}   T{ Cluster‐
       Configuration->  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} _

       The connection is established and at 1. both peers send ClusterConfigu‐
       ration  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.

EEXXAAMMPPLLEESS OOFF SSTTRROONNGG CCIIPPHHEERR SSUUIITTEESS
       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  AES‐
       GCM(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} _

AAUUTTHHOORR
       The Syncthing Authors

CCOOPPYYRRIIGGHHTT
       2014-2019, The Syncthing Authors



v1.19.2                          Apr 05, 2022                 SYNCTHING-BEP(7)
