Skip to content

Commit

Permalink
chore(config): clarify repeated XML tags vs. comma-separated in GUI (#…
Browse files Browse the repository at this point in the history
…890)

Add similar text to all repeatable configuration options, mentioning
the difference between comma-separated lists in the GUI vs. repeating
the tag (without plural "s") in the XML file.  Loosely based on the
existing sentence for <listenAddress>.
  • Loading branch information
acolomb authored Jan 7, 2025
1 parent acbc51c commit f3165de
Showing 1 changed file with 32 additions and 9 deletions.
41 changes: 32 additions & 9 deletions users/config.rst
Original file line number Diff line number Diff line change
Expand Up @@ -757,6 +757,8 @@ From the following child elements at least one ``address`` child must exist.
<address>dynamic</address>
</device>
In the GUI, multiple values are separated by commas.

.. option:: device.paused

True if synchronization with this devices is (temporarily) suspended.
Expand All @@ -766,7 +768,9 @@ From the following child elements at least one ``address`` child must exist.

If given, this restricts connections to this device to only this network.
The mechanism is described in detail in a :doc:`separate chapter
</advanced/device-allowednetworks>`).
</advanced/device-allowednetworks>`). To configure multiple networks, you
can either: repeat ``<allowedNetwork>`` tags in the configuration file or
enter several networks separated by commas in the GUI.

.. option:: device.autoAcceptFolders

Expand Down Expand Up @@ -794,6 +798,8 @@ From the following child elements at least one ``address`` child must exist.
Contains the ID of the folder that should be ignored. This folder will
always be skipped when advertised from the containing remote device,
i.e. this will be logged, but there will be no dialog shown in the web GUI.
Multiple ignored folders are represented by repeated ``<ignoredFolder>``
tags in the configuration file.

.. option:: device.maxRequestKiB

Expand Down Expand Up @@ -1055,7 +1061,10 @@ The ``options`` element contains all other global configuration options.
:aliases: options.listenAddresses

The listen address for incoming sync connections. See
:ref:`listen-addresses` for the allowed syntax.
:ref:`listen-addresses` for the allowed syntax. To configure multiple
addresses, you can either: repeat ``<listenAddress>`` tags in the
configuration file or enter several addresses separated by commas in the
GUI.

.. option:: options.globalAnnounceServer
:aliases: options.globalAnnounceServers
Expand All @@ -1066,7 +1075,10 @@ The ``options`` element contains all other global configuration options.
HTTPS URL. A number of options may be added as query options to the URL:
``insecure`` to prevent certificate validation (required for HTTP URLs)
and ``id=<device ID>`` to perform certificate pinning. The device ID to
use is printed by the discovery server on startup.
use is printed by the discovery server on startup. To configure multiple
servers, you can either: repeat ``<globalAnnounceServer>`` tags in the
configuration file or enter several servers separated by commas in the
GUI.

.. option:: options.globalAnnounceEnabled

Expand Down Expand Up @@ -1206,7 +1218,10 @@ The ``options`` element contains all other global configuration options.
.. option:: options.alwaysLocalNet
:aliases: options.alwaysLocalNets

Network that should be considered as local given in CIDR notation.
Network that should be considered as local given in CIDR notation. To
configure multiple networks, you can either: repeat ``<alwaysLocalNet>``
tags in the configuration file or enter several networks separated by
commas in the GUI.

.. option:: options.overwriteRemoteDeviceNamesOnConnect

Expand All @@ -1223,7 +1238,9 @@ The ``options`` element contains all other global configuration options.
:aliases: options.unackedNotificationIDs

ID of a notification to be displayed in the web GUI. Will be removed once
the user acknowledged it (e.g. an transition notice on an upgrade).
the user acknowledged it (e.g. a transition notice on an upgrade). Multiple
IDs are represented by repeated ``<unackedNotificationID>`` tags in the
configuration file.

.. option:: options.trafficClass

Expand All @@ -1246,6 +1263,10 @@ The ``options`` element contains all other global configuration options.
``stun.voiparound.com:3478``, ``stun.voipbuster.com:3478``,
``stun.voipstunt.com:3478`` and ``stun.xten.com:3478`` (this is the default).

To configure multiple servers, you can either: repeat ``<stunServer>`` tags
in the configuration file or enter several servers separated by commas in
the GUI.

.. option:: options.stunKeepaliveStartS

Interval in seconds between contacting a STUN server to maintain NAT
Expand Down Expand Up @@ -1316,7 +1337,9 @@ The ``options`` element contains all other global configuration options.
Feature flags are simple strings that, when added to the configuration, may
unleash unfinished or still-in-development features to allow early user
testing. Any supported value will be separately announced with the feature,
so that regular users do not enable it by accident.
so that regular users do not enable it by accident. To configure multiple
flags, you can either: repeat ``<featureFlag>`` tags in the configuration
file or enter several flags separated by commas in the GUI.

.. option:: options.connectionLimitEnough

Expand Down Expand Up @@ -1439,9 +1462,9 @@ Listen Addresses
^^^^^^^^^^^^^^^^

The following address types are accepted in sync protocol listen addresses.
If you want Syncthing to listen on multiple addresses, you can either: add
multiple ``<listenAddress>`` tags in the configuration file or enter several
addresses separated by commas in the GUI.
If you want Syncthing to listen on multiple addresses, you can either: repeat
``<listenAddress>`` tags in the configuration file or enter several addresses
separated by commas in the GUI.

Default listen addresses (``default``)
This is equivalent to ``tcp://0.0.0.0:22000``, ``quic://0.0.0.0:22000``
Expand Down

0 comments on commit f3165de

Please sign in to comment.