Include generated man pages

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

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.

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

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
+<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.
+.

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.
+.

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=<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.
+.

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<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 [email protected]
+.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.
+.

man/syncthing-networking.7

@@ -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.
+.

man/syncthing-rest-api.7

@@ -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.
+.

man/syncthing-security.7

@@ -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.
+.

man/syncthing-stignore.5

@@ -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.
+.

man/syncthing-versioning.7

@@ -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.
+.

man/syncthing.1

@@ -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.
+.