felixfoertsch/syncthing
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 10 Wiki Activity

Create syncthing-faq(7)

Browse Source
This commit is contained in:
Stefan Tatschner
2015-05-29 16:44:16 +02:00
parent a979a50124
commit e6d0b370d2
1 changed files with 109 additions and 115 deletions
Download Patch File Download Diff File Expand all files Collapse all files
users/faq.rst
+109 -115
View File
@@ -9,39 +9,36 @@ General
What is Syncthing? What is Syncthing?
~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~
Syncthing is an application that lets you synchronize your files across Syncthing is an application that lets you synchronize your files across multiple
multiple devices. This means the creation, modification or deletion of devices. This means the creation, modification or deletion of files on one
files on one machine will automatically be replicated to your other machine will automatically be replicated to your other devices. We believe your
devices. We believe your data is your data alone and you deserve to data is your data alone and you deserve to choose where it is stored. Therefore
choose where it is stored. Therefore Syncthing does not upload your data Syncthing does not upload your data to the cloud but exchanges your data across
to the cloud but exchanges your data across your machines as soon as your machines as soon as they are online at the same time.
they are online at the same time.
Is it "syncthing", "Syncthing" or "SyncThing"? Is it "syncthing", "Syncthing" or "SyncThing"?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
It's **Syncthing**, although the command and source repository is It's **Syncthing**, although the command and source repository is spelled
spelled ``syncthing`` so it may be referred to in that way as well. It's ``syncthing`` so it may be referred to in that way as well. It's definitely not
definitely not :strike:`SyncThing`, even though the abbreviation :strike:`SyncThing`, even though the abbreviation ``st`` is used in some
``st`` is used in some circumstances and file names. circumstances and file names.
How does Syncthing differ from BitTorrent Sync? How does Syncthing differ from BitTorrent Sync?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The two are different and not related. Syncthing and BitTorrent Sync The two are different and not related. Syncthing and BitTorrent Sync accomplish
accomplish some of the same things, namely syncing files between two or some of the same things, namely syncing files between two or more computers.
more computers.
BitTorrent Sync by BitTorrent, Inc is a proprietary peer-to-peer file BitTorrent Sync by BitTorrent, Inc is a proprietary peer-to-peer file
synchronization tool available for Windows, Mac, Linux, Android, iOS, synchronization tool available for Windows, Mac, Linux, Android, iOS, Windows
Windows Phone, Amazon Kindle Fire and BSD. Phone, Amazon Kindle Fire and BSD. `1
`1 <http://en.wikipedia.org/wiki/BitTorrent_Sync>`__ Syncthing is an <http://en.wikipedia.org/wiki/BitTorrent_Sync>`__ Syncthing is an open source
open source file synchronization tool. file synchronization tool.
Syncthing uses an open and documented protocol, and likewise the Syncthing uses an open and documented protocol, and likewise the security
security mechanisms in use are well defined and visible in the source mechanisms in use are well defined and visible in the source code. BitTorrent
code. BitTorrent Sync uses an undocumented, closed protocol with unknown Sync uses an undocumented, closed protocol with unknown security properties.
security properties.
Usage Usage
----- -----
@@ -49,12 +46,12 @@ Usage
What things are synced? What things are synced?
~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~
The following things are *always* synchronized; The following things are *always* synchronized:
- File Contents - File Contents
- File Modification Times - File Modification Times
The following may be synchronized or not, depending; The following may be synchronized or not, depending:
- File Permissions (When supported by file system. On Windows, only the - File Permissions (When supported by file system. On Windows, only the
read only bit is synchronized.) read only bit is synchronized.)
@@ -75,17 +72,16 @@ The following is *not* synchronized;
Is synchronization fast? Is synchronization fast?
~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~
Syncthing segments files into pieces, called blocks, to transfer data Syncthing segments files into pieces, called blocks, to transfer data from one
from one device to another. Therefore, multiple devices can share the device to another. Therefore, multiple devices can share the synchronization
synchronization load, in a similar way as the torrent protocol. The more load, in a similar way as the torrent protocol. The more devices you have online
devices you have online (and synchronized), the faster an additional (and synchronized), the faster an additional device will receive the data
device will receive the data because small blocks will be fetched from because small blocks will be fetched from all devices in parallel.
all devices in parallel.
Syncthing handles renaming files and updating their metadata in an Syncthing handles renaming files and updating their metadata in an efficient
efficient manner. This means that renaming a large file will not cause a manner. This means that renaming a large file will not cause a retransmission of
retransmission of that file. Additionally, appending data to existing that file. Additionally, appending data to existing large files should be
large files should be handled efficiently as well. handled efficiently as well.
Temporary files are used to store partial data downloaded from other devices. Temporary files are used to store partial data downloaded from other devices.
They are automatically removed whenever a file transfer has been completed or They are automatically removed whenever a file transfer has been completed or
@@ -95,63 +91,60 @@ hours by default).
Should I keep my device IDs secret? Should I keep my device IDs secret?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
No. The IDs are not sensitive. Given a device ID it's possible to find No. The IDs are not sensitive. Given a device ID it's possible to find the IP
the IP address for that node, if global discovery is enabled on it. address for that node, if global discovery is enabled on it. Knowing the device
Knowing the device ID doesn't help you actually establish a connection ID doesn't help you actually establish a connection to that node or get a list
to that node or get a list of files, etc. of files, etc.
For a connection to be established, both nodes need to know about the For a connection to be established, both nodes need to know about the other's
other's device ID. It's not possible (in practice) to forge a device ID. device ID. It's not possible (in practice) to forge a device ID. (To forge a
(To forge a device ID you need to create a TLS certificate with that device ID you need to create a TLS certificate with that specific SHA-256 hash.
specific SHA-256 hash. If you can do that, you can spoof any TLS If you can do that, you can spoof any TLS certificate. The world is your
certificate. The world is your oyster!) oyster!)
See also `Understanding Device .. see-also::
IDs <http://docs.syncthing.net/dev/device-ids.html>`__. :ref:`dev/device-ids`
What if there is a conflict? What if there is a conflict?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Syncthing does recognize conflicts. When a file has been modified on two Syncthing does recognize conflicts. When a file has been modified on two devices
devices simultaneously, one of the files will be renamed to simultaneously, one of the files will be renamed to ``<filename>.sync-
``<filename>.sync- conflict-<date>-<time>.<ext>``. The device which has conflict-<date>-<time>.<ext>``. The device which has the larger value of the
the larger value of the first 63 bits for his device ID will have his first 63 bits for his device ID will have his file marked as the conflicting
file marked as the conflicting file. Note that we only create file. Note that we only create ``sync-conflict`` files when the actual content
``sync-conflict`` files when the actual content differs. differs.
Beware that the ``<filename>.sync-conflict-<date>-<time>.<ext>`` files Beware that the ``<filename>.sync-conflict-<date>-<time>.<ext>`` files are
are treated as normal files after they are created, so they are treated as normal files after they are created, so they are propagated between
propagated between devices. We do this because the conflict is detected devices. We do this because the conflict is detected and resolved on one device,
and resolved on one device, creating the ``sync-conflict`` file, but creating the ``sync-conflict`` file, but it's just as much of a conflict
it's just as much of a conflict everywhere else and we don't know which everywhere else and we don't know which of the conflicting files is the "best"
of the conflicting files is the "best" from the user point of view. from the user point of view. Moreover, if there's something that automatically
Moreover, if there's something that automatically causes a conflict on causes a conflict on change you'll end up with ``sync-conflict-...sync-conflict
change you'll end up with -...-sync-conflict`` files.
``sync-conflict-...sync-conflict -...-sync-conflict`` files.
How to configure multiple users on a single machine? How to configure multiple users on a single machine?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Each user should run their own Syncthing instance. Be aware that you Each user should run their own Syncthing instance. Be aware that you might need
might need to configure ports such that they do not overlap (see the to configure ports such that they do not overlap (see the config.xml).
config.xml).
Is Syncthing my ideal backup application? Is Syncthing my ideal backup application?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
No, Syncthing is not a backup application because all changes to your No, Syncthing is not a backup application because all changes to your files
files (modification, deletion, etc) will be propagated to all your (modification, deletion, etc) will be propagated to all your devices. You can
devices. You can enable versioning, but we encourage the use of other enable versioning, but we encourage the use of other tools to keep your data
tools to keep your data safe from your (or our) mistakes. safe from your (or our) mistakes.
Why is there no iOS client? Why is there no iOS client?
~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~
Alternative implementation Syncthing (using the Syncthing protocol) are Alternative implementation Syncthing (using the Syncthing protocol) are being
being developed at this point in time to enable iOS support. developed at this point in time to enable iOS support. Additionally, it seems
Additionally, it seems that the next version of Go will support the that the next version of Go will support the darwin-arm architecture such that
darwin-arm architecture such that we can compile the mainstream code for we can compile the mainstream code for the iOS platform.
the iOS platform.
Why does it use so much CPU? Why does it use so much CPU?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -163,35 +156,34 @@ Why does it use so much CPU?
encrypted using AES-128. When receiving data, it must be decrypted encrypted using AES-128. When receiving data, it must be decrypted
and decompressed. and decompressed.
Hashing, compression and encryption cost CPU time. Also, using the GUI Hashing, compression and encryption cost CPU time. Also, using the GUI causes a
causes a certain amount of CPU usage. Note however that once things are certain amount of CPU usage. Note however that once things are *in sync* CPU
*in sync* CPU usage should be negligible. usage should be negligible.
How can I exclude files with brackets (``[]``) in the name? How can I exclude files with brackets (``[]``) in the name?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The patterns in .stignore are glob patterns, where brackets are used to The patterns in .stignore are glob patterns, where brackets are used to denote
denote character ranges. That is, the pattern ``q[abc]x`` will match the character ranges. That is, the pattern ``q[abc]x`` will match the files ``qax``,
files ``qax``, ``qbx`` and ``qcx``. ``qbx`` and ``qcx``.
To match an actual file *called* ``q[abc]x`` the pattern needs to To match an actual file *called* ``q[abc]x`` the pattern needs to "escape" the
"escape" the brackets, like so: ``q\[abc\]x``. brackets, like so: ``q\[abc\]x``.
Why is the setup more complicated than BTSync? Why is the setup more complicated than BTSync?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Security over convenience. In Syncthing you have to setup both sides to Security over convenience. In Syncthing you have to setup both sides to connect
connect two nodes. An attacker can't do much with a stolen node ID, two nodes. An attacker can't do much with a stolen node ID, because you have to
because you have to add the node on the other side too. You have better add the node on the other side too. You have better control where your files are
control where your files are transferred. transferred.
How do I access the web GUI from another computer? How do I access the web GUI from another computer?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The default listening address is 127.0.0.1:8384, so you can only access The default listening address is 127.0.0.1:8384, so you can only access the GUI
the GUI from the same machine. Change the ``GUI listen address`` through from the same machine. Change the ``GUI listen address`` through the web UI from
the web UI from ``127.0.0.1:8384`` to ``0.0.0.0:8384`` or change the ``127.0.0.1:8384`` to ``0.0.0.0:8384`` or change the config.xml:
config.xml:
.. code-block:: xml .. code-block:: xml
@@ -208,58 +200,60 @@ to
Then the GUI is accessible from everywhere. You should most likely set a Then the GUI is accessible from everywhere. You should most likely set a
password and enable HTTPS now. You can do this from inside the GUI. password and enable HTTPS now. You can do this from inside the GUI.
If both your computers are Unixy (Linux, Mac, etc) You can also leave If both your computers are Unixy (Linux, Mac, etc) You can also leave the GUI
the GUI settings at default and use an ssh port forward to access it. settings at default and use an ssh port forward to access it. For example,
For example,
.. code-block:: bash .. code-block:: bash
$ ssh -L 9090:127.0.0.1:8384 user@othercomputer.example.com $ ssh -L 9090:127.0.0.1:8384 user@othercomputer.example.com
will log you into othercomputer.example.com, and present the *remote* will log you into othercomputer.example.com, and present the *remote* Syncthing
Syncthing GUI on http://localhost:9090 on your *local* computer. You GUI on http://localhost:9090 on your *local* computer. You should not open more
should not open more than one Syncthing GUI in a single browser due to than one Syncthing GUI in a single browser due to conflicting X-CSRFTokens. Any
conflicting X-CSRFTokens. Any modification will be rejected. See `Issue modification will be rejected. See `Issue 720
720 <https://github.com/syncthing/syncthing/issues/720#issuecomment-58159631>`__ <https://github.com/syncthing/syncthing/issues/720#issuecomment-58159631>`__ to
to work around this limitation. work around this limitation.
The CSRF tokens are stored using cookies. Therefore, if you get the The CSRF tokens are stored using cookies. Therefore, if you get the message
message ``Syncthing seems to be experiencing a problem processing your request``, you
``Syncthing seems to be experiencing a problem processing your request``, should verify the cookie settings of your browser.
you should verify the cookie settings of your browser.
Why do I see Syncthing twice in task manager? Why do I see Syncthing twice in task manager?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
One process manages the other, to capture logs and manage restarts. This One process manages the other, to capture logs and manage restarts. This makes
makes it easier to handle upgrades from within Syncthing itself, and it easier to handle upgrades from within Syncthing itself, and also ensures that
also ensures that we get a nice log file to help us narrow down the we get a nice log file to help us narrow down the cause for crashes and other
cause for crashes and other bugs. bugs.
Where do Syncthing logs go to? Where do Syncthing logs go to?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Syncthing logs to stdout by default. On Windows Syncthing by default Syncthing logs to stdout by default. On Windows Syncthing by default also
also creates ``syncthing.log`` in Syncthing's home directory (check creates ``syncthing.log`` in Syncthing's home directory (check ``-help`` to see
``-help`` to see where that is). where that is).
How do I upgrade Syncthing? How do I upgrade Syncthing?
~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~
- If automatic upgrades is enabled (which is the default), Syncthing will upgrade itself automatically within 24 hours of a new release. - If automatic upgrades is enabled (which is the default), Syncthing will
upgrade itself automatically within 24 hours of a new release.
- The upgrade button appears in the web GUI when a new version has been released. Pressing it will perform an upgrade. - The upgrade button appears in the web GUI when a new version has been released.
Pressing it will perform an upgrade.
- To force an upgrade from the command line, run ``syncthing -upgrade``. - To force an upgrade from the command line, run ``syncthing -upgrade``.
Note that your system should have CA certificates installed which allow a secure connection to GitHub (e.g. FreeBSD requires `sudo pkg install ca_root_nss`). If ``curl`` or ``wget`` works with normal HTTPS sites, then so should Syncthing. Note that your system should have CA certificates installed which allow a secure
connection to GitHub (e.g. FreeBSD requires ``sudo pkg install ca_root_nss``).
If ``curl`` or ``wget`` works with normal HTTPS sites, then so should Syncthing.
Where do I find the latest release? Where do I find the latest release?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
We release new versions through GitHub. The latest release is always found `on We release new versions through GitHub. The latest release is always found `on
the release page <https://github.com/syncthing/syncthing/releases/latest>`_. the release page <https://github.com/syncthing/syncthing/releases/latest>`_.
Unfortunately GitHub does not provide a single URL to automatically download Unfortunately GitHub does not provide a single URL to automatically download the
the latest version. We suggest to use the GitHub API at latest version. We suggest to use the GitHub API at
https://api.github.com/repos/syncthing/syncthing/releases/latest and parsing https://api.github.com/repos/syncthing/syncthing/releases/latest and parsing the
the JSON response. JSON response.