Stefan Tatschner
e5242d68b4
Sphinx uses .. code-block:: directives to enable highlighting:
http://sphinx-doc.org/markup/code.html#directive-code-block
Use
for i in *.rst; do
sed -i 's/code::/code-block::/g' $i
done
to update these strings to enable proper highlighting.
Note: A have disabled the windows "bash" one, because the highlighting
is broken anyway...
199 lines
6.8 KiB
ReStructuredText
199 lines
6.8 KiB
ReStructuredText
###################
|
||
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-block:: 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.
|