mirror/syncthing
1
0
Fork 0
mirror of https://github.com/syncthing/syncthing.git synced 2026-04-09 17:08:05 -04:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #7 from rumpelsepp/man

Browse Source 
Create and enable manpages
This commit is contained in:
Jakob Borg
2015-05-29 17:04:26 +02:00
parent 5b37d1b497 ef76180205
commit 31a396bc86
10 changed files with 521 additions and 507 deletions
Download Patch File Download Diff File Expand all files Collapse all files

31
conf.py
View File

@@ -239,12 +239,37 @@ latex_documents = [
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
('index', 'syncthing', u'Syncthing Documentation',
[u'The Syncthing Authors'], 1)
('users/config', 'syncthing-config',
'Syncthing Configuration',
['The Syncthing Authors'], 5),
('users/ignoring', 'syncthing-stignore',
'Prevent files from being synchronized to other nodes',
['The Syncthing Authors'], 5),
('dev/rest', 'syncthing-rest-api',
'REST API',
['The Syncthing Authors'], 7),
('dev/events', 'syncthing-event-api',
'Event API',
['The Syncthing Authors'], 7),
('dev/device-ids', 'syncthing-device-ids',
'Understanding Device IDs',
['The Syncthing Authors'], 7),
('users/security', 'syncthing-security',
'Security Principles',
['The Syncthing Authors'], 7),
('users/firewall', 'syncthing-networking',
'Firewall Setup',
['The Syncthing Authors'], 7),
('users/versioning', 'syncthing-versioning',
'Keep automatic backups of deleted files by other nodes',
['The Syncthing Authors'], 7),
('users/faq', 'syncthing-faq',
'Frequently Asked Questions',
['The Syncthing Authors'], 7),
]
# If true, show URL addresses after external links.
#man_show_urls = False
man_show_urls = True
# -- Options for Texinfo output -------------------------------------------

118
dev/device-ids.rst
View File

@@ -1,28 +1,28 @@
########################
Understanding Device IDs
########################
========================
Every device is identified by a device ID. The device ID is used for
address resolution, authentication and authorization. The term "device
ID" could interchangably have been "key ID" since the device ID is a
direct properties of the public key in use.
Description
-----------
Every device is identified by a device ID. The device ID is used for address
resolution, authentication and authorization. The term "device ID" could
interchangably have been "key ID" since the device ID is a direct properties of
the public key in use.
Keys
====
----
To understand device IDs we need to look at the underlying mechanisms.
At first startup, Syncthing will create an public/private key pair.
To understand device IDs we need to look at the underlying mechanisms. At first
startup, Syncthing will create an public/private key pair.
Currently this is a 3072 bit RSA key. The keys are saved in the form of
the private key (``key.pem``) and a self signed certificate
(``cert.pem``). 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.
Currently this is a 3072 bit RSA key. The keys are saved in the form of the
private key (``key.pem``) and a self signed certificate (``cert.pem``). 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.
The typical certificate will look something like this, inspected with
``openssl x509``:
::
``openssl x509``::
Certificate:
Data:
@@ -58,28 +58,26 @@ The typical certificate will look something like this, inspected with
88:7e:e2:61:aa:4c:02:e3:64:b0:da:70:3a:cd:1c:3d:86:db:
df:54:b9:4e:be:1b
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.
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.
An advanced user could replace the ``key.pem`` and ``cert.pem`` files
with a keypair generated directly by the ``openssl`` utility or other
mechanism.
An advanced user could replace the ``key.pem`` and ``cert.pem`` files with a
keypair generated directly by the ``openssl`` utility or other mechanism.
Device IDs
==========
----------
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
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
``Certificate:`` section above.
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 an 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
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 an 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
``MFZWI3DBONSGYYLTMRWGC43ENRQXGZDMMFZWI3DBONSGYYLTMRWA====``.
The padding (``====``) is stripped away, the device ID split in four
@@ -90,13 +88,12 @@ grouped with dashes, resulting in the final value:
``MFZWI3D-BONSGYC-YLTMRWG-C43ENR5 -QXGZDMM-FZWI3DP-BONSGYY-LTMRWAD``.
Connection Establishment
========================
~~~~~~~~~~~~~~~~~~~~~~~~
So now we know what device IDs are, here's how they are used in
Syncthing. When you add a device ID to the syncthing 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's three
possibilities here;
So now we know what device IDs are, here's how they are used in Syncthing. When
you add a device ID to the syncthing 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's three possibilities here;
- The IP and port can be set statically in the configuration. The IP
can equally well be a hostname, so if you have a static IP or a
@@ -114,10 +111,10 @@ possibilities here;
any local announcements the global discovery server will be queried
for an address.
Once we have and 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.
Once we have and 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.
#. Calculate the remote device ID by using the process above on the
received certificate.
@@ -169,27 +166,26 @@ here:
more probable than the SHA-256 collision. Briefly stated, if you
find SHA-256 collisions scary then your priorities are wrong.
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.
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.
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.
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.
Problems and Vulnerabilities
============================
----------------------------
As far as I know, these are the issues or potential issues with the
above mechanism.
Discovery Spoofing
------------------
~~~~~~~~~~~~~~~~~~
Currently, neither the local nor global discovery mechanism is protected
by crypto. This means that any device can in theory announce itself for
@@ -217,13 +213,13 @@ It's something we might want to look at at some point, but not a huge
problem as I see it.
Long Device IDs are Painful
---------------------------
~~~~~~~~~~~~~~~~~~~~~~~~~~~
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.
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.
This isn't a vulnerability as such, but a user experience problem. There
are various possible solutions;
This isn't a vulnerability as such, but a user experience problem. There are
various possible solutions:
- Use shorter device IDs with verification based on the full ID ("You
entered MFZWI3; I found and connected to a device with the ID

49
dev/events.rst
View File

@@ -1,8 +1,11 @@
Event API
=========
Syncthing provides a simple long polling interface for exposing events from
the core utility towards a GUI.
Description
-----------
Syncthing provides a simple long polling interface for exposing events from the
core utility towards a GUI.
To receive events, perform a HTTP GET of ``/rest/events?since=<lastSeenID>``,
where ``<lastSeenID>`` is the ID of the last event you've already seen or zero.
@@ -26,28 +29,36 @@ Event Structure
Each event is represented by an object similar to the following::
{
"id": 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"
}
}
{
"id": 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"
}
}
The top level keys ``id``, ``time``, ``type`` and ``data`` are always present, though ``data`` may be ``null``.
The top level keys ``id``, ``time``, ``type`` and ``data`` are always present,
though ``data`` may be ``null``.
* ``id`` is a monotonically increasing integer. The first event generated has id ``1``, the next has id ``2`` etc.
* ``time`` is the time the event was generated.
* ``type`` indicates the type of (i.e. reason for) the event and is one of the event types below.
* ``data`` is an object containing optional extra information; the exact structure is determined by the event type.
id
A monotonically increasing integer. The first event generated has id ``1``,
the next has id ``2`` etc.
time
The time the event was generated.
type
Indicates the type of (i.e. reason for) the event and is one of the event
types below.
data
An object containing optional extra information; the exact structure is
determined by the event type.
Events
------
.. toctree::
:maxdepth: 2
:glob:
:maxdepth: 2
:glob:
../events/*
../events/*

20
dev/rest.rst
View File

@@ -1,19 +1,21 @@
REST API
========
Syncthing exposes a REST interface over HTTP on the GUI port. This is
used by the GUI code (JavaScript) and can be used by other processes
wishing to control Syncthing. In most cases both the input and output
data is in JSON format. The interface is subject to change.
Description
-----------
Syncthing exposes a REST interface over HTTP on the GUI port. This is used by
the GUI code (JavaScript) and can be used by other processes wishing to control
Syncthing. In most cases both the input and output data is in JSON format. The
interface is subject to change.
API Key
-------
To use the POST methods, or *any* method when authentication is enabled,
an API key must be set and used. The API key can be generated in the
GUI, or set in the ``configuration/gui/apikey`` element in the
configuration file. To use an API key, set the request header
``X-API-Key`` to the API key value.
To use the POST methods, or *any* method when authentication is enabled, an API
key must be set and used. The API key can be generated in the GUI, or set in the
``configuration/gui/apikey`` element in the configuration file. To use an API
key, set the request header ``X-API-Key`` to the API key value.
System Endpoints
----------------

239
users/config.rst
View File

@@ -1,35 +1,51 @@
###################
Configuration Files
###################
Syncthing Configuration
=======================
.. 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:
Synopsis
--------
- ``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).
::
$HOME/.config/syncthing/config.xml
$HOME/Library/Application Support/Syncthing
%AppData%/Syncthing
%localappdata%/Syncthing
Description
-----------
Syncthing uses a single directory to store configuration, crypto keys
and index caches. The location defaults to ``$HOME/.config/syncthing``
(Unix-like), ``$HOME/Library/Application Support/Syncthing`` (Mac),
``%AppData%/Syncthing`` (Windows XP) or ``%localappdata%/Syncthing``
(Windows 7/8). It can be changed at runtime using the ``-home`` flag. In this
directory the following files are located:
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
The certificate for HTTPS GUI connections.
https-key.pem
The 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:
The following is shows the default configuration file:
.. code-block:: xml
@@ -62,20 +78,16 @@ The following is an example default configuration file:
</options>
</configuration>
The following sections should be present in a well formed config file.
configuration
-------------
~~~~~~~~~~~~~
The root element.
This is the root element.
Attributes
~~~~~~~~~~
- ``version``: The config version. ``2`` is current.
version
The config version. The current version is ``2``.
folder
------
~~~~~~
One or more ``folder`` elements must be present in the file. Each
element describes one folder.
@@ -88,111 +100,92 @@ 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.
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/263>`_.
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.
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)
address
-------
The address section is only valid inside of ``device`` elements. It contains
a single address, on one of the following forms:
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.
- 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.
There must be *exactly one* ``gui`` element.
Attributes
~~~~~~~~~~
enabled
``true``/``false``
tls
``true``/``false``: If true then the GUI will use HTTPS.
- ``enabled``: ``true``/``false``
- ``tls``: ``true``/``false`` - if true then the GUI will use HTTPS
address
One or more address elements must be present, containing an ``ip:port``
listen address.
username
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.
Children
~~~~~~~~
Additionally, there must be *exactly one* ``options`` element. It contains the
following configuration settings as 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.
listenAddress
``host:port`` or ``:port`` string denoting an address to listen for BEP
connections. More than one ``listenAddress`` may be given.
(default: ``0.0.0.0:22000``)
globalAnnounceServer
``host:port`` string denoting 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. A value of ``0`` disables the scanner. (default: ``60``)
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.

224
users/faq.rst
View File

@@ -9,39 +9,36 @@ 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.
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 :strike:`SyncThing`, even though the abbreviation
``st`` is used in some circumstances and file names.
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
:strike:`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.
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.
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.
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
-----
@@ -49,12 +46,12 @@ Usage
What things are synced?
~~~~~~~~~~~~~~~~~~~~~~~
The following things are *always* synchronized;
The following things are *always* synchronized:
- File Contents
- 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
read only bit is synchronized.)
@@ -75,17 +72,16 @@ The following is *not* synchronized;
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 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.
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.
Temporary files are used to store partial data downloaded from other devices.
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?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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.
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!)
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>`__.
.. see-also::
:ref:`dev/device-ids`
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.
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.
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).
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.
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.
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?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -163,35 +156,34 @@ Why does it use so much CPU?
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.
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``.
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``.
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.
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:
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-block:: xml
@@ -208,58 +200,60 @@ to
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,
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-block:: 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.
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.
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.
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).
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).
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``.
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?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
We release new versions through GitHub. The latest release is always found `on
the release page <https://github.com/syncthing/syncthing/releases/latest>`_.
Unfortunately GitHub does not provide a single URL to automatically download
the latest version. We suggest to use the GitHub API at
https://api.github.com/repos/syncthing/syncthing/releases/latest and parsing
the JSON response.
Unfortunately GitHub does not provide a single URL to automatically download the
latest version. We suggest to use the GitHub API at
https://api.github.com/repos/syncthing/syncthing/releases/latest and parsing the
JSON response.

58
users/firewall.rst
View File

@@ -6,29 +6,27 @@ Firewall Setup
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:
::
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).
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.
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:
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.)
@@ -37,29 +35,25 @@ ports for incoming traffic:
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.
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:
::
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.
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.
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.

28
users/ignoring.rst
View File

@@ -1,12 +1,22 @@
Ignoring Files
==============
Synopsis
--------
::
.stignore
Description
-----------
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.
``.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
--------
@@ -59,9 +69,7 @@ The ``.stignore`` file contains a list of file or path patterns. The
Example
-------
Given a directory layout:
::
Given a directory layout::
foo
foofoo
@@ -75,9 +83,7 @@ Given a directory layout:
My Pictures/
Img15.PNG
and an ``.stignore`` file with the contents:
::
and an ``.stignore`` file with the contents::
!frobble
!quuz
@@ -87,9 +93,7 @@ and an ``.stignore`` file with the contents:
(?i)my pictures
all files and directories called "foo", ending in a "2" or starting with
"qu" will be ignored. The end result becomes
::
"qu" will be ignored. The end result becomes::
foo # ignored, matches "foo"
foofoo # synced, does not match "foo" but would match "foo*" or "*foo"

178
users/security.rst
View File

@@ -1,126 +1,116 @@
###################
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
===================
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 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.
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.
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**.
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.
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.
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).
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.
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.
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.
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.
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.
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.
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.
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**.
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.
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.

83
users/versioning.rst
View File

@@ -2,20 +2,33 @@ File Versioning
===============
.. warning::
This page may be out of date and requires review.
External versioning requires documenting.
This page may be out of date and requires review.
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.
.. todo::
External versioning requires documenting.
Description
-----------
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.
.. todo::
More detail needed here: Can this be a relative path, or must it be
an absolute path?
With "Staggered File Versioning" method (only), 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.
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.)
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
----------------------
@@ -28,41 +41,33 @@ 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.
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 than the maximum age or exceed the number of files
allowed in an interval.
(just like "Simple File Versioning"), however, Version are automatically deleted
if they are older than 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.
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.
Maximum 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?*\ ]
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
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 or 10 days, use 10. **Note: Set to 0 to keep versions forever.**