From 0d06e47acf7e63c7790b7e25bcb017ab7165a3a9 Mon Sep 17 00:00:00 2001 From: Stefan Tatschner Date: Fri, 29 May 2015 12:36:34 +0200 Subject: [PATCH] Create syncthing-config(5) Convert users/config.rst to a properly formatted manpage --- users/config.rst | 239 +++++++++++++++++++++++------------------------ 1 file changed, 116 insertions(+), 123 deletions(-) diff --git a/users/config.rst b/users/config.rst index 4a1433612..333a3c02e 100644 --- a/users/config.rst +++ b/users/config.rst @@ -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: -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 `__. - -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 `_. 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.