SYNCTHING-CONFIG(5) Syncthing SYNCTHING-CONFIG(5)
NAME
syncthing-config - Syncthing Configuration
SYNOPSIS
$XDG_STATE_HOME/syncthing
$HOME/.local/state/syncthing
$HOME/Library/Application Support/Syncthing
%LOCALAPPDATA%\Syncthing
DESCRIPTION
Changed in version 1.27.0: The default location of the configuration
and database directory on Unix-like systems was changed to
$XDG_STATE_HOME/syncthing or $HOME/.local/state/syncthing. Previously
the default config location was $XDG_CONFIG_HOME/syncthing or
$HOME/.config/syncthing. The database directory was previously
$HOME/.config/syncthing or, if the environment variable was set,
$XDG_DATA_HOME/syncthing. Existing installations may still use these
directories instead of the newer defaults.
New in version 1.5.0: Database and config can now be set separately.
Previously the database was always located in the same directory as the
config.
Syncthing uses a single directory to store configuration and crypto
keys. Syncthing also keeps an index database with file metadata which
is by default stored in the same directory, though this can be
overridden.
The location defaults to $XDG_STATE_HOME/syncthing or
$HOME/.local/state/syncthing (Unix-like), $HOME/Library/Application
Support/Syncthing (Mac), or %LOCALAPPDATA%\Syncthing (Windows). It can
be changed at runtime using the --config or --home flags or the
corresponding environment variables ($STCONFDIR or STHOMEDIR). The
following files are located in this directory:
config.xml
The configuration file, in XML format.
cert.pem, key.pem
The device's ECDSA public and private key. These form the basis
for the device ID. The key must be kept private.
https-cert.pem, https-key.pem
The certificate and key for HTTPS GUI connections. These may be
replaced with a custom certificate for HTTPS as desired.
The database is by default stored in the same directory as the config,
but the location may be overridden by the --data or --home flags or the
corresponding environment varibles ($STDATADIR or STHOMEDIR).
The database directory contains the following files, among others:
index-*.db
A directory holding the database with metadata and hashes of the
files currently on disk and available from peers.
syncthing.log
Log output, on some systems.
audit-*.log
Audit log data, when enabled.
panic-*.log
Crash log data, when required.
CONFIG FILE FORMAT
The following shows an example of a default configuration file (IDs
will differ):
NOTE:
The config examples are present for illustration. Do not copy them
entirely to use as your config. They are likely out-of-date and the
values may no longer correspond to the defaults.
basic
1
3600
basic
0
0
0
random
false
0
0
-1
false
false
false
25
.stfolder
false
0
2
false
standard
standard
false
false
false
false
false
false
dynamic
false
false
0
0
0
false
0
127.0.0.1:8384
k1dnz1Dd0rzTBjjFFh7CXPnrF12C49B1
default
default
default
true
true
21027
[ff12::8384]:21027
0
0
60
true
10
true
true
60
30
10
0
0
https://data.syncthing.net/newdata
false
1800
12
false
24
false
5
false
1
https://upgrades.syncthing.net/meta.json
false
10
authenticationUserAndPassword
0
true
0
https://crash.syncthing.net/newcrash
true
180
20
default
auto
0
true
false
0
0
false
basic
1
3600
basic
0
0
0
random
false
0
0
10
false
false
false
25
.stfolder
false
0
2
false
standard
standard
false
false
false
false
false
false
dynamic
false
false
0
0
0
false
0
CONFIGURATION ELEMENT
This is the root element. It has one attribute:
version
The config version. Increments whenever a change is made that
requires migration from previous formats.
It contains the elements described in the following sections and any
number of this additional child element:
remoteIgnoredDevice
Contains the ID of the device that should be ignored. Connection
attempts from this device are logged to the console but never
displayed in the web GUI.
FOLDER ELEMENT
basic
1
3600
basic
0
0
0
random
false
0
0
-1
false
false
false
25
.stfolder
false
0
2
false
standard
standard
false
false
false
false
false
false
One or more folder elements must be present in the file. Each element
describes one folder. The following attributes may be set on the folder
element:
id (mandatory)
The folder ID, which must be unique.
label The label of a folder is a human readable and descriptive local
name. May be different on each device, empty, and/or identical
to other folder labels. (optional)
filesystemType
The internal file system implementation used to access this
folder, detailed in a separate chapter.
path (mandatory)
The path to the directory where the folder is stored on this
device; not sent to other devices.
type Controls how the folder is handled by Syncthing. Possible values
are:
sendreceive
The folder is in default mode. Sending local and
accepting remote changes. Note that this type was
previously called "readwrite" which is deprecated but
still accepted in incoming configs.
sendonly
The folder is in "send only" mode - it will not be
modified by Syncthing on this device. Note that this
type was previously called "readonly" which is deprecated
but still accepted in incoming configs.
receiveonly
The folder is in "receive only" mode - it will not
propagate changes to other devices.
receiveencrypted
Must be used on untrusted devices, where the data cannot
be decrypted because no folder password was entered. See
Untrusted (Encrypted) Devices.
rescanIntervalS
The rescan interval, in seconds. Can be set to 0 to disable when
external plugins are used to trigger rescans.
fsWatcherEnabled
If set to true, this detects changes to files in the folder and
scans them.
fsWatcherDelayS
The duration during which changes detected are accumulated,
before a scan is scheduled (only takes effect if
fsWatcherEnabled is set to true).
ignorePerms
If true, files originating from this folder will be announced to
remote devices with the "no permission bits" flag. The remote
devices will use whatever their default permission setting is
when creating the files. The primary use case is for file
systems that do not support permissions, such as FAT, or
environments where changing permissions is impossible.
autoNormalize
Automatically correct UTF-8 normalization errors found in file
names. The mechanism and how to set it up is described in a
separate chapter.
The following child elements may exist:
device These must have the id attribute and can have an introducedBy
attribute, identifying the device that introduced us to share
this folder with the given device. If the original introducer
unshares this folder with this device, our device will follow
and unshare the folder (subject to skipIntroductionRemovals
being false on the introducer device).
All 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 folders. Syncthing will currently
add this automatically if it is not present in the configuration
file.
The encryptionPassword sub-element contains the secret needed to
decrypt this folder's data on the remote device. If left empty,
the data is plainly accessible (but still protected by the
transport encryption). The mechanism and how to set it up is
described in a separate chapter.
minDiskFree
The minimum required free space that should be available on the
disk this folder resides. The folder will be stopped when the
value drops below the threshold. The element content is
interpreted according to the given unit attribute. Accepted
unit values are % (percent of the disk / volume size), kB, MB,
GB and TB. Set to zero to disable.
versioning
Specifies a versioning configuration.
SEE ALSO:
File Versioning
copiers
hashers
The number of copier and hasher routines to use, or 0 for the
system determined optimums. These are low-level performance
options for advanced users only; do not change unless requested
to or you've actually read and understood the code yourself. :)
pullerMaxPendingKiB
Controls when we stop sending requests to other devices once
we've got this much unserved requests. The number of pullers is
automatically adjusted based on this desired amount of
outstanding request data.
order The order in which needed files should be pulled from the
cluster. It has no effect when the folder type is "send only".
The possibles values are:
random (default)
Pull files in random order. This optimizes for balancing
resources among the devices in a cluster.
alphabetic
Pull files ordered by file name alphabetically.
smallestFirst, largestFirst
Pull files ordered by file size; smallest and largest
first respectively.
oldestFirst, newestFirst
Pull files ordered by modification time; oldest and
newest first respectively.
Note that the scanned files are sent in batches and the sorting
is applied only to the already discovered files. This means the
sync might start with a 1 GB file even if there is 1 KB file
available on the source device until the 1 KB becomes known to
the pulling device.
ignoreDelete
WARNING:
Enabling this is highly discouraged - use at your own risk.
You have been warned.
When set to true, this device will pretend not to see
instructions to delete files from other devices. The mechanism
is described in a separate chapter.
scanProgressIntervalS
The interval in seconds with which scan progress information is
sent to the GUI. Setting to 0 will cause Syncthing to use the
default value of two.
pullerPauseS
Tweak for rate limiting the puller when it retries pulling
files. Don't change this unless you know what you're doing.
maxConflicts
The maximum number of conflict copies to keep around for any
given file. The default, -1, means an unlimited number. Setting
this to 0 disables conflict copies altogether.
disableSparseFiles
By default, blocks containing all zeros are not written, causing
files to be sparse on filesystems that support this feature.
When set to true, sparse files will not be created.
disableTempIndexes
By default, devices exchange information about blocks available
in transfers that are still in progress, which allows other
devices to download parts of files that are not yet fully
downloaded on your own device, essentially making transfers more
torrent like. When set to true, such information is not
exchanged for this folder.
paused True if this folder is (temporarily) suspended.
weakHashThresholdPct
Use weak hash if more than the given percentage of the file has
changed. Set to -1 to always use weak hash. Default is 25.
markerName
Name of a directory or file in the folder root to be used as How
do I serve a folder from a read only filesystem?. Default is
.stfolder.
copyOwnershipFromParent
On Unix systems, tries to copy file/folder ownership from the
parent directory (the directory it's located in). Requires
running Syncthing as a privileged user, or granting it
additional capabilities (e.g. CAP_CHOWN on Linux).
modTimeWindowS
Allowed modification timestamp difference when comparing files
for equivalence. To be used on file systems which have unstable
modification timestamps that might change after being recorded
during the last write operation. Default is 2 on Android when
the folder is located on a FAT partition, and 0 otherwise.
maxConcurrentWrites
Maximum number of concurrent write operations while syncing.
Increasing this might increase or decrease disk performance,
depending on the underlying storage. Default is 2.
disableFsync
WARNING:
This is a known insecure option - use at your own risk.
Disables committing file operations to disk before recording
them in the database. Disabling fsync can lead to data
corruption. The mechanism is described in a separate chapter.
blockPullOrder
Order in which the blocks of a file are downloaded. This option
controls how quickly different parts of the file spread between
the connected devices, at the cost of causing strain on the
storage.
Available options:
standard (default)
The blocks of a file are split into N equal continuous
sequences, where N is the number of connected devices.
Each device starts downloading its own sequence, after
which it picks other devices sequences at random.
Provides acceptable data distribution and minimal
spinning disk strain.
random The blocks of a file are downloaded in a random order.
Provides great data distribution, but very taxing on
spinning disk drives.
inOrder
The blocks of a file are downloaded sequentially, from
start to finish. Spinning disk drive friendly, but
provides no improvements to data distribution.
copyRangeMethod
Provides a choice of method for copying data between files.
This can be used to optimise copies on network filesystems,
improve speed of large copies or clone the data using
copy-on-write functionality if the underlying filesystem
supports it. The mechanism is described in a separate chapter.
caseSensitiveFS
Affects performance by disabling the extra safety checks for
case insensitive filesystems. The mechanism and how to set it
up is described in a separate chapter.
junctionsAsDirs
NTFS directory junctions are treated as ordinary directories, if
this is set to true.
syncOwnership
File and directory ownership is synced when this is set to true.
See syncOwnership for more information.
sendOwnership
File and directory ownership information is scanned when this is
set to true. See sendOwnership for more information.
syncXattrs
File and directory extended attributes are synced when this is
set to true. See syncXattrs for more information.
sendXattrs
File and directory extended attributes are scanned and sent to
other devices when this is set to true. See sendXattrs for more
information.
DEVICE ELEMENT
dynamic
false
false
0
0
0
false
0
0
tcp://192.0.2.1:22001
true
192.168.0.0/16
false
100
100
65536
false
8384
0
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. The following attributes may be set on
the device element:
id (mandatory)
The device ID.
name A friendly name for the device. (optional)
compression
Whether to use protocol compression when sending messages to
this device. The possible values are:
metadata
Compress metadata packets, such as index information.
Metadata is usually very compression friendly so this is
a good default.
always Compress all packets, including file data. This is
recommended if the folders contents are mainly
compressible data such as documents or text files.
never Disable all compression.
introducer
Set to true if this device should be trusted as an introducer,
i.e. we should copy their list of devices per folder when
connecting.
SEE ALSO:
Introducer Configuration
skipIntroductionRemovals
Set to true if you wish to follow only introductions and not
de-introductions. For example, if this is set, we would not
remove a device that we were introduced to even if the original
introducer is no longer listing the remote device as known.
introducedBy
Defines which device has introduced us to this device. Used only
for following de-introductions.
certName
The device certificate's common name, if it is not the default
"syncthing".
From the following child elements at least one address child must
exist.
address (mandatory: At least one must be present.)
Contains an address or host name to use when attempting to
connect to this device. Entries other than dynamic need a
protocol specific prefix. For the TCP protocol the prefixes
tcp:// (dual-stack), tcp4:// (IPv4 only) or tcp6:// (IPv6 only)
can be used. The prefixes for the QUIC protocol are analogous:
quic://, quic4:// and quic6:// Note that IP addresses need not
use IPv4 or IPv6 prefixes; these are optional. Accepted formats
are:
IPv4 address (tcp://192.0.2.42)
The default port (22000) is used.
IPv4 address and port (tcp://192.0.2.42:12345)
The address and port is used as given.
IPv6 address (tcp://[2001:db8::23:42])
The default port (22000) is used. The address must be
enclosed in square brackets.
IPv6 address and port (tcp://[2001:db8::23:42]:12345)
The address and port is used as given. The address must
be enclosed in square brackets.
Host name (tcp6://fileserver)
The host name will be used on the default port (22000)
and connections will be attempted only via IPv6.
Host name and port (tcp://fileserver:12345)
The host name will be used on the given port and
connections will be attempted via both IPv4 and IPv6,
depending on name resolution.
dynamic
The word dynamic (without any prefix) means to use local
and global discovery to find the device.
You can set multiple addresses and combine it with the dynamic
keyword for example:
tcp://192.0.2.1:22001
quic://192.0.1.254:22000
dynamic
paused True if synchronization with this devices is (temporarily)
suspended.
allowedNetwork
If given, this restricts connections to this device to only this
network. The mechanism is described in detail in a separate
chapter).
autoAcceptFolders
If true, folders shared from this remote device are
automatically added and synced locally under the default path.
For the folder name, Syncthing tries to use the label from the
remote device, and if the same label already exists, it then
tries to use the folder's ID. If that exists as well, the
folder is just offered to accept manually. A local folder
already added with the same ID will just be shared rather than
created separately.
maxSendKbps
Maximum send rate to use for this device. Unit is
kibibytes/second, despite the config name looking like
kilobits/second.
maxRecvKbps
Maximum receive rate to use for this device. Unit is
kibibytes/second, despite the config name looking like
kilobits/second.
ignoredFolder
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.
maxRequestKiB
Maximum amount of data to have outstanding in requests towards
this device. Unit is kibibytes.
remoteGUIPort
If set to a positive integer, the GUI will display an HTTP link
to the IP address which is currently used for synchronization.
Only the TCP port is exchanged for the value specified here.
Note that any port forwarding or firewall settings need to be
done manually and the link will probably not work for link-local
IPv6 addresses because of modern browser limitations.
untrusted
This boolean value marks a particular device as untrusted, which
disallows ever sharing any unencrypted data with it. Every
folder shared with that device then needs an encryption password
set, or must already be of the "receive encrypted" type locally.
Refer to the detailed explanation under Untrusted (Encrypted)
Devices.
numConnections
The number of connections to this device. See numConnections for
more information.
GUI ELEMENT
127.0.0.1:8384
k1dnz1Dd0rzTBjjFFh7CXPnrF12C49B1
default
There must be exactly one gui element. The GUI configuration is also
used by the REST API and the Event API. The following attributes may be
set on the gui element:
enabled
If not true, the GUI and API will not be started.
tls If set to true, TLS (HTTPS) will be enforced. Non-HTTPS requests
will be redirected to HTTPS. When set to false, TLS connections
are still possible but not required.
debugging
This enables Profiling and additional endpoints in the REST API,
see Debug Endpoints.
The following child elements may be present:
address (mandatory: Exactly one element must be present.)
Set the listen address. Allowed address formats are:
IPv4 address and port (127.0.0.1:8384)
The address and port are used as given.
IPv6 address and port ([::1]:8384)
The address and port are used as given. The address must
be enclosed in square brackets.
Wildcard and port (0.0.0.0:12345, [::]:12345, :12345)
These are equivalent and will result in Syncthing
listening on all interfaces via both IPv4 and IPv6.
UNIX socket location (/var/run/st.sock)
If the address is an absolute path it is interpreted as
the path to a UNIX socket.
unixSocketPermissions
When address is set to a UNIX socket location, set this to an
octal value to override the default permissions of the socket.
user 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.
insecureAdminAccess
If true, this allows access to the web GUI from outside (i.e.
not localhost) without authorization. A warning will displayed
about this setting on startup.
insecureSkipHostcheck
When the GUI / API is bound to localhost, we enforce that the
Host header looks like localhost. This option bypasses that
check.
insecureAllowFrameLoading
Allow rendering the GUI within an