diff --git a/build.sh b/build.sh
index 6da669b13..ecb5811fe 100755
--- a/build.sh
+++ b/build.sh
@@ -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
diff --git a/man/README.md b/man/README.md
new file mode 100644
index 000000000..a1f791a4f
--- /dev/null
+++ b/man/README.md
@@ -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.
diff --git a/man/refresh.sh b/man/refresh.sh
new file mode 100755
index 000000000..edc9bf90a
--- /dev/null
+++ b/man/refresh.sh
@@ -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
diff --git a/man/syncthing-config.5 b/man/syncthing-config.5
new file mode 100644
index 000000000..b26d9d62d
--- /dev/null
+++ b/man/syncthing-config.5
@@ -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
+
+
+
+
+
+ dynamic
+
+
+ 127.0.0.1:54096
+ jb
+ $2a$10$EKaTIcpz2...
+ O80CDOJ9LVUVCMHFK2OJDO4T882735
+
+
+ :54097
+ announce.syncthing.net:22025
+ true
+ true
+ 16
+ 0
+ 60
+ 60
+ 10000
+ true
+ true
+ 0
+
+
+.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.
+.
diff --git a/man/syncthing-device-ids.7 b/man/syncthing-device-ids.7
new file mode 100644
index 000000000..3097c3b37
--- /dev/null
+++ b/man/syncthing-device-ids.7
@@ -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.
+.
diff --git a/man/syncthing-event-api.7 b/man/syncthing-event-api.7
new file mode 100644
index 000000000..abe1410cf
--- /dev/null
+++ b/man/syncthing-event-api.7
@@ -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=\fP,
+where \fB\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\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.
+.
diff --git a/man/syncthing-faq.7 b/man/syncthing-faq.7
new file mode 100644
index 000000000..8e2b9a19c
--- /dev/null
+++ b/man/syncthing-faq.7
@@ -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.sync\-
+conflict\-\-