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\-\-