From aee4b10d3ac6399f3b0872e55a0a859aeed0c355 Mon Sep 17 00:00:00 2001 From: Jakob Borg Date: Mon, 22 Jun 2020 06:15:24 +0200 Subject: [PATCH] gui, man, authors: Update docs, translations, and contributors --- gui/default/assets/lang/lang-en.json | 1 + gui/default/assets/lang/lang-eu.json | 8 +- gui/default/assets/lang/lang-zh-TW.json | 2 +- man/stdiscosrv.1 | 433 +++++++- man/strelaysrv.1 | 277 ++++- man/syncthing-bep.7 | 1167 +++++++++++++++++++- man/syncthing-config.5 | 1151 +++++++++++++++++++- man/syncthing-device-ids.7 | 267 ++++- man/syncthing-event-api.7 | 882 +++++++++++++++- man/syncthing-faq.7 | 577 +++++++++- man/syncthing-globaldisco.7 | 127 ++- man/syncthing-localdisco.7 | 124 ++- man/syncthing-networking.7 | 161 ++- man/syncthing-relay.7 | 700 +++++++++++- man/syncthing-rest-api.7 | 1293 ++++++++++++++++++++++- man/syncthing-security.7 | 173 ++- man/syncthing-stignore.5 | 223 +++- man/syncthing-versioning.7 | 214 +++- man/syncthing.1 | 413 +++++++- 19 files changed, 8172 insertions(+), 21 deletions(-) diff --git a/gui/default/assets/lang/lang-en.json b/gui/default/assets/lang/lang-en.json index 09e238712..466ba4a3d 100644 --- a/gui/default/assets/lang/lang-en.json +++ b/gui/default/assets/lang/lang-en.json @@ -291,6 +291,7 @@ "Syncthing seems to be experiencing a problem processing your request. Please refresh the page or restart Syncthing if the problem persists.": "Syncthing seems to be experiencing a problem processing your request. Please refresh the page or restart Syncthing if the problem persists.", "Take me back": "Take me back", "The GUI address is overridden by startup options. Changes here will not take effect while the override is in place.": "The GUI address is overridden by startup options. Changes here will not take effect while the override is in place.", + "The Syncthing Authors": "The Syncthing Authors", "The Syncthing admin interface is configured to allow remote access without a password.": "The Syncthing admin interface is configured to allow remote access without a password.", "The aggregated statistics are publicly available at the URL below.": "The aggregated statistics are publicly available at the URL below.", "The configuration has been saved but not activated. Syncthing must restart to activate the new configuration.": "The configuration has been saved but not activated. Syncthing must restart to activate the new configuration.", diff --git a/gui/default/assets/lang/lang-eu.json b/gui/default/assets/lang/lang-eu.json index 8c19b6734..41fb1b5e0 100644 --- a/gui/default/assets/lang/lang-eu.json +++ b/gui/default/assets/lang/lang-eu.json @@ -1,5 +1,5 @@ { - "A device with that ID is already added.": "Id hori duen tresna bat jadanik bada", + "A device with that ID is already added.": "Jadanik bada Id hori duen tresna bat", "A negative number of days doesn't make sense.": "0 edo zenbaki positiboa onartzen da bakarrik", "A new major version may not be compatible with previous versions.": "Aldaketa garrantzitsuak dituen bertsio berri bat ez da beharbada bateragarria izanen bertsio zaharragoekin.", "API Key": "API giltza", @@ -24,13 +24,13 @@ "An external command handles the versioning. It has to remove the file from the shared folder. If the path to the application contains spaces, it should be quoted.": "Kanpoko kontrolagailu batek fitxategien bertsioak kudeatzen ditu. Fitxategiak kendu behar ditu errepertorio sinkronizatuan. Aplikaziorako ibilbideak espazioak baditu, komatxo artean egon behar du.", "Anonymous Usage Reporting": "Izenik gabeko erabiltze erreportak", "Anonymous usage report format has changed. Would you like to move to the new format?": "Erabilera anonimoko txostenaren formatua aldatu egin da. Formatu berria erabili nahi duzu?", - "Are you sure you want to remove device {%name%}?": "Ziur zaude {{name}} gailua ezabtu nahi duzula?", + "Are you sure you want to remove device {%name%}?": "Ziur zaude {{name}} gailua ezabatu nahi duzula?", "Are you sure you want to remove folder {%label%}?": "Ziur zaude {{label}} karpeta ezabatu nahi duzula?", "Are you sure you want to restore {%count%} files?": "Ziur zaude {{count}} fitxategi berreskuratu nahi dituzula? ", "Are you sure you want to upgrade?": "Ziur zaude eguneratu nahi duzula?", "Auto Accept": "Onartu automatikoki", "Automatic Crash Reporting": "Hutsegite txosten automatikoa", - "Automatic upgrade now offers the choice between stable releases and release candidates.": "Eguneratze automatiko sistemak iraunkor bertsioen eta aitzineko bertsioen artean hautatzea proposatzen du", + "Automatic upgrade now offers the choice between stable releases and release candidates.": "Automatikoki eguneratzeko sistemak bertsio egonkorren eta aurreko bertsioen arteko aukera proposatzen du.", "Automatic upgrades": "Eguneratze automatikoak", "Automatic upgrades are always enabled for candidate releases.": "Eguneratze automatikoak beti daude gaituta jaurtikitako bertsioetarako.", "Automatically create or share folders that this device advertises at the default path.": "Gailu honek lehenetsitako ibilbidean iragartzen dituen karpetak automatikoki sortu edo partekatu.", @@ -50,7 +50,7 @@ "Connection Type": "Konexio mota", "Connections": "Konexioak", "Continuously watching for changes is now available within Syncthing. This will detect changes on disk and issue a scan on only the modified paths. The benefits are that changes are propagated quicker and that less full scans are required.": "Orain Syncthing-en eskuragarri dago aldaketen bilaketa etengabea. Disko-aldaketak hautemango dira, eta aldatutako ibilbideetan bakarrik egingo da eskaneatzea. Onurak aldaketak azkarrago zabaltzea eta eskaneatze oso gutxiago behar izatea dira.", - "Copied from elsewhere": "Beste nunbaitik kopiatua", + "Copied from elsewhere": "Beste nonbaitetik kopiatua", "Copied from original": "Jatorrizkotik kopiatua", "Copyright © 2014-2019 the following Contributors:": "Copyright 2014-2019 ekarle hauek:", "Creating ignore patterns, overwriting an existing file at {%path%}.": "Baztertze modelo batzuen sortzea, dagoen fitxategiari ordaina ezartzea: {{path}}", diff --git a/gui/default/assets/lang/lang-zh-TW.json b/gui/default/assets/lang/lang-zh-TW.json index 9ab001ca0..20a0ed286 100644 --- a/gui/default/assets/lang/lang-zh-TW.json +++ b/gui/default/assets/lang/lang-zh-TW.json @@ -208,7 +208,7 @@ "Permissions": "權限", "Please consult the release notes before performing a major upgrade.": "執行重大升級前請先參閱版本資訊。", "Please set a GUI Authentication User and Password in the Settings dialog.": "請在設定對話框內設置 GUI 使用者認證名稱及密碼。", - "Please wait": "請稍後", + "Please wait": "請稍候", "Prefix indicating that the file can be deleted if preventing directory removal": "前綴表示當此檔案阻礙了資料夾刪除時，可一併刪除此檔", "Prefix indicating that the pattern should be matched without case sensitivity": "前綴表示此樣式不區分大小寫", "Preparing to Sync": "Preparing to Sync", diff --git a/man/stdiscosrv.1 b/man/stdiscosrv.1 index 44d986c4b..8088d05aa 100644 --- a/man/stdiscosrv.1 +++ b/man/stdiscosrv.1 @@ -1 +1,432 @@ -404 Not Found +.\" Man page generated from reStructuredText. +. +.TH "STDISCOSRV" "1" "Jun 19, 2020" "v1" "Syncthing" +.SH NAME +stdiscosrv \- Syncthing Discovery Server +. +.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 +stdiscosrv [\-cert=] [\-db\-dir=] [\-debug] [\-http] [\-key=] + [\-listen=
] [\-metrics\-listen=
] + [\-replicate=] [\-replication\-listen=
] +.ft P +.fi +.UNINDENT +.UNINDENT +.SH DESCRIPTION +.sp +Syncthing relies on a discovery server to find peers on the internet. Anyone +can run a discovery server and point Syncthing installations to it. The +Syncthing project also maintains a global cluster for public use. +.SH OPTIONS +.INDENT 0.0 +.TP +.B \-cert= +Certificate file (default “./cert.pem”). +.UNINDENT +.INDENT 0.0 +.TP +.B \-db\-dir= +Database directory, where data is stored (default “./discovery.db”). +.UNINDENT +.INDENT 0.0 +.TP +.B \-debug +Enable debug output. +.UNINDENT +.INDENT 0.0 +.TP +.B \-http +Listen on HTTP (behind an HTTPS proxy). +.UNINDENT +.INDENT 0.0 +.TP +.B \-key= +Key file (default “./key.pem”). +.UNINDENT +.INDENT 0.0 +.TP +.B \-listen=
+Listen address (default “:8443”). +.UNINDENT +.INDENT 0.0 +.TP +.B \-metrics\-listen=
+Prometheus compatible metrics endpoint listen address (default disabled). +.UNINDENT +.INDENT 0.0 +.TP +.B \-replicate= +Replication peers, \fI\%id@address\fP <\fBid@address\fP>, comma separated +.UNINDENT +.INDENT 0.0 +.TP +.B \-replication\-listen=
+Listen address for incoming replication connections (default “:19200”). +.UNINDENT +.SH POINTING SYNCTHING AT YOUR DISCOVERY SERVER +.sp +By default, Syncthing uses a number of global discovery servers, signified by +the entry \fBdefault\fP in the list of discovery servers. To make Syncthing use +your own instance of stdiscosrv, open up Syncthing’s web GUI. Go to settings, +Global Discovery Server and add stdiscosrv’s host address to the comma\-separated +list, e.g. \fBhttps://disco.example.com:8443/\fP\&. Note that stdiscosrv uses port +8443 by default. For stdiscosrv to be available over the internet with a dynamic +IP address, you will need a dynamic DNS service. +.sp +Deprecated since version v0.14.44: Prior versions need \fB/v2/\fP appended to the discovery +server address, e.g. \fBhttps://disco.example.com:8443/v2/\fP\&. + +.sp +If you wish to use \fIonly\fP your own discovery server, remove the \fBdefault\fP +entry from the list. +.SH SETTING UP +.SS Description +.sp +This guide assumes that you have already set up Syncthing. If you +haven’t yet, head over to getting\-started first. +.SS Installing +.sp +Go to \fI\%releases\fP <\fBhttps://github.com/syncthing/discosrv/releases\fP> and +download the file appropriate for your operating system. Unpacking it will +yield a binary called \fBstdiscosrv\fP (or \fBstdiscosrv.exe\fP on Windows). +Start this in whatever way you are most comfortable with; double clicking +should work in any graphical environment. At first start, stdiscosrv will +generate certificate files and database in the current directory unless +given flags to the contrary. +.SS Configuring +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +If you are running an instance of Syncthing on the discovery server, +you must either add that instance to other devices using a static +address or bind the discovery server and Syncthing instances to +different IP addresses. +.UNINDENT +.UNINDENT +.SS Certificates +.sp +The discovery server provides service over HTTPS. To ensure secure connections +from clients there are three options: +.INDENT 0.0 +.IP \(bu 2 +Use a CA\-signed certificate pair for the domain name you will use for the +discovery server. This is like any other HTTPS website; clients will +authenticate the server based on its certificate and domain name. +.IP \(bu 2 +Use any certificate pair and let clients authenticate the server based on +its “device ID” (similar to Syncthing\-to\-Syncthing authentication). This +option can be used with the certificate automatically generated by the +discovery server. +.IP \(bu 2 +Pass the \fB\-http\fP flag if the discovery server is behind an SSL\-secured +reverse proxy. See below for configuration. +.UNINDENT +.sp +For the first two options, the discovery server must be given the paths to +the certificate and key at startup. This isn’t necessary with the \fBhttp\fP flag: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ stdiscosrv \-cert=/path/to/cert.pem \-key=/path/to/key.pem +Server device ID is 7DDRT7J\-UICR4PM\-PBIZYL3\-MZOJ7X7\-EX56JP6\-IK6HHMW\-S7EK32W\-G3EUPQA +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The discovery server prints its device ID at startup. In case you are using +a non CA signed certificate, this device ID (fingerprint) must be given to +the clients in the discovery server URL: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +https://disco.example.com:8443/?id=7DDRT7J\-UICR4PM\-PBIZYL3\-MZOJ7X7\-EX56JP6\-IK6HHMW\-S7EK32W\-G3EUPQA +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Otherwise, the URL will be: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +https://disco.example.com:8443/ +.ft P +.fi +.UNINDENT +.UNINDENT +.SS Replication +.sp +The discovery server can be deployed in a redundant, load sharing fashion. +In this mode announcements are replicated from the server that receives them +to other peer servers and queries can be answered equally by all servers. +.sp +Replication connections are encrypted and authenticated using TLS. The +certificate is selected by the \fB\-cert\fP and \fB\-key\fP options and is thus +shared with the main discovery API. If the \fB\-http\fP mode is used the +certificate is not used for client requests but only for replication +connections. +.sp +Authentication of replication connections is done using \fI\%Syncthing\-style +device IDs\fP <\fBhttps://docs.syncthing.net/dev/device-ids.html#id1\fP> only \- CA +verification is not available. The device IDs in question are those printed +by the discovery server on startup. +.sp +Replication connections are unidirectional \- announcements are replication +from the \fBsender\fP to a \fBlistener\fP\&. In order to have a bidirectional +replication relationship between two servers both need to be configured as +sender and listener. +.sp +As an example, lets assume two discovery servers: +.INDENT 0.0 +.IP \(bu 2 +Server one is on 192.0.2.20 and has certificate ID I6K…H76 +.IP \(bu 2 +Server two is on 192.0.2.55 and has certificate ID MRI…7OK +.UNINDENT +.sp +In order for both to replicate to the other and thus form a redundant pair, +use the following commands. +.sp +On server one: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ stdiscosrv \-replicate=MRI...7OK@192.0.2.55:19200 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +On server two: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ stdiscosrv \-replicate=I6K...H76@192.0.2.20:19200 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The \fB\-replicate\fP directive sets which remote device IDs are expected and +allowed for both outgoing (sending) and incoming (listening) connections, +and which addresses to use when connecting out to those peers. Both IP and +port must be specified in peer addresses. +.sp +It is possible to only allow incoming connections from a peer without +establishing an outgoing replication connection. To do so, give only the +device ID without “@ip:port” address: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ stdiscosrv \-replicate=I6K...H76 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Discosrv will listen on the replication port only when \fB\-replicate\fP is +given. The default replication listen address is “:19200”. +.sp +To achieve load balancing over two mutually replicating discovery server +instances, add multiple A / AAAA DNS records for a given name and point +Syncthing towards this name. The same certificate must be used on both +discovery servers. +.SS Reverse Proxy Setup +.sp +The discovery server can be run behind an SSL\-secured reverse proxy. This +allows: +.INDENT 0.0 +.IP \(bu 2 +Use of a subdomain name without requiring a port number added to the URL +.IP \(bu 2 +Sharing an SSL certificate with multiple services on the same server +.UNINDENT +.sp +Note that after this configuration, if the proxy uses a valid HTTPS +certificate, \fBclients should omit the\fP \fB?id=...\fP \fBparameter from the +discovery server URL on their configuration\fP\&. Client\-side validation will be +done by checking the visible proxy server’s HTTPS certificate. If, however, the +proxy uses a self\-signed or somehow invalid certificate, clients must still set +the \fB?id=...\fP parameter with the computed hash of the proxy’s +certificate. Using such setup is discouraged and is not covered in this page. +Always favour using valid and widely recognised certificates. +.SS Requirements +.INDENT 0.0 +.IP \(bu 2 +Run the discovery server using the \-http flag: \fBstdiscosrv \-http\fP\&. +.IP \(bu 2 +SSL certificate/key configured for the reverse proxy. +.IP \(bu 2 +The “X\-Forwarded\-For” HTTP header must be passed through with the client’s +real IP address. +.IP \(bu 2 +The “X\-SSL\-Cert” HTTP header must be passed through with the PEM\-encoded +client SSL certificate. This will be present in POST requests and may be empty +in GET requests from clients. If you see syncthing\-discosrv outputting +\fBno certificates\fP when receiving POST requests, that’s because the proxy +is not passing this header through. +.IP \(bu 2 +The proxy must request the client SSL certificate but not require it to be +signed by a trusted CA. +.UNINDENT +.SS Nginx +.sp +These three lines in the configuration take care of the last three requirements +listed above: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +proxy_set_header X\-Forwarded\-For $proxy_add_x_forwarded_for; +proxy_set_header X\-SSL\-Cert $ssl_client_cert; +ssl_verify_client optional_no_ca; +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The following is a complete example Nginx configuration file. With this setup, +clients can use \fI\%https://discovery.example.com\fP as the discovery server URL in +the Syncthing settings. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +# HTTP 1.1 support +proxy_http_version 1.1; +proxy_buffering off; +proxy_set_header Host $http_host; +proxy_set_header Upgrade $http_upgrade; +proxy_set_header Connection $http_connection; +proxy_set_header X\-Real\-IP $remote_addr; +proxy_set_header X\-Forwarded\-For $proxy_add_x_forwarded_for; +proxy_set_header X\-Forwarded\-Proto $http_x_forwarded_proto; +proxy_set_header X\-SSL\-Cert $ssl_client_cert; +upstream discovery.example.com { + # Local IP address:port for discovery server + server 192.0.2.1:8443; +} +server { + server_name discovery.example.com; + listen 80; + access_log /var/log/nginx/access.log vhost; + return 301 https://$host$request_uri; +} +server { + server_name discovery.example.com; + listen 443 ssl http2; + access_log /var/log/nginx/access.log vhost; + ssl_protocols TLSv1 TLSv1.1 TLSv1.2; + ssl_ciphers ECDHE\-RSA\-AES128\-GCM\-SHA256:ECDHE\-ECDSA\-AES128\-GCM\-SHA256:ECDHE\-RSA\-AES256\-GCM\-SHA384:ECDHE\-ECDSA\-AES256\-GCM\-SHA384: DHE\-RSA\-AES128\-GCM\-SHA256:DHE\-DSS\-AES128\-GCM\-SHA256:kEDH+AESGCM:ECDHE\-RSA\-AES128\-SHA256:ECDHE\-ECDSA\-AES128\-SHA256:ECDHE\-RSA\-AES128\-SHA:E CDHE\-ECDSA\-AES128\-SHA:ECDHE\-RSA\-AES256\-SHA384:ECDHE\-ECDSA\-AES256\-SHA384:ECDHE\-RSA\-AES256\-SHA:ECDHE\-ECDSA\-AES256\-SHA:DHE\-RSA\-AES128\-SHA25 6:DHE\-RSA\-AES128\-SHA:DHE\-DSS\-AES128\-SHA256:DHE\-RSA\-AES256\-SHA256:DHE\-DSS\-AES256\-SHA:DHE\-RSA\-AES256\-SHA:AES128\-GCM\-SHA256:AES256\-GCM\-SHA3 84:AES128\-SHA256:AES256\-SHA256:AES128\-SHA:AES256\-SHA:AES:CAMELLIA:DES\-CBC3\-SHA:!aNULL:!eNULL:!EXPORT:!DES:!RC4:!MD5:!PSK:!aECDH:!EDH\-DSS \-DES\-CBC3\-SHA:!EDH\-RSA\-DES\-CBC3\-SHA:!KRB5\-DES\-CBC3\-SHA; + ssl_prefer_server_ciphers on; + ssl_session_timeout 5m; + ssl_session_cache shared:SSL:50m; + ssl_certificate /etc/nginx/certs/discovery.example.com.crt; + ssl_certificate_key /etc/nginx/certs/discovery.example.com.key; + ssl_dhparam /etc/nginx/certs/discovery.example.com.dhparam.pem; + add_header Strict\-Transport\-Security "max\-age=31536000"; + ssl_verify_client optional_no_ca; + location / { + proxy_pass http://discovery.example.com; + } +} +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +An example of automating the SSL certificates and reverse\-proxying the Discovery +Server and Syncthing using Nginx, \fI\%Let’s Encrypt\fP <\fBhttps://letsencrypt.org/\fP> and Docker can be found \fI\%here\fP <\fBhttps://forum.syncthing.net/t/docker-syncthing-and-syncthing-discovery-behind-nginx-reverse-proxy-with-lets-encrypt/6880\fP>\&. +.SS Apache +.sp +The following lines must be added to the configuration: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +SSLProxyEngine On +SSLVerifyClient optional_no_ca +RequestHeader set X\-SSL\-Cert "%{SSL_CLIENT_CERT}s" +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The following was observed to not be required at least under +Apache httpd 2.4.38, as the proxy module adds the needed header by default. +If you need to explicitly add the following directive, make sure to issue +\fBa2enmod remoteip\fP first. Then, add the following to your Apache httpd +configuration: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +RemoteIPHeader X\-Forwarded\-For +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +For more details, see also the recommendations in the +\fI\%Reverse Proxy Setup\fP <\fBhttps://docs.syncthing.net/users/reverseproxy.html\fP> +page. Note that that page is directed at setting up a proxy for the +Syncthing web UI. You should do the proper path and port adjustments to proxying +the discovery server and your particular setup. +.SH SEE ALSO +.sp +\fBsyncthing\-networking(7)\fP, \fBsyncthing\-faq(7)\fP +.SH AUTHOR +The Syncthing Authors +.SH COPYRIGHT +2014-2019, The Syncthing Authors +.\" Generated by docutils manpage writer. +. diff --git a/man/strelaysrv.1 b/man/strelaysrv.1 index 44d986c4b..16ea73afc 100644 --- a/man/strelaysrv.1 +++ b/man/strelaysrv.1 @@ -1 +1,276 @@ -404 Not Found +.\" Man page generated from reStructuredText. +. +.TH "STRELAYSRV" "1" "Jun 19, 2020" "v1" "Syncthing" +.SH NAME +strelaysrv \- Syncthing Relay Server +. +.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 +strelaysrv [\-debug] [\-ext\-address=
] [\-global\-rate=] [\-keys=] [\-listen=] + [\-message\-timeout=] [\-nat] [\-nat\-lease= [\-nat\-renewal=] + [\-nat\-timeout=] [\-network\-timeout=] [\-per\-session\-rate=] + [\-ping\-interval=] [\-pools=] [\-protocol=] [\-provided\-by=] + [\-status\-srv=] +.ft P +.fi +.UNINDENT +.UNINDENT +.SH DESCRIPTION +.sp +Syncthing relies on a network of community\-contributed relay servers. Anyone +can run a relay server, and it will automatically join the relay pool and be +available to Syncthing users. The current list of relays can be found at +\fI\%http://relays.syncthing.net/\fP\&. +.SH OPTIONS +.INDENT 0.0 +.TP +.B \-debug +Enable debug output. +.UNINDENT +.INDENT 0.0 +.TP +.B \-ext\-address=
+An optional address to advertising as being available on. Allows listening +on an unprivileged port with port forwarding from e.g. 443, and be +connected to on port 443. +.UNINDENT +.INDENT 0.0 +.TP +.B \-global\-rate= +Global rate limit, in bytes/s. +.UNINDENT +.INDENT 0.0 +.TP +.B \-keys= +Directory where cert.pem and key.pem is stored (default “.”). +.UNINDENT +.INDENT 0.0 +.TP +.B \-listen= +Protocol listen address (default “:22067”). +.UNINDENT +.INDENT 0.0 +.TP +.B \-message\-timeout= +Maximum amount of time we wait for relevant messages to arrive (default 1m0s). +.UNINDENT +.INDENT 0.0 +.TP +.B \-nat +Use UPnP/NAT\-PMP to acquire external port mapping +.UNINDENT +.INDENT 0.0 +.TP +.B \-nat\-lease= +NAT lease length in minutes (default 60) +.UNINDENT +.INDENT 0.0 +.TP +.B \-nat\-renewal= +NAT renewal frequency in minutes (default 30) +.UNINDENT +.INDENT 0.0 +.TP +.B \-nat\-timeout= +NAT discovery timeout in seconds (default 10) +.UNINDENT +.INDENT 0.0 +.TP +.B \-network\-timeout= +Timeout for network operations between the client and the relay. If no data +is received between the client and the relay in this period of time, the +connection is terminated. Furthermore, if no data is sent between either +clients being relayed within this period of time, the session is also +terminated. (default 2m0s) +.UNINDENT +.INDENT 0.0 +.TP +.B \-per\-session\-rate= +Per session rate limit, in bytes/s. +.UNINDENT +.INDENT 0.0 +.TP +.B \-ping\-interval= +How often pings are sent (default 1m0s). +.UNINDENT +.INDENT 0.0 +.TP +.B \-pools= +Comma separated list of relay pool addresses to join (default +“\fI\%http://relays.syncthing.net/endpoint\fP”). Blank to disable announcement to +a pool, thereby remaining a private relay. +.UNINDENT +.INDENT 0.0 +.TP +.B \-protocol= +Protocol used for listening. ‘tcp’ for IPv4 and IPv6, ‘tcp4’ for IPv4, ‘tcp6’ for IPv6 (default “tcp”). +.UNINDENT +.INDENT 0.0 +.TP +.B \-provided\-by= +An optional description about who provides the relay. +.UNINDENT +.INDENT 0.0 +.TP +.B \-status\-srv= +Listen address for status service (blank to disable) (default “:22070”). +Status service is used by the relay pool server UI for displaying stats (data transfered, number of clients, etc.) +.UNINDENT +.SH SETTING UP +.sp +Primarily, you need to decide on a directory to store the TLS key and +certificate and a listen port. The default listen port of 22067 works, but for +optimal compatibility a well known port for encrypted traffic such as 443 is +recommended. This may require additional setup to work without running +as root or a privileged user, see \fI\%Running on port 443 as an unprivileged user\fP +below. In principle something similar to this should work on a Linux/Unix +system: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ sudo useradd relaysrv +$ sudo mkdir /etc/relaysrv +$ sudo chown relaysrv /etc/relaysrv +$ sudo \-u relaysrv /usr/local/bin/relaysrv \-keys /etc/relaysrv +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +This creates a user \fBrelaysrv\fP and a directory \fB/etc/relaysrv\fP to store +the keys. The keys are generated on first startup. The relay will join the +global relay pool, unless a \fB\-pools=""\fP argument is given. +.sp +To make the relay server start automatically at boot, use the recommended +procedure for your operating system. +.SS Client configuration +.sp +Syncthing can be configured to use specific relay servers (exclusively of the public pool) by adding the required servers to the Sync Protocol Listen Address field, under Actions and Settings. The format is as follows: +.INDENT 0.0 +.INDENT 3.5 +relay://[:port]/?id= +.UNINDENT +.UNINDENT +.sp +For example: +.INDENT 0.0 +.INDENT 3.5 +relay://private\-relay\-1.example.com:443/?id=ITZRNXE\-YNROGBZ\-HXTH5P7\-VK5NYE5\-QHRQGE2\-7JQ6VNJ\-KZUEDIU\-5PPR5AM +.UNINDENT +.UNINDENT +.sp +The relay’s device ID is output on start\-up. +.SS Running on port 443 as an unprivileged user +.sp +It is recommended that you run the relay on port 443 (or another port which is +commonly allowed through corporate firewalls), in order to maximise the chances +that people are able to connect. However, binding to ports below 1024 requires +root privileges, and running a relay as root is not recommended. Thankfully +there are a couple of approaches available to you. +.sp +One option is to run the relay on port 22067, and use an \fBiptables\fP rule +to forward traffic from port 443 to port 22067, for example: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +iptables \-t nat \-A PREROUTING \-i eth0 \-p tcp \-\-dport 443 \-j REDIRECT \-\-to\-port 22067 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Or, if you’re using \fBufw\fP, add the following to \fB/etc/ufw/before.rules\fP: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +*nat +:PREROUTING ACCEPT [0:0] +:POSTROUTING ACCEPT [0:0] + +\-A PREROUTING \-i eth0 \-p tcp \-\-dport 443 \-j REDIRECT \-\-to\-port 22067 + +COMMIT +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +You will need to start \fBrelaysrv\fP with \fB\-ext\-address ":443"\fP\&. This tells +\fBrelaysrv\fP that it can be contacted on port 443, even though it is listening +on port 22067. You will also need to let both port 443 and 22067 through your +firewall. +.sp +Another option is \fI\%described here\fP <\fBhttps://wiki.apache.org/httpd/NonRootPortBinding\fP>, +although your mileage may vary. +.SH FIREWALL CONSIDERATIONS +.sp +The relay server listens on two ports by default. One for data connections and the other +for providing public statistics at \fI\%http://relays.syncthing.net/\fP\&. The firewall, such as +\fBiptables\fP, must permit incoming TCP connections to the following ports: +.INDENT 0.0 +.IP \(bu 2 +Data port: \fB22067/tcp\fP overridden with \fB\-listen\fP and advertised with \fB\-ext\-address\fP +.IP \(bu 2 +Status port: \fB22070/tcp\fP overridden with \fB\-status\-srv\fP +.UNINDENT +.sp +Runtime \fBiptables\fP rules to allow access to the default ports: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +iptables \-I INPUT \-p tcp \-\-dport 22067 \-j ACCEPT +iptables \-I INPUT \-p tcp \-\-dport 22070 \-j ACCEPT +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Please consult Linux distribution documentation to persist firewall rules. +.SH SEE ALSO +.sp +\fBsyncthing\-relay(7)\fP, \fBsyncthing\-faq(7)\fP, +\fBsyncthing\-networking(7)\fP +.SH AUTHOR +The Syncthing Authors +.SH COPYRIGHT +2014-2019, The Syncthing Authors +.\" Generated by docutils manpage writer. +. diff --git a/man/syncthing-bep.7 b/man/syncthing-bep.7 index 44d986c4b..436634e30 100644 --- a/man/syncthing-bep.7 +++ b/man/syncthing-bep.7 @@ -1 +1,1166 @@ -404 Not Found +.\" Man page generated from reStructuredText. +. +.TH "SYNCTHING-BEP" "7" "Jun 19, 2020" "v1" "Syncthing" +.SH NAME +syncthing-bep \- Block Exchange Protocol v1 +. +.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 INTRODUCTION AND DEFINITIONS +.sp +The Block Exchange Protocol (BEP) is used between two or more \fIdevices\fP thus +forming a \fIcluster\fP\&. Each device has one or more \fIfolders\fP of files +described by the \fIlocal model\fP, containing metadata and block hashes. The +local model is sent to the other devices in the cluster. The union of all +files in the local models, with files selected for highest change version, +forms the \fIglobal model\fP\&. Each device strives to get its folders in sync +with the global model by requesting missing or outdated blocks from the +other devices in the cluster. +.sp +File data is described and transferred in units of \fIblocks\fP, each being from +128 KiB (131072 bytes) to 16 MiB in size, in steps of powers of two. The +block size may vary between files but is constant in any given file, except +for the last block which may be smaller. +.sp +The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, +“SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this +document are to be interpreted as described in [RFC 2119](\fI\%https://tools.ietf.org/html/rfc2119\fP). +.SH TRANSPORT AND AUTHENTICATION +.sp +BEP is deployed as the highest level in a protocol stack, with the lower +level protocols providing encryption and authentication. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C ++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ +| Block Exchange Protocol | +|\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-| +| Encryption & Auth (TLS 1.2) | +|\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-| +| Reliable Transport | +|\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-| +v ... v +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The encryption and authentication layer SHALL use TLS 1.2 or a higher +revision. A strong cipher suite SHALL be used, with “strong cipher +suite” being defined as being without known weaknesses and providing +Perfect Forward Secrecy (PFS). Examples of strong cipher suites are +given at the end of this document. This is not to be taken as an +exhaustive list of allowed cipher suites but represents best practices +at the time of writing. +.sp +The exact nature of the authentication is up to the application, however +it SHALL be based on the TLS certificate presented at the start of the +connection. Possibilities include certificates signed by a common +trusted CA, preshared certificates, preshared certificate fingerprints +or certificate pinning combined with some out of band first +verification. The reference implementation uses preshared certificate +fingerprints (SHA\-256) referred to as “Device IDs”. +.sp +There is no required order or synchronization among BEP messages except +as noted per message type \- any message type may be sent at any time and +the sender need not await a response to one message before sending +another. +.sp +The underlying transport protocol MUST guarantee reliable packet delivery. +.sp +In this document, in diagrams and text, “bit 0” refers to the \fImost +significant\fP bit of a word; “bit 15” is thus the least significant bit of a +16 bit word (int16) and “bit 31” is the least significant bit of a 32 bit +word (int32). Non protocol buffer integers are always represented in network +byte order (i.e., big endian) and are signed unless stated otherwise, but +when describing message lengths negative values do not make sense and the +most significant bit MUST be zero. +.sp +The protocol buffer schemas in this document are in \fBproto3\fP syntax. This +means, among other things, that all fields are optional and will assume +their default value when missing. This does not necessarily mean that a +message is \fIvalid\fP with all fields empty \- for example, an index entry for a +file that does not have a name is not useful and MAY be rejected by the +implementation. However the folder label is for human consumption only so an +empty label should be accepted \- the implementation will have to choose some +way to represent the folder, perhaps by using the ID in it’s place or +automatically generating a label. +.SH PRE-AUTHENTICATION MESSAGES +.sp +AFTER establishing a connection, but BEFORE performing any authentication, +devices MUST exchange Hello messages. +.sp +Hello messages are used to carry additional information about the peer, +which might be of interest to the user even if the peer is not permitted to +communicate due to failing authentication. Note that the certificate based +authentication may be considered part of the TLS handshake that precedes the +Hello message exchange, but even in the case that a connection is rejected a +Hello message must be sent before the connection is terminated. +.sp +Hello messages MUST be prefixed with an int32 containing the magic number +\fB0x2EA7D90B\fP, followed by an int16 representing the size of the message, +followed by the contents of the Hello message itself. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C + 0 1 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 ++\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ +| Magic | +| (32 bits) | ++\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ +| Length | ++\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ +/ / +\e Hello \e +/ / ++\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The Hello message itself is in protocol buffer format with the following schema: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +message Hello { + string device_name = 1; + string client_name = 2; + string client_version = 3; +} +.ft P +.fi +.UNINDENT +.UNINDENT +.SS Fields (Hello message) +.sp +The \fBdevice_name\fP is a human readable (configured or auto detected) device +name or host name, for the remote device. +.sp +The \fBclient_name\fP and \fBclient_version\fP identifies the implementation. The +values SHOULD be simple strings identifying the implementation name, as a +user would expect to see it, and the version string in the same manner. An +example client name is “syncthing” and an example client version is “v0.7.2”. +The client version field SHOULD follow the patterns laid out in the \fI\%Semantic +Versioning\fP <\fBhttp://semver.org/\fP> standard. +.sp +Immediately after exchanging Hello messages, the connection MUST be dropped +if the remote device does not pass authentication. +.SH POST-AUTHENTICATION MESSAGES +.sp +Every message post authentication is made up of several parts: +.INDENT 0.0 +.IP \(bu 2 +A header length word +.IP \(bu 2 +A \fBHeader\fP +.IP \(bu 2 +A message length word +.IP \(bu 2 +A \fBMessage\fP +.UNINDENT +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C + 0 1 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 ++\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ +| Header Length | ++\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ +/ / +\e Header \e +/ / ++\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ +| Message Length | +| (32 bits) | ++\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ +/ / +\e Message \e +/ / ++\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The header length word is 16 bits. It indicates the length of the following +\fBHeader\fP message. The Header is in protocol buffer format. The Header +describes the type and compression status of the following message. +.sp +The message is preceded by the 32 bit message length word and is one of the +concrete BEP messages described below, identified by the \fBtype\fP field of +the Header. +.sp +As always, the length words are in network byte order (big endian). +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +message Header { + MessageType type = 1; + MessageCompression compression = 2; +} + +enum MessageType { + CLUSTER_CONFIG = 0; + INDEX = 1; + INDEX_UPDATE = 2; + REQUEST = 3; + RESPONSE = 4; + DOWNLOAD_PROGRESS = 5; + PING = 6; + CLOSE = 7; +} + +enum MessageCompression { + NONE = 0; + LZ4 = 1; +} +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +When the \fBcompression\fP field is \fBNONE\fP, the message is directly in +protocol buffer format. +.sp +When the compression field is \fBLZ4\fP, the message consists of a 32 bit +integer describing the uncompressed message length followed by a single LZ4 +block. After decompressing the LZ4 block it should be interpreted as a +protocol buffer message just as in the uncompressed case. +.SH MESSAGE SUBTYPES +.SS Cluster Config +.sp +This informational message provides information about the cluster +configuration as it pertains to the current connection. A Cluster Config +message MUST be the first post authentication message sent on a BEP +connection. Additional Cluster Config messages MUST NOT be sent after the +initial exchange. +.SS Protocol Buffer Schema +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +message ClusterConfig { + repeated Folder folders = 1; +} + +message Folder { + string id = 1; + string label = 2; + bool read_only = 3; + bool ignore_permissions = 4; + bool ignore_delete = 5; + bool disable_temp_indexes = 6; + bool paused = 7; + + repeated Device devices = 16; +} + +message Device { + bytes id = 1; + string name = 2; + repeated string addresses = 3; + Compression compression = 4; + string cert_name = 5; + int64 max_sequence = 6; + bool introducer = 7; + uint64 index_id = 8; + bool skip_introduction_removals = 9; +} + +enum Compression { + METADATA = 0; + NEVER = 1; + ALWAYS = 2; +} +.ft P +.fi +.UNINDENT +.UNINDENT +.SS Fields (Cluster Config Message) +.sp +The \fBfolders\fP field contains the list of folders that will be synchronized +over the current connection. +.SS Fields (Folder Message) +.sp +The \fBid\fP field contains the folder ID, which is the unique identifier of +the folder. +.sp +The \fBlabel\fP field contains the folder label, the human readable name of +the folder. +.sp +The \fBread only\fP field is set for folders that the device will accept no +updates from the network for. +.sp +The \fBignore permissions\fP field is set for folders that the device will not +accept or announce file permissions for. +.sp +The \fBignore delete\fP field is set for folders that the device will ignore +deletes for. +.sp +The \fBdisable temp indexes\fP field is set for folders that will not dispatch +and do not wish to receive progress updates about partially downloaded files +via Download Progress messages. +.sp +The \fBpaused\fP field is set for folders that are currently paused. +.sp +The \fBdevices\fP field is a list of devices participating in sharing this +folder. +.SS Fields (Device Message) +.sp +The device \fBid\fP field is a 32 byte number that uniquely identifies the +device. For instance, the reference implementation uses the SHA\-256 of the +device X.509 certificate. +.sp +The \fBname\fP field is a human readable name assigned to the described device +by the sending device. It MAY be empty and it need not be unique. +.sp +The list of \fBaddresses\fP is that used by the sending device to connect to +the described device. +.sp +The \fBcompression\fP field indicates the compression mode in use for this +device and folder. The following values are valid: +.INDENT 0.0 +.TP +.B 0 +Compress metadata. This enables compression of metadata messages such as Index. +.TP +.B 1 +Compression disabled. No compression is used on any message. +.TP +.B 2 +Compress always. Metadata messages as well as Response messages are compressed. +.UNINDENT +.sp +The \fBcert name\fP field indicates the expected certificate name for this +device. It is commonly blank, indicating to use the implementation default. +.sp +The \fBmax sequence\fP field contains the highest sequence number of the files +in the index. See \fI\%Delta Index Exchange\fP for the usage of this field. +.sp +The \fBintroducer\fP field is set for devices that are trusted as cluster +introducers. +.sp +The \fBindex id\fP field contains the unique identifier for the current set of +index data. See \fI\%Delta Index Exchange\fP for the usage of this field. +.sp +The \fBskip introduction removals\fP field signifies if the remote device has +opted to ignore introduction removals for the given device. This setting is +copied across as we are being introduced to a new device. +.SS Index and Index Update +.sp +The Index and Index Update messages define the contents of the senders +folder. An Index message represents the full contents of the folder and +thus supersedes any previous index. An Index Update amends an existing +index with new information, not affecting any entries not included in +the message. An Index Update MAY NOT be sent unless preceded by an +Index, unless a non\-zero Max Sequence has been announced for the +given folder by the peer device. +.sp +The Index and Index Update messages are currently identical in format, +although this is not guaranteed to be the case in the future. +.SS Protocol Buffer Schema +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +message Index { + string folder = 1; + repeated FileInfo files = 2; +} + +message IndexUpdate { + string folder = 1; + repeated FileInfo files = 2; +} + +message FileInfo { + string name = 1; + FileInfoType type = 2; + int64 size = 3; + uint32 permissions = 4; + int64 modified_s = 5; + int32 modified_ns = 11; + uint64 modified_by = 12; + bool deleted = 6; + bool invalid = 7; + bool no_permissions = 8; + Vector version = 9; + int64 sequence = 10; + int32 block_size = 13; + + repeated BlockInfo Blocks = 16; + string symlink_target = 17; +} + +enum FileInfoType { + FILE = 0; + DIRECTORY = 1; + SYMLINK_FILE = 2 [deprecated = true]; + SYMLINK_DIRECTORY = 3 [deprecated = true]; + SYMLINK = 4; +} + +message BlockInfo { + int64 offset = 1; + int32 size = 2; + bytes hash = 3; + uint32 weak_hash = 4; +} + +message Vector { + repeated Counter counters = 1; +} + +message Counter { + uint64 id = 1; + uint64 value = 2; +} +.ft P +.fi +.UNINDENT +.UNINDENT +.SS Fields (Index Message) +.sp +The \fBfolder\fP field identifies the folder that the index message pertains to. +.sp +The \fBfiles\fP field is a list of files making up the index information. +.SS Fields (FileInfo Message) +.sp +The \fBname\fP is the file name path relative to the folder root. Like all +strings in BEP, the Name is always in UTF\-8 NFC regardless of operating +system or file system specific conventions. The name field uses the slash +character (“/”) as path separator, regardless of the implementation’s +operating system conventions. The combination of folder and name uniquely +identifies each file in a cluster. +.sp +The \fBtype\fP field contains the type of the described item. The type is one +of \fBfile (0)\fP, \fBdirectory (1)\fP, or \fBsymlink (4)\fP\&. +.sp +The \fBsize\fP field contains the size of the file, in bytes. For directories +and symlinks the size is zero. +.sp +The \fBpermissions\fP field holds the common Unix permission bits. An +implementation MAY ignore or interpret these as is suitable on the host +operating system. +.sp +The \fBmodified_s\fP time is expressed as the number of seconds since the Unix +Epoch (1970\-01\-01 00:00:00 UTC). The \fBmodified_ns\fP field holds the +nanosecond part of the modification time. +.sp +The \fBmodified_by\fP field holds the short id of the client that last made +any modification to the file whether add, change or delete. This will be +overwritten every time a change is made to the file by the last client to do +so and so does not hold history. +.sp +The \fBdeleted\fP field is set when the file has been deleted. The block list +SHALL be of length zero and the modification time indicates the time of +deletion or, if the time of deletion is not reliably determinable, the last +known modification time. +.sp +The \fBinvalid\fP field is set when the file is invalid and unavailable for +synchronization. A peer MAY set this bit to indicate that it can temporarily +not serve data for the file. +.sp +The \fBno permissions\fP field is set when there is no permission information +for the file. This is the case when it originates on a file system which +does not support permissions. Changes to only permission bits SHOULD be +disregarded on files with this bit set. The permissions bits MUST be set to +the octal value 0666. +.sp +The \fBversion\fP field is a version vector describing the updates performed +to a file by all members in the cluster. Each counter in the version vector +is an ID\-Value tuple. The ID is the first 64 bits of the device ID. The +Value is a simple incrementing counter, starting at zero. The combination of +Folder, Name and Version uniquely identifies the contents of a file at a +given point in time. +.sp +The \fBsequence\fP field is the value of a device local monotonic clock at the +time of last local database update to a file. The clock ticks on every local +database update, thus forming a sequence number over database updates. +.sp +The \fBblock_size\fP field is the size, in bytes, of each individual block in +the block list (except, possibly, the last block). If this field is missing +or zero, the block size is assumed to be 128 KiB (131072 bytes). Valid +values of this field are the powers of two from 128 KiB through 16 MiB. See +also \fI\%Selection of Block Size\fP\&. +.sp +The \fBblocks\fP list contains the size and hash for each block in the file. +Each block represents a \fBblock_size\fP\-sized slice of the file, except for +the last block which may represent a smaller amount of data. The block list +is empty for directories and symlinks. +.sp +The \fBsymlink_target\fP field contains the symlink target, for entries of +symlink type. It is empty for all other entry types. +.SS Request +.sp +The Request message expresses the desire to receive a data block +corresponding to a part of a certain file in the peer’s folder. +.SS Protocol Buffer Schema +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +message Request { + int32 id = 1; + string folder = 2; + string name = 3; + int64 offset = 4; + int32 size = 5; + bytes hash = 6; + bool from_temporary = 7; +} +.ft P +.fi +.UNINDENT +.UNINDENT +.SS Fields +.sp +The \fBid\fP is the request identifier. It will be matched in the +corresponding \fBResponse\fP message. Each outstanding request must have a +unique ID. +.sp +The \fBfolder\fP and \fBname\fP fields are as documented for the Index message. +The \fBoffset\fP and \fBsize\fP fields specify the region of the file to be +transferred. This SHOULD equate to exactly one block as seen in an Index +message. +.sp +The \fIhash\fP field MAY be set to the expected hash value of the block. If set, +the other device SHOULD ensure that the transmitted block matches the +requested hash. The other device MAY reuse a block from a different file and +offset having the same size and hash, if one exists. +.sp +The \fBfrom temporary\fP field is set to indicate that the read should be +performed from the temporary file (converting name to it’s temporary form) +and falling back to the non temporary file if any error occurs. Knowledge of +contents of temporary files comes from DownloadProgress messages. +.SS Response +.sp +The Response message is sent in response to a Request message. +.SS Protocol Buffer Schema +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +message Response { + int32 id = 1; + bytes data = 2; + ErrorCode code = 3; +} + +enum ErrorCode { + NO_ERROR = 0; + GENERIC = 1; + NO_SUCH_FILE = 2; + INVALID_FILE = 3; +} +.ft P +.fi +.UNINDENT +.UNINDENT +.SS Fields +.sp +The \fBid\fP field is the request identifier. It must match the ID of the +\fBRequest\fP that is being responded to. +.sp +The \fBdata\fP field contains either the requested data block or is empty if +the requested block is not available. +.sp +The \fBcode\fP field contains an error code describing the reason a Request +could not be fulfilled, in the case where zero length data was returned. The +following values are defined: +.INDENT 0.0 +.TP +.B 0 +No Error (data should be present) +.TP +.B 1 +Generic Error +.TP +.B 2 +No Such File (the requested file does not exist, or the offset is +outside the acceptable range for the file) +.TP +.B 3 +Invalid (file exists but has invalid bit set or is otherwise +unavailable) +.UNINDENT +.SS DownloadProgress +.sp +The DownloadProgress message is used to notify remote devices about partial +availability of files. By default, these messages are sent every 5 seconds, +and only in the cases where progress or state changes have been detected. +Each DownloadProgress message is addressed to a specific folder and MUST +contain zero or more FileDownloadProgressUpdate messages. +.SS Protocol Buffer Schema +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +message DownloadProgress { + string folder = 1; + repeated FileDownloadProgressUpdate updates = 2; +} + +message FileDownloadProgressUpdate { + FileDownloadProgressUpdateType update_type = 1; + string name = 2; + Vector version = 3; + repeated int32 block_indexes = 4; +} + +enum FileDownloadProgressUpdateType { + APPEND = 0; + FORGET = 1; +} +.ft P +.fi +.UNINDENT +.UNINDENT +.SS Fields (DownloadProgress Message) +.sp +The \fBfolder\fP field represents the ID of the folder for which the update is +being provided. +.sp +The \fBupdates\fP field is a list of progress update messages. +.SS Fields (FileDownloadProgressUpdate Message) +.sp +The \fBupdate type\fP indicates whether the update is of type \fBappend (0)\fP +(new blocks are available) or \fBforget (1)\fP (the file transfer has +completed or failed). +.sp +The \fBname\fP field defines the file name from the global index for which +this update is being sent. +.sp +The \fBversion\fP message defines the version of the file for which this +update is being sent. +.sp +The \fBblock indexes\fP field is a list of positive integers, where each +integer represents the index of the block in the FileInfo message Blocks +array that has become available for download. +.sp +For example an integer with value 3 represents that the data defined in the +fourth BlockInfo message of the FileInfo message of that file is now +available. Please note that matching should be done on \fBname\fP AND +\fBversion\fP\&. Furthermore, each update received is incremental, for example +the initial update message might contain indexes 0, 1, 2, an update 5 +seconds later might contain indexes 3, 4, 5 which should be appended to the +original list, which implies that blocks 0\-5 are currently available. +.sp +Block indexes MAY be added in any order. An implementation MUST NOT assume +that block indexes are added in any specific order. +.sp +The \fBforget\fP field being set implies that previously advertised file is no +longer available, therefore the list of block indexes should be truncated. +.sp +Messages with the \fBforget\fP field set MUST NOT have any block indexes. +.sp +Any update message which is being sent for a different \fBversion\fP of the +same file name must be preceded with an update message for the old version +of that file with the \fBforget\fP field set. +.sp +As a safeguard on the receiving side, the value of \fBversion\fP changing +between update messages implies that the file has changed and that any +indexes previously advertised are no longer available. The list of available +block indexes MUST be replaced (rather than appended) with the indexes +specified in this message. +.SS Ping +.sp +The Ping message is used to determine that a connection is alive, and to +keep connections alive through state tracking network elements such as +firewalls and NAT gateways. A Ping message is sent every 90 seconds, if no +other message has been sent in the preceding 90 seconds. +.SS Protocol Buffer Schema +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +message Ping { +} +.ft P +.fi +.UNINDENT +.UNINDENT +.SS Close +.sp +The Close message MAY be sent to indicate that the connection will be torn +down due to an error condition. A Close message MUST NOT be followed by +further messages. +.SS Protocol Buffer Schema +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +message Close { + string reason = 1; +} +.ft P +.fi +.UNINDENT +.UNINDENT +.SS Fields +.sp +The \fBreason\fP field contains a human readable description of the error +condition. +.SH SHARING MODES +.SS Trusted +.sp +Trusted mode is the default sharing mode. Updates are exchanged in both +directions. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C ++\-\-\-\-\-\-\-\-\-\-\-\-+ Updates /\-\-\-\-\-\-\-\-\-\e +| | \-\-\-\-\-\-\-\-\-\-\-> / \e +| Device | | Cluster | +| | <\-\-\-\-\-\-\-\-\-\-\- \e / ++\-\-\-\-\-\-\-\-\-\-\-\-+ Updates \e\-\-\-\-\-\-\-\-\-/ +.ft P +.fi +.UNINDENT +.UNINDENT +.SS Send Only +.sp +In send only mode, a device does not apply any updates from the cluster, but +publishes changes of its local folder to the cluster as usual. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C ++\-\-\-\-\-\-\-\-\-\-\-\-+ Updates /\-\-\-\-\-\-\-\-\-\e +| | \-\-\-\-\-\-\-\-\-\-\-> / \e +| Device | | Cluster | +| | \e / ++\-\-\-\-\-\-\-\-\-\-\-\-+ \e\-\-\-\-\-\-\-\-\-/ +.ft P +.fi +.UNINDENT +.UNINDENT +.SS Receive Only +.sp +In receive only mode, a device does not send any updates to the cluster, but +accepts changes to its local folder from the cluster as usual. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C ++\-\-\-\-\-\-\-\-\-\-\-\-+ Updates /\-\-\-\-\-\-\-\-\-\e +| | <\-\-\-\-\-\-\-\-\-\-\- / \e +| Device | | Cluster | +| | \e / ++\-\-\-\-\-\-\-\-\-\-\-\-+ \e\-\-\-\-\-\-\-\-\-/ +.ft P +.fi +.UNINDENT +.UNINDENT +.SH DELTA INDEX EXCHANGE +.sp +Index data must be exchanged whenever two devices connect so that one knows +the files available on the other. In the most basic case this happens by way +of sending an \fBIndex\fP message followed by one or more \fBIndex Update\fP +messages. Any previous index data known for a remote device is removed and +replaced with the new index data received in an \fBIndex\fP message, while the +contents of an \fBIndex Update\fP message is simply added to the existing +index data. +.sp +For situations with large indexes or frequent reconnects this can be quite +inefficient. A mechanism can then be used to retain index data between +connections and only transmit any changes since that data on connection +start. This is called “delta indexes”. To enable this mechanism the +\fBsequence\fP and \fBindex ID\fP fields are used. +.INDENT 0.0 +.TP +.B Sequence: +Each index item (i.e., file, directory or symlink) has a sequence number +field. It contains the value of a counter at the time the index item was +updated. The counter increments by one for each change. That is, as files +are scanned and added to the index they get assigned sequence numbers +1, 2, 3 and so on. The next file to be changed or detected gets sequence +number 4, and future updates continue in the same fashion. +.TP +.B Index ID: +Each folder has an Index ID. This is a 64 bit random identifier set at +index creation time. +.UNINDENT +.sp +Given the above, we know that the tuple {index ID, maximum sequence number} +uniquely identifies a point in time of a given index. Any further changes +will increase the sequence number of some item, and thus the maximum +sequence number for the index itself. Should the index be reset or removed +(i.e., the sequence number reset to zero), a new index ID must be generated. +.sp +By letting a device know the {index ID, maximum sequence number} we have for +their index data, that device can arrange to only transmit \fBIndex Update\fP +messages for items with a higher sequence number. This is the delta index +mechanism. +.sp +The index ID and maximum sequence number known for each device is +transmitted in the \fBCluster Config\fP message at connection start. +.sp +For this mechanism to be reliable it is essential that outgoing index +information is ordered by increasing sequence number. Devices announcing a +non\-zero index ID in the \fBCluster Config\fP message MUST send all index data +ordered by increasing sequence number. Devices not intending to participate +in delta index exchange MUST send a zero index ID or, equivalently, not send +the \fBindex_id\fP attribute at all. +.SH MESSAGE LIMITS +.sp +An implementation MAY impose reasonable limits on the length of messages and +message fields to aid robustness in the face of corruption or broken +implementations. An implementation should strive to keep messages short +and to the point, favouring more and smaller messages over fewer and larger. +For example, favour a smaller Index message followed by one or more Index +Update messages rather than sending a very large Index message. +.sp +The Syncthing implementation imposes a hard limit of 500,000,000 bytes on +all messages. Attempting to send or receive a larger message will result in +a connection close. This size was chosen to accommodate Index messages +containing a large block list. It’s intended that the limit may be further +reduced in a future protocol update supporting variable block sizes (and +thus shorter block lists for large files). +.SH SELECTION OF BLOCK SIZE +.sp +The desired block size for any given file is the smallest block size that +results in fewer than 2000 blocks, or the maximum block size for larger +files. This rule results in the following table of block sizes per file +size: +.TS +center; +|l|l|. +_ +T{ +File Size +T} T{ +Block Size +T} +_ +T{ +0 \- 250 MiB +T} T{ +128 KiB +T} +_ +T{ +250 MiB \- 500 MiB +T} T{ +256 KiB +T} +_ +T{ +500 MiB \- 1 GiB +T} T{ +512 KiB +T} +_ +T{ +1 GiB \- 2 GiB +T} T{ +1 MiB +T} +_ +T{ +2 GiB \- 4 GiB +T} T{ +2 MiB +T} +_ +T{ +4 GiB \- 8 GiB +T} T{ +4 MiB +T} +_ +T{ +8 GiB \- 16 GiB +T} T{ +8 MiB +T} +_ +T{ +16 GiB \- up +T} T{ +16 MiB +T} +_ +.TE +.sp +An implementation MAY deviate from the block size rule when there is good +reason to do so. For example, if a file has been indexed at a certain block +size and grows beyond 2000 blocks it may be retained at the current block +size for practical reasons. When there is no overriding reason to the +contrary, such as when indexing a new file for the first time, the block +size rule above SHOULD be followed. +.sp +An implementation MUST therefore accept files with a block size differing +from the above rule. This does not mean that arbitrary block sizes are +allowed. The block size used MUST be exactly one of the power\-of\-two block +sizes listed in the table above. +.SH EXAMPLE EXCHANGE +.TS +center; +|l|l|l|. +_ +T{ +# +T} T{ +A +T} T{ +B +T} +_ +T{ +1 +T} T{ +ClusterConfiguration\-> +T} T{ +<\-ClusterConfiguration +T} +_ +T{ +2 +T} T{ +Index\-> +T} T{ +<\-Index +T} +_ +T{ +3 +T} T{ +IndexUpdate\-> +T} T{ +<\-IndexUpdate +T} +_ +T{ +4 +T} T{ +IndexUpdate\-> +T} T{ +T} +_ +T{ +5 +T} T{ +Request\-> +T} T{ +T} +_ +T{ +6 +T} T{ +Request\-> +T} T{ +T} +_ +T{ +7 +T} T{ +Request\-> +T} T{ +T} +_ +T{ +8 +T} T{ +Request\-> +T} T{ +T} +_ +T{ +9 +T} T{ +T} T{ +<\-Response +T} +_ +T{ +10 +T} T{ +T} T{ +<\-Response +T} +_ +T{ +11 +T} T{ +T} T{ +<\-Response +T} +_ +T{ +12 +T} T{ +T} T{ +<\-Response +T} +_ +T{ +13 +T} T{ +Index Update\-> +T} T{ +T} +_ +T{ +… +T} T{ +T} T{ +T} +_ +T{ +14 +T} T{ +T} T{ +<\-Ping +T} +_ +T{ +15 +T} T{ +Ping\-> +T} T{ +T} +_ +.TE +.sp +The connection is established and at 1. both peers send ClusterConfiguration +messages and then Index records. The Index records are received and both +peers recompute their knowledge of the data in the cluster. In this example, +peer A has four missing or outdated blocks. At 5 through 8 peer A sends +requests for these blocks. The requests are received by peer B, who +retrieves the data from the folder and transmits Response records (9 through +12). Device A updates their folder contents and transmits an Index Update +message (13). Both peers enter idle state after 13. At some later time 14, +the ping timer on device B expires and a Ping message is sent. The same +process occurs for device A at 15. +.SH EXAMPLES OF STRONG CIPHER SUITES +.TS +center; +|l|l|l|. +_ +T{ +ID +T} T{ +Name +T} T{ +Description +T} +_ +T{ +0x009F +T} T{ +DHE\-RSA\-AES256\-GCM\-SHA384 +T} T{ +TLSv1.2 DH RSA AESGCM(256) AEAD +T} +_ +T{ +0x006B +T} T{ +DHE\-RSA\-AES256\-SHA256 +T} T{ +TLSv1.2 DH RSA AES(256) SHA256 +T} +_ +T{ +0xC030 +T} T{ +ECDHE\-RSA\-AES256\-GCM\-SHA384 +T} T{ +TLSv1.2 ECDH RSA AESGCM(256) AEAD +T} +_ +T{ +0xC028 +T} T{ +ECDHE\-RSA\-AES256\-SHA384 +T} T{ +TLSv1.2 ECDH RSA AES(256) SHA384 +T} +_ +T{ +0x009E +T} T{ +DHE\-RSA\-AES128\-GCM\-SHA256 +T} T{ +TLSv1.2 DH RSA AESGCM(128) AEAD +T} +_ +T{ +0x0067 +T} T{ +DHE\-RSA\-AES128\-SHA256 +T} T{ +TLSv1.2 DH RSA AES(128) SHA256 +T} +_ +T{ +0xC02F +T} T{ +ECDHE\-RSA\-AES128\-GCM\-SHA256 +T} T{ +TLSv1.2 ECDH RSA AESGCM(128) AEAD +T} +_ +T{ +0xC027 +T} T{ +ECDHE\-RSA\-AES128\-SHA256 +T} T{ +TLSv1.2 ECDH RSA AES(128) SHA256 +T} +_ +.TE +.SH AUTHOR +The Syncthing Authors +.SH COPYRIGHT +2014-2019, The Syncthing Authors +.\" Generated by docutils manpage writer. +. diff --git a/man/syncthing-config.5 b/man/syncthing-config.5 index 44d986c4b..c39b7ffc1 100644 --- a/man/syncthing-config.5 +++ b/man/syncthing-config.5 @@ -1 +1,1150 @@ -404 Not Found +.\" Man page generated from reStructuredText. +. +.TH "SYNCTHING-CONFIG" "5" "Jun 19, 2020" "v1" "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 +.. +.SH SYNOPSIS +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +$HOME/.config/syncthing +$HOME/Library/Application Support/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), +or \fB%LOCALAPPDATA%/Syncthing\fP (Windows). 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 \fBconfig.xml\fP +The configuration file, in XML format. +.TP +.B \fBcert.pem\fP, \fBkey.pem\fP +The device’s ECDSA public and private key. These form the basis for the +device ID. The key must be kept private. +.TP +.B \fBhttps\-cert.pem\fP, \fBhttps\-key.pem\fP +The certificate and key for HTTPS GUI connections. These may be replaced +with a custom certificate for HTTPS as desired. +.TP +.B \fBindex\-\fP\fI*\fP\fB\&.db\fP +A directory holding the database with metadata and hashes of the files +currently on disk and available from peers. +.TP +.B \fBcsrftokens.txt\fP +A list of recently issued CSRF tokens (for protection against browser cross +site request forgery). +.UNINDENT +.SH CONFIG FILE FORMAT +.sp +The following shows an example of the default configuration file (IDs will differ): +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C + + + basic + + 1 + + 0 + 0 + 0 + random + false + 0 + 0 + \-1 + false + false + false + 25 + .stfolder + false + 0 + 2 + false + standard + standard + + +
dynamic
+ false + false + 0 + 0 + 0 + + +
127.0.0.1:8384
+ k1dnz1Dd0rzTBjjFFh7CXPnrF12C49B1 + default + + + + tcp://0.0.0.0:8384 + dynamic+https://relays.syncthing.net/endpoint + default + true + true + 21027 + [ff12::8384]:21027 + 0 + 0 + 60 + true + 10 + true + true + 60 + 30 + 10 + 0 + 0 + + https://data.syncthing.net/newdata + false + 1800 + true + 12 + false + 24 + false + 5 + false + 1 + https://upgrades.syncthing.net/meta.json + false + 10 + 0 + ~ + true + 0 + https://crash.syncthing.net/newcrash + true + 180 + 20 + default + auto + 0 + + +.ft P +.fi +.UNINDENT +.UNINDENT +.SH CONFIGURATION ELEMENT +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C + + + + + + + 5SYI2FS\-LW6YAXI\-JJDYETS\-NDBBPIO\-256MWBO\-XDPXWVG\-24QPUM4\-PDW4UQU + bd7q3\-zskm5 + +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +This is the root element. It has one attribute: +.INDENT 0.0 +.TP +.B version +The config version. Increments whenever a change is made that requires +migration from previous formats. +.UNINDENT +.sp +It contains the elements described in the following sections and these two +additional child elements: +.INDENT 0.0 +.TP +.B ignoredDevice +Contains the ID of the device that should be ignored. Connection attempts +from this device are logged to the console but never displayed in the web +GUI. +.TP +.B ignoredFolder +Contains the ID of the folder that should be ignored. This folder will +always be skipped when advertised from a remote device, i.e. this will be +logged, but there will be no dialog about it in the web GUI. +.UNINDENT +.SH FOLDER ELEMENT +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C + + basic + + 1 + + 0 + 0 + 0 + random + false + 0 + 0 + \-1 + false + false + false + 25 + .stfolder + false + 0 + 2 + false + standard + standard + +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +One or more \fBfolder\fP elements must be present in the file. Each element +describes one folder. The following attributes may be set on the \fBfolder\fP +element: +.INDENT 0.0 +.TP +.B id +The folder ID, must be unique. (mandatory) +.TP +.B label +The label of a folder is a human readable and descriptive local name. May +be different on each device, empty, and/or identical to other folder +labels. (optional) +.TP +.B path +The path to the directory where the folder is stored on this +device; not sent to other devices. (mandatory) +.TP +.B type +Controls how the folder is handled by Syncthing. Possible values are: +.INDENT 7.0 +.TP +.B sendreceive +The folder is in default mode. Sending local and accepting remote changes. +Note that this type was previously called “readwrite” which is deprecated +but still accepted in incoming configs. +.TP +.B sendonly +The folder is in “send only” mode – it will not be modified by +Syncthing on this device. +Note that this type was previously called “readonly” which is deprecated +but still accepted in incoming configs. +.TP +.B receiveonly +The folder is in “receive only” mode – it will not propagate +changes to other devices. +.UNINDENT +.TP +.B rescanIntervalS +The rescan interval, in seconds. Can be set to zero to disable when external +plugins are used to trigger rescans. +.TP +.B fsWatcherEnabled +If enabled this detects changes to files in the folder and scans them. +.UNINDENT +.INDENT 0.0 +.TP +.B fsWatcherDelayS +The duration during which changes detected are accumulated, before a scan is +scheduled (only takes effect if \fBfsWatcherEnabled\fP is true). +.TP +.B ignorePerms +True if the folder should ignore permissions. +.TP +.B autoNormalize +Automatically correct UTF\-8 normalization errors found in file names. +.UNINDENT +.sp +The following child elements may exist: +.INDENT 0.0 +.TP +.B device +These must have the \fBid\fP attribute and can have an \fBintroducedBy\fP attribute, +identifying the device that introduced us to share this folder with the given device. +If the original introducer unshares this folder with this device, our device will follow +and unshare the folder (subject to skipIntroductionRemovals being false on the introducer device). +All 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 folders. +Syncthing will currently add this automatically if it is not present in +the configuration file. +.TP +.B minDiskFree +The minimum required free space that should be available on the disk this folder +resides. The folder will be stopped when the value drops below the threshold. Accepted units are +\fB%\fP, \fBkB\fP, \fBMB\fP, \fBGB\fP and \fBTB\fP\&. Set to zero to disable. +.TP +.B versioning +Specifies a versioning configuration. +.UNINDENT +.sp +\fBSEE ALSO:\fP +.INDENT 0.0 +.INDENT 3.5 +versioning +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B copiers, pullers, hashers +The number of copier, puller and hasher routines to use, or zero for the +system determined optimum. These are low level performance options for +advanced users only; do not change unless requested to or you’ve actually +read and understood the code yourself. :) +.TP +.B order +The order in which needed files should be pulled from the cluster. +The possibles values are: +.INDENT 7.0 +.TP +.B random +Pull files in random order. This optimizes for balancing resources among +the devices in a cluster. +.TP +.B alphabetic +Pull files ordered by file name alphabetically. +.TP +.B smallestFirst, largestFirst +Pull files ordered by file size; smallest and largest first respectively. +.TP +.B oldestFirst, newestFirst +Pull files ordered by modification time; oldest and newest first +respectively. +.UNINDENT +.sp +Note that the scanned files are sent in batches and the sorting is applied +only to the already discovered files. This means the sync might start with +a 1 GB file even if there is 1 KB file available on the source device until +the 1 KB becomes known to the pulling device. +.TP +.B ignoreDelete +When set to true, this device will pretend not to see instructions to +delete files from other devices. +.TP +.B scanProgressIntervalS +The interval with which scan progress information is sent to the GUI. Zero +means the default value (two seconds). +.TP +.B pullerPauseS +Tweak for rate limiting the puller when it retries pulling files. Don’t +change these unless you know what you’re doing. +.TP +.B maxConflicts +The maximum number of conflict copies to keep around for any given file. +The default, \-1, means an unlimited number. Setting this to zero disables +conflict copies altogether. +.TP +.B disableSparseFiles +By default, blocks containing all zeroes are not written, causing files +to be sparse on filesystems that support the concept. When set to true, +sparse files will not be created. +.TP +.B disableTempIndexes +By default, devices exchange information about blocks available in +transfers that are still in progress, which allows other devices to +download parts of files that are not yet fully downloaded on your own +device, essentially making transfers more torrent like. When set to +true, such information is not exchanged for this folder. +.TP +.B paused +True if this folder is (temporarily) suspended. +.TP +.B weakHashThresholdPct +Use weak hash if more than the given percentage of the file has changed. Set +to \-1 to always use weak hash. Default value is 25. +.TP +.B markerName +Name of a directory or file in the folder root to be used as +marker\-faq\&. Default is “.stfolder”. +.TP +.B copyOwnershipFromParent +On Unix systems, tries to copy file/folder ownership from the parent directory (the directory it’s located in). +Requires running Syncthing as privileged user, or granting it additional capabilities (e.g. CAP_CHOWN on Linux). +.TP +.B modTimeWindowS +Allowed modification timestamp difference when comparing files for equivalence. +To be used on systems that have unstable modification timestamps, that might change after being observed after +the last write operation. Used in Android only. +.TP +.B maxConcurrentWrites +Maximum number of concurrent write operations while syncing. Defaults to 2. Increasing this might increase or +decrease disk performance, depending on the underlying storage. +.UNINDENT +.sp +disableFsync +.INDENT 0.0 +.INDENT 3.5 +.sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +This is a known insecure option \- use at your own risk. +.UNINDENT +.UNINDENT +.sp +Disables committing file operations to disk before recording them in the database. +Disabling fsync can lead to data corruption. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B blockPullOrder +Order in which the blocks of a file are downloaded. This option controls how quickly different parts of the +file spread between the connected devices, at the cost of causing strain on the storage. +.sp +Available options: +.INDENT 7.0 +.TP +.B standard (default): +The blocks of a file are split into N equal continuous sequences, where N is the number of connected +devices. Each device starts downloading it’s own sequence, after which it picks other devices +sequences at random. Provides acceptable data distribution and minimal spinning disk strain. +.TP +.B random: +The blocks of a file are downloaded in a random order. Provides great data distribution, but very taxing on +spinning disk drives. +.TP +.B inOrder: +The blocks of a file are downloaded sequentially, from start to finish. Spinning disk drive friendly, but provides +no improvements to data distribution. +.UNINDENT +.TP +.B copyRangeMethod +Provides a choice of method for copying data between files. This can be used to optimise copies on network +filesystems, improve speed of large copies or clone the data using copy\-on\-write functionality if the underlying +filesystem supports it. +.sp +\fBWARNING:\fP +.INDENT 7.0 +.INDENT 3.5 +This is an experimental feature, so please use at your own risk. +.UNINDENT +.UNINDENT +.INDENT 7.0 +.TP +.B standard (default) +Reads the data from source file into application memory, writes the data from application memory into the +destination file. +.sp +Available on: All platforms +.TP +.B copy_file_range +Uses copy_file_range syscall, which if underlying filesystem supports, uses copy\-on\-write semantics to +clone the data. Introduced in Linux 4.5 and tested on XFS and BTRFS. Some network filesystems might use this +to perform server\-side copies. +.sp +Tested on: BTRFS, XFS +Available on: Linux +.TP +.B ioctl +Uses ioctl syscall with FICLONERANGE option, which if underlying filesystem supports, uses copy\-on\-write +semantics to clone the data. Officially introduced in Linux 4.5, but was previously known as +BTRFS_IOC_CLONE_RANGE, which was used to provide copy\-on\-write semantics to BTRFS filesystems since Linux 2.6.29. +Some network filesystems might use this to perform server\-side copies. Will fail if not supported by the +underlying filesystem. +.sp +Tested on: BTRFS +Not available on: Windows, Solaris, Darwin (OS X) +.TP +.B sendfile +Uses sendfile syscall, which performs in\-kernel copy, avoiding having to copy the data into application memory. +.sp +Tested on: BTRFS, XFS +Not available on: Windows, Darwin (OS X) +.TP +.B duplicate_extents +Uses Windows Block Cloning via FSCTL_DUPLICATE_EXTENTS_TO_FILE, which provides copy\-on\-write semantics to clone +the data. Requires Windows Server 2016 or later, and a compatible filesystem (ReFS, SMB 3.1.1, CsvFS). Will +fail if not supported by the underlying filesystem. +.sp +\fBWARNING:\fP +.INDENT 7.0 +.INDENT 3.5 +Completely untested, use at your own risk. +.UNINDENT +.UNINDENT +.sp +Available on: Windows +.TP +.B all +Tries all of the copy methods in the following order: ioctl, copy_file_range, sendfile, duplicate_extents, +standard. +.sp +Available on: All platforms +.sp +\fBWARNING:\fP +.INDENT 7.0 +.INDENT 3.5 +Not recommended on Windows as it has not been tested, might be very costly on all other platforms. +.UNINDENT +.UNINDENT +.UNINDENT +.TP +.B fsync +Deprecated since version v0.14.37. + +.sp +Transfer updated (from other devices) files to permanent storage before +committing the changes to the internal database. +.TP +.B pullerSleepS +Deprecated since version v0.14.41. + +.sp +Tweak for rate limiting the puller. Don’t change these unless you know +what you’re doing. +.UNINDENT +.SH DEVICE ELEMENT +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C + +
dynamic
+ false + false + 0 + 0 + 0 + + +
tcp://192.0.2.1:22001
+ true + 192.168.0.0/16 + false + 100 + 100 + 65536 + +.ft P +.fi +.UNINDENT +.UNINDENT +.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. The following attributes may be set on the \fBdevice\fP +element: +.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 compression +Whether to use protocol compression when sending messages to this device. +The possible values are: +.INDENT 7.0 +.TP +.B metadata +Compress metadata packets, such as index information. Metadata is +usually very compression friendly so this is a good default. +.TP +.B always +Compress all packets, including file data. This is recommended if the +folders contents are mainly compressible data such as documents or +text files. +.TP +.B never +Disable all compression. +.UNINDENT +.TP +.B introducer +Set to true if this device should be trusted as an introducer, i.e. we +should copy their list of devices per folder when connecting. +.UNINDENT +.sp +\fBSEE ALSO:\fP +.INDENT 0.0 +.INDENT 3.5 +introducer +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B skipIntroductionRemovals +Set to true if you wish to follow only introductions and not de\-introductions. +For example, if this is set, we would not remove a device that we were introduced +to even if the original introducer is no longer listing the remote device as known. +.TP +.B introducedBy +Defines which device has introduced us to this device. Used only for following de\-introductions. +.TP +.B certName +The device certificate common name, if it is not the default “syncthing”. +.UNINDENT +.sp +From following child elements at least one \fBaddress\fP child must exist. +.INDENT 0.0 +.TP +.B address +Contains an address or host name to use when attempting to connect to this device. +Entries other than \fBdynamic\fP must be prefixed with \fBtcp://\fP (dual\-stack), +\fBtcp4://\fP (IPv4 only) or \fBtcp6://\fP (IPv6 only). Note that IP addresses need +not use tcp4/tcp6; these are optional. Accepted formats are: +.INDENT 7.0 +.TP +.B IPv4 address (\fBtcp://192.0.2.42\fP) +The default port (22000) is used. +.TP +.B IPv4 address and port (\fBtcp://192.0.2.42:12345\fP) +The address and port is used as given. +.TP +.B IPv6 address (\fBtcp://[2001:db8::23:42]\fP) +The default port (22000) is used. The address must be enclosed in +square brackets. +.TP +.B IPv6 address and port (\fBtcp://[2001:db8::23:42]:12345\fP) +The address and port is used as given. The address must be enclosed in +square brackets. +.TP +.B Host name (\fBtcp6://fileserver\fP) +The host name will be used on the default port (22000) and connections +will be attempted only via IPv6. +.TP +.B Host name and port (\fBtcp://fileserver:12345\fP) +The host name will be used on the given port and connections will be +attempted via both IPv4 and IPv6, depending on name resolution. +.TP +.B \fBdynamic\fP +The word \fBdynamic\fP (without \fBtcp://\fP prefix) means to use local and +global discovery to find the device. +.UNINDENT +.sp +You can set multiple addresses \fIand\fP combine it with the \fBdynamic\fP keyword +for example: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C + +
tcp://192.0.2.1:22001
+
tcp://192.0.1.254:22000
+
dynamic
+ +.ft P +.fi +.UNINDENT +.UNINDENT +.TP +.B paused +True if synchronization with this devices is (temporarily) suspended. +.TP +.B allowedNetwork +If given, this restricts connections to this device to only this network +(see allowed\-networks). +.TP +.B maxSendKbps +Maximum send rate to use for this device. Unit is kibibytes/second, despite +the config name looking like kilobits/second. +.TP +.B maxRecvKbps +Maximum receive rate to use for this device. Unit is kibibytes/second, +despite the config name looking like kilobits/second. +.TP +.B maxRequestKiB +Maximum amount of data to have outstanding in requests towards this device. +Unit is kibibytes. +.UNINDENT +.SH GUI ELEMENT +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C + +
127.0.0.1:8384
+ l7jSbCqPD95JYZ0g8vi4ZLAMg3ulnN1b + default + +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +There must be exactly one \fBgui\fP element. The GUI configuration is also used +by the rest\-api and the event\-api\&. The following attributes may +be set on the \fBgui\fP element: +.INDENT 0.0 +.TP +.B enabled +If not \fBtrue\fP, the GUI and API will not be started. +.TP +.B tls +If set to \fBtrue\fP, TLS (HTTPS) will be enforced. Non\-HTTPS requests will +be redirected to HTTPS. When this is set to \fBfalse\fP, TLS connections are +still possible but it is not mandatory. +.TP +.B debugging +This enables profiling and additional debugging endpoints in the rest\-api\&. +.UNINDENT +.sp +The following child elements may be present: +.INDENT 0.0 +.TP +.B address +Set the listen address. One address element must be present. Allowed address formats are: +.INDENT 7.0 +.TP +.B IPv4 address and port (\fB127.0.0.1:8384\fP) +The address and port is used as given. +.TP +.B IPv6 address and port (\fB[::1]:8384\fP) +The address and port is used as given. The address must be enclosed in +square brackets. +.TP +.B Wildcard and port (\fB0.0.0.0:12345\fP, \fB[::]:12345\fP, \fB:12345\fP) +These are equivalent and will result in Syncthing listening on all +interfaces via both IPv4 and IPv6. +.TP +.B UNIX socket location (\fB/var/run/st.sock\fP) +If the address is an absolute path it is interpreted as the path to a UNIX socket. +(Added in v0.14.52.) +.UNINDENT +.TP +.B unixSocketPermissions +In the case that a UNIX socket location is used for \fBaddress\fP, set this to an octal to override the default permissions of the socket. +.TP +.B user +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. +.TP +.B insecureAdminAccess +If true, this allows access to the web GUI from outside (i.e. not localhost) +without authorization. A warning will displayed about this setting on startup. +.TP +.B theme +The name of the theme to use. +.TP +.B authMode +Authentication mode to use. If not present authentication mode (static) +is controlled by presence of user/passward fields for backward compatibility. +.INDENT 7.0 +.TP +.B static +Authentication using user and password. +.TP +.B ldap +LDAP authentication. Requires ldap top level config section to be present. +.UNINDENT +.UNINDENT +.SH LDAP ELEMENT +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C + +
localhost:389
+ cn=%s,ou=users,dc=syncthing,dc=net + nontls + false + +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The \fBldap\fP element contains LDAP configuration options. +.INDENT 0.0 +.TP +.B address +LDAP server address (server:port). +.TP +.B bindDN +BindDN for user authentication. +Special %s variable shoild be used to pass username to LDAP. +.UNINDENT +.sp +transport +.INDENT 0.0 +.INDENT 3.5 +.INDENT 0.0 +.TP +.B nontls +Non secure connection. +.TP +.B tls +TLS secured connection. +.TP +.B starttls +StartTLS connection mode. +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B insecureSkipVerify +Skip verification (true or false). +.UNINDENT +.SH OPTIONS ELEMENT +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C + + tcp://0.0.0.0:8384 + dynamic+https://relays.syncthing.net/endpoint + default + true + true + 21027 + [ff12::8384]:21027 + 0 + 0 + 60 + true + 10 + true + true + 60 + 30 + 10 + 0 + 0 + + https://data.syncthing.net/newdata + false + 1800 + true + 12 + false + 24 + false + 5 + false + 1 + https://upgrades.syncthing.net/meta.json + false + 10 + 0 + ~ + true + 0 + https://crash.syncthing.net/newcrash + true + 180 + 20 + default + auto + 0 + +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The \fBoptions\fP element contains all other global configuration options. +.INDENT 0.0 +.TP +.B listenAddress +The listen address for incoming sync connections. See +\fI\%Listen Addresses\fP for allowed syntax. +.TP +.B globalAnnounceServer +A URI to a global announce (discovery) server, or the word \fBdefault\fP to +include the default servers. Any number of globalAnnounceServer elements +may be present. The syntax for non\-default entries is that of a HTTP or +HTTPS URL. A number of options may be added as query options to the URL: +\fBinsecure\fP to prevent certificate validation (required for HTTP URLs) +and \fBid=\fP to perform certificate pinning. The device ID to +use is printed by the discovery server on startup. +.TP +.B globalAnnounceEnabled +Whether to announce this device to the global announce (discovery) server, +and also use it to look up other devices. +.TP +.B localAnnounceEnabled +Whether to send announcements to the local LAN, also use such +announcements to find other devices. +.TP +.B localAnnouncePort +The port on which to listen and send IPv4 broadcast announcements to. +.TP +.B localAnnounceMCAddr +The group address and port to join and send IPv6 multicast announcements on. +.TP +.B maxSendKbps +Outgoing data rate limit, in kibibytes per second. +.TP +.B maxRecvKbps +Incoming data rate limits, in kibibytes per second. +.TP +.B reconnectionIntervalS +The number of seconds to wait between each attempt to connect to currently +unconnected devices. +.TP +.B relaysEnabled +When true, relays will be connected to and potentially used for device to device connections. +.TP +.B relayReconnectIntervalM +Sets the interval, in minutes, between relay reconnect attempts. +.TP +.B startBrowser +Whether to attempt to start a browser to show the GUI when Syncthing starts. +.TP +.B natEnabled +Whether to attempt to perform a UPnP and NAT\-PMP port mapping for +incoming sync connections. +.TP +.B natLeaseMinutes +Request a lease for this many minutes; zero to request a permanent lease. +.TP +.B natRenewalMinutes +Attempt to renew the lease after this many minutes. +.TP +.B natTimeoutSeconds +When scanning for UPnP devices, wait this long for responses. +.TP +.B urAccepted +Whether the user has 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, a number above zero means that that +version of usage reporting has been accepted. +.TP +.B urSeen +The highest usage reporting version that has already been shown in the web GUI. +.TP +.B urUniqueID +The unique ID sent together with the usage report. Generated when usage +reporting is enabled. +.TP +.B urURL +The URL to post usage report data to, when enabled. +.TP +.B urPostInsecurely +When true, the UR URL can be http instead of https, or have a self\-signed +certificate. The default is \fBfalse\fP\&. +.TP +.B urInitialDelayS +The time to wait from startup to the first usage report being sent. Allows +the system to stabilize before reporting statistics. +.TP +.B restartOnWakeup +Whether to perform a restart of Syncthing when it is detected that we are +waking from sleep mode (i.e. a folded up laptop). +.TP +.B autoUpgradeIntervalH +Check for a newer version after this many hours. Set to zero to disable +automatic upgrades. +.TP +.B upgradeToPreReleases +If true, automatic upgrades include release candidates (see +releases). +.TP +.B keepTemporariesH +Keep temporary failed transfers for this many hours. While the temporaries +are kept, the data they contain need not be transferred again. +.TP +.B cacheIgnoredFiles +Whether to cache the results of ignore pattern evaluation. Performance +at the price of memory. Defaults to \fBfalse\fP as the cost for evaluating +ignores is usually not significant. +.TP +.B progressUpdateIntervalS +How often in seconds the progress of ongoing downloads is made available to +the GUI. +.TP +.B limitBandwidthInLan +Whether to apply bandwidth limits to devices in the same broadcast domain +as the local device. +.TP +.B minHomeDiskFree +The minimum required free space that should be available on the +partition holding the configuration and index. Accepted units are \fB%\fP, \fBkB\fP, +\fBMB\fP, \fBGB\fP and \fBTB\fP\&. +.TP +.B releasesURL +The URL from which release information is loaded, for automatic upgrades. +.TP +.B alwaysLocalNet +Network that should be considered as local given in CIDR notation. +.TP +.B overwriteRemoteDeviceNamesOnConnect +If set, device names will always be overwritten with the name given by +remote on each connection. By default, the name that the remote device +announces will only be adopted when a name has not already been set. +.TP +.B tempIndexMinBlocks +When exchanging index information for incomplete transfers, only take +into account files that have at least this many blocks. +.TP +.B unackedNotificationID +ID of a notification to be displayed in the web GUI. Will be removed once +the user acknowledged it (e.g. an transition notice on an upgrade). +.TP +.B trafficClass +Specify a type of service (TOS)/traffic class of outgoing packets. +.TP +.B stunServer +Server to be used for STUN, given as ip:port. The keyword \fBdefault\fP gets +expanded to +\fBstun.callwithus.com:3478\fP, \fBstun.counterpath.com:3478\fP, +\fBstun.counterpath.net:3478\fP, \fBstun.ekiga.net:3478\fP, +\fBstun.ideasip.com:3478\fP, \fBstun.internetcalls.com:3478\fP, +\fBstun.schlund.de:3478\fP, \fBstun.sipgate.net:10000\fP, +\fBstun.sipgate.net:3478\fP, \fBstun.voip.aebc.com:3478\fP, +\fBstun.voiparound.com:3478\fP, \fBstun.voipbuster.com:3478\fP, +\fBstun.voipstunt.com:3478\fP and \fBstun.xten.com:3478\fP (this is the default). +.TP +.B stunKeepaliveSeconds +Interval in seconds between contacting a STUN server to +maintain NAT mapping. Default is \fB24\fP and you can set it to \fB0\fP to +disable contacting STUN servers. +.TP +.B defaultFolderPath +The UI will propose to create new folders at this path. This can be disabled by +setting this to an empty string. +.UNINDENT +.INDENT 0.0 +.TP +.B setLowPriority +Syncthing will attempt to lower its process priority at startup. +Specifically: on Linux, set itself to a separate process group, set the +niceness level of that process group to nine and the I/O priority to +best effort level five; on other Unixes, set the process niceness level +to nine; on Windows, set the process priority class to below normal. To +disable this behavior, for example to control process priority yourself +as part of launching Syncthing, set this option to \fBfalse\fP\&. +.UNINDENT +.SS Listen Addresses +.sp +The following address types are accepted in sync protocol listen addresses. If you want Syncthing to listen on multiple addresses, you can have multiple \fB\fP tags. The same is achieved in the GUI by entering several addresses separated by comma. +.INDENT 0.0 +.TP +.B Default listen addresses (\fBdefault\fP) +This is equivalent to \fBtcp://0.0.0.0:22000\fP, \fBquic://0.0.0.0:22000\fP +and \fBdynamic+https://relays.syncthing.net/endpoint\fP\&. +.TP +.B TCP wildcard and port (\fBtcp://0.0.0.0:22000\fP, \fBtcp://:22000\fP) +These are equivalent and will result in Syncthing listening on all +interfaces, IPv4 and IPv6, on the specified port. +.TP +.B TCP IPv4 wildcard and port (\fBtcp4://0.0.0.0:22000\fP, \fBtcp4://:22000\fP) +These are equivalent and will result in Syncthing listening on all +interfaces via IPv4 only. +.TP +.B TCP IPv4 address and port (\fBtcp4://192.0.2.1:22000\fP) +This results in Syncthing listening on the specified address and port, IPv4 +only. +.TP +.B TCP IPv6 wildcard and port (\fBtcp6://[::]:22000\fP, \fBtcp6://:22000\fP) +These are equivalent and will result in Syncthing listening on all +interfaces via IPv6 only. +.TP +.B TCP IPv6 address and port (\fBtcp6://[2001:db8::42]:22000\fP) +This results in Syncthing listening on the specified address and port, IPv6 +only. +.TP +.B QUIC address and port (e.g. \fBquic://0.0.0.0:22000\fP) +Syntax is the same as for TCP, also \fBquic4\fP and \fBquic6\fP can be used. +.TP +.B Static relay address (\fBrelay://192.0.2.42:22067?id=abcd123...\fP) +Syncthing will connect to and listen for incoming connections via the +specified relay address. +.INDENT 7.0 +.INDENT 3.5 +.SS Todo +.sp +Document available URL parameters. +.UNINDENT +.UNINDENT +.TP +.B Dynamic relay pool (\fBdynamic+https://192.0.2.42/relays\fP) +Syncthing will fetch the specified HTTPS URL, parse it for a JSON payload +describing relays, select a relay from the available ones and listen via +that as if specified as a static relay above. +.INDENT 7.0 +.INDENT 3.5 +.SS Todo +.sp +Document available URL parameters. +.UNINDENT +.UNINDENT +.UNINDENT +.SH SYNCING CONFIGURATION FILES +.sp +Syncing configuration files between devices (such that multiple devices are +using the same configuration files) can cause issues. This is easy to do +accidentally if you sync your home folder between devices. A common symptom +of syncing configuration files is two devices ending up with the same Device ID. +.sp +If you want to use Syncthing to backup your configuration files, it is recommended +that the files you are backing up are in a folder\-sendonly to prevent other +devices from overwriting the per device configuration. The folder on the remote +device(s) should not be used as configuration for the remote devices. +.sp +If you’d like to sync your home folder in non\-send only mode, you may add the +folder that stores the configuration files to the ignore list\&. +If you’d also like to backup your configuration files, add another folder in +send only mode for just the configuration folder. +.SH AUTHOR +The Syncthing Authors +.SH COPYRIGHT +2014-2019, The Syncthing Authors +.\" Generated by docutils manpage writer. +. diff --git a/man/syncthing-device-ids.7 b/man/syncthing-device-ids.7 index 44d986c4b..9271d8a19 100644 --- a/man/syncthing-device-ids.7 +++ b/man/syncthing-device-ids.7 @@ -1 +1,266 @@ -404 Not Found +.\" Man page generated from reStructuredText. +. +.TH "SYNCTHING-DEVICE-IDS" "7" "Jun 19, 2020" "v1" "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 +.. +.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 +interchangeably have been “key ID” since the device ID is a direct property of +the public key in use. +.SH KEYS +.sp +To understand device IDs we need to look at the underlying mechanisms. At first +startup, Syncthing will create a public/private keypair. +.sp +Currently this is a 384 bit ECDSA key (3072 bit RSA prior to v0.12.5, +which is what is used as an example in this article). 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’t 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 a whole number of bytes. The +base32 encoding adds padding to 280 bits (the next multiple of both 5 and 8 +bits) so the resulting ID looks something like: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +MFZWI3DBONSGYYLTMRWGC43ENRQXGZDMMFZWI3DBONSGYYLTMRWA==== +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The padding (\fB====\fP) is stripped away, the device ID split into four +groups, and \fI\%check +digits\fP <\fBhttps://forum.syncthing.net/t/v0-9-0-new-node-id-format/478\fP> +are added for each group. For presentation purposes the device ID is +grouped with dashes, resulting in the final value: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +MFZWI3D\-BONSGYC\-YLTMRWG\-C43ENR5\-QXGZDMM\-FZWI3DP\-BONSGYY\-LTMRWAD +.ft P +.fi +.UNINDENT +.UNINDENT +.SS Connection Establishment +.sp +Now we know what device IDs are, here’s how they are used in Syncthing. When +you add a device ID to the configuration, Syncthing will attempt to +connect to that device. The first thing we need to do is figure out the IP and +port to connect to. There are three possibilities here: +.INDENT 0.0 +.IP \(bu 2 +The IP and port can be set statically in the configuration. The IP +can equally well be a host name, so if you have a static IP or a +dynamic DNS setup this might be a good option. +.IP \(bu 2 +Using local discovery, if enabled. Every Syncthing instance on a LAN +periodically broadcasts information about itself (device ID, address, +port number). If we’ve seen one of these broadcasts for a given +device ID that’s 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’t have a static address and haven’t seen +any local announcements the global discovery server will be queried +for an address. +.UNINDENT +.sp +Once we have an address and port a TCP connection is established and a TLS +handshake performed. As part of the handshake both devices present their +certificates. Once the handshake has completed and the peer certificate is +known, the following steps are performed: +.INDENT 0.0 +.IP 1. 3 +Calculate the remote device ID by processing the received certificate as above. +.IP 2. 3 +Weed out a few possible misconfigurations \- i.e. if the device ID is +that of the local device or of a device we already have an active +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’s an infinite +amount of inputs and a finite amount of outputs \- so by definition there +are infinitely many messages that result in the same hash. +.sp +I’m going to quote \fI\%stack +overflow\fP <\fBhttps://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’s 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’s 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’t 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’t get in. +.sp +Note also that it’s 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, the local discovery mechanism isn’t protected by crypto. This +means that any device can in theory announce itself for any device ID and +potentially receive connections for that device from the local network. +.SS Long Device IDs are Painful +.sp +It’s 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’t 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 +2014-2019, The Syncthing Authors +.\" Generated by docutils manpage writer. +. diff --git a/man/syncthing-event-api.7 b/man/syncthing-event-api.7 index 44d986c4b..5ab906a42 100644 --- a/man/syncthing-event-api.7 +++ b/man/syncthing-event-api.7 @@ -1 +1,881 @@ -404 Not Found +.\" Man page generated from reStructuredText. +. +.TH "SYNCTHING-EVENT-API" "7" "Jun 19, 2020" "v1" "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. To receive events, see events\-get\&. +.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, + "globalID": 3, + "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, \fBglobalID\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 unique ID for this event on the events API. It always increases by 1: the first +event generated has id \fB1\fP, the next has id \fB2\fP etc. If this increases by +more than 1, then one or more events have been skipped by the events API. +.TP +.B globalID +A global ID for this event, across the events API, the audit log, and any other +sources. It may increase by more than 1, but it will always be greater +than or equal to the id. +.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 EVENT TYPES +.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, + "globalID": 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, + "globalID": 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", + "deviceName": "Laptop", + "clientName": "syncthing", + "clientVersion": "v0.13.4", + "type": "TCP (Client)" + } +} +.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, + "globalID": 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, + "globalID": 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 DevicePaused +.sp +Emitted when a device was paused. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +{ + "id": 13, + "globalID": 13, + "type": "DevicePaused", + "time": "2014\-07\-17T13:28:05.043465207+02:00", + "data": { + "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, + "globalID": 24, + "type": "DeviceRejected", + "time": "2014\-08\-19T10:43:00.562821045+02:00", + "data": { + "address": "127.0.0.1:51807", + "name": "My dusty computer", + "device": "EJHMPAQ\-OGCVORE\-ISB4IS3\-SYYVJXF\-TKJGLTU\-66DIQPF\-GJ5D2GX\-GQ3OWQK" + } +} +.ft P +.fi +.UNINDENT +.UNINDENT +.SS DeviceResumed +.sp +Generated each time a device was resumed. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +{ + "id": 2, + "globalID": 2, + "type": "DeviceResumed", + "time": "2014\-07\-13T21:04:33.687836696+02:00", + "data": { + "device": "NFGKEKE\-7Z6RTH7\-I3PRZXS\-DEJF3UJ\-FRWJBFO\-VBBTDND\-4SGNGVZ\-QUQHJAG" + } +} +.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, + "globalID": 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 have been finished or failed for that file/folder. There is +always a last event emitted with no data, which implies all downloads +have 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, + "globalID": 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 FolderErrors +.sp +The \fBFolderErrors\fP event is emitted when a folder cannot be successfully +synchronized. The event contains the ID of the affected folder and a list of +errors for files or directories therein. This list of errors is obsolete once +the folder changes state to \fBsyncing\fP \- if errors remain after the next +synchronization attempt, a new \fBFolderErrors\fP event is emitted. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +{ + "id": 132, + "type": "FolderErrors", + "time": "2015\-06\-26T13:39:24.697401384+02:00", + "data": { + "errors": [ + { + "error": "open /Users/jb/src/github.com/syncthing/syncthing/test/s2/h2j/.syncthing.aslkjd.tmp: permission denied", + "path": "h2j/aslkjd" + } + ], + "folder": "default" + } +} +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +New in version 0.11.12. + +.sp +\fBSEE ALSO:\fP +.INDENT 0.0 +.INDENT 3.5 +The statechanged event. +.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, + "globalID": 27, + "type": "FolderRejected", + "time": "2014\-08\-19T10:41:06.761751399+02:00", + "data": { + "device": "EJHMPAQ\-OGCVORE\-ISB4IS3\-SYYVJXF\-TKJGLTU\-66DIQPF\-GJ5D2GX\-GQ3OWQK", + "folder": "GXWxf\-3zgnU", + "folderLabel": "My Pictures" + } +} +.ft P +.fi +.UNINDENT +.UNINDENT +.SS Folder Scan Progress +.sp +Emitted in regular intervals (folder setting ProgressIntervalS, 2s by default) +during scans giving the amount of bytes already scanned and to be scanned in +total , as well as the current scanning rates in bytes per second. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +{ + "data" : { + "total" : 1, + "rate" : 0, + "current" : 0, + "folder" : "bd7q3\-zskm5" + }, + "globalID" : 29, + "type" : "FolderScanProgress", + "time" : "2017\-03\-06T15:00:58.072004209+01:00", + "id" : 29 +} +.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, + "globalID": 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, + "globalID": 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, + "globalID": 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 (contents changed), \fBmetadata\fP (file metadata changed but not contents), or \fBdelete\fP\&. +.sp +New in version 0.11.10: The \fBmetadata\fP action. + +.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, + "globalID": 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 (contents changed), \fBmetadata\fP (file metadata changed but not contents), or \fBdelete\fP\&. +.sp +New in version 0.11.10: The \fBmetadata\fP action. + +.SS Listen Addresses Changed +.sp +This event is emitted when a listen address changes. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +{ + "type" : "ListenAddressesChanged", + "id" : 70, + "time" : "2017\-03\-06T15:01:24.88340663+01:00", + "globalID" : 70, + "data" : { + "address" : { + "Fragment" : "", + "RawQuery" : "", + "Scheme" : "dynamic+https", + "Path" : "/endpoint", + "RawPath" : "", + "User" : null, + "ForceQuery" : false, + "Host" : "relays.syncthing.net", + "Opaque" : "" + }, + "wan" : [ + { + "ForceQuery" : false, + "User" : null, + "Host" : "31.15.66.212:443", + "Opaque" : "", + "Path" : "/", + "RawPath" : "", + "RawQuery" : "id=F4HSJVO\-CP2C3IL\-YLQYLSU\-XTYODAG\-PPU4LGV\-PH3MU4N\-G6K56DV\-IPN47A&pingInterval=1m0s&networkTimeout=2m0s&sessionLimitBps=0&globalLimitBps=0&statusAddr=:22070&providedBy=", + "Scheme" : "relay", + "Fragment" : "" + } + ], + "lan" : [ + { + "RawQuery" : "id=F4HSJVO\-CP2C3IL\-YLQYLSU\-XTYODAG\-PPU4LGV\-PH3MU4N\-G6K56DV\-IPN47A&pingInterval=1m0s&networkTimeout=2m0s&sessionLimitBps=0&globalLimitBps=0&statusAddr=:22070&providedBy=", + "Scheme" : "relay", + "Fragment" : "", + "RawPath" : "", + "Path" : "/", + "Host" : "31.15.66.212:443", + "Opaque" : "", + "ForceQuery" : false, + "User" : null + } + ] + } +} +.ft P +.fi +.UNINDENT +.UNINDENT +.SS LocalChangeDetected +.sp +Generated upon scan whenever the local disk has discovered an updated file from the +previous scan. This does \fInot\fP include events that are discovered and copied from +other devices (remote\-change\-detected), only files that were changed on the +local filesystem. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +{ + "id": 7, + "globalID": 59, + "time": "2016\-09\-26T22:07:10.7189141\-04:00", + "type": "LocalChangeDetected", + "data": { + "action": "deleted", + "folderID": "vitwy\-zjxqt", + "label": "TestSync", + "path": "C:\e\eUsers\e\eNate\e\eSync\e\etestfolder\e\etest file.rtf", + "type": "file" + } +} +.ft P +.fi +.UNINDENT +.UNINDENT +.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, + "globalID": 59, + "type": "LocalIndexUpdated", + "time": "2014\-07\-17T13:27:28.051369434+02:00", + "data": { + "folder": "default", + "items": 1000, + } +} +.ft P +.fi +.UNINDENT +.UNINDENT +.SS Login Attempt +.sp +When authentication is enabled for the GUI, this event is emitted on every +login attempt. If either the username or password are incorrect, \fBsuccess\fP +is false and in any case the given username is returned. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +{ + "id" : 187, + "time" : "2017\-03\-07T00:19:24.420386143+01:00", + "data" : { + "username" : "somename", + "success" : false + }, + "type" : "LoginAttempt", + "globalID" : 195 +} +.ft P +.fi +.UNINDENT +.UNINDENT +.SS RemoteChangeDetected +.sp +Generated upon scan whenever a file is locally updated due to a remote change. +Files that are updated locally produce a local\-change\-detected event. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +{ + "time" : "2017\-03\-06T23:58:21.844739891+01:00", + "globalID" : 123, + "data" : { + "type" : "file", + "action" : "deleted", + "path" : "/media/ntfs_data/Dokumente/testfile", + "label" : "Dokumente", + "folderID" : "Dokumente", + "modifiedBy" : "BPDFDTU" + }, + "type" : "RemoteChangeDetected", + "id" : 2 +} +.ft P +.fi +.UNINDENT +.UNINDENT +.SS Remote Download Progress +.sp +This event is emitted when a download\-progress message is +received. It returns a map \fBdata\fP of filenames with a count of +downloaded blocks. The files in questions are currently being +downloaded on the remote \fBdevice\fP and belong to \fBfolder\fP\&. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +{ + "time" : "2017\-03\-07T00:11:37.65838955+01:00", + "globalID" : 170, + "data" : { + "state" : { + "tahr64\-6.0.5.iso" : 1784 + }, + "device" : "F4HSJVO\-CP2C3IL\-YLQYLSU\-XTYODAG\-PPU4LGV\-PH3MU4N\-G6K56DV\-IPN47A", + "folder" : "Dokumente" + }, + "type" : "RemoteDownloadProgress", + "id" : 163 +} +.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, + "globalID": 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, + "globalID": 1, + "type": "Starting", + "time": "2014\-07\-17T13:13:32.044470055+02:00", + "data": { + "home": "/home/jb/.config/syncthing" + } +} +.ft P +.fi +.UNINDENT +.UNINDENT +.SS StartupComplete +.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, + "globalID": 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, \fBsyncing\fP and \fBerror\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, + "globalID": 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 +2014-2019, The Syncthing Authors +.\" Generated by docutils manpage writer. +. diff --git a/man/syncthing-faq.7 b/man/syncthing-faq.7 index 44d986c4b..ea7b68863 100644 --- a/man/syncthing-faq.7 +++ b/man/syncthing-faq.7 @@ -1 +1,576 @@ -404 Not Found +.\" Man page generated from reStructuredText. +. +.TH "SYNCTHING-FAQ" "7" "Jun 19, 2020" "v1" "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 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. +.SH IS IT “SYNCTHING”, “SYNCTHING” OR “SYNCTHING”? +.sp +It’s \fBSyncthing\fP, although the command and source repository is spelled +\fBsyncthing\fP so it may be referred to in that way as well. It’s definitely not +SyncThing, even though the abbreviation \fBst\fP is used in some +circumstances and file names. +.SH HOW DOES SYNCTHING DIFFER FROM BITTORRENT/RESILIO SYNC? +.sp +The two are different and not related. Syncthing and BitTorrent/Resilio Sync accomplish +some of the same things, namely syncing files between two or more computers. +.sp +BitTorrent Sync, now called Resilio Sync, is a proprietary peer\-to\-peer file +synchronization tool available for Windows, Mac, Linux, Android, iOS, Windows +Phone, Amazon Kindle Fire and BSD. [1] 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. Resilio +Sync uses an undocumented, closed protocol with unknown security properties. +.IP [1] 5 +\fI\%https://en.wikipedia.org/wiki/Resilio_Sync\fP +.SH 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 (synced, except on Windows, but never followed) +.UNINDENT +.sp +The following are \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 and Windows directory junctions (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 sparse, when supported by the OS & filesystem) +.UNINDENT +.SH 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 to the torrent protocol. The more devices you have online, +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). +.SH WHY IS THE SYNC SO SLOW? +.sp +When troubleshooting a slow sync, there are a number of things to check. +.sp +First of all, verify that you are not connected via a relay. In the “Remote +Devices” list on the right side of the GUI, double check that you see +“Address: ” and \fInot\fP “Relay: ”. +[image] +.sp +If you are connected via a relay, this is because a direct connection could +not be established. Double check and follow the suggestions in +firewall\-setup to enable direct connections. +.sp +Second, if one of the devices is a very low powered machine (a Raspberry Pi, +or a phone, or a NAS, or similar) you are likely constrained by the CPU on +that device. See the next question for reasons Syncthing likes a faster CPU. +.sp +Third, verify that the network connection is OK. Tools such as iperf or just +an Internet speed test can be used to verify the performance here. +.SH 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 compressed (optionally) and +encrypted (always). When receiving data it must be decrypted and then (if +compressed) decompressed. +.IP 3. 3 +There is a certain amount of housekeeping that must be done to track the +current and available versions of each file in the index database. +.IP 4. 3 +By default Syncthing uses periodic scanning every hour when watching for +changes or every minute if that’s disabled to detect +file changes. This means checking every file’s modification time and +comparing it to the database. This can cause spikes of CPU usage for large +folders. +.UNINDENT +.sp +Hashing, compression and encryption cost CPU time. Also, using the GUI +causes a certain amount of extra CPU usage to calculate the summary data it +presents. Note however that once things are \fIin sync\fP CPU usage should be +negligible. +.sp +To minimize the impact of this, Syncthing attempts to lower the +process priority when starting up. +.sp +To further limit the amount of CPU used when syncing and scanning, set the +environment variable \fBGOMAXPROCS\fP to the maximum number of CPU cores +Syncthing should use at any given moment. For example, \fBGOMAXPROCS=2\fP on a +machine with four cores will limit Syncthing to no more than half the +system’s CPU power. +.SH SHOULD I KEEP MY DEVICE IDS SECRET? +.sp +No. The IDs are not sensitive. Given a device ID it’s possible to find the IP +address for that device, if global discovery is enabled on it. Knowing the device +ID doesn’t help you actually establish a connection to that device or get a list +of files, etc. +.sp +For a connection to be established, both devices need to know about the other’s +device ID. It’s 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 +.SH WHAT IF THERE IS A CONFLICT? +.sp +Syncthing does recognize conflicts. When a file has been modified on two devices +simultaneously and the content actually differs, one of the files will be +renamed to \fB.sync\-conflict\-\-