mirror of
https://github.com/octoleo/syncthing.git
synced 2024-12-23 11:28:59 +00:00
476 lines
20 KiB
Groff
476 lines
20 KiB
Groff
.\" Man page generated from reStructuredText.
|
|
.
|
|
.TH "SYNCTHING-FAQ" "7" "March 31, 2017" "v0.14" "Syncthing"
|
|
.SH NAME
|
|
syncthing-faq \- Frequently Asked Questions
|
|
.
|
|
.nr rst2man-indent-level 0
|
|
.
|
|
.de1 rstReportMargin
|
|
\\$1 \\n[an-margin]
|
|
level \\n[rst2man-indent-level]
|
|
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|
-
|
|
\\n[rst2man-indent0]
|
|
\\n[rst2man-indent1]
|
|
\\n[rst2man-indent2]
|
|
..
|
|
.de1 INDENT
|
|
.\" .rstReportMargin pre:
|
|
. RS \\$1
|
|
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
|
|
. nr rst2man-indent-level +1
|
|
.\" .rstReportMargin post:
|
|
..
|
|
.de UNINDENT
|
|
. RE
|
|
.\" indent \\n[an-margin]
|
|
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|
.nr rst2man-indent-level -1
|
|
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
|
|
..
|
|
.SH GENERAL
|
|
.SS What is Syncthing?
|
|
.sp
|
|
Syncthing is an application that lets you synchronize your files across multiple
|
|
devices. This means the creation, modification or deletion of files on one
|
|
machine will automatically be replicated to your other devices. We believe your
|
|
data is your data alone and you deserve to choose where it is stored. Therefore
|
|
Syncthing does not upload your data to the cloud but exchanges your data across
|
|
your machines as soon as they are online at the same time.
|
|
.SS Is it "syncthing", "Syncthing" or "SyncThing"?
|
|
.sp
|
|
It\(aqs \fBSyncthing\fP, although the command and source repository is spelled
|
|
\fBsyncthing\fP so it may be referred to in that way as well. It\(aqs definitely not
|
|
SyncThing, even though the abbreviation \fBst\fP is used in some
|
|
circumstances and file names.
|
|
.SS How does Syncthing differ from BitTorrent/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 USAGE
|
|
.SS What things are synced?
|
|
.sp
|
|
The following things are \fIalways\fP synchronized:
|
|
.INDENT 0.0
|
|
.IP \(bu 2
|
|
File Contents
|
|
.IP \(bu 2
|
|
File Modification Times
|
|
.UNINDENT
|
|
.sp
|
|
The following may be synchronized or not, depending:
|
|
.INDENT 0.0
|
|
.IP \(bu 2
|
|
File Permissions (When supported by file system. On Windows, only the
|
|
read only bit is synchronized.)
|
|
.IP \(bu 2
|
|
Symbolic Links (Except on Windows.)
|
|
.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 (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
|
|
.SS Is synchronization fast?
|
|
.sp
|
|
Syncthing segments files into pieces, called blocks, to transfer data from one
|
|
device to another. Therefore, multiple devices can share the synchronization
|
|
load, in a similar way 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).
|
|
.SS 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.
|
|
You can verify this by looking at the CPU utilization in the GUI. If it is
|
|
constantly at or close to 100%, you are limited by the CPU speed. In some
|
|
cases a lower CPU usage number can also indicate being limited by the CPU \-
|
|
for example constant 25% usage on a four core CPU likely means that
|
|
Syncthing is doing something that is not parallellizable and thus limited to
|
|
a single CPU core.
|
|
.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.
|
|
.SS Why does it use so much CPU?
|
|
.INDENT 0.0
|
|
.IP 1. 3
|
|
When new or changed files are detected, or Syncthing starts for the
|
|
first time, your files are hashed using SHA\-256.
|
|
.IP 2. 3
|
|
Data that is sent over the network is (optionally) compressed and
|
|
encrypted using AES\-128. When receiving data, it must be decrypted.
|
|
.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 60 seconds to detect
|
|
file changes. This means checking every file\(aqs 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 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\(aqs CPU power.
|
|
.sp
|
|
To reduce CPU spikes from scanning activity, use a filesystem notifications
|
|
plugin. This is delivered by default via Synctrayzor, Syncthing\-GTK and on
|
|
Android. For other setups, consider using \fI\%syncthing\-inotify\fP <\fBhttps://github.com/syncthing/syncthing-inotify\fP>\&.
|
|
.SS Should I keep my device IDs secret?
|
|
.sp
|
|
No. The IDs are not sensitive. Given a device ID it\(aqs possible to find the IP
|
|
address for that device, if global discovery is enabled on it. Knowing the device
|
|
ID doesn\(aqt 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\(aqs
|
|
device ID. It\(aqs not possible (in practice) to forge a device ID. (To forge a
|
|
device ID you need to create a TLS certificate with that specific SHA\-256 hash.
|
|
If you can do that, you can spoof any TLS certificate. The world is your
|
|
oyster!)
|
|
.sp
|
|
\fBSEE ALSO:\fP
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
device\-ids
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SS What if there is a conflict?
|
|
.sp
|
|
Syncthing does recognize conflicts. When a file has been modified on two devices
|
|
simultaneously and the content actually differs, one of the files will be
|
|
renamed to \fB<filename>.sync\-conflict\-<date>\-<time>.<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>.<ext>\fP files are
|
|
treated as normal files after they are created, so they are propagated between
|
|
devices. We do this because the conflict is detected and resolved on one device,
|
|
creating the \fBsync\-conflict\fP file, but it\(aqs just as much of a conflict
|
|
everywhere else and we don\(aqt know which of the conflicting files is the "best"
|
|
from the user point of view. Moreover, if there\(aqs something that automatically
|
|
causes a conflict on change you\(aqll end up with \fBsync\-conflict\-...sync\-conflict
|
|
\-...\-sync\-conflict\fP files.
|
|
.SS Am I able to use nested Syncthing folders?
|
|
.sp
|
|
Do not nest shared folders. This behaviour is in no way supported,
|
|
recommended or coded for in any way, and comes with many pitfalls.
|
|
.SS How do I rename/move a synced folder?
|
|
.sp
|
|
Syncthing doesn\(aqt have a direct way to do this, as it\(aqs potentially
|
|
dangerous to do so if you\(aqre 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\(aqs 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, edit
|
|
the path directly in the configuration file and then start Syncthing again.
|
|
.SS 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).
|
|
.SS 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\(aqs method would be wasteful. There are better
|
|
programs to achieve this such as rsync or Unison.
|
|
.SS 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.
|
|
.SS 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.
|
|
.SS 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.
|
|
.SS How can I exclude files with brackets (\fB[]\fP) in the name?
|
|
.sp
|
|
The patterns in .stignore are glob patterns, where brackets are used to
|
|
denote character ranges. That is, the pattern \fBq[abc]x\fP will match the
|
|
files \fBqax\fP, \fBqbx\fP and \fBqcx\fP\&.
|
|
.sp
|
|
To match an actual file \fIcalled\fP \fBq[abc]x\fP the pattern needs to "escape"
|
|
the brackets, like so: \fBq\e[abc\e]x\fP\&.
|
|
.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.
|
|
.SS 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\(aqt 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.
|
|
.SS How do I access the web GUI from another computer?
|
|
.sp
|
|
The default listening address is 127.0.0.1:8384, so you can only access the
|
|
GUI from the same machine. 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\(aqt 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
|
|
.SS 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.
|
|
.SS 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\(aqs 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.
|
|
.SS I don\(aqt 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/master/gui/default\fP
|
|
to get an idea how to do that.
|
|
.SS Why do I see Syncthing twice in task manager?
|
|
.sp
|
|
One process manages the other, to capture logs and manage restarts. This
|
|
makes it easier to handle upgrades from within Syncthing itself, and also
|
|
ensures that we get a nice log file to help us narrow down the cause for
|
|
crashes and other bugs.
|
|
.SS Where do Syncthing logs go to?
|
|
.sp
|
|
Syncthing logs to stdout by default. On Windows Syncthing by default also
|
|
creates \fBsyncthing.log\fP in Syncthing\(aqs home directory (run \fBsyncthing
|
|
\-paths\fP to see where that is). Command line option \fB\-logfile\fP can be used
|
|
to specify a user\-defined logfile.
|
|
.SS How do I upgrade Syncthing?
|
|
.sp
|
|
If you use a package manager such as Debian\(aqs 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.
|
|
.SS Where do I find the latest release?
|
|
.sp
|
|
We release new versions through GitHub. The latest release is always found
|
|
\fI\%on the release page\fP <\fBhttps://github.com/syncthing/syncthing/releases/latest\fP>\&. Unfortunately
|
|
GitHub does not provide a single URL to automatically download the latest
|
|
version. We suggest to use the GitHub API at
|
|
\fI\%https://api.github.com/repos/syncthing/syncthing/releases/latest\fP and parsing
|
|
the JSON response.
|
|
.SS How do I run Syncthing as a daemon process on Linux?
|
|
.sp
|
|
If you\(aqre using systemd, runit, or upstart, we already ship examples, check
|
|
\fI\%https://github.com/syncthing/syncthing/tree/master/etc\fP for example
|
|
configurations.
|
|
.sp
|
|
If however you\(aqre 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\(aqs 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\(aqt 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 AUTHOR
|
|
The Syncthing Authors
|
|
.SH COPYRIGHT
|
|
2015, The Syncthing Authors
|
|
.\" Generated by docutils manpage writer.
|
|
.
|