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

Create syncthing-config(5)

Browse Source 
Convert users/config.rst to a properly formatted manpage
This commit is contained in:
Stefan Tatschner
2015-05-29 16:39:22 +02:00
parent 2e407d3cf7
commit 0d06e47acf
1 changed files with 116 additions and 123 deletions
Download Patch File Download Diff File Expand all files Collapse all files
users/config.rst
+116 -123
View File
@@ -1,35 +1,51 @@
################### Syncthing Configuration
Configuration Files =======================
###################
.. warning:: .. warning::
This page may be outdated and requires review. This page may be outdated and requires review.
Attributes have been added that are not documented. Attributes have been added that are not documented.
Syncthing uses a single directory to store configuration, crypto keys Synopsis
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 $HOME/.config/syncthing/config.xml
protected. $HOME/Library/Application Support/Syncthing
- ``config.xml``: The configuration file, in XML format. %AppData%/Syncthing
- ``https-cert.pem`` and ``https-key.pem``: The certificate and key for %localappdata%/Syncthing
HTTPS GUI connections.
- ``index/``: A directory holding the database with metadata and hashes Description
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). 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 Config File Format
================== ------------------
The following is an example default configuration file: The following is shows the default configuration file:
.. code-block:: xml .. code-block:: xml
@@ -62,20 +78,16 @@ The following is an example default configuration file:
</options> </options>
</configuration> </configuration>
The following sections should be present in a well formed config file.
configuration configuration
------------- ~~~~~~~~~~~~~
The root element. This is the root element.
Attributes version
~~~~~~~~~~ The config version. The current version is ``2``.
- ``version``: The config version. ``2`` is current.
folder folder
------ ~~~~~~
One or more ``folder`` elements must be present in the file. Each One or more ``folder`` elements must be present in the file. Each
element describes one folder. 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 repositories. Syncthing will currently add this automatically if it is
not present in the configuration file. not present in the configuration file.
Attributes id
~~~~~~~~~~ The folder ID, must be unique. (mandatory)
directory
- ``id``: The folder ID, must be unique. (mandatory) The directory where the folder is stored on this
- ``directory``: The directory where the folder is stored on this device; not sent to other devices. (mandatory)
device; not sent to other devices. (mandatory) ro
- ``ro``: True if the folder is read only (will not be modified by True if the folder is read only (will not be modified by Syncthing) on this
Syncthing) on this device. (optional, defaults to ``false``) device. (optional, defaults to ``false``)
- ``ignorePerms``: True if the folder should `ignore ignorePerms
permissions <http://forum.syncthing.net/t/v0-8-10-ignore-permissions/263>`__. True if the folder should `ignore permissions <http://forum.syncthing.net/t/263>`_.
Children
~~~~~~~~
- One or mode ``device`` elements.
device device
------ ~~~~~~
One or more ``device`` elements must be present in the file. Each One or more ``device`` elements must be present in the file. Each
element describes a device participating in the cluster. It is customary element describes a device participating in the cluster. It is customary
to include a ``device`` element for the local device; Syncthing will to include a ``device`` element for the local device; Syncthing will
currently add one if it is not present. 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)
- ``id``: The device ID. This must be written in canonical form, that name
is without any spaces or dashes. (mandatory) A friendly name for the device. (optional)
- ``name``: A friendly name for the device. (optional)
Children
~~~~~~~~
- One or mode ``address`` elements.
address 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 - IPv4 addresses, IPv6 addresses within brackets, or DNS names, all
contains a single address, on one of the following forms: 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 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`` address
- ``tls``: ``true``/``false`` - if true then the GUI will use HTTPS 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 listenAddress
an ``ip:port`` listen address. ``host:port`` or ``:port`` string denoting an address to listen for BEP
- ``username`` and ``password``: Set to require authentication. connections. More than one ``listenAddress`` may be given.
``password`` contains the bcrypt hash of the real password. (default: ``0.0.0.0:22000``)
- ``apikey``: If set, this is the API key that enables usage of the REST interface. globalAnnounceServer
``host:port`` string denoting where a global announce server may be
options reached. (default: ``announce.syncthing.net:22025``)
------- globalAnnounceEnabled
``true``/``false`` (default: ``true``)
There must be exactly one ``options`` element. It contains the following localAnnounceEnabled
configuration settings as children; ``true``/``false`` (default: ``true``)
parallelRequests
- ``listenAddress`` : ``host:port`` or ``:port`` string denoting an The maximum number of outstanding block requests to have against any given
address to listen for BEP (sync protocol) connections. More than one peer. (default: ``16``)
``listenAddress`` may be given. (default ``0.0.0.0:22000``) maxSendKbps
Rate limit
- ``globalAnnounceServer`` : ``host:port`` where a global announce rescanIntervalS
server may be reached. (default \`announce.syncthing.net:22025´) The number of seconds to wait between each scan for modification of the
local repositories. A value of ``0`` disables the scanner. (default: ``60``)
- ``globalAnnounceEnabled``: ``true``/``false`` (default ``true``) reconnectionIntervalS
The number of seconds to wait between each attempt to connect to currently
- ``localAnnounceEnabled``: ``true``/``false`` (default ``true``) unconnected devices. (default: ``60``)
maxChangeKbps
- ``parallelRequests``: The maximum number of outstanding block The maximum rate of change allowed for a single file. When this rate is
requests to have against any given peer. (default ``16``) exceeded, further changes to the file are not announced, until the rate is
reduced below the limit. (default: ``10000``)
- ``maxSendKbps``: Rate limit startBrowser
``true``/``false`` (default: ``true``)
- ``rescanIntervalS``: The number of seconds to wait between each scan upnpEnabled
for modification of the local repositories. (default ``60``) A value ``true``/``false`` (default: ``true``)
of 0 disables the scanner. urAccepted
Whether the user as accepted to submit anonymous usage data. The default,
- ``reconnectionIntervalS``: The number of seconds to wait between each ``0``, mean the user has not made a choice, and Syncthing will ask at some
attempt to connect to currently unconnected devices. (default ``60``) point in the future. ``-1`` means no, ``1`` means yes.
- ``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.