octoleo/syncthing
1
0
Fork 0
mirror of https://github.com/octoleo/syncthing.git synced 2024-11-08 22:31:04 +00:00
Code Issues Packages Projects Releases Wiki Activity

Include generated man pages

Browse Source
This commit is contained in:
Jakob Borg 2015-05-30 13:05:37 +02:00
parent 8bb18fa988
commit db52646655
13 changed files with 2904 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
build.sh
View File

@ -47,6 +47,8 @@ case "${1:-default}" in
prerelease)
go run build.go transifex
git add -A gui/assets/ internal/auto/
pushd man ; ./refresh.sh ; popd
git add -A man
echo
echo Changelog:
go run changelog.go

3
man/README.md Normal file
View File

@ -0,0 +1,3 @@
These manual pages are generates on http://docs.syncthing.net/, based on
the https://github.com/syncthing/docs repo. Do not edit them in this
repo.

8
man/refresh.sh Executable file
View File

@ -0,0 +1,8 @@
#!/bin/sh
base=http://docs.syncthing.net/man/
pages=(syncthing-config.5 syncthing-device-ids.7 syncthing-event-api.7 syncthing-faq.7 syncthing-networking.7 syncthing-rest-api.7 syncthing-security.7 syncthing-stignore.5 syncthing-versioning.7 syncthing.1)
for page in "${pages[@]}" ; do
curl -sLO "$base$page"
done

270
man/syncthing-config.5 Normal file
View File

@ -0,0 +1,270 @@
.\" Man page generated from reStructuredText.
.
.TH "SYNCTHING-CONFIG" "5" "May 30, 2015" "v0.11" "Syncthing"
.SH NAME
syncthing-config \- Syncthing Configuration
.
.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
..
.sp
\fBWARNING:\fP
.INDENT 0.0
.INDENT 3.5
This page may be outdated and requires review.
Attributes have been added that are not documented.
.UNINDENT
.UNINDENT
.SH SYNOPSIS
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$HOME/.config/syncthing/config.xml
$HOME/Library/Application Support/Syncthing
%AppData%/Syncthing
%localappdata%/Syncthing
.ft P
.fi
.UNINDENT
.UNINDENT
.SH DESCRIPTION
.sp
Syncthing uses a single directory to store configuration, crypto keys
and index caches. The location defaults to \fB$HOME/.config/syncthing\fP
(Unix\-like), \fB$HOME/Library/Application Support/Syncthing\fP (Mac),
\fB%AppData%/Syncthing\fP (Windows XP) or \fB%localappdata%/Syncthing\fP
(Windows 7/8). It can be changed at runtime using the \fB\-home\fP flag. In this
directory the following files are located:
.INDENT 0.0
.TP
.B cert.pem
The device\(aqs RSA public key, named "cert" for legacy reasons.
.TP
.B key.pem
The device\(aqs RSA private key. This needs to be protected.
.TP
.B config.xml
The configuration file, in XML format.
.TP
.B https\-cert.pem
The certificate for HTTPS GUI connections.
.TP
.B https\-key.pem
The key for HTTPS GUI connections.
.TP
.B index/
A directory holding the database with metadata and hashes of the files
currently on disk and available from peers.
.TP
.B csrftokens.txt
A list of recently issued CSRF tokens (for protection against browser cross
site request forgery).
.UNINDENT
.SH CONFIG FILE FORMAT
.sp
The following is shows the default configuration file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
<configuration version="2">
<folder id="default" directory="/Users/jb/Sync" ro="false" ignorePerms="false">
<device id="GXN5ECCWTA2B7EB5FXYL5OWGOADX5EF5VNJAQSIBAY6XHJ24BNOA"></device>
</folder>
<device id="GXN5ECCWTA2B7EB5FXYL5OWGOADX5EF5VNJAQSIBAY6XHJ24BNOA" name="jborg\-mbp">
<address>dynamic</address>
</device>
<gui enabled="true" tls="true">
<address>127.0.0.1:54096</address>
<user>jb</user>
<password>$2a$10$EKaTIcpz2...</password>
<apikey>O80CDOJ9LVUVCMHFK2OJDO4T882735</apikey>
</gui>
<options>
<listenAddress>:54097</listenAddress>
<globalAnnounceServer>announce.syncthing.net:22025</globalAnnounceServer>
<globalAnnounceEnabled>true</globalAnnounceEnabled>
<localAnnounceEnabled>true</localAnnounceEnabled>
<parallelRequests>16</parallelRequests>
<maxSendKbps>0</maxSendKbps>
<rescanIntervalS>60</rescanIntervalS>
<reconnectionIntervalS>60</reconnectionIntervalS>
<maxChangeKbps>10000</maxChangeKbps>
<startBrowser>true</startBrowser>
<upnpEnabled>true</upnpEnabled>
<urAccepted>0</urAccepted>
</options>
</configuration>
.ft P
.fi
.UNINDENT
.UNINDENT
.SS configuration
.sp
This is the root element.
.INDENT 0.0
.TP
.B version
The config version. The current version is \fB2\fP\&.
.UNINDENT
.SS folder
.sp
One or more \fBfolder\fP elements must be present in the file. Each
element describes one folder.
.sp
Within the \fBfolder\fP element one or more \fBdevice\fP element should be
present. These must contain the \fBid\fP attribute and nothing else.
Mentioned devices are those that will be sharing the folder in question.
Each mentioned device must have a separate \fBdevice\fP element later in
the file. It is customary that the local device ID is included in all
repositories. Syncthing will currently add this automatically if it is
not present in the configuration file.
.INDENT 0.0
.TP
.B id
The folder ID, must be unique. (mandatory)
.TP
.B directory
The directory where the folder is stored on this
device; not sent to other devices. (mandatory)
.TP
.B ro
True if the folder is read only (will not be modified by Syncthing) on this
device. (optional, defaults to \fBfalse\fP)
.TP
.B ignorePerms
True if the folder should \fI\%ignore permissions\fP <\fBhttp://forum.syncthing.net/t/263\fP>\&.
.UNINDENT
.SS device
.sp
One or more \fBdevice\fP elements must be present in the file. Each
element describes a device participating in the cluster. It is customary
to include a \fBdevice\fP element for the local device; Syncthing will
currently add one if it is not present.
.INDENT 0.0
.TP
.B id
The device ID. This must be written in canonical form, that is without any
spaces or dashes. (mandatory)
.TP
.B name
A friendly name for the device. (optional)
.TP
.B address
The address section is only valid inside of \fBdevice\fP elements. It contains
a single address, on one of the following forms:
.INDENT 7.0
.IP \(bu 2
IPv4 addresses, IPv6 addresses within brackets, or DNS names, all
optionally followed by a port number.
.IP \(bu 2
\fBdynamic\fP: The address will be resolved using discovery.
.UNINDENT
.UNINDENT
.SS gui
.sp
There must be \fIexactly one\fP \fBgui\fP element.
.INDENT 0.0
.TP
.B enabled
\fBtrue\fP/\fBfalse\fP
.TP
.B tls
\fBtrue\fP/\fBfalse\fP: If true then the GUI will use HTTPS.
.TP
.B address
One or more address elements must be present, containing an \fBip:port\fP
listen address.
.TP
.B username
Set to require authentication.
.TP
.B password
Contains the bcrypt hash of the real password.
.TP
.B apikey
If set, this is the API key that enables usage of the REST interface.
.UNINDENT
.sp
Additionally, there must be \fIexactly one\fP \fBoptions\fP element. It contains the
following configuration settings as children:
.INDENT 0.0
.TP
.B listenAddress
\fBhost:port\fP or \fB:port\fP string denoting an address to listen for BEP
connections. More than one \fBlistenAddress\fP may be given.
(default: \fB0.0.0.0:22000\fP)
.TP
.B globalAnnounceServer
\fBhost:port\fP string denoting where a global announce server may be
reached. (default: \fBannounce.syncthing.net:22025\fP)
.TP
.B globalAnnounceEnabled
\fBtrue\fP/\fBfalse\fP (default: \fBtrue\fP)
.TP
.B localAnnounceEnabled
\fBtrue\fP/\fBfalse\fP (default: \fBtrue\fP)
.TP
.B parallelRequests
The maximum number of outstanding block requests to have against any given
peer. (default: \fB16\fP)
.TP
.B maxSendKbps
Rate limit
.TP
.B rescanIntervalS
The number of seconds to wait between each scan for modification of the
local repositories. A value of \fB0\fP disables the scanner. (default: \fB60\fP)
.TP
.B reconnectionIntervalS
The number of seconds to wait between each attempt to connect to currently
unconnected devices. (default: \fB60\fP)
.TP
.B maxChangeKbps
The maximum rate of change allowed for a single file. When this rate is
exceeded, further changes to the file are not announced, until the rate is
reduced below the limit. (default: \fB10000\fP)
.TP
.B startBrowser
\fBtrue\fP/\fBfalse\fP (default: \fBtrue\fP)
.TP
.B upnpEnabled
\fBtrue\fP/\fBfalse\fP (default: \fBtrue\fP)
.TP
.B urAccepted
Whether the user as accepted to submit anonymous usage data. The default,
\fB0\fP, mean the user has not made a choice, and Syncthing will ask at some
point in the future. \fB\-1\fP means no, \fB1\fP means yes.
.UNINDENT
.SH AUTHOR
The Syncthing Authors
.SH COPYRIGHT
2015, The Syncthing Authors
.\" Generated by docutils manpage writer.
.

272
man/syncthing-device-ids.7 Normal file
View File

@ -0,0 +1,272 @@
.\" Man page generated from reStructuredText.
.
.TH "SYNCTHING-DEVICE-IDS" "7" "May 30, 2015" "v0.11" "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
interchangably have been "key ID" since the device ID is a direct properties 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.
.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\(aqt 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 an 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
\fBMFZWI3DBONSGYYLTMRWGC43ENRQXGZDMMFZWI3DBONSGYYLTMRWA====\fP\&.
.sp
The padding (\fB====\fP) is stripped away, the device ID split in 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
grouped with dashes, resulting in the final value:
\fBMFZWI3D\-BONSGYC\-YLTMRWG\-C43ENR5 \-QXGZDMM\-FZWI3DP\-BONSGYY\-LTMRWAD\fP\&.
.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
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;
.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
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\(aqve seen one of these broadcasts for a given
device ID that\(aqs 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\(aqt have a static address and haven\(aqt seen
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
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 using the process above on the
received certificate.
.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\(aqs an infinite
amount of inputs and a finite amount of outputs, so per definition there
are infinitely many messages that result in the same hash.
.sp
I\(aqm going to quote \fI\%stack
overflow\fP <\fBhttp://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\(aqs 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\(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
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,
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\(aqt find the real device
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;
.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 to the device to tell the truth.
.IP \(bu 2
The user could statically configure IP or hostname for the devices.
.IP \(bu 2
The user could run a trusted global server.
.UNINDENT
.sp
It\(aqs 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\(aqs 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\(aqt 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.
.

610
man/syncthing-event-api.7 Normal file
View File

@ -0,0 +1,610 @@
.\" Man page generated from reStructuredText.
.
.TH "SYNCTHING-EVENT-API" "7" "May 30, 2015" "v0.11" "Syncthing"
.SH NAME
syncthing-event-api \- Event 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 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?since=<lastSeenID>\fP,
where \fB<lastSeenID>\fP is the ID of the last event you\(aqve already seen or zero.
Syncthing returns a JSON encoded array of event objects, starting at the event
just after the one with the last seen ID. 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<lastSeenID>\fP, the HTTP call blocks and
waits for new events to happen before returning, or if no new events are
produced within 60 seconds, times out.
.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\&.
.SH 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,
"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, \fBtime\fP, \fBtype\fP and \fBdata\fP are always present,
though \fBdata\fP may be \fBnull\fP\&.
.INDENT 0.0
.TP
.B id
A monotonically increasing integer. The first event generated has id \fB1\fP,
the next has id \fB2\fP etc.
.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
.SH EVENTS
.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"
}
}
.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 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 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 has been finished or failed for that file/folder. There is
always a last event emitted with no data, which implies all downloads
being 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 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": "unique"
}
}
.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 or \fBdelete\fP\&.
.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 or \fBdelete\fP\&.
.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 Ping
.sp
The Ping event is generated automatically every 60 seconds. This means
that even in the absence of any other activity, the event polling HTTP
request will return within a minute.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{
"id": 46,
"type": "Ping",
"time": "2014\-07\-13T21:13:18.502171586+02:00",
"data": null
}
.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 StartupCompleted
.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, \fBcleaning\fP and \fBsyncing\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
.SH AUTHOR
The Syncthing Authors
.SH COPYRIGHT
2015, The Syncthing Authors
.\" Generated by docutils manpage writer.
.

290
man/syncthing-faq.7 Normal file
View File

@ -0,0 +1,290 @@
.\" Man page generated from reStructuredText.
.
.TH "SYNCTHING-FAQ" "7" "May 30, 2015" "v0.11" "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\(aqs \fBSyncthing\fP, although the command and source repository is spelled
\fBsyncthing\fP so it may be referred to in that way as well. It\(aqs definitely not
SyncThing, even though the abbreviation \fBst\fP is used in some
circumstances and file names.
.SS How does Syncthing differ from BitTorrent Sync?
.sp
The two are different and not related. Syncthing and BitTorrent Sync accomplish
some of the same things, namely syncing files between two or more computers.
.sp
BitTorrent Sync by BitTorrent, Inc is a proprietary peer\-to\-peer file
synchronization tool available for Windows, Mac, Linux, Android, iOS, Windows
Phone, Amazon Kindle Fire and BSD. \fI\%1\fP <\fBhttp://en.wikipedia.org/wiki/BitTorrent_Sync\fP> 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. BitTorrent
Sync uses an undocumented, closed protocol with unknown security properties.
.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 (When supported by the OS. On Windows Vista and up,
requires administrator privileges. Links are synced as is and are not
followed.)
.UNINDENT
.sp
The following is \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 unsparse)
.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 as the torrent protocol. The more devices you have online
(and synchronized), 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 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
address for that node, if global discovery is enabled on it. Knowing the device
ID doesn\(aqt help you actually establish a connection to that node or get a list
of files, etc.
.sp
For a connection to be established, both nodes need to know about the other\(aqs
device ID. It\(aqs 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, one of the files will be renamed to \fB<filename>.sync\-
conflict\-<date>\-<time>.<ext>\fP\&. The device which has the larger value of the
first 63 bits for his device ID will have his file marked as the conflicting
file. Note that we only create \fBsync\-conflict\fP files when the actual content
differs.
.sp
Beware that the \fB<filename>.sync\-conflict\-<date>\-<time>.<ext>\fP files are
treated as normal files after they are created, so they are propagated between
devices. We do this because the conflict is detected and resolved on one device,
creating the \fBsync\-conflict\fP file, but it\(aqs just as much of a conflict
everywhere else and we don\(aqt know which of the conflicting files is the "best"
from the user point of view. Moreover, if there\(aqs something that automatically
causes a conflict on change you\(aqll end up with \fBsync\-conflict\-...sync\-conflict
\-...\-sync\-conflict\fP files.
.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).
.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.
.SS Why is there no iOS client?
.sp
Alternative implementation Syncthing (using the Syncthing protocol) are 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.
.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\&.
.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\&.
.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.
.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:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
<gui enabled="true" tls="false">
<address>127.0.0.1:8384</address>
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
to
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
<gui enabled="true" tls="false">
<address>0.0.0.0:8384</address>
.ft P
.fi
.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.
.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,
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ ssh \-L 9090:127.0.0.1:8384 user@othercomputer.example.com
.ft P
.fi
.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.
.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.
.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).
.SS How do I upgrade Syncthing?
.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.
.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.
.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.
.SH AUTHOR
The Syncthing Authors
.SH COPYRIGHT
2015, The Syncthing Authors
.\" Generated by docutils manpage writer.
.

104
man/syncthing-networking.7 Normal file
View File

@ -0,0 +1,104 @@
.\" Man page generated from reStructuredText.
.
.TH "SYNCTHING-NETWORKING" "7" "May 30, 2015" "v0.11" "Syncthing"
.SH NAME
syncthing-networking \- Firewall Setup
.
.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 PORT FORWARDS
.sp
If you have a NAT router which supports UPnP, the easiest way to get a working
port forward is to make sure UPnP setting is enabled on both Syncthing and the
router – Syncthing will try to handle the rest. If it succeeds you will see a
message in the console saying:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
Created UPnP port mapping for external port XXXXX on UPnP device YYYYY.
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If this is not possible or desirable you should set up a port forward for port
\fB22000/TCP\fP, or the port set in the \fISync Protocol Listen Address\fP setting.
The external forwarded port and the internal destination port has to be the same
(i.e. 22000/TCP).
.sp
Communication in Syncthing works both ways. Therefore if you set up port
forwards for one device, other devices will be able to connect to it even when
they are behind a NAT network or firewall.
.SH LOCAL FIREWALL
.sp
If your PC has a local firewall, you will need to open the following ports for
incoming traffic:
.INDENT 0.0
.IP \(bu 2
Port \fB22000/TCP\fP (or the actual listening port if you have changed
the \fISync Protocol Listen Address\fP setting.)
.IP \(bu 2
Port \fB21025/UDP\fP (for discovery broadcasts)
.UNINDENT
.SH REMOTE WEB GUI
.sp
To be able to access the web GUI from other computers, you need to change the
\fIGUI Listen Address\fP setting from the default \fB127.0.0.1:8384\fP to
\fB0.0.0.0:8384\fP\&. You also need to open the port in your local firewall if you
have one.
.SS Tunneling via SSH
.sp
If you have SSH access to the machine running Syncthing but would rather not
open the web GUI port to the outside world, you can access it through a SSH
tunnel instead. You can start a tunnel with a command like the following:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
ssh \-L 9999:localhost:8384 machine
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
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
2015, The Syncthing Authors
.\" Generated by docutils manpage writer.
.

668
man/syncthing-rest-api.7 Normal file
View File

@ -0,0 +1,668 @@
.\" Man page generated from reStructuredText.
.
.TH "SYNCTHING-REST-API" "7" "May 30, 2015" "v0.11" "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 POST methods, or \fIany\fP method when authentication is enabled, 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.
.SH SYSTEM ENDPOINTS
.SS GET /rest/system/config
.sp
Returns the current configuration.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{
# etc
}
.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
Returns the list of current connections and some metadata associated
with the connection/peer.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{
"connections": {
"SMAHWLH\-AP74FAB\-QWLDYGV\-Q65ASPL\-GAAR2TB\-KEF5FLB\-DRLZCPN\-DJBFZAG": {
"address": "172.21.20.78:22000",
"at": "2015\-03\-16T21:51:38.672758819+01:00",
"clientVersion": "v0.10.27",
"inBytesTotal": 415980,
"outBytesTotal": 396300
}
},
"total": {
"address": "",
"at": "2015\-03\-16T21:51:38.672868814+01:00",
"clientVersion": "",
"inBytesTotal": 415980,
"outBytesTotal": 396300
}
}
.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/hint
.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/hint?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/hint?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
Returns the list of recent errors.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{
"errors": [
{
"time": "2014\-09\-18T12:59:26.549953186+02:00",
"error": "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/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.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Due to being a POST request, this method requires using an API key or CSRF token, as opposed to the GET request to the same URL.
.UNINDENT
.UNINDENT
.SS POST /rest/system/reset
.sp
Post with empty body to immediately \fIreset\fP Syncthing. This means
renaming all folder directories to temporary, unique names, wiping all
indexes and restarting. This should probably not be used during normal
operations...
.SS POST /rest/system/restart
.sp
Post with empty body to immediately restart Syncthing.
.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,
"cpuPercent": 0.006944836512046966,
"extAnnounceOK": {
"udp4://announce.syncthing.net:22026": true,
"udp6://announce\-v6.syncthing.net:22026": true
},
"goroutines": 49,
"myID": "P56IOI7\-MZJNU2Y\-IQGDREY\-DM2MGTI\-MGL3BXN\-PQ6W5BM\-TBBZ4TJ\-XZWICQ2",
"pathSeparator": "/",
"sys": 42092792,
"tilde": "/Users/jb"
}
.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": 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.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{
"availability": [
"I6KAH76\-66SLLLB\-5PFXSOA\-UFJCDZC\-YAOMLEK\-CP2GB32\-BV5RQST\-3PSROAU"
],
"global": {
"flags": "0644",
"localVersion": 3,
"modified": "2015\-04\-20T22:20:45+09:00",
"name": "util.go",
"numBlocks": 1,
"size": 9642,
"version": [
"5407294127585413568:1"
]
},
"local": {
"flags": "0644",
"localVersion": 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, \fBpatterns\fP,
provides a compiled version of all included ignore patterns in the form
of regular expressions. Excluded items in the \fBpatterns\fP field have a
nonstandard \fB(?exclude)\fP marker in front of the regular expression.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{
"ignore": [
"/Backups"
],
"patterns": [
"(?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 (\fBpatterns\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 parameter, \fBfolder\fP, and returns lists of files which are
needed by this device in order for it to become in sync.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{
# Files currently being downloaded
"progress": [
{
"flags": "0755",
"localVersion": 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": [
...
]
}
.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 rescan of a folder, or a specific path within a folder.
Takes the mandatory parameter \fIfolder\fP (folder ID), an optional parameter
\fBsub\fP (path relative to the folder root) and an optional parameter \fBnext\fP\&. If
\fBsub\fP is omitted or empty, the entire folder is scanned for changes, otherwise
only the given path (and children, in case it\(aqs a directory) is scanned. The
\fBnext\fP argument delays Syncthing\(aqs 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 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, only contains the
last synced file.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ curl \-s http://localhost:8384/rest/stats/folder | json
{
"folderid" : {
"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/report
.sp
Returns the data sent in the anonymous usage report.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{
"folderMaxFiles": 42106,
"folderMaxMiB": 12563,
"longVersion": "syncthing v0.10.27+5\-g36c93b7 (go1.4 darwin\-amd64 default) jb@syno 2015\-03\-16 20:43:34 UTC",
"memorySize": 16384,
"memoryUsageMiB": 41,
"numDevices": 10,
"numFolders": 4,
"platform": "darwin\-amd64",
"sha256Perf": 122.38,
"totFiles": 45180,
"totMiB": 18151,
"uniqueID": "6vulmdGw",
"version": "v0.10.27+5\-g36c93b7"
}
.ft P
.fi
.UNINDENT
.UNINDENT
.SH AUTHOR
The Syncthing Authors
.SH COPYRIGHT
2015, The Syncthing Authors
.\" Generated by docutils manpage writer.
.

134
man/syncthing-security.7 Normal file
View File

@ -0,0 +1,134 @@
.\" Man page generated from reStructuredText.
.
.TH "SYNCTHING-SECURITY" "7" "May 30, 2015" "v0.11" "Syncthing"
.SH NAME
syncthing-security \- Security Principles
.
.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
..
.sp
Security is one of the primary project goals. This means that it should not be
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.
.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.
.sp
For information about ensuring you are running the code you think you are and
for reporting security vulnerabilities, please see the official \fI\%security page\fP <\fBhttp://syncthing.net/security.html\fP>\&.
.SH INFORMATION LEAKAGE
.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
currently \fBhosted by @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
If a different global discovery server is configured, no data is sent to the
default global discovery server.
.SS Local Discovery
.sp
When local discovery is enabled, Syncthing sends broadcast (IPv4) and multicast
(IPv6) packets to the local network every 30 seconds. The packets contain the
device ID and listening port. Local discovery defaults to \fBon\fP\&.
.sp
An eavesdropper on the local network can deduce which machines are running
Syncthing with local discovery enabled, and what their device IDs are.
.sp
When turned off, devices with dynamic addresses on the local network cannot be
found and connected to.
.SS Upgrade Checks
.sp
When automatic upgrades are enabled, Syncthing checks for a new version at
startup and then once every twelve hours. This is by an HTTPS request to the
download site for releases, currently \fBhosted at GitHub\fP\&. Automatic upgrades
default to \fBon\fP (unless Syncthing was compiled with upgrades disabled).
.sp
Even when automatic upgrades are disabled in the configuration, an upgrade check
as above is done when the GUI is loaded, in order to show the "Upgrade to ..."
button when necessary. This can be disabled only by compiling syncthing with
upgrades disabled.
.sp
In effect this exposes the majority of the Syncthing population to tracking by
the operator of the download site (currently GitHub). That data is not available
to outside parties (including @calmh etc), except that download counts per
release binary are available in the GitHub API. The upgrade check (or download)
requests \fIdo not\fP contain any identifiable information about the user, device,
Syncthing version, etc.
.SS Usage Reporting
.sp
When usage reporting is enabled, Syncthing reports usage data at startup and
then every 24 hours. The report is sent as an HTTPS POST to the usage reporting
server, currently \fBhosted by @calmh\fP\&. The contents of the usage report can be
seen behind the "Preview" link in settings. Usage reporting defaults to \fBoff\fP
but the GUI will ask once about enabling it, shortly after the first install.
.sp
The reported data is protected from eavesdroppers, but the connection to the
usage reporting server itself may expose the client as running Syncthing.
.SS Sync Connections (BEP)
.sp
Sync connections are attempted to all configured devices, when the address is
possible to resolve. The sync connection is based on TLS 1.2. The TLS
certificates are sent in clear text (as in HTTPS etc), meaning that the
certificate Common Name (by default \fBsyncthing\fP) is visible.
.sp
An eavesdropper can deduce that this is a Syncthing connection and calculate the
device ID:s involved based on the hashes of the sent certificates.
.sp
Likewise, if the sync port (default 22000) is accessible from the internet, a
port scanner may discover it, attempt a TLS negotiation and thus obtain the
device certificate. This provides the same information as in the eavesdropper
case.
.SS Web GUI
.sp
If the web GUI is accessible, it exposes the device as running Syncthing. The
web GUI defaults to being reachable from the \fBlocal host only\fP\&.
.SH IN SHORT
.sp
Parties doing surveillance on your network (whether that be corporate IT, the
NSA or someone else) will be able to see that you use Syncthing, and your device
ID\(aqs \fI\%are OK to share anyway\fP <\fBhttp://docs.syncthing.net/users/faq.html#should-i-keep-my-device-ids-secret\fP>,
but the actual transmitted data is protected as well as we can. Knowing your
device ID can expose your IP address, using global discovery.
.SH AUTHOR
The Syncthing Authors
.SH COPYRIGHT
2015, The Syncthing Authors
.\" Generated by docutils manpage writer.
.

199
man/syncthing-stignore.5 Normal file
View File

@ -0,0 +1,199 @@
.\" Man page generated from reStructuredText.
.
.TH "SYNCTHING-STIGNORE" "5" "May 30, 2015" "v0.11" "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 nodes, 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 repository. The
\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.
.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
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 repository \fIroot\fP\&. Example:
\fB#include more\-patterns.txt\fP\&.
.IP \(bu 2
A pattern beginning with \fB!\fP 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
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.
.IP \(bu 2
A line beginning with \fB//\fP is a comment and has no effect.
.UNINDENT
.SH EXAMPLE
.sp
Given a directory layout:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
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
!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
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 director and it\(aqs
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 nodes, Alice and Bob, where Alice has 100 files to share, but
Bob ignores 25 of these. From Alice\(aqs 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\(aqs point of view it\(aqs 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 repository than in the local,
but still 100% in sync (\fI\%issue #624\fP <\fBhttps://github.com/syncthing/syncthing/issues/624\fP>). From
Alice\(aqs point of view, Bob will remain 100% in sync until the next
reconnect, because Bob has already announce 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.
.

117
man/syncthing-versioning.7 Normal file
View File

@ -0,0 +1,117 @@
.\" Man page generated from reStructuredText.
.
.TH "TODO" "7" "May 30, 2015" "v0.11" "Syncthing"
.SH NAME
Todo \- 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
..
.sp
\fBWARNING:\fP
.INDENT 0.0
.INDENT 3.5
This page may be out of date and requires review.
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
External versioning requires documenting.
.UNINDENT
.UNINDENT
.SH DESCRIPTION
.sp
There are 3 types of File Versioning. When you select each in the web interface,
a short description of each is shown to help you decide.
.INDENT 0.0
.INDENT 3.5
.SH TODO
.sp
More detail needed here: Can this be a relative path, or must it be
an absolute path?
.UNINDENT
.UNINDENT
.sp
With "Staggered File Versioning" method (only), you would like to specify where
removed and deleted files are stored as part of the Versioning feature, you can
specify the path in the "Versions Path" input after this method is selected.
.SH NO FILE VERSIONING
.sp
This is the default setting. With no file versioning, files that are replaced or
deleted on one device are deleted on other devices that the directory is shared
with. (Note: If a folder is marked "Master Folder" on a device, that device will
not accept changes to the files in the folder, and therefore will not have files
replaced or deleted.)
.SH SIMPLE FILE VERSIONING
.sp
With "Simple File Versioning" files are moved to the ".stversions"
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.
With "Simple File Versioning" files are moved to the ".stversions" 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 the ".stversions"
folder (inside your shared folder) when replaced or deleted on a remote device
(just like "Simple File Versioning"), however, Version are automatically deleted
if they are older than the maximum age or exceed the number of files allowed in
an interval.
.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
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 or 10 days, use 10. \fBNote: Set to 0 to keep versions forever.\fP
.UNINDENT
.SH AUTHOR
The Syncthing Authors
.SH COPYRIGHT
2015, The Syncthing Authors
.\" Generated by docutils manpage writer.
.

227
man/syncthing.1 Normal file
View File

@ -0,0 +1,227 @@
.\" Man page generated from reStructuredText.
.
.TH "SYNCTHING" "1" "May 30, 2015" "v0.11" "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] [\-generate=<dir>] [\-gui\-address=<address>]
[\-gui\-apikey=<key>] [\-gui\-authentication=<username:password>]
[\-home=<dir>] [\-logflags=<flags>] [\-no\-browser] [\-no\-restart]
[\-reset] [\-upgrade] [\-upgrade\-check] [\-upgrade\-to=<url>]
[\-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 \fB\-audit\fP
Write events to audit file.
.TP
.B \fB\-generate=<dir>\fP
Generate key and config in specified dir, then exit.
.TP
.B \fB\-gui\-address=<address>\fP
Override GUI address.
.TP
.B \fB\-gui\-apikey=<key>\fP
Override GUI API key.
.TP
.B \fB\-gui\-authentication=<username:password>\fP
Override GUI authentication; username:password.
.TP
.B \fB\-home=<dir>\fP
Set configuration directory. The default configuration directory is:
\fB$HOME/.config/syncthing\fP\&.
.TP
.B \fB\-logflags=<flags>\fP
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).
.TP
.B \fB\-no\-browser\fP
Do not start a browser.
.TP
.B \fB\-no\-restart\fP
Do not restart; just exit.
.TP
.B \fB\-reset\fP
Reset the database.
.TP
.B \fB\-upgrade\fP
Perform upgrade.
.TP
.B \fB\-upgrade\-check\fP
Check for available upgrade.
.TP
.B \fB\-upgrade\-to=<url>\fP
Force upgrade directly from specified URL.
.TP
.B \fB\-verbose\fP
Print verbose log output.
.TP
.B \fB\-version\fP
Show version.
.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 5
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\(aqs behavior in ways that
are mostly useful for developers. Use with care.
.INDENT 0.0
.TP
.B STGUIASSETS
Directory to load GUI assets from. Overrides compiled in assets.
.TP
.B STTRACE
A comma separated string of facilities to trace. The valid facility strings
are:
.INDENT 7.0
.IP \(bu 2
\fBbeacon\fP: the beacon package
.IP \(bu 2
\fBdiscover\fP: the discover package
.IP \(bu 2
\fBevents\fP: the events package
.IP \(bu 2
\fBfiles\fP: the files package
.IP \(bu 2
\fBhttp\fP: the main package; HTTP requests
.IP \(bu 2
\fBlocks\fP: the sync package; trace long held locks
.IP \(bu 2
\fBnet\fP: the main package; connections & network messages
.IP \(bu 2
\fBmodel\fP: the model package
.IP \(bu 2
\fBscanner\fP: the scanner package
.IP \(bu 2
\fBstats\fP: the stats package
.IP \(bu 2
\fBupnp\fP: the upnp package
.IP \(bu 2
\fBxdr\fP: the xdr package
.IP \(bu 2
\fBall\fP: all of the above
.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 heap\-$pid\-$timestamp.pprof 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 perf\-$pid.csv. Not supported on
Windows.
.TP
.B STNOUPGRADE
Disable automatic upgrades.
.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
(ie. performance).
.UNINDENT
.SH SEE ALSO
.sp
\fIsyncthing\-config(5)\fP, \fIsyncthing\-stignore(5)\fP,
\fIsyncthing\-device\-ids(7)\fP, \fIsyncthing\-security(7)\fP,
\fIsyncthing\-networking(7)\fP, \fIsyncthing\-versioning(7)\fP,
\fIsyncthing\-faq(7)\fP
.SH AUTHOR
The Syncthing Authors
.SH COPYRIGHT
2015, The Syncthing Authors
.\" Generated by docutils manpage writer.
.