octoleo/syncthing
1
0
Fork 0
mirror of https://github.com/octoleo/syncthing.git synced 2025-01-22 14:48:30 +00:00
Code Issues Packages Projects Releases Wiki Activity

gui, man, authors: Update docs, translations, and contributors

Browse Source
This commit is contained in:
Jakob Borg 2020-06-22 06:15:24 +02:00
parent dc145bfad7
commit aee4b10d3a
19 changed files with 8172 additions and 21 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
gui/default/assets/lang/lang-en.json
View File

@ -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.",

8
gui/default/assets/lang/lang-eu.json
View File

@ -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}}",

2
gui/default/assets/lang/lang-zh-TW.json
View File

@ -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",

433
man/stdiscosrv.1
View File

@ -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=<file>] [\-db\-dir=<string>] [\-debug] [\-http] [\-key=<string>]
[\-listen=<address>] [\-metrics\-listen=<address>]
[\-replicate=<peers>] [\-replication\-listen=<address>]
.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=<file>
Certificate file (default “./cert.pem”).
.UNINDENT
.INDENT 0.0
.TP
.B \-db\-dir=<string>
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=<file>
Key file (default “./key.pem”).
.UNINDENT
.INDENT 0.0
.TP
.B \-listen=<address>
Listen address (default “:8443”).
.UNINDENT
.INDENT 0.0
.TP
.B \-metrics\-listen=<address>
Prometheus compatible metrics endpoint listen address (default disabled).
.UNINDENT
.INDENT 0.0
.TP
.B \-replicate=<peers>
Replication peers, \fI\%id@address\fP <\fBid@address\fP>, comma separated
.UNINDENT
.INDENT 0.0
.TP
.B \-replication\-listen=<address>
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 <other options>
.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 <other options>
.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 <other options>
.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.
.

277
man/strelaysrv.1
View File

@ -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=<address>] [\-global\-rate=<bytes/s>] [\-keys=<dir>] [\-listen=<listen addr>]
[\-message\-timeout=<duration>] [\-nat] [\-nat\-lease=<duration> [\-nat\-renewal=<duration>]
[\-nat\-timeout=<duration>] [\-network\-timeout=<duration>] [\-per\-session\-rate=<bytes/s>]
[\-ping\-interval=<duration>] [\-pools=<pool addresses>] [\-protocol=<string>] [\-provided\-by=<string>]
[\-status\-srv=<listen addr>]
.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=<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=<bytes/s>
Global rate limit, in bytes/s.
.UNINDENT
.INDENT 0.0
.TP
.B \-keys=<dir>
Directory where cert.pem and key.pem is stored (default “.”).
.UNINDENT
.INDENT 0.0
.TP
.B \-listen=<listen addr>
Protocol listen address (default “:22067”).
.UNINDENT
.INDENT 0.0
.TP
.B \-message\-timeout=<duration>
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=<duration>
NAT lease length in minutes (default 60)
.UNINDENT
.INDENT 0.0
.TP
.B \-nat\-renewal=<duration>
NAT renewal frequency in minutes (default 30)
.UNINDENT
.INDENT 0.0
.TP
.B \-nat\-timeout=<duration>
NAT discovery timeout in seconds (default 10)
.UNINDENT
.INDENT 0.0
.TP
.B \-network\-timeout=<duration>
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=<bytes/s>
Per session rate limit, in bytes/s.
.UNINDENT
.INDENT 0.0
.TP
.B \-ping\-interval=<duration>
How often pings are sent (default 1m0s).
.UNINDENT
.INDENT 0.0
.TP
.B \-pools=<pool addresses>
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=<string>
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=<string>
An optional description about who provides the relay.
.UNINDENT
.INDENT 0.0
.TP
.B \-status\-srv=<listen addr>
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://<host name|IP>[:port]/?id=<relay device 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.
.

1167
man/syncthing-bep.7
View File

File diff suppressed because it is too large Load Diff

1151
man/syncthing-config.5
View File

File diff suppressed because it is too large Load Diff

267
man/syncthing-device-ids.7
View File

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

882
man/syncthing-event-api.7
View File

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

577
man/syncthing-faq.7
View File

@ -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: <some address>” and \fInot\fP “Relay: <some address>”.
[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<filename>.sync\-conflict\-<date>\-<time>\-<modifiedBy>.<ext>\fP\&. The file with the
older modification time will be marked as the conflicting file and thus be
renamed. If the modification times are equal, the file originating from the
device which has the larger value of the first 63 bits for his device ID will be
marked as the conflicting file.
If the conflict is between a modification and a deletion of the file, the
modified file always wins and is resurrected without renaming on the
device where it was deleted.
.sp
Beware that the \fB<filename>.sync\-conflict\-<date>\-<time>\-<modifiedBy>.<ext>\fP files are
treated as normal files after they are created, so they are propagated between
devices. We do this because the conflict is detected and resolved on one device,
creating the \fBsync\-conflict\fP file, but it’s just as much of a conflict
everywhere else and we don’t know which of the conflicting files is the “best”
from the user point of view.
.SH HOW DO I SERVE A FOLDER FROM A READ ONLY FILESYSTEM?
.sp
Syncthing requires a “folder marker” to indicate that the folder is present
and healthy. By default this is a directory called \fB\&.stfolder\fP that is
created by Syncthing when the folder is added. If this folder can’t be
created (you are serving files from a CD or something) you can instead set
the advanced config \fBMarker Name\fP to the name of some file or folder that
you know will always exist in the folder.
.SH I REALLY HATE THE .STFOLDER DIRECTORY, CAN I REMOVE IT?
.sp
See the previous question.
.SH AM I ABLE TO NEST SHARED FOLDERS IN SYNCTHING?
.sp
Sharing a folder that is within an already shared folder is possible, but it has
its caveats. What you must absolutely avoid are circular shares. This is just
one example, there may be other undesired effects. Nesting shared folders is not
supported, recommended or coded for, but it can be done successfully when you
know what you’re doing \- you have been warned.
.SH HOW DO I RENAME/MOVE A SYNCED FOLDER?
.sp
Syncthing doesn’t have a direct way to do this, as it’s potentially
dangerous to do so if you’re not careful \- it may result in data loss if
something goes wrong during the move and is synchronized to your other
devices.
.sp
The easy way to rename or move a synced folder on the local system is to
remove the folder in the Syncthing UI, move it on disk, then re\-add it using
the new path.
.sp
It’s best to do this when the folder is already in sync between your
devices, as it is otherwise unpredictable which changes will “win” after the
move. Changes made on other devices may be overwritten, or changes made
locally may be overwritten by those on other devices.
.sp
An alternative way is to shut down Syncthing, move the folder on disk (including
the \fB\&.stfolder\fP marker), edit the path directly in \fBconfig.xml\fP in the
configuration folder (see config) and then start Syncthing again.
.SH HOW DO I CONFIGURE MULTIPLE USERS ON A SINGLE MACHINE?
.sp
Each user should run their own Syncthing instance. Be aware that you might need
to configure listening ports such that they do not overlap (see config).
.SH DOES SYNCTHING SUPPORT SYNCING BETWEEN FOLDERS ON THE SAME SYSTEM?
.sp
No. Syncthing is not designed to sync locally and the overhead involved in
doing so using Syncthing’s method would be wasteful. There are better
programs to achieve this such as [rsync](\fI\%https://rsync.samba.org/\fP) or
[Unison](\fI\%https://www.cis.upenn.edu/~bcpierce/unison\fP).
.SH WHEN I DO HAVE TWO DISTINCT SYNCTHING-MANAGED FOLDERS ON TWO HOSTS, HOW DOES SYNCTHING HANDLE MOVING FILES BETWEEN THEM?
.sp
Syncthing does not specially handle this case, and most files most likely get
re\-downloaded.
.sp
In detail, the behavior depends on the scan order. If you have folder A and B,
and move files from A to B, if A gets scanned first, it will announce removal of
the files to others who will remove the files. As you rescan B, B will
announce addition of new files, and other peers will have nowhere to get
them from apart from re\-downloading them.
.sp
If B gets rescanned first, B will announce additions first, remote
peers will reconstruct the files (not rename, more like copy block by
block) from A, and then as A gets rescanned remove the files from A.
.sp
A workaround would be to copy first from A to B, rescan B, wait for B to
rebuild on remote ends, and then delete from A.
.SH IS SYNCTHING MY IDEAL BACKUP APPLICATION?
.sp
No. Syncthing is not a great backup application because all changes to your
files (modifications, deletions, etc.) will be propagated to all your
devices. You can enable versioning, but we encourage the use of other tools
to keep your data safe from your (or our) mistakes.
.SH WHY IS THERE NO IOS CLIENT?
.sp
There is an alternative implementation of Syncthing (using the same network
protocol) called \fBfsync()\fP\&. There are no plans by the current Syncthing
team to support iOS in the foreseeable future, as the code required to do so
would be quite different from what Syncthing is today.
.SH HOW CAN I EXCLUDE FILES WITH BRACKETS ([]) IN THE NAME?
.sp
The patterns in .stignore are glob patterns, where brackets are used to
denote character ranges. That is, the pattern \fBq[abc]x\fP will match the
files \fBqax\fP, \fBqbx\fP and \fBqcx\fP\&.
.sp
To match an actual file \fIcalled\fP \fBq[abc]x\fP the pattern needs to “escape”
the brackets, like so: \fBq\e[abc\e]x\fP\&.
.sp
On Windows, escaping special characters is not supported as the \fB\e\fP
character is used as a path separator. On the other hand, special characters
such as \fB[\fP and \fB?\fP are not allowed in file names on Windows.
.SH WHY IS THE SETUP MORE COMPLICATED THAN BITTORRENT/RESILIO SYNC?
.sp
Security over convenience. In Syncthing you have to setup both sides to
connect two devices. An attacker can’t do much with a stolen device ID, because
you have to add the device on the other side too. You have better control
where your files are transferred.
.sp
This is an area that we are working to improve in the long term.
.SH HOW DO I ACCESS THE WEB GUI FROM ANOTHER COMPUTER?
.sp
The default listening address is 127.0.0.1:8384, so you can only access the
GUI from the same machine. This is for security reasons. Change the \fBGUI
listen address\fP through the web UI from \fB127.0.0.1:8384\fP to
\fB0.0.0.0:8384\fP or change the config.xml:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
<gui enabled="true" tls="false">
<address>127.0.0.1:8384</address>
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
to
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
<gui enabled="true" tls="false">
<address>0.0.0.0:8384</address>
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Then the GUI is accessible from everywhere. You should set a password and
enable HTTPS with this configuration. You can do this from inside the GUI.
.sp
If both your computers are Unix\-like (Linux, Mac, etc.) you can also leave the
GUI settings at default and use an ssh port forward to access it. For
example,
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ ssh \-L 9090:127.0.0.1:8384 user@othercomputer.example.com
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
will log you into othercomputer.example.com, and present the \fIremote\fP
Syncthing GUI on \fI\%http://localhost:9090\fP on your \fIlocal\fP computer.
.sp
If you only want to access the remote gui and don’t want the terminal
session, use this example,
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ ssh \-N \-L 9090:127.0.0.1:8384 user@othercomputer.example.com
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If only your remote computer is Unix\-like,
you can still access it with ssh from Windows.
.sp
Under Windows 10 (64 bit) you can use the same ssh command if you install
the Windows Subsystem for Linux.
\fI\%https://msdn.microsoft.com/en\-gb/commandline/wsl/install_guide\fP
.sp
Another Windows way to run ssh is to install gow.
(Gnu On Windows) \fI\%https://github.com/bmatzelle/gow\fP
.sp
The easiest way to install gow is with chocolatey.
\fI\%https://chocolatey.org/\fP
.SH WHY DO I GET “HOST CHECK ERROR” IN THE GUI/API?
.sp
Since version 0.14.6 Syncthing does an extra security check when the GUI/API
is bound to localhost \- namely that the browser is talking to localhost.
This protects against most forms of \fI\%DNS rebinding attack\fP <\fBhttps://en.wikipedia.org/wiki/DNS_rebinding\fP> against the GUI.
.sp
To pass this test, ensure that you are accessing the GUI using an URL that
begins with \fIhttp://localhost\fP, \fIhttp://127.0.0.1\fP or \fIhttp://[::1]\fP\&. HTTPS
is fine too, of course.
.sp
If you are using a proxy in front of Syncthing you may need to disable this
check, after ensuring that the proxy provides sufficient authentication to
protect against unauthorized access. Either:
.INDENT 0.0
.IP \(bu 2
Make sure the proxy sets a \fIHost\fP header containing \fIlocalhost\fP, or
.IP \(bu 2
Set \fIinsecureSkipHostcheck\fP in the advanced settings, or
.IP \(bu 2
Bind the GUI/API to a non\-localhost listen port.
.UNINDENT
.sp
In all cases, username/password authentication and HTTPS should be used.
.SH MY SYNCTHING DATABASE IS CORRUPT
.sp
This is almost always a result of bad RAM, storage device or other hardware. When the index database is found to be corrupt Syncthing cannot operate and will note this in the logs and exit. To overcome this delete the \fI\%database folder\fP <\fBhttps://docs.syncthing.net/users/config.html#description\fP> inside Syncthing’s home directory and re\-start Syncthing. It will then need to perform a full re\-hashing of all shared folders. You should check your system in case the underlying cause is indeed faulty hardware which may put the system at risk of further data loss.
.SH I DON’T LIKE THE GUI OR THE THEME. CAN IT BE CHANGED?
.sp
You can change the theme in the settings. Syncthing ships with other themes
than the default.
.sp
If you want a custom theme or a completely different GUI, you can add your
own.
By default, Syncthing will look for a directory \fBgui\fP inside the Syncthing
home folder. To change the directory to look for themes, you need to set the
STGUIASSETS environment variable. To get the concrete directory, run
syncthing with the \fB\-paths\fP parameter. It will print all the relevant paths,
including the “GUI override directory”.
.sp
To add e.g. a red theme, you can create the file \fBred/assets/css/theme.css\fP
inside the GUI override directory to override the default CSS styles.
.sp
To create a whole new GUI, you should checkout the files at
\fI\%https://github.com/syncthing/syncthing/tree/main/gui/default\fP
to get an idea how to do that.
.SH WHY DO I SEE SYNCTHING TWICE IN TASK MANAGER?
.sp
One process manages the other, to capture logs and manage restarts. This
makes it easier to handle upgrades from within Syncthing itself, and also
ensures that we get a nice log file to help us narrow down the cause for
crashes and other bugs.
.SH WHERE DO SYNCTHING LOGS GO TO?
.sp
Syncthing logs to stdout by default. On Windows Syncthing by default also
creates \fBsyncthing.log\fP in Syncthing’s home directory (run \fBsyncthing
\-paths\fP to see where that is). Command line option \fB\-logfile\fP can be used
to specify a user\-defined logfile.
.SH HOW CAN I VIEW THE HISTORY OF CHANGES?
.sp
The web GUI contains a \fBGlobal Changes\fP button under the device list which
displays changes since the last (re)start of Syncthing. With the \fB\-audit\fP
option you can enable a persistent, detailed log of changes and most
activities, which contains a \fBJSON\fP formatted sequence of events in the
\fB~/.config/syncthing/audit\-_date_\-_time_.log\fP file.
.SH DOES THE AUDIT LOG CONTAIN EVERY CHANGE?
.sp
The audit log (and the \fBGlobal Changes\fP window) sees the changes that your
Syncthing sees. When Syncthing is continuously connected it usually sees every change
happening immediately and thus knows which node initiated the change.
When topology gets complex or when your node reconnects after some time offline,
Syncthing synchronises with its neighbours: It gets the latest synchronised state
from the neighbour, which is the \fIresult\fP of all the changes between the last
known state (before disconnect or network delay) and the current state at the
neighbour, and if there were updates, deletes, creates, conflicts, which were
overlapping we only see the \fIlatest change\fP for a given file or directory (and
the node where that latest change occurred). When we connect to multiple neighbours
Syncthing decides which neighbor has the latest state, or if the states conflict
it initiates the conflict resolution procedure, which in the end results in a consistent
up\-to\-date state with all the neighbours.
.SH HOW DO I UPGRADE SYNCTHING?
.sp
If you use a package manager such as Debian’s apt\-get, you should upgrade
using the package manager. If you use the binary packages linked from
Syncthing.net, you can use Syncthing built in automatic upgrades.
.INDENT 0.0
.IP \(bu 2
If automatic upgrades is enabled (which is the default), Syncthing will
upgrade itself automatically within 24 hours of a new release.
.IP \(bu 2
The upgrade button appears in the web GUI when a new version has been
released. Pressing it will perform an upgrade.
.IP \(bu 2
To force an upgrade from the command line, run \fBsyncthing \-upgrade\fP\&.
.UNINDENT
.sp
Note that your system should have CA certificates installed which allow a
secure connection to GitHub (e.g. FreeBSD requires \fBsudo pkg install
ca_root_nss\fP). If \fBcurl\fP or \fBwget\fP works with normal HTTPS sites, then
so should Syncthing.
.SH WHERE DO I FIND THE LATEST RELEASE?
.sp
We release new versions through GitHub. The latest release is always found
\fI\%on the release page\fP <\fBhttps://github.com/syncthing/syncthing/releases/latest\fP>\&. Unfortunately
GitHub does not provide a single URL to automatically download the latest
version. We suggest to use the GitHub API at
\fI\%https://api.github.com/repos/syncthing/syncthing/releases/latest\fP and parsing
the JSON response.
.SH HOW DO I RUN SYNCTHING AS A DAEMON PROCESS ON LINUX?
.sp
If you’re using systemd, runit, or upstart, we already ship examples, check
\fI\%https://github.com/syncthing/syncthing/tree/main/etc\fP for example
configurations.
.sp
If however you’re not using one of these tools, you have a couple of options.
If your system has a tool called \fBstart\-stop\-daemon\fP installed (that’s the name
of the command, not the package), look into the local documentation for that, it
will almost certainly cover 100% of what you want to do. If you don’t have
\fBstart\-stop\-daemon\fP, there are a bunch of other software packages you could use
to do this. The most well known is called daemontools, and can be found in the
standard package repositories for almost every modern Linux distribution.
Other popular tools with similar functionality include S6 and the aforementioned
runit.
.SH HOW DO I INCREASE THE INOTIFY LIMIT TO GET MY FILESYSTEM WATCHER TO WORK?
.sp
You are probably reading this because you encountered the following error with
the filesystem watcher on linux:
.INDENT 0.0
.INDENT 3.5
Failed to start filesystem watcher for folder yourLabel (yourID): failed to
setup inotify handler. Please increase inotify limits, see
\fI\%https://docs.syncthing.net/users/faq.html#inotify\-limits\fP
.UNINDENT
.UNINDENT
.sp
Linux typically restricts the amount of watches per user (usually 8192). When
you have more directories you need to adjust that number.
.sp
On many Linux distributions you can run the following to fix it:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
echo "fs.inotify.max_user_watches=204800" | sudo tee \-a /etc/sysctl.conf
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
On Arch Linux and potentially others it is preferred to write this line into a
separate file, i.e. you should run:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
echo "fs.inotify.max_user_watches=204800" | sudo tee \-a /etc/sysctl.d/90\-override.conf
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This only takes effect after a reboot. To adjust the limit immediately, run:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
sudo sh \-c \(aqecho 204800 > /proc/sys/fs/inotify/max_user_watches\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.SH HOW DO I RESET THE GUI PASSWORD?
.sp
If you’ve forgotten/lost the GUI password, you can remove it by deleting the \fB<user>\fP and \fB<password>\fP XML tags from the \fB<gui>\fP block in file \fBconfig.xml\fP\&. This should be done while Syncthing is not running. The location of the file depends on OS and is described in the configuration documentation.
.sp
For example, the two emphasized lines below would be removed from the file.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
<gui enabled="true" tls="false" debugging="false">
<address>127.0.0.1:8384</address>
<user>syncguy</user>
<password>$2a$10$s9wWHOQe...Cq7GPye69</password>
<apikey>9RCKohqCAyrj5RjpyZdR2wXmQ9PyQFeN</apikey>
<theme>default</theme>
</gui>
.ft P
.fi
.UNINDENT
.UNINDENT
.SH AUTHOR
The Syncthing Authors
.SH COPYRIGHT
2014-2019, The Syncthing Authors
.\" Generated by docutils manpage writer.
.

127
man/syncthing-globaldisco.7
View File

@ -1 +1,126 @@
404 Not Found
.\" Man page generated from reStructuredText.
.
.TH "SYNCTHING-GLOBALDISCO" "7" "Jun 19, 2020" "v1" "Syncthing"
.SH NAME
syncthing-globaldisco \- Global Discovery Protocol v3
.
.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 ANNOUNCEMENTS
.sp
A device should announce itself at startup. It does this by an HTTPS POST to
the announce server URL. Standard discovery currently requires the path to be
“/v2/”, yet this can be up to the discovery server. The POST has a JSON payload
listing connection addresses (if any):
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{
addresses: ["tcp://192.0.2.45:22000", "tcp://:22202", "relay://192.0.2.99:22028"],
}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
It’s OK for the “addresses” field to be either the empty list (\fB[]\fP),
\fBnull\fP, or missing entirely. An announcement with the field missing
or empty is however not useful…
.sp
Any empty or unspecified IP addresses (i.e. addresses like \fBtcp://:22000\fP,
\fBtcp://0.0.0.0:22000\fP, \fBtcp://[::]:22000\fP) are interpreted as referring to
the source IP address of the announcement.
.sp
The device ID of the announcing device is not part of the announcement.
Instead, the server requires that the client perform certificate
authentication. The device ID is deduced from the presented certificate.
.sp
The server response is empty, with code \fB204\fP (No Content) on success. If no
certificate was presented, status \fB403\fP (Forbidden) is returned. If the
posted data doesn’t conform to the expected format, \fB400\fP (Bad Request) is
returned.
.sp
In successful responses, the server may return a \fBReannounce\-After\fP header
containing the number of seconds after which the client should perform a new
announcement.
.sp
In error responses, the server may return a \fBRetry\-After\fP header containing
the number of seconds after which the client should retry.
.sp
Performing announcements significantly more often than indicated by the
\fBReannounce\-After\fP or \fBRetry\-After\fP headers may result in the client being
throttled. In such cases the server may respond with status code \fB429\fP (Too
Many Requests).
.SH QUERIES
.sp
Queries are performed as HTTPS GET requests to the announce server URL. The
requested device ID is passed as the query parameter “device”, in canonical
string form, i.e. \fBhttps://discovery.syncthing.net/?device=ABC12345\-....\fP
.sp
Successful responses will have status code \fB200\fP (OK) and carry a JSON payload
of the same format as the announcement above. The response will not contain
empty or unspecified addresses.
.sp
If the “device” query parameter is missing or malformed, the status code 400
(Bad Request) is returned.
.sp
If the device ID is of a valid format but not found in the registry, 404 (Not
Found) is returned.
.sp
If the client has exceeded a rate limit, the server may respond with 429 (Too
Many Requests).
.SH AUTHENTICATION
.sp
Global discovery is spoken over HTTPS and is protected against attackers in
the same manner as other HTTPS traffic. However, there are a few Syncthing
specific considerations on top of this. As mentioned above, for
announcements the client must provide a certificate to prove ownership of
the announced device ID.
.sp
In addition, Syncthing has a mechanism to verify the identity of the
discovery server. While this would normally be accomplished by using a CA
signed certificate, Syncthing often runs in environments with outdated or
simply nonexistent root CA bundles. Instead, Syncthing can verify the
discovery server certificate fingerprint using the device ID mechanism. This
is certificate pinning and conveyed in the Syncthing configuration as a
synthetic “id” parameter on the discovery server URL:
\fBhttps://discovery.syncthing.net/?id=...\fP\&. The “id” parameter is not, in
fact, sent to the discovery server \- it’s used by Syncthing itself to know
which certificate to expect on the server side.
.sp
The public discovery network uses this authentication mechanism instead of
CA signed certificates.
.sp
The discovery server prints its certificate ID in this manner on startup.
.SH AUTHOR
The Syncthing Authors
.SH COPYRIGHT
2014-2019, The Syncthing Authors
.\" Generated by docutils manpage writer.
.

124
man/syncthing-localdisco.7
View File

@ -1 +1,123 @@
404 Not Found
.\" Man page generated from reStructuredText.
.
.TH "SYNCTHING-LOCALDISCO" "7" "Jun 19, 2020" "v1" "Syncthing"
.SH NAME
syncthing-localdisco \- Local Discovery Protocol v4
.
.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 MODE OF OPERATION
.sp
Each participating device periodically sends an Announcement packet. It also
keeps a table of the announcements it has seen. There is no way to solicit a
reply; the only message type is Announcement.
.sp
On multihomed hosts the announcement packets should be sent on each interface
on which Syncthing will accept connections.
.sp
The announcement packet is sent over UDP.
.sp
For IPv4, the Announcement packet is broadcast either to the link\-specific
broadcast address, or to the generic link\-local broadcast address
\fB255.255.255.255\fP, with destination port 21027.
.sp
For IPv6, the Announcement packet is multicast to the transient link\-local
multicast address \fBff12::8384\fP, with destination port 21027.
.sp
It is recommended that local discovery Announcement packets be sent on a 30
to 60 second interval, possibly with immediate transmissions when a
previously unknown device is discovered or a device has restarted (see the
\fBinstance_id\fP field).
.SH DEVICE ID
.sp
The device ID is the SHA\-256 (32 bytes) of the device X.509 certificate. See
device\-ids in the Syncthing documentation.
.SH ANNOUNCEMENT PACKET
.sp
The Announcement packet has the following structure:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
| Magic |
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
/ /
\e Announce Message \e
/ /
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
There is no explicit length field as the length is given by the length of
the discovery announcement packet itself.
.sp
The Magic field is a 32 bit word representing 0x2EA7D90B in network (big
endian) byte order. It identifies the packet as being a Syncthing discovery
protocol packet.
.sp
The Announce Message contents are in protocol buffer format using the
following schema:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
message Announce {
bytes id = 1;
repeated string addresses = 2;
int64 instance_id = 3;
}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The \fBid\fP field contains the Device ID of the sending device.
.sp
The \fBaddresses\fP field contains a list of addresses where the device can be
contacted. Direct connections will typically have the \fBtcp://\fP scheme.
Relay connections will typically use the \fBrelay://\fP scheme.
.sp
When interpreting addresses with an unspecified address, e.g.,
\fBtcp://0.0.0.0:22000\fP or \fBtcp://:42424\fP, the source address of the
discovery announcement is to be used.
.sp
The \fBinstance_id\fP field is set to a randomly generated ID at client
startup. Other devices on the network can detect a change in instance ID
between two announces and conclude that the announcing device has restarted.
.SH AUTHOR
The Syncthing Authors
.SH COPYRIGHT
2014-2019, The Syncthing Authors
.\" Generated by docutils manpage writer.
.

161
man/syncthing-networking.7
View File

@ -1 +1,160 @@
404 Not Found
.\" Man page generated from reStructuredText.
.
.TH "SYNCTHING-NETWORKING" "7" "Jun 19, 2020" "v1" "Syncthing"
.SH NAME
syncthing-networking \- Firewall Setup
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.SH PORT FORWARDS
.sp
If you have a NAT router which supports UPnP, the easiest way to get a working
port forward is to make sure UPnP setting is enabled on both Syncthing and the
router – Syncthing will try to handle the rest. If it succeeds you will see a
message in the console saying:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
Created UPnP port mapping for external port XXXXX on UPnP device YYYYY.
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If this is not possible or desirable you should set up a port forward for port
\fB22000/TCP\fP, or the port set in the \fISync Protocol Listen Address\fP setting.
The external forwarded port and the internal destination port has to be the same
(i.e. 22000/TCP).
.sp
Communication in Syncthing works both ways. Therefore if you set up port
forwards for one device, other devices will be able to connect to it even when
they are behind a NAT network or firewall.
.sp
In the absence of port forwarding, relaying may work well enough to get
devices connected and synced, but will perform poorly in comparison to a
direct connection.
.SH LOCAL FIREWALL
.sp
If your PC has a local firewall, you will need to open the following ports for
incoming and outgoing traffic:
.INDENT 0.0
.IP \(bu 2
Port \fB22000/TCP\fP (or the actual listening port if you have changed
the \fISync Protocol Listen Address\fP setting.)
.IP \(bu 2
Port \fB21027/UDP\fP (for discovery broadcasts on IPv4 and multicasts on IPv6)
.UNINDENT
.SS Uncomplicated Firewall (ufw)
.sp
If you’re using \fBufw\fP on Linux and have installed the \fI\%Syncthing package\fP <\fBhttps://apt.syncthing.net/\fP>, you can allow the necessary ports by running:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
sudo ufw allow syncthing
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If you also want to allow external access to the Syncthing web GUI, run:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
sudo ufw allow syncthing\-gui
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Allowing external access is \fBnot\fP necessary for a typical installation.
.sp
You can then verify that the ports mentioned above are allowed:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
sudo ufw status verbose
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In case you installed Syncthing manually you can follow the \fI\%instructions to manually add the syncthing preset\fP <\fBhttps://github.com/syncthing/syncthing/tree/main/etc/firewall-ufw\fP> to ufw.
.SS Firewalld
.sp
If you are using [Firewalld](\fI\%https://www.firewalld.org\fP) it has included
support for syncthing (since version 0.5.0, January 2018), and you can enable
it with
.INDENT 0.0
.INDENT 3.5
sudo firewall\-cmd –zone=public –add\-service=syncthing –permanent
sudo firewall\-cmd –reload
.UNINDENT
.UNINDENT
.sp
Similarly there is also a syncthing\-gui service.
.SH REMOTE WEB GUI
.sp
To be able to access the web GUI from other computers, you need to change the
\fIGUI Listen Address\fP setting from the default \fB127.0.0.1:8384\fP to
\fB0.0.0.0:8384\fP\&. You also need to open the port in your local firewall if you
have one.
.SS Tunneling via SSH
.sp
If you have SSH access to the machine running Syncthing but would rather not
open the web GUI port to the outside world, you can access it through a SSH
tunnel instead. You can start a tunnel with a command like the following:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
ssh \-L 9999:localhost:8384 machine
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This will bind to your local port 9999 and forward all connections from there to
port 8384 on the target machine. This still works even if Syncthing is bound to
listen on localhost only.
.SH VIA A PROXY
.sp
Syncthing can use a SOCKS5 proxy for outbound connections. Please see proxying\&.
.SH AUTHOR
The Syncthing Authors
.SH COPYRIGHT
2014-2019, The Syncthing Authors
.\" Generated by docutils manpage writer.
.

700
man/syncthing-relay.7
View File

@ -1 +1,699 @@
404 Not Found
.\" Man page generated from reStructuredText.
.
.TH "SYNCTHING-RELAY" "7" "Jun 19, 2020" "v1" "Syncthing"
.SH NAME
syncthing-relay \- Relay 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 WHAT IS A RELAY?
.sp
Relay is a service which relays data between two \fIdevices\fP which are not able to
connect to each other directly otherwise. This is usually due to both devices
being behind a NAT and neither side being able to open a port which would
be directly accessible from the internet.
.sp
A relay was designed to relay BEP protocol, hence the reliance on device ID’s
in the protocol spec, but at the same time it is general enough that could be
reused by other protocols or applications, as the data transferred between two
devices which use a relay is completely obscure and does not affect the
relaying.
.SH OPERATION MODES
.sp
Relay listens on a single TCP socket, but has two different connection modes,
where a connection mode is a predefined set of messages which the relay and
the device are expecting to exchange.
.sp
The first mode is the \fIprotocol\fP mode which allows a client to interact
with the relay, for example join the relay, or request to connect to a device,
given it is available on the relay. Similarly to BEP, protocol mode requires
the device to connect via TLS using a strong suite of ciphers (same as BEP),
which allows the relay to verify and derive the identity (Device ID) of the
device.
.sp
The second mode is the \fIsession\fP mode which after a few initial messages
connects two devices directly to each other via the relay, and is a plain\-text
protocol, which for every byte written by one device, sends the same set of
bytes to the other device and vica versa.
.SH IDENTIFYING THE CONNECTION MODE
.sp
Because both connection modes operate over the same single socket, a method
of detecting the connection mode is required.
.sp
When a new client connects to the relay, the relay checks the first byte
that the client has sent, and if that matches 0x16, that implies to us that
the connection is a protocol mode connection, due to 0x16 being the first byte
in the TLS handshake, and only protocol mode connections use TLS.
.sp
If the first byte is not 0x16, then we assume that the connection is a session
mode connection.
.SH PROTOCOL MODE
.sp
Protocol mode uses TLS and protocol name defined by the TLS header should be
\fIbep\-relay\fP\&.
.sp
Protocol mode has two submodes:
1. Permanent protocol submode \- Joining the relay, and waiting for messages from
the relay asking to connect to some device which is interested in having a
session with you.
2. Temporary protocol submode \- Only used to request a session with a device
which is connected to the relay using the permanent protocol submode.
.SS Permanent protocol submode
.sp
A permanent protocol submode begins with the client sending a JoinRelayRequest
message, which the relay responds to with either a ResponseSuccess or
ResponseAlreadyConnected message if a client with the same device ID already
exists.
.sp
After the client has joined, no more messages are exchanged apart from
Ping/Pong messages for general connection keep alive checking.
.sp
From this point onwards, the client stand\-by’s and waits for SessionInvitation
messages from the relay, which implies that some other device is trying to
connect with you. SessionInvitation message contains the unique session key
which then can be used to establish a connection in session mode.
.sp
If the client fails to send a JoinRelayRequest message within the first ping
interval, the connection is terminated.
If the client fails to send a message (even if it’s a ping message) every minute
(by default), the connection is terminated.
.SS Temporary protocol submode
.sp
A temporary protocol submode begins with ConnectRequest message, to which the
relay responds with either ResponseNotFound if the device the client it is after
is not available, or with a SessionInvitation, which contains the unique session
key which then can be used to establish a connection in session mode.
.sp
The connection is terminated immediately after that.
.SS Example Exchange
.sp
Client A \- Permanent protocol submode
Client B \- Temporary protocol submode
.TS
center;
|l|l|l|l|.
_
T{
#
T} T{
Client (A)
T} T{
Relay
T} T{
Client (B)
T}
_
T{
1
T} T{
JoinRelayRequest\->
T} T{
T} T{
T}
_
T{
2
T} T{
T} T{
<\-ResponseSuccess
T} T{
T}
_
T{
3
T} T{
Ping\->
T} T{
T} T{
T}
_
T{
4
T} T{
T} T{
<\-Pong
T} T{
T}
_
T{
5
T} T{
T} T{
T} T{
<\-ConnectRequest(A)
T}
_
T{
6
T} T{
T} T{
SessionInvitation(A)\->
T} T{
T}
_
T{
7
T} T{
T} T{
<\-SessionInvitation(B)
T} T{
T}
_
T{
8
T} T{
T} T{
T} T{
(Disconnects)
T}
_
T{
9
T} T{
Ping\->
T} T{
T} T{
T}
_
T{
10
T} T{
T} T{
<\-Pong
T} T{
T}
_
T{
11
T} T{
Ping\->
T} T{
T} T{
T}
_
T{
12
T} T{
T} T{
<\-Pong
T} T{
T}
_
.TE
.SH SESSION MODE
.sp
The first and only message the client sends in the session mode is the
JoinSessionRequest message which contains the session key identifying which
session you are trying to join. The relay responds with one of the following
Response messages:
.INDENT 0.0
.IP 1. 3
ResponseNotFound \- Session key is invalid
.IP 2. 3
ResponseAlreadyConnected \- Session is full (both sides already connected)
.IP 3. 3
ResponseSuccess \- You have successfully joined the session
.UNINDENT
.sp
After the successful response, all the bytes written and received will be
relayed between the two devices in the session directly.
.SS Example Exchange
.sp
Client A \- Permanent protocol mode
Client B \- Temporary protocol mode
.TS
center;
|l|l|l|l|.
_
T{
#
T} T{
Client (A)
T} T{
Relay
T} T{
Client (B)
T}
_
T{
1
T} T{
JoinSessionRequest(A)\->
T} T{
T} T{
T}
_
T{
2
T} T{
T} T{
<\-ResponseSuccess
T} T{
T}
_
T{
3
T} T{
Data\->
T} T{
(Buffers data)
T} T{
T}
_
T{
4
T} T{
Data\->
T} T{
(Buffers data)
T} T{
T}
_
T{
5
T} T{
T} T{
T} T{
<\-JoinSessionRequest(B)
T}
_
T{
6
T} T{
T} T{
ResponseSuccess\->
T} T{
T}
_
T{
7
T} T{
T} T{
Relays data \->
T} T{
T}
_
T{
8
T} T{
T} T{
Relays data \->
T} T{
T}
_
T{
9
T} T{
T} T{
<\-Relays data
T} T{
<\-Data
T}
_
.TE
.SH MESSAGES
.sp
All messages are preceded by a header message. Header message contains the
magic value 0x9E79BC40, message type integer, and message length.
.sp
\fBWARNING:\fP
.INDENT 0.0
.INDENT 3.5
Some messages have no content, apart from the implied header which allows
us to identify what type of message it is.
.UNINDENT
.UNINDENT
.SS Header structure
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
| Magic |
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
| Message Type |
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
| Message Length |
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
struct Header {
unsigned int Magic;
int MessageType;
int MessageLength;
}
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Ping message (Type = 0)
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
struct Ping {
}
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Pong message (Type = 1)
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
struct Pong {
}
.ft P
.fi
.UNINDENT
.UNINDENT
.SS JoinRelayRequest message (Type = 2)
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
struct JoinRelayRequest {
}
.ft P
.fi
.UNINDENT
.UNINDENT
.SS JoinSessionRequest message (Type = 3)
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
| Length of Key |
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
/ /
\e Key (variable length) \e
/ /
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
struct JoinSessionRequest {
opaque Key<32>;
}
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B : Key
This is a unique random session key generated by the relay server. It is
used to identify which session you are trying to connect to.
.UNINDENT
.SS Response message (Type = 4)
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
| Code |
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
| Length of Message |
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
/ /
\e Message (variable length) \e
/ /
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
struct Response {
int Code;
string Message<>;
}
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B : Code
An integer representing the status code.
.TP
.B : Message
Message associated with the code.
.UNINDENT
.SS ConnectRequest message (Type = 5)
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
| Length of ID |
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
/ /
\e ID (variable length) \e
/ /
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
struct ConnectRequest {
opaque ID<32>;
}
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B : ID
Device ID to which the client would like to connect.
.UNINDENT
.SS SessionInvitation message (Type = 6)
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
| Length of From |
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
/ /
\e From (variable length) \e
/ /
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
| Length of Key |
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
/ /
\e Key (variable length) \e
/ /
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
| Length of Address |
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
/ /
\e Address (variable length) \e
/ /
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
| 0x0000 | Port |
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
| Server Socket (V=0 or 1) |V|
+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+
struct SessionInvitation {
opaque From<32>;
opaque Key<32>;
opaque Address<32>;
unsigned int Port;
bool ServerSocket;
}
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B : From
Device ID identifying who you will be connecting with.
.TP
.B : Key
A unique random session key generated by the relay server. It is used to
identify which session you are trying to connect to.
.TP
.B : Address
An optional IP address on which the relay server is expecting you to
connect, in order to start a connection in session mode.
Empty/all zero IP should be replaced with the relay’s public IP address that
was used when establishing the protocol mode connection.
.TP
.B : Port
The port on which the relay server is expecting you to connect,
in order to start a connection in session mode.
.TP
.B : Server Socket
Because both sides connecting to the relay use the client side of the socket,
and some protocols behave differently depending if the connection starts on
the server side or the client side, this boolean indicates which side of the
connection this client should assume it’s getting. The value is inverted in
the invitation which is sent to the other device, so that there is always
one client socket, and one server socket.
.UNINDENT
.SH HOW SYNCTHING USES RELAYS, AND GENERAL SECURITY
.sp
In the case of Syncthing and BEP, when two devices connect via relay, they
start their standard TLS connection encapsulated within the relay’s plain\-text
session connection, effectively upgrading the plain\-text connection to a TLS
connection.
.sp
Even though the relay could be used for man\-in\-the\-middle attack, using TLS
at the application/BEP level ensures that all the traffic is safely encrypted,
and is completely meaningless to the relay. Furthermore, the secure suite of
ciphers used by BEP provides forward secrecy, meaning that even if the relay
did capture all the traffic, and even if the attacker did get their hands on the
device keys, they would still not be able to recover/decrypt any traffic which
was transported via the relay.
.sp
After establishing a relay session, Syncthing looks at the SessionInvitation
message, and depending which side it has received, wraps the raw socket in
either a TLS client socket or a TLS server socket depending on the ServerSocket
boolean value in the SessionInvitation, and starts the TLS handshake.
.sp
From that point onwards it functions exactly the same way as if Syncthing was
establishing a direct connection with the other device over the internet,
performing device ID validation, and full TLS encryption, and provides the same
security properties as it would provide when connecting over the internet.
.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.
.

1293
man/syncthing-rest-api.7
View File

File diff suppressed because it is too large Load Diff

173
man/syncthing-security.7
View File

@ -1 +1,172 @@
404 Not Found
.\" Man page generated from reStructuredText.
.
.TH "SYNCTHING-SECURITY" "7" "Jun 19, 2020" "v1" "Syncthing"
.SH NAME
syncthing-security \- Security Principles
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.sp
Security is one of the primary project goals. This means that it should not be
possible for an attacker to join a cluster uninvited, and it should not be
possible to extract private information from intercepted traffic. Currently this
is implemented as follows.
.sp
All device to device traffic is protected by TLS. To prevent uninvited devices
from joining a cluster, the certificate fingerprint of each device is compared
to a preset list of acceptable devices at connection establishment. The
fingerprint is computed as the SHA\-256 hash of the certificate and displayed
in a human\-friendly encoding, called Device ID.
.sp
Incoming requests for file data are verified to the extent that the requested
file name must exist in the local index and the global model.
.sp
For information about ensuring you are running the code you think you are and
for reporting security vulnerabilities, please see the official \fI\%security page\fP <\fBhttps://syncthing.net/security.html\fP>\&.
.SH INFORMATION LEAKAGE
.SS Global Discovery
.sp
When global discovery is enabled, Syncthing sends an announcement every 30
minutes to the global discovery servers so that they can keep a mapping
between your device ID and external IP. The announcement contain the device
ID and listening port(s). Also, when connecting to other devices that have
not been seen on the local network, a query is sent to the global discovery
servers containing the device ID of the requested device. The connection to
the discovery server is encrypted using TLS and the discovery server
certificate is verified, so the contents of the query should be considered
private between the device and the discovery server. The discovery servers
are currently hosted by \fI\%@calmh\fP <\fBhttps://github.com/calmh\fP>\&. Global discovery defaults to \fBon\fP\&.
.sp
When turned off, devices with dynamic addresses not on the local network cannot
be found and connected to.
.sp
An eavesdropper on the Internet can deduce which machines are running
Syncthing with global discovery enabled, and what their device IDs are.
.sp
The operator of the discovery server can map arbitrary device addresses to
IP addresses, and deduce which devices are connected to each other.
.sp
If a different global discovery server is configured, no data is sent to the
default global discovery servers.
.SS Local Discovery
.sp
When local discovery is enabled, Syncthing sends broadcast (IPv4) and multicast
(IPv6) packets to the local network every 30 seconds. The packets contain the
device ID and listening port. Local discovery defaults to \fBon\fP\&.
.sp
An eavesdropper on the local network can deduce which machines are running
Syncthing with local discovery enabled, and what their device IDs are.
.sp
When turned off, devices with dynamic addresses on the local network cannot be
found and connected to.
.SS Upgrade Checks
.sp
When automatic upgrades are enabled, Syncthing checks for a new version at
startup and then once every twelve hours. This is by an HTTPS request to the
download site for releases, currently hosted by \fI\%@calmh\fP <\fBhttps://github.com/calmh\fP>\&.
Automatic upgrades default to \fBon\fP (unless Syncthing was compiled with
upgrades disabled).
.sp
Even when automatic upgrades are disabled in the configuration, an upgrade check
as above is done when the GUI is loaded, in order to show the “Upgrade to …”
button when necessary. This can be disabled only by compiling Syncthing with
upgrades disabled.
.sp
The actual download, should an upgrade be available, is done from
\fBGitHub\fP, thus exposing the user to them.
.sp
The upgrade check (or download) requests \fIdo not\fP contain any identifiable
information about the user or device.
.SS Usage Reporting
.sp
When usage reporting is enabled, Syncthing reports usage data at startup and
then every 24 hours. The report is sent as an HTTPS POST to the usage reporting
server, currently hosted by \fI\%@calmh\fP <\fBhttps://github.com/calmh\fP>\&. The contents of the usage report can
be seen behind the “Preview” link in settings. Usage reporting defaults to
\fBoff\fP but the GUI will ask once about enabling it, shortly after the first
install.
.sp
The reported data is protected from eavesdroppers, but the connection to the
usage reporting server itself may expose the client as running Syncthing.
.SS Sync Connections (BEP)
.sp
Sync connections are attempted to all configured devices, when the address is
possible to resolve. The sync connection is based on TLS 1.2 or TLS 1.3. The TLS
certificates can be obtained by an eavesdropper, altough it is more difficult to do so in TLS 1.3. This means that the contents of the certificate are visible, which includes certificate Common Name (by default \fBsyncthing\fP).
.sp
An eavesdropper can deduce that this is a Syncthing connection and under certain circumstances calculate the
device IDs involved based on the hashes of the sent certificates.
.sp
Likewise, if the sync port (default 22000) is accessible from the internet, a
port scanner may discover it, attempt a TLS negotiation and thus obtain the
device certificate. This provides the same information as in the eavesdropper
case.
.SS Relay Connections
.sp
When relaying is enabled, Syncthing will look up the pool of public relays
and establish a connection to one of them (the best, based on an internal
heuristic). The selected relay server will learn the connecting device’s
device ID. Relay servers can be run by \fBanyone in the general public\fP\&.
Relaying defaults to \fBon\fP\&. Syncthing can be configured to disable
relaying, or only use specific relays.
.sp
If a relay connections is required between two devices, the relay will learn
the other device’s device ID as well.
.sp
Any data exchanged between the two devices is encrypted as usual and not
subject to inspection by the relay.
.SS Web GUI
.sp
If the web GUI is accessible, it exposes the device as running Syncthing. The
web GUI defaults to being reachable from the \fBlocal host only\fP\&.
.SH IN SHORT
.sp
Parties doing surveillance on your network (whether that be corporate IT, the
NSA or someone else) will be able to see that you use Syncthing, and your device
IDs \fI\%are OK to share anyway\fP <\fBhttps://docs.syncthing.net/users/faq.html#should-i-keep-my-device-ids-secret\fP>,
but the actual transmitted data is protected as well as we can. Knowing your
device ID can expose your IP address, using global discovery.
.SH PROTECTING YOUR SYNCTHING KEYS AND IDENTITY
.sp
Anyone who can access the Syncthing TLS keys and config file on your device can
impersonate your device, connect to your peers, and then have access to your
synced files. Here are some general principles to protect your files:
.INDENT 0.0
.IP 1. 3
If a device of yours is lost, make sure to revoke its access from your other
devices.
.IP 2. 3
If you’re syncing confidential data on an encrypted disk to guard against
device theft, put the Syncthing config folder on the same encrypted disk to
avoid leaking keys and metadata. Or, use whole disk encryption.
.UNINDENT
.SH AUTHOR
The Syncthing Authors
.SH COPYRIGHT
2014-2019, The Syncthing Authors
.\" Generated by docutils manpage writer.
.

223
man/syncthing-stignore.5
View File

@ -1 +1,222 @@
404 Not Found
.\" Man page generated from reStructuredText.
.
.TH "SYNCTHING-STIGNORE" "5" "Jun 19, 2020" "v1" "Syncthing"
.SH NAME
syncthing-stignore \- Prevent files from being synchronized to other nodes
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.SH SYNOPSIS
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\&.stignore
.ft P
.fi
.UNINDENT
.UNINDENT
.SH DESCRIPTION
.sp
If some files should not be synchronized to (or from) other devices, a file called
\fB\&.stignore\fP can be created containing file patterns to ignore. The
\fB\&.stignore\fP file must be placed in the root of the folder. The
\fB\&.stignore\fP file itself will never be synced to other devices, although it can
\fB#include\fP files that \fIare\fP synchronized between devices. All patterns are
relative to the folder root.
The contents of the \fB\&.stignore\fP file must be UTF\-8 encoded.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Note that ignored files can block removal of an otherwise empty directory.
See below for the (?d) prefix to allow deletion of ignored files.
.UNINDENT
.UNINDENT
.SH PATTERNS
.sp
The \fB\&.stignore\fP file contains a list of file or path patterns. The
\fIfirst\fP pattern that matches will decide the fate of a given file.
.INDENT 0.0
.IP \(bu 2
Regular file names match themselves, i.e. the pattern \fBfoo\fP matches
the files \fBfoo\fP, \fBsubdir/foo\fP as well as any directory named
\fBfoo\fP\&. Spaces are treated as regular characters.
.IP \(bu 2
\fBAsterisk\fP (\fB*\fP) matches zero or more characters in a filename, but does not
match the directory separator. \fBte*ne\fP matches \fBtelephone\fP,
\fBsubdir/telephone\fP but not \fBtele/phone\fP\&.
.IP \(bu 2
\fBDouble asterisk\fP (\fB**\fP) matches as above, but also directory separators.
\fBte**ne\fP matches \fBtelephone\fP, \fBsubdir/telephone\fP and
\fBtele/sub/dir/phone\fP\&.
.IP \(bu 2
\fBQuestion mark\fP (\fB?\fP) matches a single character that is not the directory
separator. \fBte??st\fP matches \fBtebest\fP but not \fBteb/st\fP or
\fBtest\fP\&.
.IP \(bu 2
\fBSquare brackets\fP (\fB[]\fP) denote a character range: \fB[a\-z]\fP matches
any lower case character.
.IP \(bu 2
\fBCurly brackets\fP (\fB{}\fP) denote a set of comma separated alternatives:
\fB{banana,pineapple}\fP matches either \fBbanana\fP or \fBpineapple\fP\&.
.IP \(bu 2
\fBBackslash\fP (\fB\e\fP) “escapes” a special character so that it loses its
special meaning. For example, \fB\e{banana\e}\fP matches \fB{banana}\fP exactly
and does not denote a set of alternatives as above. \fIEscaped characters
are not supported on Windows.\fP
.IP \(bu 2
A pattern beginning with \fB/\fP matches in the root of the folder only.
\fB/foo\fP matches \fBfoo\fP but not \fBsubdir/foo\fP\&.
.IP \(bu 2
A pattern beginning with \fB#include\fP results in loading patterns
from the named file. It is an error for a file to not exist or be
included more than once. Note that while this can be used to include
patterns from a file in a subdirectory, the patterns themselves are
still relative to the folder \fIroot\fP\&. Example:
\fB#include more\-patterns.txt\fP\&.
.IP \(bu 2
A pattern beginning with a \fB!\fP prefix negates the pattern: matching files
are \fIincluded\fP (that is, \fInot\fP ignored). This can be used to override
more general patterns that follow.
.IP \(bu 2
A pattern beginning with a \fB(?i)\fP prefix enables case\-insensitive pattern
matching. \fB(?i)test\fP matches \fBtest\fP, \fBTEST\fP and \fBtEsT\fP\&. The
\fB(?i)\fP prefix can be combined with other patterns, for example the
pattern \fB(?i)!picture*.png\fP indicates that \fBPicture1.PNG\fP should
be synchronized. On Mac OS and Windows, patterns are always case\-insensitive.
.IP \(bu 2
A pattern beginning with a \fB(?d)\fP prefix enables removal of these files if
they are preventing directory deletion. This prefix should be used by any OS
generated files which you are happy to be removed.
.IP \(bu 2
A line beginning with \fB//\fP is a comment and has no effect.
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Prefixes can be specified in any order (e.g. “(?d)(?i)”), but cannot be in a
single pair of parentheses (not “(?di)”).
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Include patterns (that begin with \fB!\fP) cause Syncthing to traverse and
watch the entire directory tree regardless of other
ignore patterns.
.sp
Top\-level include patterns are treated as special cases and will not force Syncthing to
scan the entire directory tree. For example: \fB!/foo\fP is a top\-level include
pattern, while \fB!/foo/bar\fP is not.
.UNINDENT
.UNINDENT
.SH EXAMPLE
.sp
Given a directory layout:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\&.DS_Store
foo
foofoo
bar/
baz
quux
quuz
bar2/
baz
frobble
My Pictures/
Img15.PNG
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
and an \fB\&.stignore\fP file with the contents:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
(?d).DS_Store
!frobble
!quuz
foo
*2
qu*
(?i)my pictures
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
all files and directories called “foo”, ending in a “2” or starting with
“qu” will be ignored. The end result becomes:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\&.DS_Store # ignored, will be deleted if gets in the way of parent directory removal
foo # ignored, matches "foo"
foofoo # synced, does not match "foo" but would match "foo*" or "*foo"
bar/ # synced
baz # synced
quux # ignored, matches "qu*"
quuz # synced, matches "qu*" but is excluded by the preceding "!quuz"
bar2/ # synced, despite matching "*2" due to child frobble
baz # ignored, due to parent being ignored
frobble # synced, due to "!frobble"
My Pictures/ # ignored, matched case insensitive "(?i)my pictures" pattern
Img15.PNG # ignored, due to parent being ignored
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Please note that directory patterns ending with a slash
\fBsome/directory/\fP matches the content of the directory, but not the
directory itself. If you want the pattern to match the directory and its
content, make sure it does not have a \fB/\fP at the end of the pattern.
.UNINDENT
.UNINDENT
.SH AUTHOR
The Syncthing Authors
.SH COPYRIGHT
2014-2019, The Syncthing Authors
.\" Generated by docutils manpage writer.
.

214
man/syncthing-versioning.7
View File

@ -1 +1,213 @@
404 Not Found
.\" Man page generated from reStructuredText.
.
.TH "SYNCTHING-VERSIONING" "7" "Jun 19, 2020" "v1" "Syncthing"
.SH NAME
syncthing-versioning \- Keep automatic backups of deleted files by other nodes
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.sp
Syncthing supports archiving the old version of a file when it is deleted or
replaced with a newer version from the cluster. This is called “file
versioning” and uses one of the available \fIversioning strategies\fP described
below. File versioning is configured per folder, on a per\-device basis, and
defaults to “no file versioning”, i.e. no old copies of files are kept.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Versioning applies to changes received \fIfrom other devices\fP\&. That is, if
Alice has versioning turned on and Bob changes a file, the old version
will be archived on Alice’s computer when that change is synced from
Bob. If Alice changes a file locally on her own computer Syncthing will
not and can not archive the old version.
.UNINDENT
.UNINDENT
.SH TRASH CAN FILE VERSIONING
.sp
This versioning strategy emulates the common “trash can” approach. When a file
is deleted or replaced due to a change on a remote device, it is a moved to
the trash can in the \fB\&.stversions\fP folder. If a file with the same name was
already in the trash can it is replaced.
.sp
A configuration option is available to clean the trash can from files older
than a specified number of days. If this is set to a positive number of days,
files will be removed when they have been in the trash can that long. Setting
this to zero prevents any files from being removed from the trash can
automatically.
.SH SIMPLE FILE VERSIONING
.sp
With “Simple File Versioning” files are moved to the \fB\&.stversions\fP folder
(inside your shared folder) when replaced or deleted on a remote device. This
option also takes a value in an input titled “Keep Versions” which tells
Syncthing how many old versions of the file it should keep. For example, if
you set this value to 5, if a file is replaced 5 times on a remote device, you
will see 5 time\-stamped versions on that file in the “.stversions” folder on
the other devices sharing the same folder.
.SH STAGGERED FILE VERSIONING
.sp
With “Staggered File Versioning” files are also moved to a different folder
when replaced or deleted on a remote device (just like “Simple File
Versioning”), however, versions are automatically deleted if they are older
than the maximum age or exceed the number of files allowed in an interval.
.sp
With this versioning method it’s possible to specify where the versions are
stored, with the default being the \fB\&.stversions\fP folder inside the normal
folder path. If you set a custom version path, please ensure that it’s on the
same partition or filesystem as the regular folder path, as moving files there
may otherwise fail. You can use an absolute path (this is recommended) or a
relative path. Relative paths are interpreted relative to Syncthing’s current
or startup directory.
.sp
The following intervals are used and they each have a maximum number of files
that will be kept for each.
.INDENT 0.0
.TP
.B 1 Hour
For the first hour, the most recent version is kept every 30 seconds.
.TP
.B 1 Day
For the first day, the most recent version is kept every hour.
.TP
.B 30 Days
For the first 30 days, the most recent version is kept every day.
.TP
.B Until Maximum Age
Until maximum age, the most recent version is kept every week.
.TP
.B Maximum Age
The maximum time to keep a version in days. For example, to keep replaced or
deleted files in the “.stversions” folder for an entire year, use 365. If
only for 10 days, use 10.
\fBNote: Set to 0 to keep versions forever.\fP
.UNINDENT
.SH EXTERNAL FILE VERSIONING
.sp
This versioning method delegates the decision on what to do to an external
command (program or script).
Just prior to a file being replaced, the command will be run.
The command should be specified as an absolute path, and can use the following templated arguments:
.INDENT 0.0
.TP
.B %FOLDER_PATH%
Path to the folder
.TP
.B %FILE_PATH%
Path to the file within the folder
.UNINDENT
.SS Example for Unixes
.sp
Lets say I want to keep the latest version of each file as they are replaced
or removed; essentially I want a “trash can”\-like behavior. For this, I create
the following script and store it as \fB/Users/jb/bin/onlylatest.sh\fP (i.e. the
\fBbin\fP directory in my home directory):
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
#!/bin/sh
set \-eu
# Where I want my versions stored
versionspath=~/.trashcan
# The parameters we get from Syncthing
folderpath="$1"
filepath="$2"
# First ensure the dir where we need to store the file exists
outpath=\(gadirname "$versionspath/$filepath"\(ga
mkdir \-p "$outpath"
# Then move the file there
mv \-f "$folderpath/$filepath" "$versionspath/$filepath"
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
I must ensure that the script has execute permissions (\fBchmod 755
onlylatest.sh\fP), then configure Syncthing with command \fB/Users/jb/bin/onlylatest.sh %FOLDER_PATH% %FILE_PATH%\fP
.sp
Lets assume I have a folder “default” in ~/Sync, and that within that folder
there is a file \fBdocs/letter.txt\fP that is being replaced or deleted. The
script will be called as if I ran this from the command line:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ /Users/jb/bin/onlylatest.sh /Users/jb/Sync docs/letter.txt
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The script will then move the file in question to
\fB~/.trashcan/docs/letter.txt\fP, replacing any previous version of that letter
that may already have been there.
.SS Example for Windows
.sp
On Windows we can use a batch script to perform the same “trash can”\-like
behavior as mentioned above. I created the following script and saved it as
\fBC:\eUsers\emfrnd\eScripts\eonlylatest.bat\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
@echo off
:: We need command extensions for mkdir to create intermediate folders in one go
setlocal EnableExtensions
:: Where I want my versions stored
set VERSIONS_PATH=%USERPROFILE%\e.trashcan
:: The parameters we get from Syncthing, \(aq~\(aq removes quotes if any
set FOLDER_PATH=%~1
set FILE_PATH=%~2
:: First ensure the dir where we need to store the file exists
for %%F in ("%VERSIONS_PATH%\e%FILE_PATH%") do set OUTPUT_PATH=%%~dpF
if not exist "%OUTPUT_PATH%" mkdir "%OUTPUT_PATH%" || exit /B
:: Finally move the file, overwrite existing file if any
move /Y "%FOLDER_PATH%\e%FILE_PATH%" "%VERSIONS_PATH%\e%FILE_PATH%"
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Finally, I set \fBC:\eUsers\emfrnd\eScripts\eonlylatest.bat %FOLDER_PATH% %FILE_PATH%\fP as command name in
Syncthing.
.SH AUTHOR
The Syncthing Authors
.SH COPYRIGHT
2014-2019, The Syncthing Authors
.\" Generated by docutils manpage writer.
.

413
man/syncthing.1
View File

@ -1 +1,412 @@
404 Not Found
.\" Man page generated from reStructuredText.
.
.TH "SYNCTHING" "1" "Jun 19, 2020" "v1" "Syncthing"
.SH NAME
syncthing \- Syncthing
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.SH SYNOPSIS
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
syncthing [\-audit] [\-auditfile=<file|\-|\-\->] [\-browser\-only] [device\-id]
[\-generate=<dir>] [\-gui\-address=<address>] [\-gui\-apikey=<key>]
[\-home=<dir>] [\-logfile=<filename>] [\-logflags=<flags>]
[\-no\-browser] [\-no\-console] [\-no\-restart] [\-paths] [\-paused]
[\-reset\-database] [\-reset\-deltas] [\-unpaused] [\-upgrade]
[\-upgrade\-check] [\-upgrade\-to=<url>] [\-verbose] [\-version]
.ft P
.fi
.UNINDENT
.UNINDENT
.SH DESCRIPTION
.sp
Syncthing lets you synchronize your files bidirectionally across multiple
devices. This means the creation, modification or deletion of files on one
machine will automatically be replicated to your other devices. We believe your
data is your data alone and you deserve to choose where it is stored. Therefore
Syncthing does not upload your data to the cloud but exchanges your data across
your machines as soon as they are online at the same time.
.SH OPTIONS
.INDENT 0.0
.TP
.B \-audit
Write events to timestamped file \fBaudit\-YYYYMMDD\-HHMMSS.log\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-auditfile=<file|\-|\-\->
Use specified file or stream (\fB"\-"\fP for stdout, \fB"\-\-"\fP for stderr) for audit events, rather than the timestamped default file name.
.UNINDENT
.INDENT 0.0
.TP
.B \-browser\-only
Open the web UI in a browser for an already running Syncthing instance.
.UNINDENT
.INDENT 0.0
.TP
.B \-device\-id
Print device ID to command line.
.UNINDENT
.INDENT 0.0
.TP
.B \-generate=<dir>
Generate key and config in specified dir, then exit.
.UNINDENT
.INDENT 0.0
.TP
.B \-gui\-address=<address>
Override GUI listen address. Set this to an address (\fB0.0.0.0:8384\fP)
or file path (\fB/var/run/st.sock\fP, for UNIX sockets).
.UNINDENT
.INDENT 0.0
.TP
.B \-home=<dir>
Set configuration directory. The default configuration directory is
\fB$HOME/.config/syncthing\fP (Unix\-like), \fB$HOME/Library/Application Support/Syncthing\fP (Mac) and \fB%LOCALAPPDATA%\eSyncthing\fP (Windows).
.UNINDENT
.INDENT 0.0
.TP
.B \-logfile=<filename>
Set destination filename for logging (use \fB"\-"\fP for stdout, which is the default option).
.UNINDENT
.INDENT 0.0
.TP
.B \-logflags=<flags>
Select information in log line prefix. The \fB\-logflags\fP value is a sum of
the following:
.INDENT 7.0
.IP \(bu 2
1: Date
.IP \(bu 2
2: Time
.IP \(bu 2
4: Microsecond time
.IP \(bu 2
8: Long filename
.IP \(bu 2
16: Short filename
.UNINDENT
.sp
To prefix each log line with date and time, set \fB\-logflags=3\fP (1 + 2 from
above). The value 0 is used to disable all of the above. The default is to
show time only (2).
.UNINDENT
.INDENT 0.0
.TP
.B \-no\-browser
Do not start a browser.
.UNINDENT
.INDENT 0.0
.TP
.B \-no\-console
Hide the console window. (On Windows only)
.UNINDENT
.INDENT 0.0
.TP
.B \-no\-restart
Disable the Syncthing monitor process which handles restarts for some configuration changes, upgrades, crashes and also log file writing (stdout is still written).
.UNINDENT
.INDENT 0.0
.TP
.B \-paths
Print the paths used for configuration, keys, database, GUI overrides, default sync folder and the log file.
.UNINDENT
.INDENT 0.0
.TP
.B \-paused
Start with all devices and folders paused.
.UNINDENT
.INDENT 0.0
.TP
.B \-reset\-database
Reset the database, forcing a full rescan and resync. Create \fI\&.stfolder\fP
folders in each sync folder if they do not already exist. \fBCaution\fP:
Ensure that all sync folders which are mountpoints are already mounted.
Inconsistent versions may result if the mountpoint is later mounted and
contains older versions.
.UNINDENT
.INDENT 0.0
.TP
.B \-reset\-deltas
Reset delta index IDs, forcing a full index exchange.
.UNINDENT
.INDENT 0.0
.TP
.B \-unpaused
Start with all devices and folders unpaused.
.UNINDENT
.INDENT 0.0
.TP
.B \-upgrade
Perform upgrade.
.UNINDENT
.INDENT 0.0
.TP
.B \-upgrade\-check
Check for available upgrade.
.UNINDENT
.INDENT 0.0
.TP
.B \-upgrade\-to=<url>
Force upgrade directly from specified URL.
.UNINDENT
.INDENT 0.0
.TP
.B \-verbose
Print verbose log output.
.UNINDENT
.INDENT 0.0
.TP
.B \-version
Show version.
.UNINDENT
.SH EXIT CODES
.INDENT 0.0
.TP
.B 0
Success / Shutdown
.TP
.B 1
Error
.TP
.B 2
Upgrade not available
.TP
.B 3
Restarting
.TP
.B 4
Upgrading
.UNINDENT
.sp
Some of these exit codes are only returned when running without a monitor
process (with environment variable \fBSTNORESTART\fP set). Exit codes over 125 are
usually returned by the shell/binary loader/default signal handler. Exit codes
over 128+N on Unix usually represent the signal which caused the process to
exit. For example, \fB128 + 9 (SIGKILL) = 137\fP\&.
.SH PROXIES
.sp
Syncthing can use a SOCKS, HTTP, or HTTPS proxy to talk to the outside
world. The proxy is used for outgoing connections only \- it is not possible
to accept incoming connections through the proxy. The proxy is configured
through the environment variable \fBall_proxy\fP\&. Somewhat unusually, this
variable must be named in lower case \- it is not “ALL_PROXY”. For
example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ export all_proxy=socks://192.0.2.42:8081
.ft P
.fi
.UNINDENT
.UNINDENT
.SH DEVELOPMENT SETTINGS
.sp
The following environment variables modify Syncthing’s behavior in ways that
are mostly useful for developers. Use with care.
If you start Syncthing from within service managers like systemd or supervisor,
path expansion may not be supported.
.INDENT 0.0
.TP
.B STTRACE
Used to increase the debugging verbosity in specific or all facilities,
generally mapping to a Go package. Enabling any of these also enables
microsecond timestamps, file names plus line numbers. Enter a
comma\-separated string of facilities to trace. \fBsyncthing \-help\fP always
outputs an up\-to\-date list. The valid facility strings are:
.INDENT 7.0
.TP
.B Main and operational facilities:
.INDENT 7.0
.TP
.B config
Configuration loading and saving.
.TP
.B db
The database layer.
.TP
.B main
Main package.
.TP
.B model
The root hub; the largest chunk of the system. File pulling, index
transmission and requests for chunks.
.TP
.B scanner
File change detection and hashing.
.TP
.B versioner
File versioning.
.UNINDENT
.TP
.B Networking facilities:
.INDENT 7.0
.TP
.B beacon
Multicast and broadcast UDP discovery packets: Selected interfaces
and addresses.
.TP
.B connections
Connection handling.
.TP
.B dialer
Dialing connections.
.TP
.B discover
Remote device discovery requests, replies and registration of
devices.
.TP
.B nat
NAT discovery and port mapping.
.TP
.B pmp
NAT\-PMP discovery and port mapping.
.TP
.B protocol
The BEP protocol.
.TP
.B relay
Relay interaction (\fBstrelaysrv\fP).
.TP
.B upnp
UPnP discovery and port mapping.
.UNINDENT
.TP
.B Other facilities:
.INDENT 7.0
.TP
.B fs
Filesystem access.
.TP
.B events
Event generation and logging.
.TP
.B http
REST API.
.TP
.B sha256
SHA256 hashing package (this facility currently unused).
.TP
.B stats
Persistent device and folder statistics.
.TP
.B sync
Mutexes. Used for debugging race conditions and deadlocks.
.TP
.B upgrade
Binary upgrades.
.TP
.B walkfs
Filesystem access while walking.
.TP
.B all
All of the above.
.UNINDENT
.UNINDENT
.TP
.B STBLOCKPROFILE
Write block profiles to \fBblock\-$pid\-$timestamp.pprof\fP every 20 seconds.
.TP
.B STCPUPROFILE
Write a CPU profile to \fBcpu\-$pid.pprof\fP on exit.
.TP
.B STDEADLOCKTIMEOUT
Used for debugging internal deadlocks; sets debug sensitivity. Use only
under direction of a developer.
.TP
.B STDEADLOCKTHRESHOLD
Used for debugging internal deadlocks; sets debug sensitivity. Use only
under direction of a developer.
.TP
.B STGUIASSETS
Directory to load GUI assets from. Overrides compiled in assets. Useful for
developing webgui, commonly use \fBSTGUIASSETS=gui bin/syncthing\fP\&.
.TP
.B STHASHING
Specify which hashing package to use. Defaults to automatic based on
performance. Specify “minio” (compatibility) or “standard” for the default
Go implementation.
.TP
.B STHEAPPROFILE
Write heap profiles to \fBheap\-$pid\-$timestamp.pprof\fP each time heap usage
increases.
.TP
.B STNODEFAULTFOLDER
Don’t create a default folder when starting for the first time. This
variable will be ignored anytime after the first run.
.TP
.B STNORESTART
Equivalent to the \fB\-no\-restart\fP flag. Disable the Syncthing monitor
process which handles restarts for some configuration changes, upgrades,
crashes and also log file writing (stdout is still written).
.TP
.B STNOUPGRADE
Disable automatic upgrades.
.TP
.B STPROFILER
Set to a listen address such as “127.0.0.1:9090” to start the profiler with
HTTP access, which then can be reached at
\fI\%http://localhost:9090/debug/pprof\fP\&. See \fBgo tool pprof\fP for more
information.
.TP
.B STPERFSTATS
Write running performance statistics to \fBperf\-$pid.csv\fP\&. Not supported on
Windows.
.TP
.B STRECHECKDBEVERY
Time before folder statistics (file, dir, … counts) are recalculated from
scratch. The given duration must be parseable by Go’s time.ParseDuration. If
missing or not parseable, the default value of 1 month is used. To force
recalculation on every startup, set it to \fB1s\fP\&.
.TP
.B GOMAXPROCS
Set the maximum number of CPU cores to use. Defaults to all available CPU
cores.
.TP
.B GOGC
Percentage of heap growth at which to trigger GC. Default is 100. Lower
numbers keep peak memory usage down, at the price of CPU usage
(i.e. performance).
.UNINDENT
.SH SEE ALSO
.sp
\fBsyncthing\-config(5)\fP, \fBsyncthing\-stignore(5)\fP,
\fBsyncthing\-device\-ids(7)\fP, \fBsyncthing\-security(7)\fP,
\fBsyncthing\-networking(7)\fP, \fBsyncthing\-versioning(7)\fP,
\fBsyncthing\-faq(7)\fP
.SH AUTHOR
The Syncthing Authors
.SH COPYRIGHT
2014-2019, The Syncthing Authors
.\" Generated by docutils manpage writer.
.