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

Initial

Browse Source
This commit is contained in:
Jakob Borg
2015-05-28 12:40:43 +02:00
commit fd7fe795ad
92 changed files with 4050 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
users/autostart.rst
+259
View File
@@ -0,0 +1,259 @@
Starting Syncthing Automatically
================================
.. warning::
This page may be outdated and requires review.
Windows
-------
There is currently no official installer available for Windows. However,
there are a number of easy solutions.
Third-party Tools
~~~~~~~~~~~~~~~~~
There are a number of third-party utilities which aim to address this
issue. These typically provide an installer, let Syncthing start
automatically, and a more polished user experience (e.g. by behaving as
a "proper" Windows application, rather than forcing you to start your
browser to interact with Syncthing).
.. seealso:: :ref:`Windows GUI Wrappers <contrib-windows>`, :ref:`Cross-platform GUI Wrappers <contrib-all>`.
Start on Login
~~~~~~~~~~~~~~
Starting Syncthing on login, without a console window or browser opening
on start, is relatively easy.
1. Find the correct link of the Windows binary from the `Syncthing
website <https://github.com/syncthing/syncthing/releases>`__ (choose
**amd64** if you have a 64-bit version of Windows)
2. Extract the files in the folder (``syncthing-windows-*``) in the zip
to the folder ``C:\syncthing``
3. Go to the ``C:\syncthing`` folder, make a file named
``syncthing.bat``
4. Right-click the file and choose **Edit**. The file should open in
Notepad or your default text editor.
5. Paste the following command into the file and save the changes:
``start "Syncthing" syncthing.exe -no-console -no-browser``
6. Right-click on ``syncthing.bat`` and press "Create Shortcut"
7. Right-click the shortcut file ``syncthing.bat - Shortcut`` and click
**Copy**
8. Click **Start**, click **All Programs**, then click **Startup**.
Right-click on **Startup** then click **Open**.
|Setup Screenshot|
9. Paste the shortcut (right-click in the folder and choose **Paste**,
or press ``CTRL+V``)
Syncthing will now automatically start the next time Windows boots. No
console or browser window will pop-up. Access the interface by browsing
to http://localhost:8384/
If you prefer slower indexing but a more responsive system during scans,
copy the following command instead of the command in step 5:
``start "Syncthing" /low syncthing.exe -no-console -no-browser``
Run independent of user login
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. warning::
There are important security considerations with this approach. If you do not
secure Syncthing's GUI (and REST API), then **any** process running with
**any** permissions can read/write **any** file on your filesystem, by opening
a connection with Syncthing.
Therefore, you **must** ensure that you set a GUI password, or run Syncthing
as an unprivileged user.
With the above configuration, syncthing only starts when a user logs in
onto the machine. This is not optimal on servers, where a machine can
run long times after a reboot without anyone logged in. In this case, it
is best to create a service that runs as soon as Windows starts. This
can be achieved using nssm.
Note that starting Syncthing on login is the preferred approach for
almost any end-user scenario. The only scenario where running Syncthing
as a service makes sense is for (mostly) headless servers, administered
by a sysadmin who knows enough to understand the security implications.
1. Download and extract `nssm <http://nssm.cc/download>`__ to a folder
where it can stay (e.g. *c:Files* or the syncthing folder.
2. run *nssm.exe install syncthing*
3. Select ``syncthing.exe`` in the first tab and enter
``-no-console -no-browser`` as Arguments
|Configuration Screenshot|
4. at the Details tab you can switch to *Automatic (Delayed Start)* to
start it only some time after boot and speed up the boot process
(optional)
5. At the *Log On* tab you can enter a username and password for the
user to run syncthing as. This user needs to have access to all the
synced folders. Usually, you can leave it as the System account.
6. At the Process Tab you can change the priority to low if you want a
more responsive system at the cost of longer sync time
7. Click the *Install Service* Button
8. Start the service using the windows service manager, enter
``sc start syncthing`` in a console window or restart the PC.
9. Connect to the Syncthing UI, enable HTTPS, and set a secure username
and password.
Mac OS X
--------
Using `homebrew <http://brew.sh>`__
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1. ``brew install syncthing``
2. Follow the info to autostart syncthing using launchctl. At the moment
this is done using this command:
``launchctl load ~/Library/LaunchAgents/homebrew.mxcl.syncthing.plist``.
Without homebrew
~~~~~~~~~~~~~~~~
Download syncthing for Mac:
https://github.com/syncthing/syncthing/releases/latest.
1. Copy the syncthing binary (the file you would open to launch
syncthing) in a directory called ``bin`` in your home directory. If
"bin" does not exist, create it.
2. Edit the ``syncthing.plist`` (located in /etc/macosx-launchd) in the
two places that refer to your home directory; that is, replace
/Users/jb with your actual home directory location.
3. Copy the ``syncthing.plist`` file to ``~/Library/LaunchAgents``. If
you have trouble finding this location select the "Go" menu in Finder
and choose "Go to folder..." and then type
``~/Library/LaunchAgents``. Copying to ~/Library/LaunchAgents will
require admin password in most cases.
4. Log out and back in again. Or, if you do not want to log out, you can
run this command in terminal:
``launchctl load ~/Library/LaunchAgents/syncthing.plist``
**Note:** You probably want to turn off "Start Browser" in the web GUI
settings to avoid it opening a browser window on each login. Then, to
access the GUI type 127.0.0.1:8384 (by default) into Safari.
Linux
-----
Ubuntu like systems
~~~~~~~~~~~~~~~~~~~
1. Click the dashboard (hit 'Win' button).
2. Open 'Startup Applications'.
3. Click 'Add'.
4. Fill out the form:
- Name: Syncthing
- Command: /path/to/syncthing/binary -no-browser
-home="/home/your\_user/.config/syncthing"
Supervisord
~~~~~~~~~~~
Add following to your /etc/supervisord.conf.
::
[program:syncthing]
command = /path/to/syncthing/binary -no-browser -home="/home/some_user/.config/syncthing"
directory = /home/some_user/
autorestart = True
user = some_user
systemd
~~~~~~~
systemd is a suite of system management daemons, libraries, and
utilities designed as a central management and configuration platform
for the Linux computer operating system. It also offers users the
ability to manage services under the user's control with a per-user
systemd instance, enabling users to start, stop, enable, and disable
their own units. Service files for system are provided by syncthing and
can be found in
```etc/linux-systemd`` <https://github.com/syncthing/syncthing/tree/master/etc/linux-systemd>`__.
Several distros (including arch linux) ship these service files with the
syncthing package. If your distro provides a systemd service file for
syncthing you can skip step 2.
How to use the system instance
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Running synchting as a system service ensures that syncthing is run at
startup even if the syncthing user has no active session.
1. Create the user who should run the service, or choose an existing
one.
2. Copy the ``system/syncthing@.service`` file into the `load path of
the system
instance <http://www.freedesktop.org/software/systemd/man/systemd.unit.html#Unit%20Load%20Path>`__.
3. Enable and start the service. Append the syncthing user after the
``@``:
::
systemctl enable syncthing@myuser.service
systemctl start syncthing@myuser.service
How to use the user instance
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Running synchting as a user service ensures that syncthing is run after
the syncthing user has created a session (e.g. via the graphical login
screen or ssh). This could be used e.g. on a multiuser desktop computer
when you want to avoid unnecessarly running syncthing instances.
1. Create the user who should run the service, or choose an existing
one.
2. Copy the ``user/syncthing.service`` file into the `load path of the
user
instance <http://www.freedesktop.org/software/systemd/man/systemd.unit.html#Unit%20Load%20Path>`__.
To do this without root privileges you can use
``~/.config/systemd/user/``.
3. Enable and start the service:
::
systemctl --user enable syncthing.service
systemctl --user start syncthing.service
To check if syncthing runs properly you can use the ``status``
subcommand:
::
systemctl status syncthing@myuser.service
systemctl --user status syncthing.service
Using the journal
^^^^^^^^^^^^^^^^^
Systemd logs everything into the journal. You can easily acces syncthing
log messages (``-e`` lets the pager jump to the very end):
::
journalctl -e -u syncthing@myuser.service
journalctl -e --user-unit=syncthing.service
Debugging
^^^^^^^^^
If you are asked on the bugtracker to start syncthing with specific
environment variables it will not work the easy way. Systemd isolates
each service and it cannot access global environment variables. The
solution is to add this variables to the service file instead. Just use:
::
systemctl edit syncthing@myuser.service
systemctl --user edit syncthing.service
This will create an additional configuration file automatically and you
can define (or overwrite) further service parameters like e.g.
``Environment=STTRACE=model``.
.. |Configuration Screenshot| image:: st1.png
.. |Setup Screenshot| image:: st2.png
users/config.rst
+198
View File
@@ -0,0 +1,198 @@
###################
Configuration Files
###################
.. warning::
This page may be outdated and requires review.
Attributes have been added that are not documented.
Syncthing uses a single directory to store configuration, crypto keys
and index caches. The location defaults to ``~/.config/syncthing``
(Unixes), ``%AppData%/Syncthing`` (Windows XP),
``%localappdata%/Syncthing`` (Windows 7/8) or
``~/Library/Application Support/Syncthing`` (Mac) but is also settable
at runtime using the ``-home`` flag. In this directory you'll generally
see something like the following files:
- ``cert.pem``: The device's RSA public key, named "cert" for legacy
reasons.
- ``key.pem``: The device's RSA private key. This needs to be
protected.
- ``config.xml``: The configuration file, in XML format.
- ``https-cert.pem`` and ``https-key.pem``: The certificate and key for
HTTPS GUI connections.
- ``index/``: A directory holding the database with metadata and hashes
of the files currently on disk and available from peers.
- ``csrftokens.txt``: A list of recently issued CSRF tokens (for
protection against browser cross site request forgery).
Config File Format
==================
The following is an example default configuration file:
.. code:: xml
<configuration version="2">
<folder id="default" directory="/Users/jb/Sync" ro="false" ignorePerms="false">
<device id="GXN5ECCWTA2B7EB5FXYL5OWGOADX5EF5VNJAQSIBAY6XHJ24BNOA"></device>
</folder>
<device id="GXN5ECCWTA2B7EB5FXYL5OWGOADX5EF5VNJAQSIBAY6XHJ24BNOA" name="jborg-mbp">
<address>dynamic</address>
</device>
<gui enabled="true" tls="true">
<address>127.0.0.1:54096</address>
<user>jb</user>
<password>$2a$10$EKaTIcpz2...</password>
<apikey>O80CDOJ9LVUVCMHFK2OJDO4T882735</apikey>
</gui>
<options>
<listenAddress>:54097</listenAddress>
<globalAnnounceServer>announce.syncthing.net:22025</globalAnnounceServer>
<globalAnnounceEnabled>true</globalAnnounceEnabled>
<localAnnounceEnabled>true</localAnnounceEnabled>
<parallelRequests>16</parallelRequests>
<maxSendKbps>0</maxSendKbps>
<rescanIntervalS>60</rescanIntervalS>
<reconnectionIntervalS>60</reconnectionIntervalS>
<maxChangeKbps>10000</maxChangeKbps>
<startBrowser>true</startBrowser>
<upnpEnabled>true</upnpEnabled>
<urAccepted>0</urAccepted>
</options>
</configuration>
The following sections should be present in a well formed config file.
configuration
-------------
The root element.
Attributes
~~~~~~~~~~
- ``version``: The config version. ``2`` is current.
folder
------
One or more ``folder`` elements must be present in the file. Each
element describes one folder.
Within the ``folder`` element one or more ``device`` element should be
present. These must contain the ``id`` attribute and nothing else.
Mentioned devices are those that will be sharing the folder in question.
Each mentioned device must have a separate ``device`` element later in
the file. It is customary that the local device ID is included in all
repositories. Syncthing will currently add this automatically if it is
not present in the configuration file.
Attributes
~~~~~~~~~~
- ``id``: The folder ID, must be unique. (mandatory)
- ``directory``: The directory where the folder is stored on this
device; not sent to other devices. (mandatory)
- ``ro``: True if the folder is read only (will not be modified by
syncthing) on this device. (optional, defaults to ``false``)
- ``ignorePerms``: True if the folder should `ignore
permissions <http://forum.syncthing.net/t/v0-8-10-ignore-permissions/263>`__.
Children
~~~~~~~~
- One or mode ``device`` elements.
device
------
One or more ``device`` elements must be present in the file. Each
element describes a device participating in the cluster. It is customary
to include a ``device`` element for the local device; syncthing will
currently add one if it is not present.
Attributes
~~~~~~~~~~
- ``id``: The device ID. This must be written in canonical form, that
is without any spaces or dashes. (mandatory)
- ``name``: A friendly name for the device. (optional)
Children
~~~~~~~~
- One or mode ``address`` elements.
address
-------
The address section is only valid inside of ``device`` elements. It
contains a single address, on one of the following forms:
- IPv4 addresses, IPv6 addresses within brackets, or DNS names, all
optionally followed by a port number.
- ``dynamic``: The address will be resolved using discovery.
gui
---
There must be exactly one ``gui`` element.
Attributes
~~~~~~~~~~
- ``enabled``: ``true``/``false``
- ``tls``: ``true``/``false`` - if true then the GUI will use HTTPS
Children
~~~~~~~~
- ``address``: One or more address elements must be present, containing
an ``ip:port`` listen address.
- ``username`` and ``password``: Set to require authentication.
``password`` contains the bcrypt hash of the real password.
- ``apikey``: If set, this is the API key that enables usage of the REST interface.
options
-------
There must be exactly one ``options`` element. It contains the following
configuration settings as children;
- ``listenAddress`` : ``host:port`` or ``:port`` string denoting an
address to listen for BEP (sync protocol) connections. More than one
``listenAddress`` may be given. (default ``0.0.0.0:22000``)
- ``globalAnnounceServer`` : ``host:port`` where a global announce
server may be reached. (default \`announce.syncthing.net:22025´)
- ``globalAnnounceEnabled``: ``true``/``false`` (default ``true``)
- ``localAnnounceEnabled``: ``true``/``false`` (default ``true``)
- ``parallelRequests``: The maximum number of outstanding block
requests to have against any given peer. (default ``16``)
- ``maxSendKbps``: Rate limit
- ``rescanIntervalS``: The number of seconds to wait between each scan
for modification of the local repositories. (default ``60``) A value
of 0 disables the scanner.
- ``reconnectionIntervalS``: The number of seconds to wait between each
attempt to connect to currently unconnected devices. (default ``60``)
- ``maxChangeKbps``: The maximum rate of change allowed for a single
file. When this rate is exceeded, further changes to the file are not
announced, until the rate is reduced below the limit. (default
``10000``)
- ``startBrowser``: ``true``/``false`` (default ``true``)
- ``upnpEnabled``: ``true``/``false`` (default ``true``)
- ``urAccepted``: Whether the user as accepted to submit anonymous
usage data. The default, ``0``, mean the user has not made a choice,
and syncthing will ask at some point in the future. ``-1`` means no,
``1`` means yes.
users/contrib.rst
+152
View File
@@ -0,0 +1,152 @@
Community Contributions
=======================
This page lists integrations, addons and packagings of syncthing created
by the community. Like all documentation pages, it's wiki editable so
feel free to edit and add your own.
GUI Wrappers
------------
.. _contrib-all:
Cross-platform
~~~~~~~~~~~~~~
- https://github.com/syncthing/syncthing-gtk
- https://github.com/alex2108/syncthing-tray (Tray icon only)
Android
~~~~~~~
- https://github.com/syncthing/syncthing-android
Ubuntu
~~~~~~
- https://github.com/icaruseffect/syncthing-ubuntu-indicator
.. _contrib-windows:
Windows
~~~~~~~
- https://github.com/iss0/SyncthingTray
- https://github.com/bloones/SyncThingWin (Windows service helper and
tray icon)
- https://github.com/canton7/SyncTrayzor (Windows host for Syncthing.
Installer, auto-start, built-in browser, tray icon, folder watcher,
and more)
- https://github.com/kreischweide/metrothing (Windows UI to monitor
multiple Synchthing instances through the REST API)
OS X
~~~~
- https://github.com/m0ppers/syncthing-bar
Kindle Touch
~~~~~~~~~~~~
- https://github.com/gutenye/syncthing-kindle
Packages and Bundlings
----------------------
ArchLinux
~~~~~~~~~
- https://www.archlinux.org/packages/?name=syncthing
- https://www.archlinux.org/packages/?name=syncthing-gtk
- https://aur.archlinux.org/packages/syncthing-inotify
- https://aur.archlinux.org/packages/syncthing-discosrv
arkOS
~~~~~
Syncthing is included in arkOS, https://arkos.io/.
Debian / Ubuntu
~~~~~~~~~~~~~~~
- PPA: https://launchpad.net/~ytvwld/+archive/ubuntu/syncthing
- Syncthing GTK PPA:
https://launchpad.net/~nilarimogard/+archive/ubuntu/webupd8/
- https://forum.syncthing.net/t/lxle-a-respin-of-lubuntu-now-has-syncthing-included-by-default/1392
Docker
~~~~~~
- https://github.com/firecat53/dockerfiles/tree/master/syncthing (runs
Syncthing and/or builds the binary from source)
- https://github.com/firecat53/dockerfiles/tree/master/syncthing\_discovery
(Global announce server in a container)
- https://github.com/joeybaker/docker-syncthing/ A fully baked docker
container that allows custom config and will keep your settings and
data past docker image restarts.
Fedora
~~~~~~
- https://github.com/thunderbirdtr/syncthing\_rpm (SRPM, binary
packages coming)
- https://copr.fedoraproject.org/coprs/tune2fs/syncthing/ (RPMs, based
on https://github.com/thunderbirdtr/syncthing\_rpm)
FreeBSD
~~~~~~~
- http://www.freshports.org/net/syncthing/
OpenSUSE
~~~~~~~~
- http://software.opensuse.org/package/syncthing
Synology NAS
~~~~~~~~~~~~
- http://packages.synocommunity.com/ Add url to Package Center in DSM.
(NOTE: This page is not readable in your web browser. You can browse
the files at https://synocommunity.com/packages). Numerous CPU
architectures are supported. SPK's may be older versions, however you
can execute a Syncthing version upgrade via Web-GUI after
installation on Synology device. As Syncthing is marked as beta by
the SynoCommunity, you need to enable beta-versions in the settings.
QNAP NAS
~~~~~~~~
- http://forum.qnap.com/viewtopic.php?f=320&t=97035&start=45#p429896
QPKG (Qnap Package) Available for ALL models x86, x86\_64, Arm (all
including new models)
Integrations
------------
REST API Bindings
~~~~~~~~~~~~~~~~~
- Ruby: https://github.com/retgoat/syncthing-ruby
- Python: https://github.com/Astalaseven/syncthing-python
Ports
~~~~~
- Swift: https://github.com/dapperstout/pulse-swift
- Java: https://github.com/dapperstout/pulse-java
- PHP: https://github.com/cebe/pulse-php-discover (Only Discovery so
far)
Configuration management
~~~~~~~~~~~~~~~~~~~~~~~~
- Saltstack: https://bitbucket.org/StartledPhoenix/saltstack-syncthing
- Puppet: https://github.com/whefter/puppet-syncthing
- Command line interface: https://github.com/syncthing/syncthing-cli
Other
-----
`Pulse <http://ind.ie/pulse/>`__ is a rebranding / fork of syncthing.
users/exit-codes.rst
+23
View File
@@ -0,0 +1,23 @@
Exit Codes
==========
These are the known exit codes returned by Syncthing:
==== =======
Code Meaning
==== =======
0 Success / Shutdown
1 Error
2 Upgrade not available
3 Restarting
5 Upgrading
==== =======
Some of these exit codes are only returned when running without a
monitor process (with environment variable ``STNORESTART`` 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, ``128 + 9 (SIGKILL) = 137``.
users/faq.rst
+236
View File
@@ -0,0 +1,236 @@
FAQ
===
General
-------
What is Syncthing?
~~~~~~~~~~~~~~~~~~
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.
Is it "syncthing", "Syncthing" or "SyncThing"?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
It's **Syncthing**, although the command and source repository is
spelled ``syncthing`` so it may be referred to in that way as well. It's
definitely not [STRIKEOUT:SyncThing], even though the abbreviation
``st`` is used in some circumstances and file names.
How does Syncthing differ from BitTorrent Sync?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The two are different and not related. Syncthing and BitTorrent Sync
accomplish some of the same things, namely syncing files between two or
more computers.
BitTorrent Sync by BitTorrent, Inc is a proprietary peer-to-peer file
synchronization tool available for Windows, Mac, Linux, Android, iOS,
Windows Phone, Amazon Kindle Fire and BSD.
`1 <http://en.wikipedia.org/wiki/BitTorrent_Sync>`__ Syncthing is an
open source file synchronization tool.
Syncthing uses an open and documented protocol, and likewise the
security mechanisms in use are well defined and visible in the source
code. BitTorrent Sync uses an undocumented, closed protocol with unknown
security properties.
Usage
-----
What things are synced?
~~~~~~~~~~~~~~~~~~~~~~~
The following is *always* synchronized;
- File Contents
- File Modification Times
The following is synchronized or not, depending;
- File Permissions (When supported by file system. On Windows, only the
read only bit is synchronized)
- Symbolic Links (When supported by the OS. On Windows Vista and up,
requires administrator privileges. Links are synced as is and are not
followed.)
The following is *not* synchronized;
- File or Directory Owners and Groups (not preserved)
- Directory Modification Times (not preserved)
- Hard Links (followed, not preserved)
- Extended Attributes, Resource Forks (not preserved)
- Windows, POSIX or NFS ACLs (not preserved)
- Devices, FIFOs, and Other Specials (ignored)
Is synchronization fast?
~~~~~~~~~~~~~~~~~~~~~~~~
Syncthing segments files into pieces, called blocks, to transfer data
from one device to another. Therefore, multiple devices can share the
synchronization load, in a similar way as the torrent protocol. The more
devices you have online (and synchronized), the faster an additional
device will receive the data because small blocks will be fetched from
all devices in parallel.
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.
Should I keep my device IDs secret?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
No. The IDs are not sensitive. Given a device ID it's possible to find
the IP address for that node, if global discovery is enabled on it.
Knowing the device ID doesn't help you actually establish a connection
to that node or get a list of files, etc.
For a connection to be established, both nodes 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!)
See also `Understanding Device
IDs <http://docs.syncthing.net/dev/device-ids.html>`__.
What if there is a conflict?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Syncthing does recognize conflicts. When a file has been modified on two
devices simultaneously, one of the files will be renamed to
``<filename>.sync- conflict-<date>-<time>.<ext>``. The device which has
the larger value of the first 63 bits for his device ID will have his
file marked as the conflicting file. Note that we only create
``sync-conflict`` files when the actual content differs.
Beware that the ``<filename>.sync-conflict-<date>-<time>.<ext>`` 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 ``sync-conflict`` 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.
Moreover, if there's something that automatically causes a conflict on
change you'll end up with
``sync-conflict-...sync-conflict -...-sync-conflict`` files.
How to configure multiple users on a single machine?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Each user should run their own Syncthing instance. Be aware that you
might need to configure ports such that they do not overlap (see the
config.xml).
Is Syncthing my ideal backup application?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
No, Syncthing is not a backup application because all changes to your
files (modification, deletion, 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.
Why is there no iOS client?
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Alternative implementation Syncthing (using the Syncthing protocol) are
being developed at this point in time to enable iOS support.
Additionally, it seems that the next version of Go will support the
darwin-arm architecture such that we can compile the mainstream code for
the iOS platform.
Why does it use so much CPU?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1. When new or changed files are detected, or Syncthing starts for the
first time, your files are hashed using SHA-256.
2. Data that is sent over the network is first compressed and then
encrypted using AES-128. When receiving data, it must be decrypted
and decompressed.
Hashing, compression and encryption cost CPU time. Also, using the GUI
causes a certain amount of CPU usage. Note however that once things are
*in sync* CPU usage should be negligible.
How can I exclude files with brackets (``[]``) in the name?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The patterns in .stignore are glob patterns, where brackets are used to
denote character ranges. That is, the pattern ``q[abc]x`` will match the
files ``qax``, ``qbx`` and ``qcx``.
To match an actual file *called* ``q[abc]x`` the pattern needs to
"escape" the brackets, like so: ``q\[abc\]x``.
Why is the setup more complicated than BTSync?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Security over convenience. In Syncthing you have to setup both sides to
connect two nodes. An attacker can't do much with a stolen node ID,
because you have to add the node on the other side too. You have better
control where your files are transferred.
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 GUI from the same machine. Change the ``GUI listen address`` through
the web UI from ``127.0.0.1:8384`` to ``0.0.0.0:8384`` or change the
config.xml:
.. code:: xml
<gui enabled="true" tls="false">
<address>127.0.0.1:8384</address>
to
.. code:: xml
<gui enabled="true" tls="false">
<address>0.0.0.0:8384</address>
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.
If both your computers are Unixy (Linux, Mac, etc) You can also leave
the GUI settings at default and use an ssh port forward to access it.
For example,
.. code:: bash
$ ssh -L 9090:127.0.0.1:8384 user@othercomputer.example.com
will log you into othercomputer.example.com, and present the *remote*
Syncthing GUI on http://localhost:9090 on your *local* computer. You
should not open more than one Syncthing GUI in a single browser due to
conflicting X-CSRFTokens. Any modification will be rejected. See `Issue
720 <https://github.com/syncthing/syncthing/issues/720#issuecomment-58159631>`__
to work around this limitation.
The CSRF tokens are stored using cookies. Therefore, if you get the
message
``Syncthing seems to be experiencing a problem processing your request``,
you should verify the cookie settings of your browser.
Why do I see Syncthing twice in task manager?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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.
Where do syncthing logs go to?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Syncthing logs to stdout by default. On Windows Syncthing by default
also creates ``syncthing.log`` in Syncthing's home directory (check
``-help`` to see where that is).
users/firewalls.rst
+63
View File
@@ -0,0 +1,63 @@
Firewalls
=========
Port Forwards
-------------
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:
::
Created UPnP port mapping for external port XXXXX on UPnP device YYYYY.
If this is not possible or desirable you should set up a port forward
for port **22000/TCP**, or the port set in the *Sync Protocol Listen
Address* setting. The external forwarded port and the internal
destination port has to be the same (i.e. 22000/TCP).
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.
Local Firewall
--------------
If your PC has a local firewall, you will need to open the following
ports for incoming traffic:
- Port **22000/TCP** (or the actual listening port if you have changed
the *Sync Protocol Listen Address* setting.)
- Port **21025/UDP** (for discovery broadcasts)
Remote Web GUI
--------------
To be able to access the web GUI from other computers, you need to
change the *GUI Listen Address* setting from the default
``127.0.0.1:8384`` to ``0.0.0.0:8384``. You also need to open the port
in your local firewall if you have one.
Tunneling via SSH
~~~~~~~~~~~~~~~~~
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:
::
ssh -L 9999:localhost:8384 machine
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.
You can forward multiple ports corresponding to many machines this way,
but because Syncthing uses session cookies for the entire domain (i.e.
your local machine), you will need to connect to each control panel in a
separate browser instance or explicitly issue a browser reload when
switching between them.
users/foldermaster.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 456 KiB

users/foldermaster.rst
+24
View File
@@ -0,0 +1,24 @@
Folder Master
=============
A folder can be set in "master mode" among the folder settings.
.. figure:: foldermaster.png
The intention is for this to be used on devices where a "master copy" of
files are kept - where the files are not expected to be changed on other
devices or where such changes would be undesirable.
In master mode, all changes from other devices in the cluster are
ignored. Changes are still *received* so the folder may become "out of
sync", but no changes will be applied.
When a master folder becomes out of sync, a red "Override Changes"
button is shown at the bottom of the folder details.
.. figure:: override.png
Clicking this button will make enforce the master's current state on the
rest of the cluster. Any changes made to files will be overwritten by
the version on the master, any files that don't exist on the master will
be deleted, and so on.
users/ignoring.rst
+142
View File
@@ -0,0 +1,142 @@
Ignoring Files
==============
If some files should not be synchronized to other nodes, a file called
``.stignore`` can be created containing file patterns to ignore. The
``.stignore`` file must be placed in the root of the repository. The
``.stignore`` file itself will never be synced to other nodes, although
it can ``#include`` files that *are* synchronized between nodes. All
patterns are relative to the repository root.
Patterns
--------
The ``.stignore`` file contains a list of file or path patterns. The
*first* pattern that matches will decide the fate of a given file.
- Regular file names match themselves, i.e. the pattern ``foo`` matches
the files ``foo``, ``subdir/foo`` as well as any directory named
``foo``. Spaces are treated as regular characters.
- Asterisk matches zero or more characters in a filename, but does not
match the directory separator. ``te*st`` matches ``test``,
``subdir/telerest`` but not ``tele/rest``.
- Double asterisk matches as above, but also directory separators.
``te**st`` matches ``test``, ``subdir/telerest`` and
``tele/sub/dir/rest``.
- Question mark matches a single character that is not the directory
separator. ``te??st`` matches ``tebest`` but not ``teb/st`` or
``test``.
- A pattern beginning with ``/`` matches in the current directory only.
``/foo`` matches ``foo`` but not ``subdir/foo``.
- A pattern beginning with ``#include`` 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 repository *root*. Example:
``#include more-patterns.txt``.
- A pattern beginning with ``!`` negates the pattern: matching files
are *included* (that is, *not* ignored). This can be used to override
more general patterns that follow. Note that files in ignored
directories can not be re-included this way. This is due to the fact
that syncthing stops scanning when it reaches an ignored directory,
so doesn't know what files it might contain.
- A pattern beginning with ``(?i)`` enables case-insensitive pattern
matching. ``(?i)test`` matches ``test``, ``TEST`` and ``tEsT``. The
``(?i)`` prefix can be combined with other patterns, for example the
pattern ``(?i)!picture*.png`` indicates that ``Picture1.PNG`` should
be synchronized. Note that case-insensitive patterns must start with
``(?i)`` when combined with other flags.
- A line beginning with ``//`` is a comment and has no effect.
Example
-------
Given a directory layout:
::
foo
foofoo
bar/
baz
quux
quuz
bar2/
baz
frobble
My Pictures/
Img15.PNG
and an ``.stignore`` file with the contents:
.. code:: xml
!frobble
!quuz
foo
*2
qu*
(?i)my pictures
all files and directories called "foo", ending in a "2" or starting with
"qu" will be ignored. The end result becomes
.. code:: xml
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/ # ignored, matched "*2"
baz # ignored, due to parent being ignored
frobble # ignored, due to parent being ignored; "!frobble" doesn't help
My Pictures/ # ignored, matched case insensitive "(?i)my pictures" pattern
Img15.PNG # ignored, due to parent being ignored
.. raw:: html
<p class="message warning">
Please note that directory patterns ending with a slash
``some/directory/`` matches the content of the directory, but not the
directory itself. If you want the pattern to match the director and it's
content, make sure it does not have a ``/`` at the end of the pattern.
.. raw:: html
</p>
Effects on "In Sync" Status
---------------------------
Currently the effects on who is in sync with what can be a bit confusing
when using ignore patterns. This should be cleared up in a future
version...
Assume two nodes, Alice and Bob, where Alice has 100 files to share, but
Bob ignores 25 of these. From Alice's point of view Bob will become
about 75% in sync (the actual number depends on the sizes of the
individual files) and remain in "Syncing" state even though it is in
fact not syncing anything (issue
`#623 <https://github.com/syncthing/syncthing/issues/623>`__). From
Bob's point of view it's 100% up to date but will show fewer files in
both the local and global view.
If Bob adds files that have already been synced to the ignore list, they
will remain in the "global" view but disappear from the "local" view.
The end result is more files in the global repository than in the local,
but still 100% in sync (issue
`#624 <https://github.com/syncthing/syncthing/issues/624>`__). From
Alice's point of view, Bob will remain 100% in sync until the next
reconnect, because Bob has already announce that he has the files that
are now suddenly ignored.
users/override.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 106 KiB

users/security.rst
+126
View File
@@ -0,0 +1,126 @@
###################
Security Principles
###################
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.
All traffic is protected by TLS. To prevent uninvited nodes from joining
a cluster, the certificate fingerprint of each node is compared to a
preset list of acceptable nodes at connection establishment. The
fingerprint is computed as the SHA-256 hash of the certificate and
displayed in BASE32 encoding to form a reasonably compact and convenient
string.
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.
For information about ensuring you are running the code you think you
are and for reporting security vulnerabilities, please see the official
`security page <http://syncthing.net/security.html>`__.
Information Leakage
===================
Global Discovery
----------------
When global discovery is enabled, syncthing sends an announcement packet
every 30 minutes to the global discovery server, so that it can keep a
mapping between your device ID and external IP. Also, when connecting to
other devices that have not been seen on the local network, a query is
sent to the global discovery server containing the device ID of the
requested device. The discovery server is currently **hosted by
@calmh**. Global discovery defaults to **on**.
When turned off, devices with dynamic addresses not on the local network
cannot be found and connected to.
If a different global discovery server is configured, no data is sent to
the default global discovery server.
Local Discovery
---------------
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 **on**.
An eavesdropper on the local network can deduce which machines are
running syncthing with local discovery enabled, and what their device
IDs are.
When turned off, devices with dynamic addresses on the local network
cannot be found and connected to.
Upgrade Checks
--------------
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 at GitHub**.
Automatic upgrades default to **on** (unless syncthing was compiled with
upgrades disabled).
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.
In effect this exposes the majority of the syncthing population to
tracking by the operator of the download site (currently GitHub). That
data is not available to outside parties (including @calmh etc), except
that download counts per release binary are available in the GitHub API.
The upgrade check (or download) requests *do not* contain any
identifiable information about the user, device, syncthing version, etc.
Usage Reporting
---------------
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 @calmh**. The contents of
the usage report can be seen behind the "Preview" link in settings.
Usage reporting defaults to **off** but the GUI will ask once about
enabling it, shortly after the first install.
The reported data is protected from eavesdroppers, but the connection to
the usage reporting server itself may expose the client as running
syncthing.
Sync Connections (BEP)
----------------------
Sync connections are attempted to all configured devices, when the
address is possible to resolve. The sync connection is based on TLS 1.2.
The TLS certificates are sent in clear text (as in HTTPS etc), meaning
that the certificate Common Name (by default ``syncthing``) is visible.
An eavesdropper can deduce that this is a syncthing connection and
calculate the device ID:s involved based on the hashes of the sent
certificates.
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.
Web GUI
-------
If the web GUI is accessible, it exposes the device as running
syncthing. The web GUI defaults to being reachable from the **local host
only**.
In Short
========
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 ID's `are OK to share
anyway <http://docs.syncthing.net/users/faq.html#should-i-keep-my-device-ids-secret>`__,
but the actual transmitted data is protected as well as we can. Knowing
your device ID can expose your IP address, using global discovery.
users/st1.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 2.9 KiB

users/st2.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 71 KiB

users/versioning.rst
+68
View File
@@ -0,0 +1,68 @@
File Versioning
===============
.. warning::
This page may be out of date and requires review.
External versioning requires documenting.
There are 3 types of File Versioning. When you select each in the web
interface, a short description of each is shown to help you decide.
No File Versioning
------------------
This is the default setting. With no file versioning, files that are
replaced or deleted on one device are deleted on other devices that the
directory is shared with. (Note: If a folder is marked "Master Folder"
on a device, that device will not accept changes to the files in the
folder, and therefore will not have files replaced or deleted.)
Simple File Versioning
----------------------
With "Simple File Versioning" files are moved to the ".stversions"
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.
Staggered File Versioning
-------------------------
With "Staggered File Versioning" files are also moved to the
".stversions" folder (inside your shared folder) when replaced or
deleted on a remote device (just like "Simple File Versioning"),
however, Version are automatically deleted if they are older then the
maximum age or exceed the number of files allowed in an interval.
The following intervals are used and they each have a maximum number of
files that will be kept for each.
- 1 Hour - For the first hour, the most recent version is kept every 30
seconds.
- 1 Day - For the first day, the most recent version is kept every
hour.
- 30 Days - For the first 30 days, the most recent version is kept
every day.
- Until Maximum Age - Until the maximum age, the most recent version is
kept every week.
Maxiumum Age
~~~~~~~~~~~~
The "Maximum Age" input is 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. **Note:
Set to 0 to keep versions forever.**
Versions Path
~~~~~~~~~~~~~
With "Staggered File Versioning" method (only), if you would like to
specify where removed and deleted files are stored as part of the
Versioning feature, you can specify the path in the "Versions Path"
input after this method is selected. [*More detail needed here: Can this
be a relative path, or must it be an absolute path?*\ ]