syncthing/0000755000000000000000000000000013225132630011557 5ustar rootrootsyncthing/man/0000755000000000000000000000000013225132625012336 5ustar rootrootsyncthing/man/syncthing-bep.70000644000000000000000000007611113225132625015206 0ustar rootroot.\" Man page generated from reStructuredText. . .TH "SYNCTHING-BEP" "7" "Dec 19, 2017" "v0.14" "Syncthing" .SH NAME syncthing-bep \- Block Exchange Protocol v1 . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .SH INTRODUCTION AND DEFINITIONS .sp The Block Exchange Protocol (BEP) is used between two or more \fIdevices\fP thus forming a \fIcluster\fP\&. Each device has one or more \fIfolders\fP of files described by the \fIlocal model\fP, 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 \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. .sp 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 RFC 2119. .SH TRANSPORT AND AUTHENTICATION .sp BEP is deployed as the highest level in a protocol stack, with the lower level protocols providing encryption and authentication. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ | Block Exchange Protocol | |\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-| | Encryption & Auth (TLS 1.2) | |\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-| | Reliable Transport | |\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-| v ... v .ft P .fi .UNINDENT .UNINDENT .sp 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. .sp The exact nature of the authentication is up to the application, however 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 verification. The reference implementation uses preshared certificate fingerprints (SHA\-256) referred to as “Device IDs”. .sp 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. .sp The underlying transport protocol MUST guarantee reliable packet delivery. .sp In this document, in diagrams and text, “bit 0” refers to the \fImost significant\fP 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. .sp The protocol buffer schemas in this document are in \fBproto3\fP syntax. This means, among other things, that all fields are optional and will assume their default value when missing. This does not nececessarily mean that a message is \fIvalid\fP 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 consumption 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. .SH PRE-AUTHENTICATION MESSAGES .sp AFTER establishing a connection, but BEFORE performing any authentication, devices 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. Note that the certificate based authentication may be considered part of the TLS handshake 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. .sp Hello messages MUST be prefixed with an int32 containing the magic number \fB0x2EA7D90B\fP, followed by an int16 representing the size of the message, followed by the contents of the Hello message itself. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 0 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ | Magic | | (32 bits) | +\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ | Length | +\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ / / \e Hello \e / / +\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ .ft P .fi .UNINDENT .UNINDENT .sp The Hello message itself is in protocol buffer format with the following schema: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C message Hello { string device_name = 1; string client_name = 2; string client_version = 3; } .ft P .fi .UNINDENT .UNINDENT .SS Fields (Hello message) .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. .sp Immediately after exchanging Hello messages, the connection MUST be dropped if the remote device does not pass authentication. .SH POST-AUTHENTICATION MESSAGES .sp Every message post authentication is made up of several parts: .INDENT 0.0 .IP \(bu 2 A header length word .IP \(bu 2 A \fBHeader\fP .IP \(bu 2 A message length word .IP \(bu 2 A \fBMessage\fP .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 0 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ | Header Length | +\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ / / \e Header \e / / +\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ | Message Length | | (32 bits) | +\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ / / \e Message \e / / +\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ .ft P .fi .UNINDENT .UNINDENT .sp The header length word is 16 bits. It indicates the length of the following \fBHeader\fP message. The Header is in protocol buffer format. The Header describes the type and compression status of the following message. .sp The message is preceded by the 32 bit message length word and is one of the concrete BEP messages described below, identified by the \fBtype\fP field of the Header. .sp As always, the length words are in network byte order (big endian). .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 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; } .ft P .fi .UNINDENT .UNINDENT .sp When the \fBcompression\fP field is \fBNONE\fP, the message is directly in protocol buffer format. .sp When the compression field is \fBLZ4\fP, 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. .SH MESSAGE SUBTYPES .SS Cluster Config .sp 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. .SS Protocol Buffer Schema .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 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; 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; } enum Compression { METADATA = 0; NEVER = 1; ALWAYS = 2; } .ft P .fi .UNINDENT .UNINDENT .SS Fields (Cluster Config Message) .sp The \fBfolders\fP field contains the list of folders that will be synchronized over the current connection. .SS Fields (Folder Message) .sp The \fBid\fP field contains the folder ID, which is the unique identifier of the folder. .sp The \fBlabel\fP field contains the folder label, the human readable name of the folder. .sp The \fBread only\fP field is set for folders that the device will accept no updates from the network for. .sp The \fBignore permissions\fP field is set for folders that the device will not accept or announce file permissions for. .sp The \fBignore delete\fP field is set for folders that the device will ignore deletes for. .sp The \fBdisable temp indexes\fP 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. .sp The \fBdevices\fP field is a list of devices participating in sharing this folder. .SS Fields (Device Message) .sp The device \fBid\fP 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. .sp The \fBname\fP 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. .sp The list of \fBaddresses\fP is that used by the sending device to connect to the described device. .sp The \fBcompression\fP field indicates the compression mode in use for this device and folder. The following values are valid: .INDENT 0.0 .TP .B 0 Compress metadata. This enables compression of metadata messages such as Index. .TP .B 1 Compression disabled. No compression is used on any message. .TP .B 2 Compress always. Metadata messages as well as Response messages are compressed. .UNINDENT .sp 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 sequence\fP field contains the highest sequence 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. .sp The \fBskip introduction removals\fP 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. .SS Index and Index Update .sp 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. .sp The Index and Index Update messages are currently identical in format, although this is not guaranteed to be the case in the future. .SS Protocol Buffer Schema .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 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; 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; } message Vector { repeated Counter counters = 1; } message Counter { uint64 id = 1; uint64 value = 2; } .ft P .fi .UNINDENT .UNINDENT .SS Fields (Index Message) .sp The \fBfolder\fP field identifies the folder that the index message pertains to. .sp The \fBfiles\fP field is a list of files making up the index information. .SS Fields (FileInfo Message) .sp The \fBname\fP 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. .sp The \fBtype\fP field contains the type of the described item. The type is one of \fBfile (0)\fP, \fBdirectory (1)\fP, or \fBsymlink (4)\fP\&. .sp The \fBsize\fP field contains the size of the file, in bytes. For directories and symlinks the size is zero. .sp The \fBpermissions\fP field holds the common Unix permission bits. An implementation MAY ignore or interpret these as is suitable on the host operating system. .sp The \fBmodified_s\fP time is expressed as the number of seconds since the Unix Epoch (1970\-01\-01 00:00:00 UTC). The \fBmodified_ns\fP field holds the nanosecond part of the modification time. .sp The \fBmodified_by\fP 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. .sp The \fBdeleted\fP 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. .sp The \fBinvalid\fP 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. .sp The \fBno permissions\fP 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. .sp The \fBversion\fP 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. .sp 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 \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. .sp The \fBsymlink_target\fP field contains the symlink target, for entries of symlink type. It is empty for all other entry types. .SS Request .sp The Request message expresses the desire to receive a data block corresponding to a part of a certain file in the peer’s folder. .SS Protocol Buffer Schema .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C message Request { int32 id = 1; string folder = 2; string name = 3; int64 offset = 4; int32 size = 5; bytes hash = 6; bool from_temporary = 7; } .ft P .fi .UNINDENT .UNINDENT .SS Fields .sp The \fBid\fP is the request identifier. It will be matched in the corresponding \fBResponse\fP message. Each outstanding request must have a unique ID. .sp The \fBfolder\fP and \fBname\fP fields are as documented for the Index message. The \fBoffset\fP and \fBsize\fP fields specify the region of the file to be transferred. This SHOULD equate to exactly one block as seen in an Index message. .sp The \fIhash\fP 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. .sp The \fBfrom temporary\fP 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. .SS Response .sp The Response message is sent in response to a Request message. .SS Protocol Buffer Schema .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 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; } .ft P .fi .UNINDENT .UNINDENT .SS Fields .sp The \fBid\fP field is the request identifier. It must match the ID of the \fBRequest\fP that is being responded to. .sp The \fBdata\fP field contains either the requested data block or is empty if the requested block is not available. .sp The \fBcode\fP 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: .INDENT 0.0 .TP .B 0 No Error (data should be present) .TP .B 1 Generic Error .TP .B 2 No Such File (the requested file does not exist, or the offset is outside the acceptable range for the file) .TP .B 3 Invalid (file exists but has invalid bit set or is otherwise unavailable) .UNINDENT .SS DownloadProgress .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 messages. .SS Protocol Buffer Schema .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 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; } .ft P .fi .UNINDENT .UNINDENT .SS Fields (DownloadProgress Message) .sp The \fBfolder\fP field represents the ID of the folder for which the update is being provided. .sp The \fBupdates\fP field is a list of progress update messages. .SS Fields (FileDownloadProgressUpdate Message) .sp The \fBupdate type\fP indicates whether the update is of type \fBappend (0)\fP (new blocks are available) or \fBforget (1)\fP (the file transfer has completed or failed). .sp The \fBname\fP field defines the file name from the global index for which this update is being sent. .sp The \fBversion\fP message defines the version of the file for which this update is being sent. .sp The \fBblock indexes\fP 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. .sp 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 \fBname\fP AND \fBversion\fP\&. 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. .sp Block indexes MAY be added in any order. An implementation MUST NOT assume that block indexes are added in any specific order. .sp The \fBforget\fP field being set implies that previously advertised file is no longer available, therefore the list of block indexes should be truncated. .sp Messages with the \fBforget\fP field 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 preceded with an update message for the old version of that file with the \fBforget\fP field set. .sp As a safeguard on the receiving side, the 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 Ping .sp 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. .SS Protocol Buffer Schema .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C message Ping { } .ft P .fi .UNINDENT .UNINDENT .SS Close .sp 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. .SS Protocol Buffer Schema .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C message Close { string reason = 1; } .ft P .fi .UNINDENT .UNINDENT .SS Fields .sp The \fBreason\fP field contains a human readable description of the error condition. .SH SHARING MODES .SS Trusted .sp Trusted mode is the default sharing mode. Updates are exchanged in both directions. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C +\-\-\-\-\-\-\-\-\-\-\-\-+ Updates /\-\-\-\-\-\-\-\-\-\e | | \-\-\-\-\-\-\-\-\-\-\-> / \e | Device | | Cluster | | | <\-\-\-\-\-\-\-\-\-\-\- \e / +\-\-\-\-\-\-\-\-\-\-\-\-+ Updates \e\-\-\-\-\-\-\-\-\-/ .ft P .fi .UNINDENT .UNINDENT .SS Send Only .sp 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. The local folder can be seen as a “master copy” that is never affected by the actions of other cluster devices. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C +\-\-\-\-\-\-\-\-\-\-\-\-+ Updates /\-\-\-\-\-\-\-\-\-\e | | \-\-\-\-\-\-\-\-\-\-\-> / \e | Device | | Cluster | | | \e / +\-\-\-\-\-\-\-\-\-\-\-\-+ \e\-\-\-\-\-\-\-\-\-/ .ft P .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 \fBsequence\fP and \fBindex ID\fP fields are used. .INDENT 0.0 .TP .B Sequence: 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. .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 sequence number} uniquely identifies a point in time of a given index. Any further 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. .sp By letting a device know the {index ID, maximum sequence number} we have for their index data, that device can arrange to only transmit \fBIndex Update\fP messages for items with a higher sequence number. This is the delta index mechanism. .sp The index ID and maximum sequence number 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 sequence number. Devices announcing a non\-zero index ID in the \fBCluster Config\fP 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 \fBindex_id\fP attribute at all. .SH MESSAGE LIMITS .sp An implementation MAY impose reasonable limits on the length of messages and message fields to aid robustness in the face of corruption or broken implementations. An implementation should strive to keep messages 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. .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 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 EXAMPLE EXCHANGE .TS center; |l|l|l|. _ T{ # T} T{ A T} T{ B T} _ T{ 1 T} T{ ClusterConfiguration\-> 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} _ .TE .sp The connection is established and at 1. both peers send ClusterConfiguration 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. .SH EXAMPLES OF STRONG CIPHER SUITES .TS 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 AESGCM(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} _ .TE .SH AUTHOR The Syncthing Authors .SH COPYRIGHT 2015, The Syncthing Authors .\" Generated by docutils manpage writer. . syncthing/man/syncthing-device-ids.70000644000000000000000000002616413225132625016457 0ustar rootroot.\" Man page generated from reStructuredText. . .TH "SYNCTHING-DEVICE-IDS" "7" "Dec 19, 2017" "v0.14" "Syncthing" .SH NAME syncthing-device-ids \- Understanding Device IDs . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .SH DESCRIPTION .sp Every device is identified by a device ID. The device ID is used for address resolution, authentication and authorization. The term “device ID” could interchangeably have been “key ID” since the device ID is a direct property of the public key in use. .SH KEYS .sp To understand device IDs we need to look at the underlying mechanisms. At first startup, Syncthing will create a public/private keypair. .sp Currently this is a 3072 bit RSA key. The keys are saved in the form of the private key (\fBkey.pem\fP) and a self signed certificate (\fBcert.pem\fP). The self signing part doesn’t actually add any security or functionality as far as Syncthing is concerned but it enables the use of the keys in a standard TLS exchange. .sp The typical certificate will look something like this, inspected with \fBopenssl x509\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Certificate: Data: Version: 3 (0x2) Serial Number: 0 (0x0) Signature Algorithm: sha1WithRSAEncryption Issuer: CN=syncthing Validity Not Before: Mar 30 21:10:52 2014 GMT Not After : Dec 31 23:59:59 2049 GMT Subject: CN=syncthing Subject Public Key Info: Public Key Algorithm: rsaEncryption RSA Public Key: (3072 bit) Modulus (3072 bit): 00:da:83:8a:c0:95:af:0a:42:af:43:74:65:29:f2: 30:e3:b9:12:d2:6b:70:93:da:0b:7b:8a:1e:e5:79: ... 99:09:4c:a9:7b:ba:4a:6a:8b:3b:e6:e7:c7:2c:00: 90:aa:bc:ad:94:e7:80:95:d2:1b Exponent: 65537 (0x10001) X509v3 extensions: X509v3 Key Usage: critical Digital Signature, Key Encipherment X509v3 Extended Key Usage: TLS Web Server Authentication, TLS Web Client Authentication X509v3 Basic Constraints: critical CA:FALSE Signature Algorithm: sha1WithRSAEncryption 68:72:43:8b:83:61:09:68:f0:ef:f0:43:b7:30:a6:73:1e:a8: d9:24:6c:2d:b4:bc:c9:e8:3e:0b:1e:3c:cc:7a:b2:c8:f1:1d: ... 88:7e:e2:61:aa:4c:02:e3:64:b0:da:70:3a:cd:1c:3d:86:db: df:54:b9:4e:be:1b .ft P .fi .UNINDENT .UNINDENT .sp We can see here that the certificate is little more than a container for the public key; the serial number is zero and the Issuer and Subject are both “syncthing” where a qualified name might otherwise be expected. .sp An advanced user could replace the \fBkey.pem\fP and \fBcert.pem\fP files with a keypair generated directly by the \fBopenssl\fP utility or other mechanism. .SH DEVICE IDS .sp To form a device ID the SHA\-256 hash of the certificate data in DER form is calculated. This means the hash covers all information under the \fBCertificate:\fP section above. .sp The hashing results in a 256 bit hash which we encode using base32. Base32 encodes five bits per character so we need 256 / 5 = 51.2 characters to encode the device ID. This becomes 52 characters in practice, but 52 characters of base32 would decode to 260 bits which is not a whole number of bytes. The base32 encoding adds padding to 280 bits (the next multiple of both 5 and 8 bits) so the resulting ID looks something like: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C MFZWI3DBONSGYYLTMRWGC43ENRQXGZDMMFZWI3DBONSGYYLTMRWA==== .ft P .fi .UNINDENT .UNINDENT .sp The padding (\fB====\fP) is stripped away, the device ID split into four groups, and \fI\%check digits\fP <\fBhttps://forum.syncthing.net/t/v0-9-0-new-node-id-format/478\fP> are added for each group. For presentation purposes the device ID is grouped with dashes, resulting in the final value: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C MFZWI3D\-BONSGYC\-YLTMRWG\-C43ENR5\-QXGZDMM\-FZWI3DP\-BONSGYY\-LTMRWAD .ft P .fi .UNINDENT .UNINDENT .SS Connection Establishment .sp Now we know what device IDs are, here’s how they are used in Syncthing. When you add a device ID to the configuration, Syncthing will attempt to connect to that device. The first thing we need to do is figure out the IP and port to connect to. There are three possibilities here: .INDENT 0.0 .IP \(bu 2 The IP and port can be set statically in the configuration. The IP can equally well be a host name, so if you have a static IP or a dynamic DNS setup this might be a good option. .IP \(bu 2 Using local discovery, if enabled. Every Syncthing instance on a LAN periodically broadcasts information about itself (device ID, address, port number). If we’ve seen one of these broadcasts for a given device ID that’s where we try to connect. .IP \(bu 2 Using global discovery, if enabled. Every Syncthing instance announces itself to the global discovery service (device ID and external port number \- the internal address is not announced to the global server). If we don’t have a static address and haven’t seen any local announcements the global discovery server will be queried for an address. .UNINDENT .sp Once we have an address and port a TCP connection is established and a TLS handshake performed. As part of the handshake both devices present their certificates. Once the handshake has completed and the peer certificate is known, the following steps are performed: .INDENT 0.0 .IP 1. 3 Calculate the remote device ID by processing the received certificate as above. .IP 2. 3 Weed out a few possible misconfigurations \- i.e. if the device ID is that of the local device or of a device we already have an active connection to. Drop the connection in these cases. .IP 3. 3 Verify the remote device ID against the configuration. If it is not a device ID we are expecting to talk to, drop the connection. .IP 4. 3 Verify the certificate \fBCommonName\fP against the configuration. By default, we expect it to be \fBsyncthing\fP, but when using custom certificates this can be changed. .IP 5. 3 If everything checks out so far, accept the connection. .UNINDENT .SH AN ASIDE ABOUT COLLISIONS .sp The SHA\-256 hash is cryptographically collision resistant. This means that there is no way that we know of to create two different messages with the same hash. .sp You can argue that of course there are collisions \- there’s an infinite amount of inputs and a finite amount of outputs \- so by definition there are infinitely many messages that result in the same hash. .sp I’m going to quote \fI\%stack overflow\fP <\fBhttps://stackoverflow.com/questions/4014090/is-it-safe-to-ignore-the-possibility-of-sha-collisions-in-practice\fP> here: .INDENT 0.0 .INDENT 3.5 The usual answer goes thus: what is the probability that a rogue asteroid crashes on Earth within the next second, obliterating civilization\-as\-we\- know\-it, and killing off a few billion people ? It can be argued that any unlucky event with a probability lower than that is not actually very important. .sp If we have a “perfect” hash function with output size n, and we have p messages to hash (individual message length is not important), then probability of collision is about p2/2n+1 (this is an approximation which is valid for “small” p, i.e. substantially smaller than 2n/2). For instance, with SHA\-256 (n=256) and one billion messages (p=10^9) then the probability is about 4.3*10^\-60. .sp A mass\-murderer space rock happens about once every 30 million years on average. This leads to a probability of such an event occurring in the next second to about 10^\-15. That’s 45 orders of magnitude more probable than the SHA\-256 collision. Briefly stated, if you find SHA\-256 collisions scary then your priorities are wrong. .UNINDENT .UNINDENT .sp It’s also worth noting that the property of SHA\-256 that we are using is not simply collision resistance but resistance to a preimage attack, i.e. even if you can find two messages that result in a hash collision that doesn’t help you attack Syncthing (or TLS in general). You need to create a message that hashes to exactly the hash that my certificate already has or you won’t get in. .sp Note also that it’s not good enough to find a random blob of bits that happen to have the same hash as my certificate. You need to create a valid DER\-encoded, signed certificate that has the same hash as mine. The difficulty of this is staggeringly far beyond the already staggering difficulty of finding a SHA\-256 collision. .SH PROBLEMS AND VULNERABILITIES .sp As far as I know, these are the issues or potential issues with the above mechanism. .SS Discovery Spoofing .sp Currently, neither the local nor global discovery mechanism is protected by crypto. This means that any device can in theory announce itself for any device ID and potentially receive connections for that device. .sp This could be a denial of service attack (we can’t find the real device for a given device ID, so can’t connect to it and sync). It could also be an intelligence gathering attack; if I spoof a given ID, I can see which devices try to connect to it. .sp It could be mitigated in several ways: .INDENT 0.0 .IP \(bu 2 Announcements could be signed by the device private key. This requires already having the public key to verify. .IP \(bu 2 Announcements to the global announce server could be done using TLS, so the server calculates the device ID based on the certificate instead of trusting the device to tell the truth. .IP \(bu 2 The user could statically configure IP or host name for the devices. .IP \(bu 2 The user could run a trusted global server. .UNINDENT .sp It’s something we might want to look at at some point, but not a huge problem as I see it. .SS Long Device IDs are Painful .sp It’s a mouthful to read over the phone, annoying to type into an SMS or even into a computer. And it needs to be done twice, once for each side. .sp This isn’t a vulnerability as such, but a user experience problem. There are various possible solutions: .INDENT 0.0 .IP \(bu 2 Use shorter device IDs with verification based on the full ID (“You entered MFZWI3; I found and connected to a device with the ID MFZWI3\-DBONSG\-YYLTMR\-WGC43E\-NRQXGZ\-DMMFZW\-I3DBON\-SGYYLT\-MRWA, please confirm that this is correct”). .IP \(bu 2 Use shorter device IDs with an out of band authentication, a la Bluetooth pairing. You enter a one time PIN into Syncthing and give that PIN plus a short device ID to another user. On initial connect, both sides verify that the other knows the correct PIN before accepting the connection. .UNINDENT .SH AUTHOR The Syncthing Authors .SH COPYRIGHT 2015, The Syncthing Authors .\" Generated by docutils manpage writer. . syncthing/man/syncthing-globaldisco.70000644000000000000000000000701013225132625016712 0ustar rootroot.\" Man page generated from reStructuredText. . .TH "SYNCTHING-GLOBALDISCO" "7" "Dec 19, 2017" "v0.14" "Syncthing" .SH NAME syncthing-globaldisco \- Global Discovery Protocol v3 . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .SH ANNOUNCEMENTS .sp A device should announce itself at startup. It does this by an HTTPS POST to the announce server URL. Standard discovery currently requires the path to be “/v2/”, yet this can be up to the discovery server. The POST has a JSON payload listing connection addresses (if any): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { addresses: ["tcp://192.0.2.45:22000", "tcp://:22202", "relay://192.0.2.99:22028"], } .ft P .fi .UNINDENT .UNINDENT .sp It’s OK for the “addresses” field to be either the empty list (\fB[]\fP), \fBnull\fP, or missing entirely. An announcement with the field missing or empty is however not useful… .sp Any empty or unspecified IP addresses (i.e. addresses like \fBtcp://:22000\fP, \fBtcp://0.0.0.0:22000\fP, \fBtcp://[::]:22000\fP) are interpreted as referring to the source IP address of the announcement. .sp The device ID of the announcing device is not part of the announcement. Instead, the server requires that the client perform certificate authentication. The device ID is deduced from the presented certificate. .sp The server response is empty, with code \fB204\fP (No Content) on success. If no certificate was presented, status \fB403\fP (Forbidden) is returned. If the posted data doesn’t conform to the expected format, \fB400\fP (Bad Request) is returned. .sp In successful responses, the server may return a \fBReannounce\-After\fP header containing the number of seconds after which the client should perform a new announcement. .sp In error responses, the server may return a \fBRetry\-After\fP header containing the number of seconds after which the client should retry. .sp Performing announcements significantly more often than indicated by the \fBReannounce\-After\fP or \fBRetry\-After\fP headers may result in the client being throttled. In such cases the server may respond with status code \fB429\fP (Too Many Requests). .SH QUERIES .sp Queries are performed as HTTPS GET requests to the announce server URL. The requested device ID is passed as the query parameter “device”, in canonical string form, i.e. \fBhttps://announce.syncthing.net/v2/?device=ABC12345\-....\fP .sp Successful responses will have status code \fB200\fP (OK) and carry a JSON payload of the same format as the announcement above. The response will not contain empty or unspecified addresses. .sp If the “device” query parameter is missing or malformed, the status code 400 (Bad Request) is returned. .sp If the device ID is of a valid format but not found in the registry, 404 (Not Found) is returned. .sp If the client has exceeded a rate limit, the server may respond with 429 (Too Many Requests). .SH AUTHOR The Syncthing Authors .SH COPYRIGHT 2015, The Syncthing Authors .\" Generated by docutils manpage writer. . syncthing/man/README.md0000644000000000000000000000022513225132625013614 0ustar rootrootThese manual pages are generates on https://docs.syncthing.net/, based on the https://github.com/syncthing/docs repo. Do not edit them in this repo. syncthing/man/syncthing-versioning.70000644000000000000000000001554713225132625016631 0ustar rootroot.\" Man page generated from reStructuredText. . .TH "SYNCTHING-VERSIONING" "7" "Dec 19, 2017" "v0.14" "Syncthing" .SH NAME syncthing-versioning \- Keep automatic backups of deleted files by other nodes . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .SH DESCRIPTION .sp Syncthing supports archiving the old version of a file when it is deleted or replaced with a newer version from the cluster. This is called “file versioning” and uses one of the available \fIversioning strategies\fP described below. File versioning is configured per folder, on a per\-device basis, and defaults to “no file versioning”, i.e. no old copies of files are kept. .SH TRASH CAN FILE VERSIONING .sp This versioning strategy emulates the common “trash can” approach. When a file is deleted or replaced due to a change on a remote device, it is a moved to the trash can in the \fB\&.stversions\fP folder. If a file with the same name was already in the trash can it is replaced. .sp A configuration option is available to clean the trash can from files older than a specified number of days. If this is set to a positive number of days, files will be removed when they have been in the trash can that long. Setting this to zero prevents any files from being removed from the trash can automatically. .SH SIMPLE FILE VERSIONING .sp With “Simple File Versioning” files are moved to the \fB\&.stversions\fP folder (inside your shared folder) when replaced or deleted on a remote device. This option also takes a value in an input titled “Keep Versions” which tells Syncthing how many old versions of the file it should keep. For example, if you set this value to 5, if a file is replaced 5 times on a remote device, you will see 5 time\-stamped versions on that file in the “.stversions” folder on the other devices sharing the same folder. .SH STAGGERED FILE VERSIONING .sp With “Staggered File Versioning” files are also moved to a different folder when replaced or deleted on a remote device (just like “Simple File Versioning”), however, versions are automatically deleted if they are older than the maximum age or exceed the number of files allowed in an interval. .sp With this versioning method it’s possible to specify where the versions are stored, with the default being the \fB\&.stversions\fP folder inside the normal folder path. If you set a custom version path, please ensure that it’s on the same partition or filesystem as the regular folder path, as moving files there may otherwise fail. You can use an absolute path (this is recommended) or a relative path. Relative paths are interpreted relative to Syncthing’s current or startup directory. .sp The following intervals are used and they each have a maximum number of files that will be kept for each. .INDENT 0.0 .TP .B 1 Hour For the first hour, the most recent version is kept every 30 seconds. .TP .B 1 Day For the first day, the most recent version is kept every hour. .TP .B 30 Days For the first 30 days, the most recent version is kept every day. .TP .B Until Maximum Age Until maximum age, the most recent version is kept every week. .TP .B Maximum Age The maximum time to keep a version in days. For example, to keep replaced or deleted files in the “.stversions” folder for an entire year, use 365. If only for 10 days, use 10. \fBNote: Set to 0 to keep versions forever.\fP .UNINDENT .SH EXTERNAL FILE VERSIONING .sp This versioning method delegates the decision on what to do to an external command (program or script). Just prior to a file being replaced, the command will be run. The command should be specified as an absolute path, and can use the following templated arguments: .INDENT 0.0 .TP .B %FOLDER_PATH% Path to the folder .TP .B %FILE_PATH% Path to the file within the folder .UNINDENT .SS Example for Unixes .sp Lets say I want to keep the latest version of each file as they are replaced or removed; essentially I want a “trash can”\-like behavior. For this, I create the following script and store it as \fB/Users/jb/bin/onlylatest.sh\fP (i.e. the \fBbin\fP directory in my home directory): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C #!/bin/sh set \-eu # Where I want my versions stored versionspath=~/.trashcan # The parameters we get from Syncthing folderpath="$1" filepath="$2" # First ensure the dir where we need to store the file exists outpath=\(gadirname "$versionspath/$filepath"\(ga mkdir \-p "$outpath" # Then move the file there mv \-f "$folderpath/$filepath" "$versionspath/$filepath" .ft P .fi .UNINDENT .UNINDENT .sp I must ensure that the script has execute permissions (\fBchmod 755 onlylatest.sh\fP), then configure Syncthing with command \fB/Users/jb/bin/onlylatest.sh %FOLDER_PATH% %FILE_PATH%\fP .sp Lets assume I have a folder “default” in ~/Sync, and that within that folder there is a file \fBdocs/letter.txt\fP that is being replaced or deleted. The script will be called as if I ran this from the command line: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ /Users/jb/bin/onlylatest.sh /Users/jb/Sync docs/letter.txt .ft P .fi .UNINDENT .UNINDENT .sp The script will then move the file in question to \fB~/.trashcan/docs/letter.txt\fP, replacing any previous version of that letter that may already have been there. .SS Example for Windows .sp On Windows we can use a batch script to perform the same “trash can”\-like behavior as mentioned above. I created the following script and saved it as \fBC:\eUsers\emfrnd\eScripts\eonlylatest.bat\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C @echo off :: We need command extensions for mkdir to create intermediate folders in one go setlocal EnableExtensions :: Where I want my versions stored set VERSIONS_PATH=%USERPROFILE%\e.trashcan :: The parameters we get from Syncthing, \(aq~\(aq removes quotes if any set FOLDER_PATH=%~1 set FILE_PATH=%~2 :: First ensure the dir where we need to store the file exists for %%F in ("%VERSIONS_PATH%\e%FILE_PATH%") do set OUTPUT_PATH=%%~dpF if not exist "%OUTPUT_PATH%" mkdir "%OUTPUT_PATH%" || exit /B :: Finally move the file, overwrite existing file if any move /Y "%FOLDER_PATH%\e%FILE_PATH%" "%VERSIONS_PATH%\e%FILE_PATH%" .ft P .fi .UNINDENT .UNINDENT .sp Finally, I set \fBC:\eUsers\emfrnd\eScripts\eonlylatest.bat %FOLDER_PATH% %FILE_PATH%\fP as command name in Syncthing. .SH AUTHOR The Syncthing Authors .SH COPYRIGHT 2015, The Syncthing Authors .\" Generated by docutils manpage writer. . syncthing/man/syncthing-stignore.50000644000000000000000000001644013225132625016267 0ustar rootroot.\" Man page generated from reStructuredText. . .TH "SYNCTHING-STIGNORE" "5" "Dec 19, 2017" "v0.14" "Syncthing" .SH NAME syncthing-stignore \- Prevent files from being synchronized to other nodes . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .SH SYNOPSIS .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \&.stignore .ft P .fi .UNINDENT .UNINDENT .SH DESCRIPTION .sp If some files should not be synchronized to other devices, a file called \fB\&.stignore\fP can be created containing file patterns to ignore. The \fB\&.stignore\fP file must be placed in the root of the folder. The \fB\&.stignore\fP file itself will never be synced to other devices, although it can \fB#include\fP files that \fIare\fP synchronized between devices. All patterns are relative to the folder root. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Note that ignored files can block removal of an otherwise empty directory. See below for the (?d) prefix to allow deletion of ignored files. .UNINDENT .UNINDENT .SH PATTERNS .sp The \fB\&.stignore\fP file contains a list of file or path patterns. The \fIfirst\fP pattern that matches will decide the fate of a given file. .INDENT 0.0 .IP \(bu 2 Regular file names match themselves, i.e. the pattern \fBfoo\fP matches the files \fBfoo\fP, \fBsubdir/foo\fP as well as any directory named \fBfoo\fP\&. Spaces are treated as regular characters. .IP \(bu 2 Asterisk matches zero or more characters in a filename, but does not match the directory separator. \fBte*st\fP matches \fBtest\fP, \fBsubdir/telerest\fP but not \fBtele/rest\fP\&. .IP \(bu 2 Double asterisk matches as above, but also directory separators. \fBte**st\fP matches \fBtest\fP, \fBsubdir/telerest\fP and \fBtele/sub/dir/rest\fP\&. .IP \(bu 2 Question mark matches a single character that is not the directory separator. \fBte??st\fP matches \fBtebest\fP but not \fBteb/st\fP or \fBtest\fP\&. .IP \(bu 2 Characters enclosed in square brackets \fB[]\fP are interpreted as a character range \fB[a\-z]\fP\&. Before using this syntax you should have a basic understanding of regular expression character classes. .IP \(bu 2 A pattern beginning with \fB/\fP matches in the current directory only. \fB/foo\fP matches \fBfoo\fP but not \fBsubdir/foo\fP\&. .IP \(bu 2 A pattern beginning with \fB#include\fP results in loading patterns from the named file. It is an error for a file to not exist or be included more than once. Note that while this can be used to include patterns from a file in a subdirectory, the patterns themselves are still relative to the folder \fIroot\fP\&. Example: \fB#include more\-patterns.txt\fP\&. .IP \(bu 2 A pattern beginning with a \fB!\fP prefix negates the pattern: matching files are \fIincluded\fP (that is, \fInot\fP ignored). This can be used to override more general patterns that follow. Note that files in ignored directories can not be re\-included this way. This is due to the fact that Syncthing stops scanning when it reaches an ignored directory, so doesn’t know what files it might contain. .IP \(bu 2 A pattern beginning with a \fB(?i)\fP prefix enables case\-insensitive pattern matching. \fB(?i)test\fP matches \fBtest\fP, \fBTEST\fP and \fBtEsT\fP\&. The \fB(?i)\fP prefix can be combined with other patterns, for example the pattern \fB(?i)!picture*.png\fP indicates that \fBPicture1.PNG\fP should be synchronized. On Mac OS and Windows, patterns are always case\-insensitive. .IP \(bu 2 A pattern beginning with a \fB(?d)\fP prefix enables removal of these files if they are preventing directory deletion. This prefix should be used by any OS generated files which you are happy to be removed. .IP \(bu 2 A line beginning with \fB//\fP is a comment and has no effect. .IP \(bu 2 Windows does not support escaping \fB\e[foo \- bar\e]\fP\&. .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Prefixes can be specified in any order (e.g. “(?d)(?i)”), but cannot be in a single pair of parentheses (not “(?di)”). .UNINDENT .UNINDENT .SH EXAMPLE .sp Given a directory layout: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \&.DS_Store foo foofoo bar/ baz quux quuz bar2/ baz frobble My Pictures/ Img15.PNG .ft P .fi .UNINDENT .UNINDENT .sp and an \fB\&.stignore\fP file with the contents: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C (?d).DS_Store !frobble !quuz foo *2 qu* (?i)my pictures .ft P .fi .UNINDENT .UNINDENT .sp all files and directories called “foo”, ending in a “2” or starting with “qu” will be ignored. The end result becomes: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \&.DS_Store # ignored, will be deleted if gets in the way of parent directory removal foo # ignored, matches "foo" foofoo # synced, does not match "foo" but would match "foo*" or "*foo" bar/ # synced baz # synced quux # ignored, matches "qu*" quuz # synced, matches "qu*" but is excluded by the preceding "!quuz" bar2/ # ignored, matched "*2" baz # ignored, due to parent being ignored frobble # ignored, due to parent being ignored; "!frobble" doesn\(aqt help My Pictures/ # ignored, matched case insensitive "(?i)my pictures" pattern Img15.PNG # ignored, due to parent being ignored .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Please note that directory patterns ending with a slash \fBsome/directory/\fP matches the content of the directory, but not the directory itself. If you want the pattern to match the directory and its content, make sure it does not have a \fB/\fP at the end of the pattern. .UNINDENT .UNINDENT .SH EFFECTS ON “IN SYNC” STATUS .sp Currently the effects on who is in sync with what can be a bit confusing when using ignore patterns. This should be cleared up in a future version… .sp Assume two devices, Alice and Bob, where Alice has 100 files to share, but Bob ignores 25 of these. From Alice’s point of view Bob will become about 75% in sync (the actual number depends on the sizes of the individual files) and remain in “Syncing” state even though it is in fact not syncing anything (\fI\%issue #623\fP <\fBhttps://github.com/syncthing/syncthing/issues/623\fP>). From Bob’s point of view, it’s 100% up to date but will show fewer files in both the local and global view. .sp If Bob adds files that have already been synced to the ignore list, they will remain in the “global” view but disappear from the “local” view. The end result is more files in the global folder than in the local, but still 100% in sync (\fI\%issue #624\fP <\fBhttps://github.com/syncthing/syncthing/issues/624\fP>). From Alice’s point of view, Bob will remain 100% in sync until the next reconnect, because Bob has already announced that he has the files that are now suddenly ignored. .SH AUTHOR The Syncthing Authors .SH COPYRIGHT 2015, The Syncthing Authors .\" Generated by docutils manpage writer. . syncthing/man/syncthing.10000644000000000000000000002252713225132625014436 0ustar rootroot.\" Man page generated from reStructuredText. . .TH "SYNCTHING" "1" "Dec 19, 2017" "v0.14" "Syncthing" .SH NAME syncthing \- Syncthing . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .SH SYNOPSIS .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C syncthing [\-audit] [\-auditfile=] [\-browser\-only] [device\-id] [\-generate=] [\-gui\-address=
] [\-gui\-apikey=] [\-home=] [\-logfile=] [\-logflags=] [\-no\-browser] [\-no\-console] [\-no\-restart] [\-paths] [\-paused] [\-reset\-database] [\-reset\-deltas] [\-unpaused] [\-upgrade] [\-upgrade\-check] [\-upgrade\-to=] [\-verbose] [\-version] .ft P .fi .UNINDENT .UNINDENT .SH DESCRIPTION .sp Syncthing is an application that lets you synchronize your files across multiple devices. This means the creation, modification or deletion of files on one machine will automatically be replicated to your other devices. We believe your data is your data alone and you deserve to choose where it is stored. Therefore Syncthing does not upload your data to the cloud but exchanges your data across your machines as soon as they are online at the same time. .SH OPTIONS .INDENT 0.0 .TP .B \-audit Write events to timestamped file \fBaudit\-YYYYMMDD\-HHMMSS.log\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-auditfile= Use specified file or stream (\fB"\-"\fP for stdout, \fB"\-\-"\fP for stderr) for audit events, rather than the timestamped default file name. .UNINDENT .INDENT 0.0 .TP .B \-browser\-only Open the web UI in a browser for an already running Syncthing instance. .UNINDENT .INDENT 0.0 .TP .B \-device\-id Print device ID to command line. .UNINDENT .INDENT 0.0 .TP .B \-generate= Generate key and config in specified dir, then exit. .UNINDENT .INDENT 0.0 .TP .B \-gui\-address=
Override GUI listen address. .UNINDENT .INDENT 0.0 .TP .B \-home= Set configuration directory. The default configuration directory is \fB$HOME/.config/syncthing\fP (Unix\-like), \fB$HOME/Library/Application Support/Syncthing\fP (Mac) and \fB%LOCALAPPDATA%\eSyncthing\fP (Windows). .UNINDENT .INDENT 0.0 .TP .B \-logfile= Set destination filename for logging (use \fB"\-"\fP for stdout, which is the default option). .UNINDENT .INDENT 0.0 .TP .B \-logflags= Select information in log line prefix, default 2. The \fB\-logflags\fP value is a sum of the following: .INDENT 7.0 .IP \(bu 2 1: Date .IP \(bu 2 2: Time .IP \(bu 2 4: Microsecond time .IP \(bu 2 8: Long filename .IP \(bu 2 16: Short filename .UNINDENT .sp To prefix each log line with date and time, set \fB\-logflags=3\fP (1 + 2 from above). The value 0 is used to disable all of the above. The default is to show time only (2). .UNINDENT .INDENT 0.0 .TP .B \-no\-browser Do not start a browser. .UNINDENT .INDENT 0.0 .TP .B \-no\-console Hide the console window. (On Windows only) .UNINDENT .INDENT 0.0 .TP .B \-no\-restart Disable the Syncthing monitor process which handles restarts for some configuration changes, upgrades, crashes and also log file writing (stdout is still written). .UNINDENT .INDENT 0.0 .TP .B \-paths Print the paths used for configuration, keys, database, GUI overrides, default sync folder and the log file. .UNINDENT .INDENT 0.0 .TP .B \-paused Start with all devices and folders paused. .UNINDENT .INDENT 0.0 .TP .B \-reset\-database Reset the database, forcing a full rescan and resync. Create \fI\&.stfolder\fP folders in each sync folder if they do not already exist. \fBCaution\fP: Ensure that all sync folders which are mountpoints are already mounted. Inconsistent versions may result if the mountpoint is later mounted and contains older versions. .UNINDENT .INDENT 0.0 .TP .B \-reset\-deltas Reset delta index IDs, forcing a full index exchange. .UNINDENT .INDENT 0.0 .TP .B \-unpaused Start with all devices and folders unpaused. .UNINDENT .INDENT 0.0 .TP .B \-upgrade Perform upgrade. .UNINDENT .INDENT 0.0 .TP .B \-upgrade\-check Check for available upgrade. .UNINDENT .INDENT 0.0 .TP .B \-upgrade\-to= Force upgrade directly from specified URL. .UNINDENT .INDENT 0.0 .TP .B \-verbose Print verbose log output. .UNINDENT .INDENT 0.0 .TP .B \-version Show version. .UNINDENT .SH DEPRECATED OPTIONS .INDENT 0.0 .TP .B \-gui\-apikey= Override GUI API key (deprecated as of v0.13, to be removed in the future \- do not use). .UNINDENT .SH EXIT CODES .INDENT 0.0 .TP .B 0 Success / Shutdown .TP .B 1 Error .TP .B 2 Upgrade not available .TP .B 3 Restarting .TP .B 4 Upgrading .UNINDENT .sp Some of these exit codes are only returned when running without a monitor process (with environment variable \fBSTNORESTART\fP set). Exit codes over 125 are usually returned by the shell/binary loader/default signal handler. Exit codes over 128+N on Unix usually represent the signal which caused the process to exit. For example, \fB128 + 9 (SIGKILL) = 137\fP\&. .SH DEVELOPMENT SETTINGS .sp The following environment variables modify Syncthing’s behavior in ways that are mostly useful for developers. Use with care. If you start Syncthing from within service managers like systemd or supervisor, path expansion may not be supported. .INDENT 0.0 .TP .B STNODEFAULTFOLDER Don’t create a default folder when starting for the first time. This variable will be ignored anytime after the first run. .TP .B STGUIASSETS Directory to load GUI assets from. Overrides compiled in assets. .TP .B STTRACE Used to increase the debugging verbosity in specific or all facilities, generally mapping to a Go package. Enabling any of these also enables microsecond timestamps, file names plus line numbers. Enter a comma\-separated string of facilities to trace. \fBsyncthing \-help\fP always outputs an up\-to\-date list. The valid facility strings are: .INDENT 7.0 .TP .B Main and operational facilities: .INDENT 7.0 .TP .B main Main package. .TP .B model The root hub; the largest chunk of the system. File pulling, index transmission and requests for chunks. .TP .B config Configuration loading and saving. .TP .B db The database layer. .TP .B scanner File change detection and hashing. .TP .B versioner File versioning. .UNINDENT .TP .B Networking facilities: .INDENT 7.0 .TP .B beacon Multicast and broadcast discovery packets. .TP .B connections Connection handling. .TP .B dialer Dialing connections. .TP .B discover Remote device discovery requests, replies and registration of devices. .TP .B relay Relay interaction. .TP .B protocol The BEP protocol. .TP .B nat NAT discovery and port mapping. .TP .B pmp NAT\-PMP discovery and port mapping. .TP .B upnp UPnP discovery and port mapping. .UNINDENT .TP .B Other facilities: .INDENT 7.0 .TP .B events Event generation and logging. .TP .B http REST API. .TP .B sha256 SHA256 hashing package (this facility currently unused). .TP .B stats Persistent device and folder statistics. .TP .B sync Mutexes. Used for debugging race conditions and deadlocks. .TP .B upgrade Binary upgrades. .TP .B all All of the above. .UNINDENT .UNINDENT .TP .B STPROFILER Set to a listen address such as “127.0.0.1:9090” to start the profiler with HTTP access. .TP .B STCPUPROFILE Write a CPU profile to cpu\-$pid.pprof on exit. .TP .B STHEAPPROFILE Write heap profiles to \fBheap\-$pid\-$timestamp.pprof\fP each time heap usage increases. .TP .B STBLOCKPROFILE Write block profiles to \fBblock\-$pid\-$timestamp.pprof\fP every 20 seconds. .TP .B STPERFSTATS Write running performance statistics to \fBperf\-$pid.csv\fP\&. Not supported on Windows. .TP .B STDEADLOCK Used for debugging internal deadlocks. Use only under direction of a developer. .TP .B STDEADLOCKTIMEOUT Used for debugging internal deadlocks; sets debug sensitivity. Use only under direction of a developer. .TP .B STDEADLOCKTHRESHOLD Used for debugging internal deadlocks; sets debug sensitivity. Use only under direction of a developer. .TP .B STNORESTART Equivalent to the \-no\-restart argument. Disable the Syncthing monitor process which handles restarts for some configuration changes, upgrades, crashes and also log file writing (stdout is still written). .TP .B STNOUPGRADE Disable automatic upgrades. .TP .B STHASHING Specify which hashing package to use. Defaults to automatic based on performance. Specify “minio” (compatibility) or “standard” for the default Go implementation. .TP .B GOMAXPROCS Set the maximum number of CPU cores to use. Defaults to all available CPU cores. .TP .B GOGC Percentage of heap growth at which to trigger GC. Default is 100. Lower numbers keep peak memory usage down, at the price of CPU usage (i.e. performance). .UNINDENT .SH SEE ALSO .sp \fBsyncthing\-config(5)\fP, \fBsyncthing\-stignore(5)\fP, \fBsyncthing\-device\-ids(7)\fP, \fBsyncthing\-security(7)\fP, \fBsyncthing\-networking(7)\fP, \fBsyncthing\-versioning(7)\fP, \fBsyncthing\-faq(7)\fP .SH AUTHOR The Syncthing Authors .SH COPYRIGHT 2015, The Syncthing Authors .\" Generated by docutils manpage writer. . syncthing/man/syncthing-rest-api.70000644000000000000000000014205113225132625016161 0ustar rootroot.\" Man page generated from reStructuredText. . .TH "SYNCTHING-REST-API" "7" "Dec 19, 2017" "v0.14" "Syncthing" .SH NAME syncthing-rest-api \- REST API . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .SH DESCRIPTION .sp Syncthing exposes a REST interface over HTTP on the GUI port. This is used by the GUI code (JavaScript) and can be used by other processes wishing to control Syncthing. In most cases both the input and output data is in JSON format. The interface is subject to change. .SH API KEY .sp To use the REST AP an API key must be set and used. The API key can be generated in the GUI, or set in the \fBconfiguration/gui/apikey\fP element in the configuration file. To use an API key, set the request header \fBX\-API\-Key\fP to the API key value. For example, \fBcurl \-X POST \-H "X\-API\-Key: abc123" http://localhost:8384/rest/...\fP can be used to invoke with \fBcurl\fP\&. .SH SYSTEM ENDPOINTS .SS GET /rest/system/browse .sp Returns a list of directories matching the path given by the optional parameter \fBcurrent\fP\&. The path can use \fI\%patterns as described in Go’s filepath package\fP <\fBhttps://golang.org/pkg/path/filepath/#Match\fP>\&. A ‘*’ will always be appended to the given path (e.g. \fB/tmp/\fP matches all its subdirectories). If the option \fBcurrent\fP is not given, filesystem root paths are returned. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ curl \-H "X\-API\-Key: yourkey" localhost:8384/rest/system/browse | json_pp [ "/" ] $ curl \-H "X\-API\-Key: yourkey" localhost:8384/rest/system/browse?current=/var/ | json_pp [ "/var/backups/", "/var/cache/", "/var/lib/", "/var/local/", "/var/lock/", "/var/log/", "/var/mail/", "/var/opt/", "/var/run/", "/var/spool/", "/var/tmp/" ] $ curl \-H "X\-API\-Key: yourkey" localhost:8384/rest/system/browse?current=/var/*o | json_pp [ "/var/local/", "/var/lock/", "/var/log/", "/var/opt/", "/var/spool/" ] .ft P .fi .UNINDENT .UNINDENT .SS GET /rest/system/config .sp Returns the current configuration. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { { "version": 15, "folders": [ { "id": "GXWxf\-3zgnU", "label": "MyFolder", "path": "...", "type": "readwrite", "devices": [ { "deviceID": "..." } ], "rescanIntervalS": 60, "ignorePerms": false, "autoNormalize": true, "minDiskFreePct": 1, "versioning": { "type": "simple", "params": { "keep": "5" } }, "copiers": 0, "pullers": 0, "hashers": 0, "order": "random", "ignoreDelete": false, "scanProgressIntervalS": 0, "pullerSleepS": 0, "pullerPauseS": 0, "maxConflicts": 10, "disableSparseFiles": false, "disableTempIndexes": false, "fsync": false, "invalid": "" } ], "devices": [ { "deviceID": "...", "name": "Laptop", "addresses": [ "dynamic", "tcp://192.168.1.2:22000" ], "compression": "metadata", "certName": "", "introducer": false } ], "gui": { "enabled": true, "address": "127.0.0.1:8384", "user": "Username", "password": "$2a$10$ZFws69T4FlvWwsqeIwL.TOo5zOYqsa/.TxlUnsGYS.j3JvjFTmxo6", "useTLS": false, "apiKey": "pGahcht56664QU5eoFQW6szbEG6Ec2Cr", "insecureAdminAccess": false, "theme": "default" }, "options": { "listenAddresses": [ "default" ], "globalAnnounceServers": [ "default" ], "globalAnnounceEnabled": true, "localAnnounceEnabled": true, "localAnnouncePort": 21027, "localAnnounceMCAddr": "[ff12::8384]:21027", "maxSendKbps": 0, "maxRecvKbps": 0, "reconnectionIntervalS": 60, "relaysEnabled": true, "relayReconnectIntervalM": 10, "startBrowser": false, "natEnabled": true, "natLeaseMinutes": 60, "natRenewalMinutes": 30, "natTimeoutSeconds": 10, "urAccepted": \-1, "urUniqueId": "", "urURL": "https://data.syncthing.net/newdata", "urPostInsecurely": false, "urInitialDelayS": 1800, "restartOnWakeup": true, "autoUpgradeIntervalH": 12, "keepTemporariesH": 24, "cacheIgnoredFiles": false, "progressUpdateIntervalS": 5, "limitBandwidthInLan": false, "minHomeDiskFreePct": 1, "releasesURL": "https://upgrades.syncthing.net/meta.json", "alwaysLocalNets": [], "overwriteRemoteDeviceNamesOnConnect": false, "tempIndexMinBlocks": 10 }, "ignoredDevices": [] } } .ft P .fi .UNINDENT .UNINDENT .SS GET /rest/system/config/insync .sp Returns whether the config is in sync, i.e. whether the running configuration is the same as that on disk. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { "configInSync": true } .ft P .fi .UNINDENT .UNINDENT .SS POST /rest/system/config .sp Post the full contents of the configuration, in the same format as returned by the corresponding GET request. The configuration will be saved to disk and the \fBconfigInSync\fP flag set to false. Restart Syncthing to activate. .SS GET /rest/system/connections .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Return format changed in 0.13.0. .UNINDENT .UNINDENT .sp Returns the list of configured devices and some metadata associated with them. The list also contains the local device itself as not connected. .sp The connection types are \fBTCP (Client)\fP, \fBTCP (Server)\fP, \fBRelay (Client)\fP and \fBRelay (Server)\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { "total" : { "paused" : false, "clientVersion" : "", "at" : "2015\-11\-07T17:29:47.691637262+01:00", "connected" : false, "inBytesTotal" : 1479, "type" : "", "outBytesTotal" : 1318, "address" : "" }, "connections" : { "YZJBJFX\-RDBL7WY\-6ZGKJ2D\-4MJB4E7\-ZATSDUY\-LD6Y3L3\-MLFUYWE\-AEMXJAC" : { "connected" : true, "inBytesTotal" : 556, "paused" : false, "at" : "2015\-11\-07T17:29:47.691548971+01:00", "clientVersion" : "v0.12.1", "address" : "127.0.0.1:22002", "type" : "TCP (Client)", "outBytesTotal" : 550 }, "DOVII4U\-SQEEESM\-VZ2CVTC\-CJM4YN5\-QNV7DCU\-5U3ASRL\-YVFG6TH\-W5DV5AA" : { "outBytesTotal" : 0, "type" : "", "address" : "", "at" : "0001\-01\-01T00:00:00Z", "clientVersion" : "", "paused" : false, "inBytesTotal" : 0, "connected" : false }, "UYGDMA4\-TPHOFO5\-2VQYDCC\-7CWX7XW\-INZINQT\-LE4B42N\-4JUZTSM\-IWCSXA4" : { "address" : "", "type" : "", "outBytesTotal" : 0, "connected" : false, "inBytesTotal" : 0, "paused" : false, "at" : "0001\-01\-01T00:00:00Z", "clientVersion" : "" } } } .ft P .fi .UNINDENT .UNINDENT .SS GET /rest/system/debug .sp New in version 0.12.0. .sp Returns the set of debug facilities and which of them are currently enabled. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { "enabled": [ "beacon" ], "facilities": { "beacon": "Multicast and broadcast discovery", "config": "Configuration loading and saving", "connections": "Connection handling", "db": "The database layer", "dialer": "Dialing connections", "discover": "Remote device discovery", "events": "Event generation and logging", "http": "REST API", "main": "Main package", "model": "The root hub", "protocol": "The BEP protocol", "relay": "Relay connection handling", "scanner": "File change detection and hashing", "stats": "Persistent device and folder statistics", "sync": "Mutexes", "upgrade": "Binary upgrades", "upnp": "UPnP discovery and port mapping", "versioner": "File versioning" } } .ft P .fi .UNINDENT .UNINDENT .SS POST /rest/system/debug .sp New in version 0.12.0. .sp Enables or disables debugging for specified facilities. Give one or both of \fBenable\fP and \fBdisable\fP query parameters, with comma separated facility names. To disable debugging of the beacon and discovery packages, and enable it for config and db: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ curl \-H X\-API\-Key:abc123 \-X POST \(aqhttp://localhost:8384/rest/system/debug?disable=beacon,discovery&enable=config,db\(aq .ft P .fi .UNINDENT .UNINDENT .SS GET /rest/system/discovery .sp Returns the contents of the local discovery cache. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { "LGFPDIT7SKNNJVJZA4FC7QNCRKCE753K72BW5QD2FOZ7FRFEP57Q": [ "192.162.129.11:22000" ] } .ft P .fi .UNINDENT .UNINDENT .SS POST /rest/system/discovery .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Removed in v0.12.0. .UNINDENT .UNINDENT .sp Post with the query parameters \fBdevice\fP and \fBaddr\fP to add entries to the discovery cache. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C curl \-X POST http://127.0.0.1:8384/rest/system/discovery?device=LGFPDIT7SKNNJVJZA4FC7QNCRKCE753K72BW5QD2FOZ7FRFEP57Q\e&addr=192.162.129.11:22000 # Or with the X\-API\-Key header: curl \-X POST \-\-header "X\-API\-Key: TcE28kVPdtJ8COws1JdM0b2nodj77WeQ" http://127.0.0.1:8384/rest/system/discovery?device=LGFPDIT7SKNNJVJZA4FC7QNCRKCE753K72BW5QD2FOZ7FRFEP57Q\e&addr=192.162.129.11:22000 .ft P .fi .UNINDENT .UNINDENT .SS POST /rest/system/error/clear .sp Post with empty to body to remove all recent errors. .SS GET /rest/system/error .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Return format changed in 0.12.0. .UNINDENT .UNINDENT .sp Returns the list of recent errors. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { "errors": [ { "when": "2014\-09\-18T12:59:26.549953186+02:00", "message": "This is an error string" } ] } .ft P .fi .UNINDENT .UNINDENT .SS POST /rest/system/error .sp Post with an error message in the body (plain text) to register a new error. The new error will be displayed on any active GUI clients. .SS GET /rest/system/log .sp New in version 0.12.0. .sp Returns the list of recent log entries. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { "messages": [ { "when": "2014\-09\-18T12:59:26.549953186+02:00", "message": "This is a log entry" } ] } .ft P .fi .UNINDENT .UNINDENT .SS POST /rest/system/pause .sp Pause the given device or all devices. .sp Takes the optional parameter \fBdevice\fP (device ID). When omitted, pauses all devices. Returns status 200 and no content upon success, or status 500 and a plain text error on failure. .SS GET /rest/system/ping .sp Returns a \fB{"ping": "pong"}\fP object. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { "ping": "pong" } .ft P .fi .UNINDENT .UNINDENT .SS POST /rest/system/ping .sp Returns a \fB{"ping": "pong"}\fP object. .SS POST /rest/system/reset .sp Post with empty body to erase the current index database and restart Syncthing. With no query parameters, the entire database is erased from disk. By specifying the \fBfolder\fP parameter with a valid folder ID, only information for that folder will be erased: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ curl \-X POST \-H "X\-API\-Key: abc123" http://localhost:8384/rest/system/reset?folder=default .ft P .fi .UNINDENT .UNINDENT .SS POST /rest/system/restart .sp Post with empty body to immediately restart Syncthing. .SS POST /rest/system/resume .sp Resume the given device or all devices. .sp Takes the optional parameter \fBdevice\fP (device ID). When omitted, resumes all devices. Returns status 200 and no content upon success, or status 500 and a plain text error on failure. .SS POST /rest/system/shutdown .sp Post with empty body to cause Syncthing to exit and not restart. .SS GET /rest/system/status .sp Returns information about current system status and resource usage. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { "alloc": 30618136, "connectionServiceStatus": { "dynamic+https://relays.syncthing.net/endpoint": { "lanAddresses": [ "relay://23.92.71.120:443/?id=53STGR7\-YBM6FCX\-PAZ2RHM\-YPY6OEJ\-WYHVZO7\-PCKQRCK\-PZLTP7T\-434XCAD&pingInterval=1m0s&networkTimeout=2m0s&sessionLimitBps=0&globalLimitBps=0&statusAddr=:22070&providedBy=canton7" ], "wanAddresses": [ "relay://23.92.71.120:443/?id=53STGR7\-YBM6FCX\-PAZ2RHM\-YPY6OEJ\-WYHVZO7\-PCKQRCK\-PZLTP7T\-434XCAD&pingInterval=1m0s&networkTimeout=2m0s&sessionLimitBps=0&globalLimitBps=0&statusAddr=:22070&providedBy=canton7" ] }, "tcp://0.0.0.0:22000": { "lanAddresses": [ "tcp://0.0.0.0:22000" ], "wanAddresses": [ "tcp://0.0.0.0:22000" ] } }, "cpuPercent": 0.006944836512046966, "discoveryEnabled": true, "discoveryErrors": { "global@https://discovery\-v4\-1.syncthing.net/v2/": "500 Internal Server Error", "global@https://discovery\-v4\-2.syncthing.net/v2/": "Post https://discovery\-v4\-2.syncthing.net/v2/: net/http: request canceled while waiting for connection (Client.Timeout exceeded while awaiting headers)", "global@https://discovery\-v4\-3.syncthing.net/v2/": "Post https://discovery\-v4\-3.syncthing.net/v2/: net/http: request canceled while waiting for connection (Client.Timeout exceeded while awaiting headers)", "global@https://discovery\-v6\-1.syncthing.net/v2/": "Post https://discovery\-v6\-1.syncthing.net/v2/: dial tcp [2001:470:28:4d6::5]:443: connect: no route to host", "global@https://discovery\-v6\-2.syncthing.net/v2/": "Post https://discovery\-v6\-2.syncthing.net/v2/: dial tcp [2604:a880:800:10::182:a001]:443: connect: no route to host", "global@https://discovery\-v6\-3.syncthing.net/v2/": "Post https://discovery\-v6\-3.syncthing.net/v2/: dial tcp [2400:6180:0:d0::d9:d001]:443: connect: no route to host" }, "discoveryMethods": 8, "goroutines": 49, "myID": "P56IOI7\-MZJNU2Y\-IQGDREY\-DM2MGTI\-MGL3BXN\-PQ6W5BM\-TBBZ4TJ\-XZWICQ2", "pathSeparator": "/", "startTime": "2016\-06\-06T19:41:43.039284753+02:00", "sys": 42092792, "themes": [ "default", "dark" ], "tilde": "/Users/jb", "uptime": 2635 } .ft P .fi .UNINDENT .UNINDENT .SS GET /rest/system/upgrade .sp Checks for a possible upgrade and returns an object describing the newest version and upgrade possibility. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { "latest": "v0.10.27", "newer": false, "running": "v0.10.27+5\-g36c93b7" } .ft P .fi .UNINDENT .UNINDENT .SS POST /rest/system/upgrade .sp Perform an upgrade to the newest released version and restart. Does nothing if there is no newer version than currently running. .SS GET /rest/system/version .sp Returns the current Syncthing version information. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { "arch": "amd64", "longVersion": "syncthing v0.10.27+3\-gea8c3de (go1.4 darwin\-amd64 default) jb@syno 2015\-03\-16 11:01:29 UTC", "os": "darwin", "version": "v0.10.27+3\-gea8c3de" } .ft P .fi .UNINDENT .UNINDENT .SH DATABASE ENDPOINTS .SS GET /rest/db/browse .sp Returns the directory tree of the global model. Directories are always JSON objects (map/dictionary), and files are always arrays of modification time and size. The first integer is the files modification time, and the second integer is the file size. .sp The call takes one mandatory \fBfolder\fP parameter and two optional parameters. Optional parameter \fBlevels\fP defines how deep within the tree we want to dwell down (0 based, defaults to unlimited depth) Optional parameter \fBprefix\fP defines a prefix within the tree where to start building the structure. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ curl \-s http://localhost:8384/rest/db/browse?folder=default | json_pp { "directory": { "file": ["2015\-04\-20T22:20:45+09:00", 130940928], "subdirectory": { "another file": ["2015\-04\-20T22:20:45+09:00", 130940928] } }, "rootfile": ["2015\-04\-20T22:20:45+09:00", 130940928] } $ curl \-s http://localhost:8384/rest/db/browse?folder=default&levels=0 | json_pp { "directory": {}, "rootfile": ["2015\-04\-20T22:20:45+09:00", 130940928] } $ curl \-s http://localhost:8384/rest/db/browse?folder=default&levels=1 | json_pp { "directory": { "file": ["2015\-04\-20T22:20:45+09:00", 130940928], "subdirectory": {} }, "rootfile": ["2015\-04\-20T22:20:45+09:00", 130940928] } $ curl \-s http://localhost:8384/rest/db/browse?folder=default&prefix=directory/subdirectory | json_pp { "another file": ["2015\-04\-20T22:20:45+09:00", 130940928] } $ curl \-s http://localhost:8384/rest/db/browse?folder=default&prefix=directory&levels=0 | json_pp { "file": ["2015\-04\-20T22:20:45+09:00", 130940928], "subdirectory": {} } .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This is an expensive call, increasing CPU and RAM usage on the device. Use sparingly. .UNINDENT .UNINDENT .SS GET /rest/db/completion .sp Returns the completion percentage (0 to 100) for a given device and folder. Takes \fBdevice\fP and \fBfolder\fP parameters. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { "completion": 100, "globalBytes": 156793013575, "needBytes": 0, "needDeletes": 0 } .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This is an expensive call, increasing CPU and RAM usage on the device. Use sparingly. .UNINDENT .UNINDENT .SS GET /rest/db/file .sp Returns most data available about a given file, including version and availability. Takes \fBfolder\fP and \fBfile\fP parameters. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { "availability": [ "I6KAH76\-66SLLLB\-5PFXSOA\-UFJCDZC\-YAOMLEK\-CP2GB32\-BV5RQST\-3PSROAU" ], "global": { "flags": "0644", "sequence": 3, "modified": "2015\-04\-20T22:20:45+09:00", "name": "util.go", "numBlocks": 1, "size": 9642, "version": [ "5407294127585413568:1" ] }, "local": { "flags": "0644", "sequence": 4, "modified": "2015\-04\-20T22:20:45+09:00", "name": "util.go", "numBlocks": 1, "size": 9642, "version": [ "5407294127585413568:1" ] } } .ft P .fi .UNINDENT .UNINDENT .SS GET /rest/db/ignores .sp Takes one parameter, \fBfolder\fP, and returns the content of the \fB\&.stignore\fP as the \fBignore\fP field. A second field, \fBexpanded\fP, provides a list of strings which represent globbing patterns described by gobwas/glob (based on standard wildcards) that match the patterns in \fB\&.stignore\fP and all the includes. If appropriate these globs are prepended by the following modifiers: \fB!\fP to negate the glob, \fB(?i)\fP to do case insensitive matching and \fB(?d)\fP to enable removing of ignored files in an otherwise empty directory. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { "ignore": [ "(?i)/Backups" ], "expanded": [ "(?i)Backups", "(?i)Backups/**" ] } .ft P .fi .UNINDENT .UNINDENT .SS POST /rest/db/ignores .sp Expects a format similar to the output of \fBGET\fP call, but only containing the \fBignore\fP field (\fBexpanded\fP field should be omitted). It takes one parameter, \fBfolder\fP, and either updates the content of the \fB\&.stignore\fP echoing it back as a response, or returns an error. .SS GET /rest/db/need .sp Takes one mandatory parameter, \fBfolder\fP, and returns lists of files which are needed by this device in order for it to become in sync. .sp Furthermore takes an optional \fBpage\fP and \fBperpage\fP arguments for pagination. Pagination happens, across the union of all needed files, that is \- across all 3 sections of the response. For example, given the current need state is as follows: .INDENT 0.0 .IP 1. 3 \fBprogress\fP has 15 items .IP 2. 3 \fBqueued\fP has 3 items .IP 3. 3 \fBrest\fP has 12 items .UNINDENT .sp If you issue a query with \fBpage=1\fP and \fBperpage=10\fP, only the \fBprogress\fP section in the response will have 10 items. If you issue a request query with \fBpage=2\fP and \fBperpage=10\fP, \fBprogress\fP section will have the last 5 items, \fBqueued\fP section will have all 3 items, and \fBrest\fP section will have first 2 items. If you issue a query for \fBpage=3\fP and \fBperpage=10\fP, you will only have the last 10 items of the \fBrest\fP section. .sp In all these calls, \fBtotal\fP will be 30 to indicate the total number of available items. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { # Files currently being downloaded "progress": [ { "flags": "0755", "sequence": 6, "modified": "2015\-04\-20T23:06:12+09:00", "name": "ls", "size": 34640, "version": [ "5157751870738175669:1" ] } ], # Files queued to be downloaded next (as per array order) "queued": [ ... ], # Files to be downloaded after all queued files will be downloaded. # This happens when we start downloading files, and new files get added while we are downloading. "rest": [ ... ], "page": 1, "perpage": 100, "total": 2000 } .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This is an expensive call, increasing CPU and RAM usage on the device. Use sparingly. .UNINDENT .UNINDENT .SS POST /rest/db/override .sp Request override of a send\-only folder. Takes the mandatory parameter \fIfolder\fP (folder ID). .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C curl \-X POST http://127.0.0.1:8384/rest/db/override?folder=default .ft P .fi .UNINDENT .UNINDENT .SS POST /rest/db/prio .sp Moves the file to the top of the download queue. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C curl \-X POST http://127.0.0.1:8384/rest/db/prio?folder=default&file=foo/bar .ft P .fi .UNINDENT .UNINDENT .sp Response contains the same output as \fBGET /rest/db/need\fP .SS POST /rest/db/scan .sp Request immediate scan. Takes the optional parameters \fBfolder\fP (folder ID), \fBsub\fP (path relative to the folder root) and \fBnext\fP (time in seconds). If \fBfolder\fP is omitted or empty all folders are scanned. If \fBsub\fP is given, only this path (and children, in case it’s a directory) is scanned. The \fBnext\fP argument delays Syncthing’s automated rescan interval for a given amount of seconds. .sp Requesting scan of a path that no longer exists, but previously did, is valid and will result in Syncthing noticing the deletion of the path in question. .sp Returns status 200 and no content upon success, or status 500 and a plain text error if an error occurred during scanning. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C curl \-X POST http://127.0.0.1:8384/rest/db/scan?folder=default&sub=foo/bar .ft P .fi .UNINDENT .UNINDENT .SS GET /rest/db/status .sp Returns information about the current status of a folder. .sp Parameters: \fBfolder\fP, the ID of a folder. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { # latest version according to cluster: "globalBytes": 13173473780, "globalDeleted": 1847, "globalFiles": 42106, # what we have locally: "localBytes": 13173473780, "localDeleted": 1847, "localFiles": 42106, # which part of what we have locally is the latest cluster version: "inSyncBytes": 13173473780, "inSyncFiles": 42106, # which part of what we have locally should be fetched from the cluster: "needBytes": 0, "needFiles": 0, # various other metadata "ignorePatterns": true, "invalid": "", "state": "idle", "stateChanged": "2015\-03\-16T21:47:28.750853241+01:00", "version": 71989 } .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This is an expensive call, increasing CPU and RAM usage on the device. Use sparingly. .UNINDENT .UNINDENT .SH EVENT ENDPOINTS .SS Event API .SS Description .sp Syncthing provides a simple long polling interface for exposing events from the core utility towards a GUI. .sp To receive events, perform a HTTP GET of \fB/rest/events\fP or \fB/rest/events/disk\fP\&. The latter returns only local\-change\-detected and remote\-change\-detected events, the former all other events unless filtered. .sp To filter the event list, in effect creating a specific subscription for only the desired event types, add a parameter \fBevents=EventTypeA,EventTypeB,...\fP where the event types are any from the list below. .sp The optional parameter \fBsince=\fP sets the ID of the last event you’ve already seen. Syncthing returns a JSON encoded array of event objects, starting at the event just after the one with this last seen ID. The default value is 0, which returns all events. There is a limit to the number of events buffered, so if the rate of events is high or the time between polling calls is long some events might be missed. This can be detected by noting a discontinuity in the event IDs. .sp If no new events are produced since \fB\fP, the HTTP call blocks and waits for new events to happen before returning. By default it times out after 60 seconds returning an empty array. The time out duration can be customized with the optional parameter \fBtimeout=seconds\fP\&. .sp To receive only a limited number of events, add the \fBlimit=n\fP parameter with a suitable value for \fBn\fP and only the \fIlast\fP \fBn\fP events will be returned. This can be used to catch up with the latest event ID after a disconnection for example: \fB/rest/events?since=0&limit=1\fP\&. .SS Event Structure .sp Each event is represented by an object similar to the following: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { "id": 2, "globalID": 3, "type": "DeviceConnected", "time": "2014\-07\-13T21:04:33.687836696+02:00", "data": { "addr": "172.16.32.25:22000", "id": "NFGKEKE\-7Z6RTH7\-I3PRZXS\-DEJF3UJ\-FRWJBFO\-VBBTDND\-4SGNGVZ\-QUQHJAG" } } .ft P .fi .UNINDENT .UNINDENT .sp The top level keys \fBid\fP, \fBglobalID\fP, \fBtime\fP, \fBtype\fP and \fBdata\fP are always present, though \fBdata\fP may be \fBnull\fP\&. .INDENT 0.0 .TP .B id A unique ID for this event on the events API. It always increases by 1: the first event generated has id \fB1\fP, the next has id \fB2\fP etc. If this increases by more than 1, then one or more events have been skipped by the events API. .TP .B globalID A global ID for this event, across the events API, the audit log, and any other sources. It may increase by more than 1, but it will always be greater than or equal to the id. .TP .B time The time the event was generated. .TP .B type Indicates the type of (i.e. reason for) the event and is one of the event types below. .TP .B data An object containing optional extra information; the exact structure is determined by the event type. .UNINDENT .SS Event Types .SS ConfigSaved .sp Emitted after the config has been saved by the user or by Syncthing itself. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { "id": 50, "type": "ConfigSaved", "time": "2014\-12\-13T00:09:13.5166486Z", "data": { "Version": 7, "Options": {"..."}, "GUI": {"..."}, "Devices": [{"..."}], "Folders": [{"..."}] } } .ft P .fi .UNINDENT .UNINDENT .SS DeviceConnected .sp Generated each time a connection to a device has been established. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { "id": 2, "type": "DeviceConnected", "time": "2014\-07\-13T21:04:33.687836696+02:00", "data": { "addr": "172.16.32.25:22000", "id": "NFGKEKE\-7Z6RTH7\-I3PRZXS\-DEJF3UJ\-FRWJBFO\-VBBTDND\-4SGNGVZ\-QUQHJAG", "deviceName": "Laptop", "clientName": "syncthing", "clientVersion": "v0.13.4", "type": "TCP (Client)" } } .ft P .fi .UNINDENT .UNINDENT .SS DeviceDisconnected .sp Generated each time a connection to a device has been terminated. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { "id": 48, "type": "DeviceDisconnected", "time": "2014\-07\-13T21:18:52.859929215+02:00", "data": { "error": "unexpected EOF", "id": "NFGKEKE\-7Z6RTH7\-I3PRZXS\-DEJF3UJ\-FRWJBFO\-VBBTDND\-4SGNGVZ\-QUQHJAG" } } .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The error key contains the cause for disconnection, which might not necessarily be an error as such. Specifically, “EOF” and “unexpected EOF” both signify TCP connection termination, either due to the other device restarting or going offline or due to a network change. .UNINDENT .UNINDENT .SS DeviceDiscovered .sp Emitted when a new device is discovered using local discovery. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { "id": 13, "type": "DeviceDiscovered", "time": "2014\-07\-17T13:28:05.043465207+02:00", "data": { "addrs": [ "172.16.32.25:22000" ], "device": "NFGKEKE\-7Z6RTH7\-I3PRZXS\-DEJF3UJ\-FRWJBFO\-VBBTDND\-4SGNGVZ\-QUQHJAG" } } .ft P .fi .UNINDENT .UNINDENT .SS DevicePaused .sp Emitted when a device was paused. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { "id": 13, "type": "DevicePaused", "time": "2014\-07\-17T13:28:05.043465207+02:00", "data": { "device": "NFGKEKE\-7Z6RTH7\-I3PRZXS\-DEJF3UJ\-FRWJBFO\-VBBTDND\-4SGNGVZ\-QUQHJAG" } } .ft P .fi .UNINDENT .UNINDENT .SS DeviceRejected .sp Emitted when there is a connection from a device we are not configured to talk to. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { "id": 24, "type": "DeviceRejected", "time": "2014\-08\-19T10:43:00.562821045+02:00", "data": { "address": "127.0.0.1:51807", "device": "EJHMPAQ\-OGCVORE\-ISB4IS3\-SYYVJXF\-TKJGLTU\-66DIQPF\-GJ5D2GX\-GQ3OWQK" } } .ft P .fi .UNINDENT .UNINDENT .SS DeviceResumed .sp Generated each time a device was resumed. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { "id": 2, "type": "DeviceResumed", "time": "2014\-07\-13T21:04:33.687836696+02:00", "data": { "device": "NFGKEKE\-7Z6RTH7\-I3PRZXS\-DEJF3UJ\-FRWJBFO\-VBBTDND\-4SGNGVZ\-QUQHJAG" } } .ft P .fi .UNINDENT .UNINDENT .SS DownloadProgress .sp Emitted during file downloads for each folder for each file. By default only a single file in a folder is handled at the same time, but custom configuration can cause multiple files to be shown. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { "id": 221, "type": "DownloadProgress", "time": "2014\-12\-13T00:26:12.9876937Z", "data": { "folder1": { "file1": { "Total": 800, "Pulling": 2, "CopiedFromOrigin": 0, "Reused": 633, "CopiedFromElsewhere": 0, "Pulled": 38, "BytesTotal": 104792064, "BytesDone": 87883776 }, "dir\e\efile2": { "Total": 80, "Pulling": 2, "CopiedFromOrigin": 0, "Reused": 0, "CopiedFromElsewhere": 0, "Pulled": 32, "BytesTotal": 10420224, "BytesDone": 4128768 } }, "folder2": { "file3": { "Total": 800, "Pulling": 2, "CopiedFromOrigin": 0, "Reused": 633, "CopiedFromElsewhere": 0, "Pulled": 38, "BytesTotal": 104792064, "BytesDone": 87883776 }, "dir\e\efile4": { "Total": 80, "Pulling": 2, "CopiedFromOrigin": 0, "Reused": 0, "CopiedFromElsewhere": 0, "Pulled": 32, "BytesTotal": 10420224, "BytesDone": 4128768 } } } } .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP \(bu 2 \fBTotal\fP \- total number of blocks in the file .IP \(bu 2 \fBPulling\fP \- number of blocks currently being downloaded .IP \(bu 2 \fBCopiedFromOrigin\fP \- number of blocks copied from the file we are about to replace .IP \(bu 2 \fBReused\fP \- number of blocks reused from a previous temporary file .IP \(bu 2 \fBCopiedFromElsewhere\fP \- number of blocks copied from other files or potentially other folders .IP \(bu 2 \fBPulled\fP \- number of blocks actually downloaded so far .IP \(bu 2 \fBBytesTotal\fP \- approximate total file size .IP \(bu 2 \fBBytesDone\fP \- approximate number of bytes already handled (already reused, copied or pulled) .UNINDENT .sp Where block size is 128KB. .sp Files/folders appearing in the event data imply that the download has been started for that file/folder, where disappearing implies that the downloads have been finished or failed for that file/folder. There is always a last event emitted with no data, which implies all downloads have finished/failed. .SS FolderCompletion .sp The \fBFolderCompletion\fP event is emitted when the local or remote contents for a folder changes. It contains the completion percentage for a given remote device and is emitted once per currently connected remote device. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { "id": 84, "type": "FolderCompletion", "time": "2015\-04\-17T14:14:27.043576583+09:00", "data": { "completion": 100, "device": "I6KAH76\-66SLLLB\-5PFXSOA\-UFJCDZC\-YAOMLEK\-CP2GB32\-BV5RQST\-3PSROAU", "folder": "default" } } .ft P .fi .UNINDENT .UNINDENT .SS FolderErrors .sp The \fBFolderErrors\fP event is emitted when a folder cannot be successfully synchronized. The event contains the ID of the affected folder and a list of errors for files or directories therein. This list of errors is obsolete once the folder changes state to \fBsyncing\fP \- if errors remain after the next synchronization attempt, a new \fBFolderErrors\fP event is emitted. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { "id": 132, "type": "FolderErrors", "time": "2015\-06\-26T13:39:24.697401384+02:00", "data": { "errors": [ { "error": "open /Users/jb/src/github.com/syncthing/syncthing/test/s2/h2j/.syncthing.aslkjd.tmp: permission denied", "path": "h2j/aslkjd" } ], "folder": "default" } } .ft P .fi .UNINDENT .UNINDENT .sp New in version 0.11.12. .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 The statechanged event. .UNINDENT .UNINDENT .SS FolderRejected .sp Emitted when a device sends index information for a folder we do not have, or have but do not share with the device in question. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { "id": 27, "type": "FolderRejected", "time": "2014\-08\-19T10:41:06.761751399+02:00", "data": { "device": "EJHMPAQ\-OGCVORE\-ISB4IS3\-SYYVJXF\-TKJGLTU\-66DIQPF\-GJ5D2GX\-GQ3OWQK", "folder": "GXWxf\-3zgnU", "folderLabel": "My Pictures" } } .ft P .fi .UNINDENT .UNINDENT .SS Folder Scan Progress .sp Emitted in regular intervals (folder setting ProgressIntervalS, 2s by default) during scans giving the amount of bytes already scanned and to be scanned in total , as well as the current scanning rates in bytes per second. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { "data" : { "total" : 1, "rate" : 0, "current" : 0, "folder" : "bd7q3\-zskm5" }, "globalID" : 29, "type" : "FolderScanProgress", "time" : "2017\-03\-06T15:00:58.072004209+01:00", "id" : 29 } .ft P .fi .UNINDENT .UNINDENT .SS FolderSummary .sp The FolderSummary event is emitted when folder contents have changed locally. This can be used to calculate the current local completion state. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { "id": 16, "type": "FolderSummary", "time": "2015\-04\-17T14:12:20.460121585+09:00", "data": { "folder": "default", "summary": { "globalBytes": 0, "globalDeleted": 0, "globalFiles": 0, "ignorePatterns": false, "inSyncBytes": 0, "inSyncFiles": 0, "invalid": "", "localBytes": 0, "localDeleted": 0, "localFiles": 0, "needBytes": 0, "needFiles": 0, "state": "idle", "stateChanged": "2015\-04\-17T14:12:12.455224687+09:00", "version": 0 } } } .ft P .fi .UNINDENT .UNINDENT .SS ItemFinished .sp Generated when Syncthing ends synchronizing a file to a newer version. A successful operation: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { "id": 93, "type": "ItemFinished", "time": "2014\-07\-13T21:22:03.414609034+02:00", "data": { "item": "test.txt", "folder": "default", "error": null, "type": "file", "action": "update" } } .ft P .fi .UNINDENT .UNINDENT .sp An unsuccessful operation: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { "id": 44, "type": "ItemFinished", "time": "2015\-05\-27T11:21:05.711133004+02:00", "data": { "action": "update", "error": "open /Users/jb/src/github.com/syncthing/syncthing/test/s2/foo/.syncthing.hej.tmp: permission denied", "folder": "default", "item": "foo/hej", "type": "file" } } .ft P .fi .UNINDENT .UNINDENT .sp The \fBaction\fP field is either \fBupdate\fP (contents changed), \fBmetadata\fP (file metadata changed but not contents), or \fBdelete\fP\&. .sp New in version 0.11.10: The \fBmetadata\fP action. .SS ItemStarted .sp Generated when Syncthing begins synchronizing a file to a newer version. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { "id": 93, "type": "ItemStarted", "time": "2014\-07\-13T21:22:03.414609034+02:00", "data": { "item": "test.txt", "folder": "default", "type": "file", "action": "update" } } .ft P .fi .UNINDENT .UNINDENT .sp The \fBaction\fP field is either \fBupdate\fP (contents changed), \fBmetadata\fP (file metadata changed but not contents), or \fBdelete\fP\&. .sp New in version 0.11.10: The \fBmetadata\fP action. .SS Listen Addresses Changed .sp This event is emitted when a listen address changes. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { "type" : "ListenAddressesChanged", "id" : 70, "time" : "2017\-03\-06T15:01:24.88340663+01:00", "globalID" : 70, "data" : { "address" : { "Fragment" : "", "RawQuery" : "", "Scheme" : "dynamic+https", "Path" : "/endpoint", "RawPath" : "", "User" : null, "ForceQuery" : false, "Host" : "relays.syncthing.net", "Opaque" : "" }, "wan" : [ { "ForceQuery" : false, "User" : null, "Host" : "31.15.66.212:443", "Opaque" : "", "Path" : "/", "RawPath" : "", "RawQuery" : "id=F4HSJVO\-CP2C3IL\-YLQYLSU\-XTYODAG\-PPU4LGV\-PH3MU4N\-G6K56DV\-IPN47A&pingInterval=1m0s&networkTimeout=2m0s&sessionLimitBps=0&globalLimitBps=0&statusAddr=:22070&providedBy=", "Scheme" : "relay", "Fragment" : "" } ], "lan" : [ { "RawQuery" : "id=F4HSJVO\-CP2C3IL\-YLQYLSU\-XTYODAG\-PPU4LGV\-PH3MU4N\-G6K56DV\-IPN47A&pingInterval=1m0s&networkTimeout=2m0s&sessionLimitBps=0&globalLimitBps=0&statusAddr=:22070&providedBy=", "Scheme" : "relay", "Fragment" : "", "RawPath" : "", "Path" : "/", "Host" : "31.15.66.212:443", "Opaque" : "", "ForceQuery" : false, "User" : null } ] } } .ft P .fi .UNINDENT .UNINDENT .SS LocalChangeDetected .sp Generated upon scan whenever the local disk has discovered an updated file from the previous scan. This does \fInot\fP include events that are discovered and copied from other devices (remote\-change\-detected), only files that were changed on the local filesystem. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { "id": 7, "globalID": 59, "time": "2016\-09\-26T22:07:10.7189141\-04:00", "type": "LocalChangeDetected", "data": { "action": "deleted", "folderID": "vitwy\-zjxqt", "label": "TestSync", "path": "C:\e\eUsers\e\eNate\e\eSync\e\etestfolder\e\etest file.rtf", "type": "file" } } .ft P .fi .UNINDENT .UNINDENT .SS LocalIndexUpdated .sp Generated when the local index information has changed, due to synchronizing one or more items from the cluster or discovering local changes during a scan. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { "id": 59, "type": "LocalIndexUpdated", "time": "2014\-07\-17T13:27:28.051369434+02:00", "data": { "folder": "default", "items": 1000, } } .ft P .fi .UNINDENT .UNINDENT .SS Login Attempt .sp When authentication is enabled for the GUI, this event is emitted on every login attempt. If either the username or password are incorrect, \fBsuccess\fP is false and in any case the given username is returned. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { "id" : 187, "time" : "2017\-03\-07T00:19:24.420386143+01:00", "data" : { "username" : "somename", "success" : false }, "type" : "LoginAttempt", "globalID" : 195 } .ft P .fi .UNINDENT .UNINDENT .SS RemoteChangeDetected .sp Generated upon scan whenever a file is locally updated due to a remote change. Files that are updated locally produce a local\-change\-detected event. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { "time" : "2017\-03\-06T23:58:21.844739891+01:00", "globalID" : 123, "data" : { "type" : "file", "action" : "deleted", "path" : "/media/ntfs_data/Dokumente/testfile", "label" : "Dokumente", "folderID" : "Dokumente", "modifiedBy" : "BPDFDTU" }, "type" : "RemoteChangeDetected", "id" : 2 } .ft P .fi .UNINDENT .UNINDENT .SS Remote Download Progress .sp This event is emitted when a download\-progress message is received. It returns a map \fBdata\fP of filenames with a count of downloaded blocks. The files in questions are currently being downloaded on the remote \fBdevice\fP and belong to \fBfolder\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { "time" : "2017\-03\-07T00:11:37.65838955+01:00", "globalID" : 170, "data" : { "state" : { "tahr64\-6.0.5.iso" : 1784 }, "device" : "F4HSJVO\-CP2C3IL\-YLQYLSU\-XTYODAG\-PPU4LGV\-PH3MU4N\-G6K56DV\-IPN47A", "folder" : "Dokumente" }, "type" : "RemoteDownloadProgress", "id" : 163 } .ft P .fi .UNINDENT .UNINDENT .SS RemoteIndexUpdated .sp Generated each time new index information is received from a device. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { "id": 44, "type": "RemoteIndexUpdated", "time": "2014\-07\-13T21:04:35.394184435+02:00", "data": { "device": "NFGKEKE\-7Z6RTH7\-I3PRZXS\-DEJF3UJ\-FRWJBFO\-VBBTDND\-4SGNGVZ\-QUQHJAG", "folder": "lightroom", "items": 1000 } } .ft P .fi .UNINDENT .UNINDENT .SS Starting .sp Emitted exactly once, when Syncthing starts, before parsing configuration etc. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { "id": 1, "type": "Starting", "time": "2014\-07\-17T13:13:32.044470055+02:00", "data": { "home": "/home/jb/.config/syncthing" } } .ft P .fi .UNINDENT .UNINDENT .SS StartupComplete .sp Emitted exactly once, when initialization is complete and Syncthing is ready to start exchanging data with other devices. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { "id": 1, "type": "StartupComplete", "time": "2014\-07\-13T21:03:18.383239179+02:00", "data": null } .ft P .fi .UNINDENT .UNINDENT .SS StateChanged .sp Emitted when a folder changes state. Possible states are \fBidle\fP, \fBscanning\fP, \fBsyncing\fP and \fBerror\fP\&. The field \fBduration\fP is the number of seconds the folder spent in state \fBfrom\fP\&. In the example below, the folder \fBdefault\fP was in state \fBscanning\fP for 0.198 seconds and is now in state \fBidle\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { "id": 8, "type": "StateChanged", "time": "2014\-07\-17T13:14:28.697493016+02:00", "data": { "folder": "default", "from": "scanning", "duration": 0.19782869900000002, "to": "idle" } } .ft P .fi .UNINDENT .UNINDENT .SS GET /rest/events/disk .sp Returns local disk events that occur when the scanner detects local file system changes (local\-change\-detected) or when files are pulled from a remote device (remote\-change\-detected). .INDENT 0.0 .TP .B Optional GET parameters: .INDENT 7.0 .IP \(bu 2 since (events starting after the given ID) .IP \(bu 2 timeout (fail after given seconds if no event is available, 2s by default) .IP \(bu 2 limit (return last x number of events) .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ curl \-s http://localhost:8384/rest/events/disk?limit=4 | json { "id": 4, "globalID": 45, "time": "2016\-09\-26T22:06:10.4734536\-04:00", "type": "LocalChangeDetected", "data": { "action": "added", "folderID": "vitwy\-zxuqt", "label": "TestSync", "path": "C:\e\eUsers\e\eNate\e\eSync\e\etestfolder", "type": "dir" } }, { "id": 5, "globalID": 46, "time": "2016\-09\-26T22:06:10.4754548\-04:00", "type": "LocalChangeDetected", "data": { "action": "added", "folderID": "vitwy\-zxuqt", "label": "TestSync", "path": "C:\e\eUsers\e\eNate\e\eSync\e\edfghdfj\e\etest file.rtf", "type": "file" } }, { "id": 6, "globalID": 58, "time": "2016\-09\-26T22:07:10.7189141\-04:00", "type": "LocalChangeDetected", "data": { "action": "deleted", "folderID": "vitwy\-zxuqt", "label": "TestSync", "path": "C:\e\eUsers\e\eNate\e\eSync\e\etestfolder", "type": "dir" } }, { "id": 7, "globalID": 59, "time": "2016\-09\-26T22:07:10.7189141\-04:00", "type": "LocalChangeDetected", "data": { "action": "deleted", "folderID": "vitwy\-zxuqt", "label": "TestSync", "path": "C:\e\eUsers\e\eNate\e\eSync\e\edfghdfj\e\etest file.rtf", "type": "file" } } .ft P .fi .UNINDENT .UNINDENT .SH STATISTICS ENDPOINTS .SS GET /rest/stats/device .sp Returns general statistics about devices. Currently, only contains the time the device was last seen. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ curl \-s http://localhost:8384/rest/stats/device | json { "P56IOI7\-MZJNU2Y\-IQGDREY\-DM2MGTI\-MGL3BXN\-PQ6W5BM\-TBBZ4TJ\-XZWICQ2": { "lastSeen" : "2015\-04\-18T11:21:31.3256277+01:00" } } .ft P .fi .UNINDENT .UNINDENT .SS GET /rest/stats/folder .sp Returns general statistics about folders. Currently contains the last scan time and the last synced file. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ curl \-s http://localhost:8384/rest/stats/folder | json { "folderid" : { "lastScan": "2016\-06\-02T13:28:01.288181412\-04:00", "lastFile" : { "filename" : "file/name", "at" : "2015\-04\-16T22:04:18.3066971+01:00" } } } .ft P .fi .UNINDENT .UNINDENT .SH MISC SERVICES ENDPOINTS .SS GET /rest/svc/deviceid .sp Verifies and formats a device ID. Accepts all currently valid formats (52 or 56 characters with or without separators, upper or lower case, with trivial substitutions). Takes one parameter, \fBid\fP, and returns either a valid device ID in modern format, or an error. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ curl \-s http://localhost:8384/rest/svc/deviceid?id=1234 | json { "error": "device ID invalid: incorrect length" } $ curl \-s http://localhost:8384/rest/svc/deviceid?id=p56ioi7m\-\-zjnu2iq\-gdr\-eydm\-2mgtmgl3bxnpq6w5btbbz4tjxzwicq | json { "id": "P56IOI7\-MZJNU2Y\-IQGDREY\-DM2MGTI\-MGL3BXN\-PQ6W5BM\-TBBZ4TJ\-XZWICQ2" } .ft P .fi .UNINDENT .UNINDENT .SS GET /rest/svc/lang .sp Returns a list of canonicalized localization codes, as picked up from the \fBAccept\-Language\fP header sent by the browser. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ["sv_sv","sv","en_us","en"] .ft P .fi .UNINDENT .UNINDENT .SS GET /rest/svc/random/string .sp Returns a strong random generated string (alphanumeric) of the specified length. Takes the \fBlength\fP parameter. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { "random": "FdPaEaZQ56sXEKYNxpgF" } .ft P .fi .UNINDENT .UNINDENT .SS GET /rest/svc/report .sp Returns the data sent in the anonymous usage report. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { "folderMaxMiB" : 0, "platform" : "linux\-amd64", "totMiB" : 0, "longVersion" : "syncthing v0.12.2 \e"Beryllium Bedbug\e" (go1.4.3 linux\-amd64 default) unknown\-user@build2.syncthing.net 2015\-11\-09 13:23:26 UTC", "upgradeAllowedManual" : true, "totFiles" : 3, "folderUses" : { "ignorePerms" : 0, "autoNormalize" : 0, "readonly" : 0, "ignoreDelete" : 0 }, "memoryUsageMiB" : 13, "version" : "v0.12.2", "sha256Perf" : 27.28, "numFolders" : 2, "memorySize" : 1992, "announce" : { "defaultServersIP" : 0, "otherServers" : 0, "globalEnabled" : false, "defaultServersDNS" : 1, "localEnabled" : false }, "usesRateLimit" : false, "numCPU" : 2, "uniqueID" : "", "urVersion" : 2, "rescanIntvs" : [ 60, 60 ], "numDevices" : 2, "folderMaxFiles" : 3, "relays" : { "defaultServers" : 1, "enabled" : true, "otherServers" : 0 }, "deviceUses" : { "compressMetadata" : 1, "customCertName" : 0, "staticAddr" : 1, "compressAlways" : 0, "compressNever" : 1, "introducer" : 0, "dynamicAddr" : 1 }, "upgradeAllowedAuto" : false } .ft P .fi .UNINDENT .UNINDENT .SH AUTHOR The Syncthing Authors .SH COPYRIGHT 2015, The Syncthing Authors .\" Generated by docutils manpage writer. . syncthing/man/stdiscosrv.10000644000000000000000000002344013225132625014626 0ustar rootroot.\" Man page generated from reStructuredText. . .TH "STDISCOSRV" "1" "Dec 19, 2017" "v0.14" "Syncthing" .SH NAME stdiscosrv \- Syncthing Discovery Server . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .SH SYNOPSIS .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C stdiscosrv [\-cert=] [\-db\-backend=] [\-db\-dsn=] [\-debug] [\-http] [\-key=] [\-limit\-avg=] [\-limit\-burst=] [\-limit\-cache=] [\-listen=
] [\-stats\-file=] .ft P .fi .UNINDENT .UNINDENT .SH DESCRIPTION .sp Syncthing relies on a discovery server to find peers on the internet. Anyone can run a discovery server and point Syncthing installations to it. .SH OPTIONS .INDENT 0.0 .TP .B \-cert= Certificate file (default “cert.pem”). .UNINDENT .INDENT 0.0 .TP .B \-db\-backend= Database backend to use (default “ql”). .UNINDENT .INDENT 0.0 .TP .B \-db\-dsn= Database DSN (default “memory://stdiscosrv”). .UNINDENT .INDENT 0.0 .TP .B \-debug Enable debug output. .UNINDENT .INDENT 0.0 .TP .B \-http Listen on HTTP (behind an HTTPS proxy). .UNINDENT .INDENT 0.0 .TP .B \-key= Key file (default “key.pem”). .UNINDENT .INDENT 0.0 .TP .B \-limit\-avg= Allowed average package rate, per 10 s (default 5). .UNINDENT .INDENT 0.0 .TP .B \-limit\-burst= Allowed burst size, packets (default 20). .UNINDENT .INDENT 0.0 .TP .B \-limit\-cache= Limiter cache entries (default 10240). .UNINDENT .INDENT 0.0 .TP .B \-listen=
Listen address (default “:8443”). .UNINDENT .INDENT 0.0 .TP .B \-stats\-file= File to write periodic operation stats to. .UNINDENT .SH POINTING SYNCTHING AT YOUR DISCOVERY SERVER .sp By default, Syncthing uses a number of global discovery servers, signified by the entry \fBdefault\fP in the list of discovery servers. To make Syncthing use your own instance of stdiscosrv, open up Syncthing’s web GUI. Go to settings, Global Discovery Server and add stdiscosrv’s host address to the comma\-separated list, e.g. \fBhttps://disco.example.com:8443/v2/\fP\&. Note that stdiscosrv uses port 8443 by default. For stdiscosrv to be available over the internet with a dynamic IP address, you will need a dynamic DNS service. .sp If you wish to use \fIonly\fP your own discovery server, remove the \fBdefault\fP entry from the list. .SH SETTING UP .SS Description .sp This guide assumes that you have already set up Syncthing. If you haven’t yet, head over to getting\-started first. .SS Installing .sp Go to \fI\%releases\fP <\fBhttps://build.syncthing.net/job/stdiscosrv\fP> and download the file appropriate for your operating system. Unpacking it will yield a binary called \fBstdiscosrv\fP (or \fBstdiscosrv.exe\fP on Windows). Start this in whatever way you are most comfortable with; double clicking should work in any graphical environment. At first start, stdiscosrv will generate the directory \fB/var/stdiscosrv\fP (\fBX:\evar\estdiscosrv\fP on Windows, where X is the partition \fBstdiscosrv.exe\fP is executed from) with configuration. If the user running \fBstdiscosrv\fP doesn’t have permission to do so, create the directory and set the owner appropriately or use the command line switches (see below) to select a different location. .SS Configuring .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 If you are running an instance of Syncthing on the discovery server, you must either add that instance to other devices using a static address or bind the discovery server and Syncthing instances to different IP addresses. .UNINDENT .UNINDENT .SS Certificates .sp The discovery server provides service over HTTPS. To ensure secure connections from clients there are three options: .INDENT 0.0 .IP \(bu 2 Use a CA\-signed certificate pair for the domain name you will use for the discovery server. This is like any other HTTPS website; clients will authenticate the server based on it’s certificate and domain name. .IP \(bu 2 Use any certificate pair and let clients authenticate the server based on it’s “device ID” (similar to Syncthing\-to\-Syncthing authentication). In this case, using \fBsyncthing \-generate\fP is a good option to create a certificate pair. .IP \(bu 2 Pass the \fB\-http\fP flag if the discovery server is behind an SSL\-secured reverse proxy. See below for configuration. .UNINDENT .sp For the first two options, the discovery server must be given the paths to the certificate and key at startup. This isn’t necessary with the \fBhttp\fP flag: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ stdiscosrv \-cert /path/to/cert.pem \-key /path/to/key.pem Server device ID is 7DDRT7J\-UICR4PM\-PBIZYL3\-MZOJ7X7\-EX56JP6\-IK6HHMW\-S7EK32W\-G3EUPQA .ft P .fi .UNINDENT .UNINDENT .sp The discovery server prints it’s device ID at startup. In the case where you are using a non CA signed certificate, this device ID (fingerprint) must be given to the clients in the discovery server URL: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C https://disco.example.com:8443/v2/?id=7DDRT7J\-UICR4PM\-PBIZYL3\-MZOJ7X7\-EX56JP6\-IK6HHMW\-S7EK32W\-G3EUPQA .ft P .fi .UNINDENT .UNINDENT .sp Otherwise, the URL (note the trailing slash after the \fBv2\fP) will be: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C https://disco.example.com:8443/v2/ .ft P .fi .UNINDENT .UNINDENT .SS Reverse Proxy Setup .sp The discovery server can be run behind an SSL\-secured reverse proxy. This allows: .INDENT 0.0 .IP \(bu 2 Use of a subdomain name without requiring a port number added to the URL .IP \(bu 2 Sharing an SSL certificate with multiple services on the same server .UNINDENT .SS Requirements .INDENT 0.0 .IP \(bu 2 Run the discovery server using the \-http flag \fBstdiscosrv \-http\fP\&. .IP \(bu 2 SSL certificate/key configured for the reverse proxy .IP \(bu 2 The “X\-Forwarded\-For” http header must be passed through with the client’s real IP address .IP \(bu 2 The “X\-SSL\-Cert” must be passed through with the PEM\-encoded client SSL certificate .IP \(bu 2 The proxy must request the client SSL certificate but not require it to be signed by a trusted CA. .UNINDENT .SS Nginx .sp These three lines in the configuration take care of the last three requirements listed above: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proxy_set_header X\-Forwarded\-For $proxy_add_x_forwarded_for; proxy_set_header X\-SSL\-Cert $ssl_client_cert; ssl_verify_client optional_no_ca; .ft P .fi .UNINDENT .UNINDENT .sp The following is a complete example Nginx configuration file. With this setup, clients can use \fI\%https://discovery.example.com\fP as the discovery server URL in the Syncthing settings. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # HTTP 1.1 support proxy_http_version 1.1; proxy_buffering off; proxy_set_header Host $http_host; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection $proxy_connection; proxy_set_header X\-Real\-IP $remote_addr; proxy_set_header X\-Forwarded\-For $proxy_add_x_forwarded_for; proxy_set_header X\-Forwarded\-Proto $proxy_x_forwarded_proto; proxy_set_header X\-SSL\-Cert $ssl_client_cert; upstream discovery.example.com { # Local IP address:port for discovery server server 192.0.2.1:8443; } server { server_name discovery.example.com; listen 80; access_log /var/log/nginx/access.log vhost; return 301 https://$host$request_uri; } server { server_name discovery.example.com; listen 443 ssl http2; access_log /var/log/nginx/access.log vhost; ssl_protocols TLSv1 TLSv1.1 TLSv1.2; ssl_ciphers ECDHE\-RSA\-AES128\-GCM\-SHA256:ECDHE\-ECDSA\-AES128\-GCM\-SHA256:ECDHE\-RSA\-AES256\-GCM\-SHA384:ECDHE\-ECDSA\-AES256\-GCM\-SHA384: DHE\-RSA\-AES128\-GCM\-SHA256:DHE\-DSS\-AES128\-GCM\-SHA256:kEDH+AESGCM:ECDHE\-RSA\-AES128\-SHA256:ECDHE\-ECDSA\-AES128\-SHA256:ECDHE\-RSA\-AES128\-SHA:E CDHE\-ECDSA\-AES128\-SHA:ECDHE\-RSA\-AES256\-SHA384:ECDHE\-ECDSA\-AES256\-SHA384:ECDHE\-RSA\-AES256\-SHA:ECDHE\-ECDSA\-AES256\-SHA:DHE\-RSA\-AES128\-SHA25 6:DHE\-RSA\-AES128\-SHA:DHE\-DSS\-AES128\-SHA256:DHE\-RSA\-AES256\-SHA256:DHE\-DSS\-AES256\-SHA:DHE\-RSA\-AES256\-SHA:AES128\-GCM\-SHA256:AES256\-GCM\-SHA3 84:AES128\-SHA256:AES256\-SHA256:AES128\-SHA:AES256\-SHA:AES:CAMELLIA:DES\-CBC3\-SHA:!aNULL:!eNULL:!EXPORT:!DES:!RC4:!MD5:!PSK:!aECDH:!EDH\-DSS \-DES\-CBC3\-SHA:!EDH\-RSA\-DES\-CBC3\-SHA:!KRB5\-DES\-CBC3\-SHA; ssl_prefer_server_ciphers on; ssl_session_timeout 5m; ssl_session_cache shared:SSL:50m; ssl_certificate /etc/nginx/certs/discovery.example.com.crt; ssl_certificate_key /etc/nginx/certs/discovery.example.com.key; ssl_dhparam /etc/nginx/certs/discovery.example.com.dhparam.pem; add_header Strict\-Transport\-Security "max\-age=31536000"; ssl_verify_client optional_no_ca; location / { proxy_pass http://discovery.example.com; } } .ft P .fi .UNINDENT .UNINDENT .sp An example of automating the SSL certificates and reverse\-proxying the Discovery Server and Syncthing using Nginx, \fI\%Let’s Encrypt\fP <\fBhttps://letsencrypt.org/\fP> and Docker can be found \fI\%here\fP <\fBhttps://forum.syncthing.net/t/docker-syncthing-and-syncthing-discovery-behind-nginx-reverse-proxy-with-lets-encrypt/6880\fP>\&. .SH SEE ALSO .sp \fBsyncthing\-networking(7)\fP, \fBsyncthing\-faq(7)\fP .SH AUTHOR The Syncthing Authors .SH COPYRIGHT 2015, The Syncthing Authors .\" Generated by docutils manpage writer. . syncthing/man/syncthing-faq.70000644000000000000000000005432013225132625015205 0ustar rootroot.\" Man page generated from reStructuredText. . .TH "SYNCTHING-FAQ" "7" "Dec 19, 2017" "v0.14" "Syncthing" .SH NAME syncthing-faq \- Frequently Asked Questions . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .SH GENERAL .SS What is Syncthing? .sp Syncthing is an application that lets you synchronize your files across multiple devices. This means the creation, modification or deletion of files on one machine will automatically be replicated to your other devices. We believe your data is your data alone and you deserve to choose where it is stored. Therefore Syncthing does not upload your data to the cloud but exchanges your data across your machines as soon as they are online at the same time. .SS Is it “syncthing”, “Syncthing” or “SyncThing”? .sp It’s \fBSyncthing\fP, although the command and source repository is spelled \fBsyncthing\fP so it may be referred to in that way as well. It’s definitely not SyncThing, even though the abbreviation \fBst\fP is used in some circumstances and file names. .SS How does Syncthing differ from BitTorrent/Resilio Sync? .sp The two are different and not related. Syncthing and BitTorrent/Resilio Sync accomplish some of the same things, namely syncing files between two or more computers. .sp BitTorrent Sync, now called Resilio Sync, is a proprietary peer\-to\-peer file synchronization tool available for Windows, Mac, Linux, Android, iOS, Windows Phone, Amazon Kindle Fire and BSD. [1] Syncthing is an open source file synchronization tool. .sp Syncthing uses an open and documented protocol, and likewise the security mechanisms in use are well defined and visible in the source code. Resilio Sync uses an undocumented, closed protocol with unknown security properties. .IP [1] 5 \fI\%https://en.wikipedia.org/wiki/Resilio_Sync\fP .SH USAGE .SS What things are synced? .sp The following things are \fIalways\fP synchronized: .INDENT 0.0 .IP \(bu 2 File Contents .IP \(bu 2 File Modification Times .UNINDENT .sp The following may be synchronized or not, depending: .INDENT 0.0 .IP \(bu 2 File Permissions (When supported by file system. On Windows, only the read only bit is synchronized.) .IP \(bu 2 Symbolic Links (Except on Windows.) .UNINDENT .sp The following are \fInot\fP synchronized; .INDENT 0.0 .IP \(bu 2 File or Directory Owners and Groups (not preserved) .IP \(bu 2 Directory Modification Times (not preserved) .IP \(bu 2 Hard Links (followed, not preserved) .IP \(bu 2 Extended Attributes, Resource Forks (not preserved) .IP \(bu 2 Windows, POSIX or NFS ACLs (not preserved) .IP \(bu 2 Devices, FIFOs, and Other Specials (ignored) .IP \(bu 2 Sparse file sparseness (will become sparse, when supported by the OS & filesystem) .UNINDENT .SS Is synchronization fast? .sp Syncthing segments files into pieces, called blocks, to transfer data from one device to another. Therefore, multiple devices can share the synchronization load, in a similar way to the torrent protocol. The more devices you have online, the faster an additional device will receive the data because small blocks will be fetched from all devices in parallel. .sp Syncthing handles renaming files and updating their metadata in an efficient manner. This means that renaming a large file will not cause a retransmission of that file. Additionally, appending data to existing large files should be handled efficiently as well. .sp Temporary files are used to store partial data downloaded from other devices. They are automatically removed whenever a file transfer has been completed or after the configured amount of time which is set in the configuration file (24 hours by default). .SS Why is the sync so slow? .sp When troubleshooting a slow sync, there are a number of things to check. .sp First of all, verify that you are not connected via a relay. In the “Remote Devices” list on the right side of the GUI, double check that you see “Address: ” and \fInot\fP “Relay: ”. [image] .sp If you are connected via a relay, this is because a direct connection could not be established. Double check and follow the suggestions in firewall\-setup to enable direct connections. .sp Second, if one of the devices is a very low powered machine (a Raspberry Pi, or a phone, or a NAS, or similar) you are likely constrained by the CPU on that device. See the next question for reasons Syncthing likes a faster CPU. You can verify this by looking at the CPU utilization in the GUI. If it is constantly at or close to 100%, you are limited by the CPU speed. In some cases a lower CPU usage number can also indicate being limited by the CPU \- for example constant 25% usage on a four core CPU likely means that Syncthing is doing something that is not parallellizable and thus limited to a single CPU core. .sp Third, verify that the network connection is OK. Tools such as iperf or just an Internet speed test can be used to verify the performance here. .SS Why does it use so much CPU? .INDENT 0.0 .IP 1. 3 When new or changed files are detected, or Syncthing starts for the first time, your files are hashed using SHA\-256. .IP 2. 3 Data that is sent over the network is (optionally) compressed and encrypted using AES\-128. When receiving data, it must be decrypted. .IP 3. 3 There is a certain amount of housekeeping that must be done to track the current and available versions of each file in the index database. .IP 4. 3 By default Syncthing uses periodic scanning every 60 seconds to detect file changes. This means checking every file’s modification time and comparing it to the database. This can cause spikes of CPU usage for large folders. .UNINDENT .sp Hashing, compression and encryption cost CPU time. Also, using the GUI causes a certain amount of extra CPU usage to calculate the summary data it presents. Note however that once things are \fIin sync\fP CPU usage should be negligible. .sp To limit the amount of CPU used when syncing and scanning, set the environment variable \fBGOMAXPROCS\fP to the maximum number of CPU cores Syncthing should use at any given moment. For example, \fBGOMAXPROCS=2\fP on a machine with four cores will limit Syncthing to no more than half the system’s CPU power. .sp To reduce CPU spikes from scanning activity, use a filesystem notifications plugin. This is delivered by default via Synctrayzor, Syncthing\-GTK and on Android. For other setups, consider using \fI\%syncthing\-inotify\fP <\fBhttps://github.com/syncthing/syncthing-inotify\fP>\&. .SS Should I keep my device IDs secret? .sp No. The IDs are not sensitive. Given a device ID it’s possible to find the IP address for that device, if global discovery is enabled on it. Knowing the device ID doesn’t help you actually establish a connection to that device or get a list of files, etc. .sp For a connection to be established, both devices need to know about the other’s device ID. It’s not possible (in practice) to forge a device ID. (To forge a device ID you need to create a TLS certificate with that specific SHA\-256 hash. If you can do that, you can spoof any TLS certificate. The world is your oyster!) .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 device\-ids .UNINDENT .UNINDENT .SS What if there is a conflict? .sp Syncthing does recognize conflicts. When a file has been modified on two devices simultaneously and the content actually differs, one of the files will be renamed to \fB.sync\-conflict\-\-