perso/syncthing-arm
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

gui, man: Update docs & translations

Browse Source 
GitHub-Pull-Request: https://github.com/syncthing/syncthing/pull/3034
This commit is contained in:
Jakob Borg
2016-05-04 19:47:08 +00:00
parent 674fc566bb
commit 459930df09
48 changed files with 596 additions and 214 deletions
Download Patch File Download Diff File Expand all files Collapse all files

361
man/syncthing-bep.7
View File

@@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH "SYNCTHING-BEP" "7" "April 14, 2016" "v0.12" "Syncthing"
.TH "SYNCTHING-BEP" "7" "May 01, 2016" "v0.12" "Syncthing"
.SH NAME
syncthing-bep \- Block Exchange Protocol v1
.
@@ -90,8 +90,91 @@ 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 be TCP.
.SH MESSAGES
The underlying transport protocol MUST guarantee reliable packet delivery.
.SH PRE-AUTHENTICATION MESSAGES
.sp
AFTER establishing a connection, but BEFORE performing any authentication,
\fIdevices\fP 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.
.sp
Hello messages MUST be prefixed with a magic number \fB0x9F79BC40\fP
represented in network byte order (BE), followed by 4 bytes representing the
size of the message in network byte order (BE), followed by the content of
the Hello message itself. The size of the contents of Hello message MUST be
less or equal to 1024 bytes.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
Prefix 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
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
| Magic |
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
| Length |
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
/ /
\e Content of HelloMessage \e
/ /
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
HelloMessage 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
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
/ /
\e Device Name (length + padded data) \e
/ /
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
/ /
\e Client Name (length + padded data) \e
/ /
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
/ /
\e Client Version (length + padded data) \e
/ /
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Fields (HelloMessage)
.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.
.SS XDR
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
struct HelloMessage {
string DeviceName<64>;
string ClientName<64>;
string ClientVersion<64>;
};
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Immediately after exchanging Hello messages, the connection should be
dropped if device does not pass authentication.
.SH POST-AUTHENTICATION 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
@@ -199,24 +282,6 @@ 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 Device Name |
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
/ /
\e Device Name (variable length) \e
/ /
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
| Length of Client Name |
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
/ /
\e Client Name (variable length) \e
/ /
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
| Length of Client Version |
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
/ /
\e Client Version (variable length) \e
/ /
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
| Number of Folders |
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
/ /
@@ -329,16 +394,6 @@ Option Structure:
.UNINDENT
.SS Fields (ClusterConfigMessage)
.sp
The \fBDevice Name\fP is a human readable (configured or auto detected) device
name or host name, for the sending 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
The \fBFolders\fP field contains the list of folders that will be synchronized
over the current connection.
.sp
@@ -372,7 +427,7 @@ folder Flags field contains the following single bit flags:
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|
| Reserved |T|D|P|R|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
.ft P
.fi
@@ -390,6 +445,15 @@ permissions for.
.TP
.B Bit 29 ("D", Ignore Deletes)
is set for folders that the device will ignore deletes for.
.TP
.B Bit 28 ("T", Disable Temporary Indexes)
is set for folders that will not dispatch and do not wish to receive
progress updates about partially downloaded files via DownloadProgress
.INDENT 7.0
.INDENT 3.5
messages.
.UNINDENT
.UNINDENT
.UNINDENT
.sp
The \fBOptions\fP field contains a list of options that apply to the folder.
@@ -464,7 +528,7 @@ cluster introducers.
.B Bits 16 through 28
are reserved and MUST be set to zero.
.TP
.B Bits 14\-15 ("Pri)
.B Bits 14\-15 ("Pri", Priority)
indicate the device\(aqs upload priority for this
folder. Possible values are:
.INDENT 7.0
@@ -499,9 +563,6 @@ The \fBOptions\fP field contains a list of options that apply to the device.
.nf
.ft C
struct ClusterConfigMessage {
string DeviceName<64>;
string ClientName<64>;
string ClientVersion<64>;
Folder Folders<1000000>;
Option Options<64>;
};
@@ -852,8 +913,35 @@ 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 Flags field is reserved for future use and MUST currently be set to
zero. The Options list is implementation defined and as described in the
The \fBFlags\fP field is made up of 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 |T|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B Bit 31 ("T", Temporary)
is set to indicate that the read should be performed
from the temporary file (converting Name to it\(aqs temporary form) and falling
back to the non temporary file if any error occurs. Knowledge of content
.INDENT 7.0
.INDENT 3.5
inside temporary files comes from DownloadProgress messages.
.UNINDENT
.UNINDENT
.UNINDENT
.sp
The Options list is implementation defined and as described in the
ClusterConfig message section.
.SS XDR
.INDENT 0.0
@@ -939,6 +1027,159 @@ struct ResponseMessage {
.fi
.UNINDENT
.UNINDENT
.SS DownloadProgress (Type = 8)
.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 structures.
.SS Graphical Representation
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
DownloadProgressMessage 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
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
/ /
\e Folder (length + padded data) \e
/ /
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
| Number of Updates |
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
/ /
\e Zero or more FileDownloadProgressUpdate Structures \e
/ /
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
| Flags |
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
| Number of Options |
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
/ /
\e Zero or more Option Structures \e
/ /
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
FileDownloadProgressUpdate 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
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
| Update Type |
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
/ /
\e Name (length + padded data) \e
/ /
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
/ /
\e Version Structure \e
/ /
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
| Number of Block Indexes |
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
/ /
| Block Indexes (n items) |
/ /
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Each
.SS Fields (DownloadProgress Message)
.sp
\fBFolder\fP represents the ID of the folder for which the update is being
provided.
.sp
The \fBFlags\fP field is reserved for future use and MUST currently be set to
zero. The \fBOptions\fP field contains a list of options that apply to the update.
.SS Fields (FileDownloadProgressUpdate Structure)
.sp
The \fBUpdate Type\fP field is made up of 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 |F|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B Bit 31 ("F", Forget)
is set to notify that the file that was previously
advertised is no longer available (at least as a temporary file).
.UNINDENT
.sp
The \fBName\fP field defines the file name from the global index for which this
update is being sent.
.sp
The \fBVersion\fP structure defines the version of the file for which this update
is being sent.
.sp
\fBBlock Indexes\fP is a list of positive integers, where each integer represents
the index of the block in the FileInfo structure Blocks array that has become
available for download.
For example an integer with with value 3 represents that the data defined in the
fourth BlockInfo structure of the FileInfo structure 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
structure 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
\fBForget\fP bit being set implies that the file that was previously advertised
is no longer available, therefore the list of block indexes should be truncated.
.sp
Messages with \fBForget\fP bit 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 preceeded with an update message for the old version of that
file with the \fBForget\fP bit set.
.sp
As a safeguard on the receiving side, 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 XDR
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
struct DownloadProgressMessage {
string Folder<64>;
FileDownloadProgressUpdate Updates<1000000>;
unsigned int Flags;
Option Options<64>;
}
struct FileDownloadProgressUpdate {
unsigned int UpdateType;
string Name<8192>;
Vector Version;
int BlockIndexes<1000000>;
}
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Ping (Type = 4)
.sp
The Ping message is used to determine that a connection is alive, and to keep
@@ -1224,6 +1465,50 @@ T} T{
1024 bytes
T}
_
T{
\fBDownload Progress Messages\fP
T}
_
T{
.nf
.fi
T} T{
Folder
T} T{
64 bytes
T}
_
T{
.nf
.fi
T} T{
Number of Updates
T} T{
1.000.000
T}
_
T{
.nf
.fi
T} T{
Name
T} T{
8192 bytes
T}
_
T{
.nf
.fi
T} T{
Number of Indexes
T} T{
1.000.000
T}
_
.TE
.sp
The currently defined values allow maximum file size of 1220 GiB

2
man/syncthing-config.5
View File

@@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH "SYNCTHING-CONFIG" "5" "April 14, 2016" "v0.12" "Syncthing"
.TH "SYNCTHING-CONFIG" "5" "May 01, 2016" "v0.12" "Syncthing"
.SH NAME
syncthing-config \- Syncthing Configuration
.

2
man/syncthing-device-ids.7
View File

@@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH "SYNCTHING-DEVICE-IDS" "7" "April 14, 2016" "v0.12" "Syncthing"
.TH "SYNCTHING-DEVICE-IDS" "7" "May 01, 2016" "v0.12" "Syncthing"
.SH NAME
syncthing-device-ids \- Understanding Device IDs
.

2
man/syncthing-event-api.7
View File

@@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH "SYNCTHING-EVENT-API" "7" "April 14, 2016" "v0.12" "Syncthing"
.TH "SYNCTHING-EVENT-API" "7" "May 01, 2016" "v0.12" "Syncthing"
.SH NAME
syncthing-event-api \- Event API
.

176
man/syncthing-faq.7
View File

@@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH "SYNCTHING-FAQ" "7" "April 14, 2016" "v0.12" "Syncthing"
.TH "SYNCTHING-FAQ" "7" "May 01, 2016" "v0.12" "Syncthing"
.SH NAME
syncthing-faq \- Frequently Asked Questions
.
@@ -116,6 +116,54 @@ 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 "Remove
Devices" list on the right side of the GUI, double check that you see
"Address: <some address>" and \fInot\fP "Relay: <some address>".
[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.
.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\(aqs CPU power.
.SS Should I keep my device IDs secret?
.sp
No. The IDs are not sensitive. Given a device ID it\(aqs possible to find the IP
@@ -155,55 +203,50 @@ causes a conflict on change you\(aqll end up with \fBsync\-conflict\-...sync\-co
.SS How to configure multiple users on a single machine?
.sp
Each user should run their own Syncthing instance. Be aware that you might need
to configure ports such that they do not overlap (see the config.xml).
to configure listening ports such that they do not overlap (see config).
.SS Does Syncthing support syncing between folders on the same system?
.sp
Syncthing is not designed to sync locally and the overhead involved in doing so will waste resources. There are better programs to achieve this such as rsync or Unison.
No. Syncthing is not designed to sync locally and the overhead involved in
doing so using Syncthing\(aqs method would be wasteful. There are better
programs to achieve this such as rsync or Unison.
.SS Is Syncthing my ideal backup application?
.sp
No, Syncthing is not a backup application because all changes to your files
(modification, deletion, etc) will be propagated to all your devices. You can
enable versioning, but we encourage the use of other tools to keep your data
safe from your (or our) mistakes.
No. Syncthing is not a great backup application because all changes to your
files (modifications, deletions, etc) will be propagated to all your
devices. You can enable versioning, but we encourage the use of other tools
to keep your data safe from your (or our) mistakes.
.SS Why is there no iOS client?
.sp
An alternative implementation of Syncthing (using the Syncthing protocol) is being
developed at this point in time to enable iOS support. Additionally, it seems
that the next version of Go will support the darwin\-arm architecture such that
we can compile the mainstream code for the iOS platform.
.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 first compressed and then
encrypted using AES\-128. When receiving data, it must be decrypted
and decompressed.
.UNINDENT
.sp
Hashing, compression and encryption cost CPU time. Also, using the GUI causes a
certain amount of CPU usage. Note however that once things are \fIin sync\fP CPU
usage should be negligible.
There is an alternative implementation of Syncthing (using the same network
protocol) called \fBfsync()\fP\&. There are no plans by the current Syncthing
team to support iOS in the foreseeable future, as the code required to do so
would be quite different from what Syncthing is today.
.SS How can I exclude files with brackets (\fB[]\fP) in the name?
.sp
The patterns in .stignore are glob patterns, where brackets are used to denote
character ranges. That is, the pattern \fBq[abc]x\fP will match the files \fBqax\fP,
\fBqbx\fP and \fBqcx\fP\&.
The patterns in .stignore are glob patterns, where brackets are used to
denote character ranges. That is, the pattern \fBq[abc]x\fP will match the
files \fBqax\fP, \fBqbx\fP and \fBqcx\fP\&.
.sp
To match an actual file \fIcalled\fP \fBq[abc]x\fP the pattern needs to "escape" the
brackets, like so: \fBq\e[abc\e]x\fP\&.
To match an actual file \fIcalled\fP \fBq[abc]x\fP the pattern needs to "escape"
the brackets, like so: \fBq\e[abc\e]x\fP\&.
.sp
On Windows, escaping special characters is not supported as the \fB\e\fP
character is used as a path separator. On the other hand, special characters
such as \fB[\fP and \fB?\fP are not allowed in file names on Windows.
.SS Why is the setup more complicated than BTSync?
.sp
Security over convenience. In Syncthing you have to setup both sides to connect
two nodes. An attacker can\(aqt do much with a stolen node ID, because you have to
add the node on the other side too. You have better control where your files are
transferred.
Security over convenience. In Syncthing you have to setup both sides to
connect two nodes. An attacker can\(aqt do much with a stolen node ID, because
you have to add the node on the other side too. You have better control
where your files are transferred.
.sp
This is an area that we are working to improve in the long term.
.SS How do I access the web GUI from another computer?
.sp
The default listening address is 127.0.0.1:8384, so you can only access the GUI
from the same machine. Change the \fBGUI listen address\fP through the web UI from
\fB127.0.0.1:8384\fP to \fB0.0.0.0:8384\fP or change the config.xml:
The default listening address is 127.0.0.1:8384, so you can only access the
GUI from the same machine. This is for security reasons. Change the \fBGUI
listen address\fP through the web UI from \fB127.0.0.1:8384\fP to
\fB0.0.0.0:8384\fP or change the config.xml:
.INDENT 0.0
.INDENT 3.5
.sp
@@ -229,11 +272,12 @@ to
.UNINDENT
.UNINDENT
.sp
Then the GUI is accessible from everywhere. You should most likely set a
password and enable HTTPS now. You can do this from inside the GUI.
Then the GUI is accessible from everywhere. You should set a password and
enable HTTPS with this configuration. You can do this from inside the GUI.
.sp
If both your computers are Unixy (Linux, Mac, etc) You can also leave the GUI
settings at default and use an ssh port forward to access it. For example,
If both your computers are Unixy (Linux, Mac, etc) You can also leave the
GUI settings at default and use an ssh port forward to access it. For
example,
.INDENT 0.0
.INDENT 3.5
.sp
@@ -245,48 +289,48 @@ $ ssh \-L 9090:127.0.0.1:8384 user@othercomputer.example.com
.UNINDENT
.UNINDENT
.sp
will log you into othercomputer.example.com, and present the \fIremote\fP Syncthing
GUI on \fI\%http://localhost:9090\fP on your \fIlocal\fP computer. You should not open more
than one Syncthing GUI in a single browser due to conflicting X\-CSRFTokens. Any
modification will be rejected. See \fI\%issue #720\fP <\fBhttps://github.com/syncthing/syncthing/issues/720\fP> to work around this limitation.
.sp
The CSRF tokens are stored using cookies. Therefore, if you get the message
\fBSyncthing seems to be experiencing a problem processing your request\fP, you
should verify the cookie settings of your browser.
will log you into othercomputer.example.com, and present the \fIremote\fP
Syncthing GUI on \fI\%http://localhost:9090\fP on your \fIlocal\fP computer.
.SS Why do I see Syncthing twice in task manager?
.sp
One process manages the other, to capture logs and manage restarts. This makes
it easier to handle upgrades from within Syncthing itself, and also ensures that
we get a nice log file to help us narrow down the cause for crashes and other
bugs.
One process manages the other, to capture logs and manage restarts. This
makes it easier to handle upgrades from within Syncthing itself, and also
ensures that we get a nice log file to help us narrow down the cause for
crashes and other bugs.
.SS Where do Syncthing logs go to?
.sp
Syncthing logs to stdout by default. On Windows Syncthing by default also
creates \fBsyncthing.log\fP in Syncthing\(aqs home directory (check \fB\-help\fP to see
where that is). Command line option \fB\-logfile\fP can be used to specify a user\-defined logfile.
creates \fBsyncthing.log\fP in Syncthing\(aqs home directory (run \fBsyncthing
\-paths\fP to see where that is). Command line option \fB\-logfile\fP can be used
to specify a user\-defined logfile.
.SS How do I upgrade Syncthing?
.sp
If you use a package manager such as Debian\(aqs apt\-get, you should upgrade
using the package manager. If you use the binary packages linked from
Syncthing.net, you can use Syncthing built in automatic upgrades.
.INDENT 0.0
.IP \(bu 2
If automatic upgrades is enabled (which is the default), Syncthing will
upgrade itself automatically within 24 hours of a new release.
.IP \(bu 2
The upgrade button appears in the web GUI when a new version has been released.
Pressing it will perform an upgrade.
The upgrade button appears in the web GUI when a new version has been
released. Pressing it will perform an upgrade.
.IP \(bu 2
To force an upgrade from the command line, run \fBsyncthing \-upgrade\fP\&.
.UNINDENT
.sp
Note that your system should have CA certificates installed which allow a secure
connection to GitHub (e.g. FreeBSD requires \fBsudo pkg install ca_root_nss\fP).
If \fBcurl\fP or \fBwget\fP works with normal HTTPS sites, then so should Syncthing.
Note that your system should have CA certificates installed which allow a
secure connection to GitHub (e.g. FreeBSD requires \fBsudo pkg install
ca_root_nss\fP). If \fBcurl\fP or \fBwget\fP works with normal HTTPS sites, then
so should Syncthing.
.SS Where do I find the latest release?
.sp
We release new versions through GitHub. The latest release is always found \fI\%on
the release page\fP <\fBhttps://github.com/syncthing/syncthing/releases/latest\fP>\&.
Unfortunately GitHub does not provide a single URL to automatically download the
latest version. We suggest to use the GitHub API at
\fI\%https://api.github.com/repos/syncthing/syncthing/releases/latest\fP and parsing the
JSON response.
We release new versions through GitHub. The latest release is always found
\fI\%on the release page\fP <\fBhttps://github.com/syncthing/syncthing/releases/latest\fP>\&. Unfortunately
GitHub does not provide a single URL to automatically download the latest
version. We suggest to use the GitHub API at
\fI\%https://api.github.com/repos/syncthing/syncthing/releases/latest\fP and parsing
the JSON response.
.SH AUTHOR
The Syncthing Authors
.SH COPYRIGHT

2
man/syncthing-globaldisco.7
View File

@@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH "SYNCTHING-GLOBALDISCO" "7" "April 14, 2016" "v0.12" "Syncthing"
.TH "SYNCTHING-GLOBALDISCO" "7" "May 01, 2016" "v0.12" "Syncthing"
.SH NAME
syncthing-globaldisco \- Global Discovery Protocol v3
.

2
man/syncthing-localdisco.7
View File

@@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH "SYNCTHING-LOCALDISCO" "7" "April 14, 2016" "v0.12" "Syncthing"
.TH "SYNCTHING-LOCALDISCO" "7" "May 01, 2016" "v0.12" "Syncthing"
.SH NAME
syncthing-localdisco \- Local Discovery Protocol v3
.

5
man/syncthing-networking.7
View File

@@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH "SYNCTHING-NETWORKING" "7" "April 14, 2016" "v0.12" "Syncthing"
.TH "SYNCTHING-NETWORKING" "7" "May 01, 2016" "v0.12" "Syncthing"
.SH NAME
syncthing-networking \- Firewall Setup
.
@@ -95,6 +95,9 @@ ssh \-L 9999:localhost:8384 machine
This will bind to your local port 9999 and forward all connections from there to
port 8384 on the target machine. This still works even if Syncthing is bound to
listen on localhost only.
.SH VIA A PROXY
.sp
Syncthing can use a SOCKS5 proxy for outbound connections. Please see proxying\&.
.SH AUTHOR
The Syncthing Authors
.SH COPYRIGHT

2
man/syncthing-relay.7
View File

@@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH "SYNCTHING-RELAY" "7" "April 14, 2016" "v0.12" "Syncthing"
.TH "SYNCTHING-RELAY" "7" "May 01, 2016" "v0.12" "Syncthing"
.SH NAME
syncthing-relay \- Relay Protocol v1
.

2
man/syncthing-rest-api.7
View File

@@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH "SYNCTHING-REST-API" "7" "April 14, 2016" "v0.12" "Syncthing"
.TH "SYNCTHING-REST-API" "7" "May 01, 2016" "v0.12" "Syncthing"
.SH NAME
syncthing-rest-api \- REST API
.

2
man/syncthing-security.7
View File

@@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH "SYNCTHING-SECURITY" "7" "April 14, 2016" "v0.12" "Syncthing"
.TH "SYNCTHING-SECURITY" "7" "May 01, 2016" "v0.12" "Syncthing"
.SH NAME
syncthing-security \- Security Principles
.

29
man/syncthing-stignore.5
View File

@@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH "SYNCTHING-STIGNORE" "5" "April 14, 2016" "v0.12" "Syncthing"
.TH "SYNCTHING-STIGNORE" "5" "May 01, 2016" "v0.12" "Syncthing"
.SH NAME
syncthing-stignore \- Prevent files from being synchronized to other nodes
.
@@ -49,6 +49,14 @@ If some files should not be synchronized to other nodes, a file called
\fB\&.stignore\fP file itself will never be synced to other nodes, although it can
\fB#include\fP files that \fIare\fP synchronized between nodes. All patterns are
relative to the repository 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
@@ -83,25 +91,34 @@ patterns from a file in a subdirectory, the patterns themselves are
still relative to the repository \fIroot\fP\&. Example:
\fB#include more\-patterns.txt\fP\&.
.IP \(bu 2
A pattern beginning with \fB!\fP negates the pattern: matching files
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\(aqt know what files it might contain.
.IP \(bu 2
A pattern beginning with \fB(?i)\fP enables case\-insensitive pattern
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. Note that case\-insensitive patterns must start with
\fB(?i)\fP when combined with other flags. On Mac OS and Windows,
patterns are always case\-insensitive.
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.
.UNINDENT
.UNINDENT
.SH EXAMPLE
.sp
Given a directory layout:

2
man/syncthing-versioning.7
View File

@@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH "TODO" "7" "April 14, 2016" "v0.12" "Syncthing"
.TH "TODO" "7" "May 01, 2016" "v0.12" "Syncthing"
.SH NAME
Todo \- Keep automatic backups of deleted files by other nodes
.

2
man/syncthing.1
View File

@@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH "SYNCTHING" "1" "April 14, 2016" "v0.12" "Syncthing"
.TH "SYNCTHING" "1" "May 01, 2016" "v0.12" "Syncthing"
.SH NAME
syncthing \- Syncthing
.