octoleo/syncthing
1
0
Fork 0
mirror of https://github.com/octoleo/syncthing.git synced 2024-12-22 10:58:57 +00:00
Code Issues Packages Projects Releases Wiki Activity

Docs update

Browse Source
This commit is contained in:
Jakob Borg 2015-10-22 08:14:43 +02:00
parent ce52963d2b
commit 7ed3b3dd3a
3 changed files with 339 additions and 145 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
lib/auto/gui.files.go
View File

@ -5,7 +5,7 @@ import (
)
const (
AssetsBuildDate = "Tue, 20 Oct 2015 07:59:38 GMT"
AssetsBuildDate = "Thu, 22 Oct 2015 06:14:16 GMT"
)
func Assets() map[string][]byte {

370
man/syncthing-bep.7
View File

@ -88,15 +88,16 @@ fingerprints (SHA\-256) referred to as "Device IDs".
There is no required order or synchronization among BEP messages except
as noted per message type \- any message type may be sent at any time and
the sender need not await a response to one message before sending
another. Responses MUST however be sent in the same order as the
requests are received.
another.
.sp
The underlying transport protocol MUST be TCP.
.SH MESSAGES
.sp
Every message starts with one 32 bit word indicating the message
version, type and ID, followed by the length of the message. The header
is in network byte order, i.e. big endian.
Every message starts with one 32 bit word indicating the message version, type
and ID, followed by the length of the message. The header is in network byte
order, i.e. big endian. In this document, in diagrams and text, "bit 0" refers
to the \fImost significant\fP bit of a word; "bit 31" is thus the least
significant bit of a 32 bit word.
.INDENT 0.0
.INDENT 3.5
.sp
@ -114,26 +115,33 @@ is in network byte order, i.e. big endian.
.UNINDENT
.UNINDENT
.sp
For BEP v1 the Version field is set to zero. Future versions with
For BEP v1 the \fBVersion\fP field is set to zero. Future versions with
incompatible message formats will increment the Version field. A message
with an unknown version is a protocol error and MUST result in the
connection being terminated. A client supporting multiple versions MAY
retry with a different protocol version upon disconnection.
.sp
The Message ID is set to a unique value for each transmitted request
message. In response messages it is set to the Message ID of the
corresponding request message. The uniqueness requirement implies that
no more than 4096 messages may be outstanding at any given moment. The
ordering requirement implies that a response to a given message ID also
means that all preceding messages have been received, specifically those
which do not otherwise demand a response. Hence their message ID:s may
be reused.
The \fBMessage ID\fP is set to a unique value for each transmitted Request
message. In Response messages it is set to the Message ID of the corresponding
Request message. The uniqueness requirement implies that no more than 4096
request messages may be outstanding at any given moment. For message types
that do not have a corresponding response (Cluster Configuration, Index, etc.)
the Message ID field is irrelevant and SHOULD be set to zero.
.sp
The Type field indicates the type of data following the message header
The \fBType\fP field indicates the type of data following the message header
and is one of the integers defined below. A message of an unknown type
is a protocol error and MUST result in the connection being terminated.
.sp
The Compression bit "C" indicates the compression used for the message.
The \fBCompression\fP bit "C" indicates the compression used for the message.
.sp
For C=0:
.INDENT 0.0
.IP \(bu 2
The Length field contains the length, in bytes, of the uncompressed
message data.
.IP \(bu 2
The message is not compressed.
.UNINDENT
.sp
For C=1:
.INDENT 0.0
@ -148,15 +156,6 @@ The message data is compressed using the LZ4 format and algorithm
described in \fI\%http://www.lz4.org/\fP\&.
.UNINDENT
.sp
For C=0:
.INDENT 0.0
.IP \(bu 2
The Length field contains the length, in bytes, of the uncompressed
message data.
.IP \(bu 2
The message is not compressed.
.UNINDENT
.sp
All data within the message (post decompression, if compression is in
use) MUST be in XDR (RFC 1014) encoding. All fields shorter than 32 bits
and all variable length data MUST be padded to a multiple of 32 bits.
@ -164,10 +163,10 @@ The actual data types in use by BEP, in XDR naming convention, are the
following:
.INDENT 0.0
.TP
.B (unsigned) int
.B (unsigned) int:
(unsigned) 32 bit integer
.TP
.B (unsigned) hyper
.B (unsigned) hyper:
(unsigned) 64 bit integer
.TP
.B opaque<>
@ -200,16 +199,22 @@ ClusterConfigMessage Structure:
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
| Length of ClientName |
| Length of Device Name |
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
/ /
\e ClientName (variable length) \e
\e Device Name (variable length) \e
/ /
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
| Length of ClientVersion |
| Length of Client Name |
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
/ /
\e ClientVersion (variable length) \e
\e Client Name (variable length) \e
/ /
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
| Length of Client Version |
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
/ /
\e Client Version (variable length) \e
/ /
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
| Number of Folders |
@ -225,7 +230,6 @@ ClusterConfigMessage Structure:
/ /
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
Folder Structure:
0 1 2 3
@ -252,7 +256,6 @@ Folder Structure:
/ /
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
Device Structure:
0 1 2 3
@ -264,6 +267,28 @@ Device Structure:
\e ID (variable length) \e
/ /
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
| Length of Name |
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
/ /
\e Name (variable length) \e
/ /
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
| Number of Addresses |
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
| Length of Address |
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
/ /
\e Address (variable length) \e
/ /
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
| Compression |
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
| Length of Cert Name |
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
/ /
\e Cert Name (variable length) \e
/ /
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
| |
+ Max Local Version (64 bits) +
| |
@ -277,7 +302,6 @@ Device Structure:
/ /
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
Option Structure:
0 1 2 3
@ -299,29 +323,110 @@ Option Structure:
.fi
.UNINDENT
.UNINDENT
.SS Fields
.SS Fields (ClusterConfigMessage)
.sp
The ClientName and ClientVersion fields identify 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 ClientName is "syncthing" and an example
ClientVersion is "v0.7.2". The ClientVersion field SHOULD follow the
patterns laid out in the \fI\%Semantic Versioning\fP <\fBhttp://semver.org/\fP>
standard.
The \fBDevice Name\fP is a human readable (configured or auto detected) device
name or host name, for the sending device.
.sp
The Folders field lists all folders that will be synchronized over the
current connection. Each folder has a list of participating Devices,
Flags and Options. Currently no flags are defined so the field MUST be
set to all zeroes. The Options field is implementation specific and
described below.
The \fBClient Name\fP and \fBClient Version\fP identifies the implementation. The
values SHOULD be simple strings identifying the implementation name, as a
user would expect to see it, and the version string in the same manner. An
example Client Name is "syncthing" and an example Client Version is "v0.7.2".
The Client Version field SHOULD follow the patterns laid out in the \fI\%Semantic
Versioning\fP <\fBhttp://semver.org/\fP> standard.
.sp
The Device ID is a 32 byte number that uniquely identifies the device.
For instance, the reference implementation uses the SHA\-256 of the
The \fBFolders\fP field contains the list of folders that will be synchronized
over the current connection.
.sp
The \fBOptions\fP field is a list of options that apply to the current
connection. The options are used in an implementation specific manner. The
options list is conceptually a map of keys to values, although it is
transmitted in the form of a list of key and value pairs, both of string type.
Key ID:s are implementation specific. An implementation MUST ignore unknown
keys. An implementation MAY impose limits on the length keys and values. The
options list may be used to inform devices of relevant local configuration
options such as rate limiting or make recommendations about request
parallelism, device priorities, etc. An empty options list is valid for
devices not having any such information to share. Devices MAY NOT make any
assumptions about peers acting in a specific manner as a result of sent
options.
.SS Fields (Folder Structure)
.sp
The \fBID\fP field contains the folder ID, as a human readable string.
.sp
The \fBDevices\fP field is list of devices participating in sharing this folder.
.sp
The \fBFlags\fP field contains flags that affect the behavior of the folder. The
folder Flags field contains the following single bit flags:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
| Reserved |D|P|R|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B Bit 31 ("R", Read Only)
is set for folders that the device will accept no updates from the network
for.
.TP
.B Bit 30 ("P", Ignore Permissions)
is set for folders that the device will not accept or announce file
permissions for.
.TP
.B Bit 29 ("D", Ignore Deletes)
is set for folders that the device will ignore deletes for.
.UNINDENT
.sp
The \fBOptions\fP field contains a list of options that apply to the folder.
.SS Fields (Device Structure)
.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
Each device has an associated Flags field to indicate the sharing mode
of that device for the folder in question. See the discussion on Sharing
Modes. The Device Flags field contains the following single bit flags:
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 \fBAddressess\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 Local Version\fP field contains the highest local file
version number of the files already known to be in the index sent by
this device. If nothing is known about the index of a given device, this
field MUST be set to zero. When receiving a Cluster Config message with
a non\-zero Max Local Version for the local device ID, a device MAY elect
to send an Index Update message containing only files with higher local
version numbers in place of the initial Index message.
.sp
The \fBFlags\fP field indicates the sharing mode of the folder and other device
& folder specific settings. See the discussion on Sharing Modes. The Device
Flags field contains the following single bit flags:
.INDENT 0.0
.INDENT 3.5
.sp
@ -380,25 +485,7 @@ are reserved and MUST be set to zero.
.sp
Exactly one of the T and R bits MUST be set.
.sp
The per device Max Local Version field contains the highest local file
version number of the files already known to be in the index sent by
this device. If nothing is known about the index of a given device, this
field MUST be set to zero. When receiving a Cluster Config message with
a non\-zero Max Local Version for the local device ID, a device MAY elect
to send an Index Update message containing only files with higher local
version numbers in place of the initial Index message.
.sp
The Options field contain option values to be used in an implementation
specific manner. The options list is conceptually a map of Key => Value
items, although it is transmitted in the form of a list of (Key, Value)
pairs, both of string type. Key ID:s are implementation specific. An
implementation MUST ignore unknown keys. An implementation MAY impose
limits on the length keys and values. The options list may be used to
inform devices of relevant local configuration options such as rate
limiting or make recommendations about request parallelism, device
priorities, etc. An empty options list is valid for devices not having
any such information to share. Devices MAY NOT make any assumptions
about peers acting in a specific manner as a result of sent options.
The \fBOptions\fP field contains a list of options that apply to the device.
.SS XDR
.INDENT 0.0
.INDENT 3.5
@ -406,29 +493,34 @@ about peers acting in a specific manner as a result of sent options.
.nf
.ft C
struct ClusterConfigMessage {
string ClientName<>;
string ClientVersion<>;
Folder Folders<>;
Option Options<>;
string DeviceName<64>;
string ClientName<64>;
string ClientVersion<64>;
Folder Folders<1000000>;
Option Options<64>;
}
struct Folder {
string ID<64>;
Device Devices<>;
string ID<256>;
Device Devices<1000000>;
unsigned int Flags;
Option Options<64>;
}
struct Device {
opaque ID<32>;
string Name<64>;
string Addresses<64>;
unsigned int Compression;
string CertName<64>;
hyper MaxLocalVersion;
unsigned int Flags;
Option Options<64>;
}
struct Option {
string Key<>;
string Value<>;
string Key<64>;
string Value<1024>;
}
.ft P
.fi
@ -475,7 +567,6 @@ IndexMessage Structure:
/ /
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
FileInfo Structure:
0 1 2 3
@ -494,7 +585,7 @@ FileInfo Structure:
| |
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
/ /
\e Vector Structure \e
\e Version (variable length) \e
/ /
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
| |
@ -508,7 +599,6 @@ FileInfo Structure:
/ /
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
Vector Structure:
0 1 2 3
@ -521,7 +611,6 @@ Vector Structure:
/ /
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
Counter Structure:
0 1 2 3
@ -554,32 +643,27 @@ BlockInfo Structure:
.fi
.UNINDENT
.UNINDENT
.SS Fields
.SS Fields (Index Message)
.sp
The Folder field identifies the folder that the index message pertains
to. For single folder implementations the device MUST use the string
"default".
The \fBFolder\fP field identifies the folder that the index message pertains to.
.sp
The Name is the file name path relative to the folder root. Like all
\fBFiles\fP
.sp
The \fBFlags\fP field is reserved for future use and MUST currently be set to
zero.
.sp
The \fBOptions\fP list is implementation defined and as described in the
ClusterConfig message section.
.SS Fields (FileInfo Structure)
.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\(aqs operating system conventions. The combination of Folder
and Name uniquely identifies each file in a cluster.
.sp
The Version field is a version vector describing the updates performed
to file by all members in the cluster. Each counter in the version
vector is an ID\-Value tuple. The ID is used 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 Local Version 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.
.sp
The Flags field (per FileInfo) is made up of the following single bit
flags:
The \fBFlags\fP field is made up of the following single bit flags:
.INDENT 0.0
.INDENT 3.5
.sp
@ -614,10 +698,10 @@ temporarily not serve data for the file.
.TP
.B Bit 17 ("P")
is set when there is no permission information for the
file. This is the case when it originates on a non\-permission\-
supporting file system. 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.
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.
.TP
.B Bit 16 ("S")
is set when the file is a symbolic link. The block list
@ -635,25 +719,26 @@ are reserved for future use and SHALL be set to
zero.
.UNINDENT
.sp
The hash algorithm is implied by the Hash length. Currently, the hash
MUST be 32 bytes long and computed by SHA256.
.sp
The Modified time is expressed as the number of seconds since the Unix
The \fBModified\fP time is expressed as the number of seconds since the Unix
Epoch (1970\-01\-01 00:00:00 UTC).
.sp
In the rare occasion that a file is simultaneously and independently
modified by two devices in the same cluster and thus end up on the same
Version number after modification, the Modified field is used as a tie
breaker (higher being better), followed by the hash values of the file
blocks (lower being better).
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 used 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 Blocks list contains the size and hash for each block in the file.
The \fBLocal Version\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.
.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.
.sp
The Flags field (in IndexMessage) is reserved for future use and MUST
currently be set to zero. The Options list is implementation defined and
as described in the ClusterConfig message section.
The hash algorithm is implied by the \fBHash\fP length. Currently, the hash
MUST be 32 bytes long and computed by SHA256.
.SS XDR
.INDENT 0.0
.INDENT 3.5
@ -661,8 +746,8 @@ as described in the ClusterConfig message section.
.nf
.ft C
struct IndexMessage {
string Folder<>;
FileInfo Files<>;
string Folder<256>;
FileInfo Files<1000000>;
unsigned int Flags;
Option Options<64>;
}
@ -673,7 +758,7 @@ struct FileInfo {
hyper Modified;
Vector Version;
hyper LocalVersion;
BlockInfo Blocks<>;
BlockInfo Blocks<1000000>;
}
struct Vector {
@ -687,7 +772,7 @@ struct Counter {
struct BlockInfo {
unsigned int Size;
opaque Hash<>;
opaque Hash<64>;
}
.ft P
.fi
@ -806,11 +891,11 @@ ResponseMessage Structure:
.UNINDENT
.SS Fields
.sp
The Data field contains either a full 128 KiB block, a shorter block in
The \fBData\fP field contains either a full 128 KiB block, a shorter block in
the case of the last block in a file, or is empty (zero length) if the
requested block is not available.
.sp
The Code field contains an error code describing the reason a Request
The \fBCode\fP field contains an error code describing the reason a Request
could not be fulfilled, in the case where a zero length Data was
returned. The following values are defined:
.INDENT 0.0
@ -845,13 +930,11 @@ struct ResponseMessage {
.UNINDENT
.SS Ping (Type = 4)
.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. The Ping message has no contents.
.SS Pong (Type = 5)
.sp
The Pong message is sent in response to a Ping. The Pong message has no
contents, but copies the Message ID from the Ping.
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. The Ping message has no contents. A Ping message is sent
every 90 seconds, if no other message has been sent in the preceding 90
seconds.
.SS Close (Type = 7)
.sp
The Close message MAY be sent to indicate that the connection will be
@ -882,8 +965,8 @@ CloseMessage Structure:
.UNINDENT
.SS Fields
.sp
The Reason field contains a human description of the error condition,
suitable for consumption by a human. The Code field is for a machine
The \fBReason\fP field contains a human description of the error condition,
suitable for consumption by a human. The \fBCode\fP field is for a machine
readable error code. Codes are reserved for future use and MUST
currently be set to zero.
.INDENT 0.0
@ -1260,17 +1343,16 @@ 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
2 through 5 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 (6 through 9). Device A updates their folder contents
and transmits an Index Update message (10). Both peers enter idle state
after 10. At some later time 11, peer A determines that it has not seen
data from B for some time and sends a Ping request. A response is sent
at 12.
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;

112
man/syncthing-globaldisco.7 Normal file
View File

@ -0,0 +1,112 @@
.\" Man page generated from reStructuredText.
.
.TH "SYNCTHING-GLOBALDISCO" "7" "October 20, 2015" "v0.11" "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 (with the path usually being "/", but this is of
course up to the discovery server). The POST has a JSON payload listing direct
connection addresses (if any) and relay addresses (if any):
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{
direct: ["tcp://192.0.2.45:22000", "tcp://:22202"],
relays: [{"url": "relay://192.0.2.99:22028", "latency": 142}]
}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
It\(aqs OK for either of the "direct" or "relays" fields to be either the empty
list (\fB[]\fP), \fBnull\fP, or missing entirely. An announcment with both fields 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\(aqt conform to the expected format, \fB400\fP (Bad Request) is
returned.
.sp
In successfull responses, the server may return a
.nf
\(ga\(ga
.fi
Reannounce\-After"
.nf
\(ga\(ga
.fi
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/?device=ABC12345\-....\fP
.sp
Successfull 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.
.