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

Docs and translation update

Browse Source
This commit is contained in:
Jakob Borg
2015-09-27 22:31:19 +02:00
parent ad2c05c3f5
commit 3c6bfb880d
40 changed files with 195 additions and 162 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
man/syncthing-config.5
View File

@@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH "SYNCTHING-CONFIG" "5" "August 20, 2015" "v0.11" "Syncthing"
.TH "SYNCTHING-CONFIG" "5" "September 23, 2015" "v0.11" "Syncthing"
.SH NAME
syncthing-config \- Syncthing Configuration
.
@@ -411,7 +411,7 @@ The listen address for incoming sync connections. See the \fBaddress\fP
element under the \fI\%GUI Element\fP for allowed syntax.
.TP
.B globalAnnounceServer
A URI to a global announce (discvoery) server. Allowed protocol prefixes
A URI to a global announce (discovery) server. Allowed protocol prefixes
are \fBudp4://\fP (UDP over IPv4), \fBudp6://\fP (UDP over IPv6) and
\fBudp://\fP (UDP over any available protocol).
.TP

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

@@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH "SYNCTHING-DEVICE-IDS" "7" "August 20, 2015" "v0.11" "Syncthing"
.TH "SYNCTHING-DEVICE-IDS" "7" "September 23, 2015" "v0.11" "Syncthing"
.SH NAME
syncthing-device-ids \- Understanding Device IDs
.
@@ -34,12 +34,12 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.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
interchangably have been "key ID" since the device ID is a direct properties of
interchangably 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 an public/private key pair.
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
@@ -104,10 +104,10 @@ 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 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 an whole number of bytes. The
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
@@ -121,7 +121,7 @@ MFZWI3DBONSGYYLTMRWGC43ENRQXGZDMMFZWI3DBONSGYYLTMRWA====
.UNINDENT
.UNINDENT
.sp
The padding (\fB====\fP) is stripped away, the device ID split in four
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-device-id-format/478\fP>
are added for each group. For presentation purposes the device ID is
@@ -138,14 +138,14 @@ MFZWI3D\-BONSGYC\-YLTMRWG\-C43ENR5\-QXGZDMM\-FZWI3DP\-BONSGYY\-LTMRWAD
.UNINDENT
.SS Connection Establishment
.sp
So now we know what device IDs are, here\(aqs how they are used in Syncthing. When
you add a device ID to the syncthing configuration, Syncthing will attempt to
Now we know what device IDs are, here\(aqs 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\(aqs three possibilities here;
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 hostname, so if you have a static IP or a
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
@@ -161,14 +161,13 @@ any local announcements the global discovery server will be queried
for an address.
.UNINDENT
.sp
Once we have and address and port a TCP connection is established and a TLS
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.
known, the following steps are performed:
.INDENT 0.0
.IP 1. 3
Calculate the remote device ID by using the process above on the
received certificate.
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
@@ -190,7 +189,7 @@ 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\(aqs an infinite
amount of inputs and a finite amount of outputs, so per definition there
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\(aqm going to quote \fI\%stack
@@ -220,13 +219,13 @@ find SHA\-256 collisions scary then your priorities are wrong.
.UNINDENT
.sp
It\(aqs 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
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\(aqt 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\(aqt get in.
.sp
Note also that it\(aqs 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,
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.
@@ -245,7 +244,7 @@ for a given device ID, so can\(aqt 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;
It could be mitigated in several ways:
.INDENT 0.0
.IP \(bu 2
Announcements could be signed by the device private key. This
@@ -255,7 +254,7 @@ 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 to the device to tell the truth.
.IP \(bu 2
The user could statically configure IP or hostname for the devices.
The user could statically configure IP or host name for the devices.
.IP \(bu 2
The user could run a trusted global server.
.UNINDENT
@@ -274,7 +273,7 @@ various possible solutions:
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.").
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

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

@@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH "SYNCTHING-EVENT-API" "7" "August 20, 2015" "v0.11" "Syncthing"
.TH "SYNCTHING-EVENT-API" "7" "September 23, 2015" "v0.11" "Syncthing"
.SH NAME
syncthing-event-api \- Event API
.
@@ -602,7 +602,7 @@ configuration etc.
.fi
.UNINDENT
.UNINDENT
.SS StartupCompleted
.SS StartupComplete
.sp
Emitted exactly once, when initialization is complete and Syncthing is
ready to start exchanging data with other devices.

4
man/syncthing-faq.7
View File

@@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH "SYNCTHING-FAQ" "7" "August 20, 2015" "v0.11" "Syncthing"
.TH "SYNCTHING-FAQ" "7" "September 23, 2015" "v0.11" "Syncthing"
.SH NAME
syncthing-faq \- Frequently Asked Questions
.
@@ -260,7 +260,7 @@ bugs.
.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).
where that is). Command line option \fB\-logfile\fP can be used to specify user\-defined logfile.
.SS How do I upgrade Syncthing?
.INDENT 0.0
.IP \(bu 2

7
man/syncthing-networking.7
View File

@@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH "SYNCTHING-NETWORKING" "7" "August 20, 2015" "v0.11" "Syncthing"
.TH "SYNCTHING-NETWORKING" "7" "September 23, 2015" "v0.11" "Syncthing"
.SH NAME
syncthing-networking \- Firewall Setup
.
@@ -93,11 +93,6 @@ 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.
.sp
You can forward multiple ports corresponding to many machines this way, but
because Syncthing uses session cookies for the entire domain (i.e. your local
machine), you will need to connect to each control panel in a separate browser
instance or explicitly issue a browser reload when switching between them.
.SH AUTHOR
The Syncthing Authors
.SH COPYRIGHT

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

@@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH "SYNCTHING-REST-API" "7" "August 20, 2015" "v0.11" "Syncthing"
.TH "SYNCTHING-REST-API" "7" "September 23, 2015" "v0.11" "Syncthing"
.SH NAME
syncthing-rest-api \- REST API
.

25
man/syncthing-security.7
View File

@@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH "SYNCTHING-SECURITY" "7" "August 20, 2015" "v0.11" "Syncthing"
.TH "SYNCTHING-SECURITY" "7" "September 23, 2015" "v0.11" "Syncthing"
.SH NAME
syncthing-security \- Security Principles
.
@@ -36,11 +36,11 @@ possible for an attacker to join a cluster uninvited, and it should not be
possible to extract private information from intercepted traffic. Currently this
is implemented as follows.
.sp
All traffic is protected by TLS. To prevent uninvited nodes from joining a
cluster, the certificate fingerprint of each node is compared to a preset list
of acceptable nodes at connection establishment. The fingerprint is computed as
the SHA\-256 hash of the certificate and displayed in BASE32 encoding to form a
reasonably compact and convenient string.
All device to device traffic is protected by TLS. To prevent uninvited nodes
from joining a cluster, the certificate fingerprint of each node is compared
to a preset list of acceptable nodes at connection establishment. The
fingerprint is computed as the SHA\-256 hash of the certificate and displayed
in BASE32 encoding to form a reasonably compact and convenient string.
.sp
Incoming requests for file data are verified to the extent that the requested
file name must exist in the local index and the global model.
@@ -51,15 +51,20 @@ for reporting security vulnerabilities, please see the official \fI\%security pa
.SS Global Discovery
.sp
When global discovery is enabled, Syncthing sends an announcement packet every
30 minutes to the global discovery server, so that it can keep a mapping between
your device ID and external IP. Also, when connecting to other devices that have
not been seen on the local network, a query is sent to the global discovery
server containing the device ID of the requested device. The discovery server is
30 minutes to the global discovery server so that it can keep a mapping
between your device ID and external IP. The packets contain the device ID and
listening port. Also, when connecting to other devices that have not been seen
on the local network, a query is sent to the global discovery server
containing the device ID of the requested device. The discovery server is
currently hosted by \fI\%@calmh\fP <\fBhttps://github.com/calmh\fP>\&. Global discovery defaults to \fBon\fP\&.
.sp
When turned off, devices with dynamic addresses not on the local network cannot
be found and connected to.
.sp
An eavesdropper on the Internet can deduce which machines are running
Syncthing with global discovery enabled, what their device IDs are, and what
device IDs they are attempting to connect to via global discovery.
.sp
If a different global discovery server is configured, no data is sent to the
default global discovery server.
.SS Local Discovery

4
man/syncthing-stignore.5
View File

@@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH "SYNCTHING-STIGNORE" "5" "August 20, 2015" "v0.11" "Syncthing"
.TH "SYNCTHING-STIGNORE" "5" "September 23, 2015" "v0.11" "Syncthing"
.SH NAME
syncthing-stignore \- Prevent files from being synchronized to other nodes
.
@@ -93,7 +93,7 @@ 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.
\fB(?i)\fP when combined with other flags. On Mac OS and Windows, patterns are always case\-insensitive.
.IP \(bu 2
A line beginning with \fB//\fP is a comment and has no effect.
.UNINDENT

2
man/syncthing-versioning.7
View File

@@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH "TODO" "7" "August 20, 2015" "v0.11" "Syncthing"
.TH "TODO" "7" "September 23, 2015" "v0.11" "Syncthing"
.SH NAME
Todo \- Keep automatic backups of deleted files by other nodes
.

13
man/syncthing.1
View File

@@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH "SYNCTHING" "1" "August 20, 2015" "v0.11" "Syncthing"
.TH "SYNCTHING" "1" "September 23, 2015" "v0.11" "Syncthing"
.SH NAME
syncthing \- Syncthing
.
@@ -38,9 +38,9 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.ft C
syncthing [\-audit] [\-generate=<dir>] [\-gui\-address=<address>]
[\-gui\-apikey=<key>] [\-gui\-authentication=<username:password>]
[\-home=<dir>] [\-logflags=<flags>] [\-no\-browser] [\-no\-console]
[\-no\-restart] [\-reset] [\-upgrade] [\-upgrade\-check] [\-upgrade\-to=<url>]
[\-verbose] [\-version]
[\-home=<dir>] [\-logfile=<filename>] [\-logflags=<flags>] [\-no\-browser]
[\-no\-console] [\-no\-restart] [\-reset] [\-upgrade] [\-upgrade\-check]
[\-upgrade\-to=<url>] [\-verbose] [\-version]
.ft P
.fi
.UNINDENT
@@ -87,6 +87,11 @@ Set configuration directory. The default configuration directory is:
.UNINDENT
.INDENT 0.0
.TP
.B \-logfile=<filename>
Set destination filename for logging (use \fB"\-"\fP for stdout, which is the default option).
.UNINDENT
.INDENT 0.0
.TP
.B \-logflags=<flags>
Select information in log line prefix, default 2. The \fB\-logflags\fP value is
a sum of the following: