users: New default config/data locations (#833)

See syncthing/syncthing#9180 --------- Co-authored-by: André Colomb <[email protected]>
syncthing · Nov 13, 2023 · 2c95cf7 · 2c95cf7
1 parent d76c966
commit 2c95cf7
Show file tree

Hide file tree

Showing 4 changed files with 44 additions and 31 deletions.
diff --git a/users/autostart.rst b/users/autostart.rst
@@ -319,7 +319,7 @@ Go to ``/etc/supervisor/conf.d/`` and create a new file named ``syncthing.conf``
     autorestart = True
     directory = /home/<USERNAME>/
     user = <USERNAME>
-    command = /usr/bin/syncthing --no-browser --home="/home/<USERNAME>/.config/syncthing"
+    command = /usr/bin/syncthing --no-browser
     environment = STNORESTART="1", HOME="/home/<USERNAME>"
 
 Reload Supervisord::

diff --git a/users/config.rst b/users/config.rst
@@ -8,7 +8,8 @@ Synopsis
 
 ::
 
-    $HOME/.config/syncthing
+    $XDG_STATE_HOME/syncthing
+    $HOME/.local/state/syncthing
     $HOME/Library/Application Support/Syncthing
     %LOCALAPPDATA%\Syncthing
 
@@ -18,18 +19,32 @@ Synopsis
 Description
 -----------
 
+.. versionchanged:: 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.
+
 .. versionadded:: 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 has a database, which is often stored in this directory too.
-The config location defaults to ``$HOME/.config/syncthing``
-(Unix-like), ``$HOME/Library/Application Support/Syncthing`` (Mac),
-or ``%LOCALAPPDATA%\Syncthing`` (Windows). It can be changed at runtime
-using the ``--config`` flag. In this directory the following files are
-located:
+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 varibles (``$STCONFDIR`` or ``STHOMEDIR``). The
+following files are located in this directory:
 
 :file:`config.xml`
     The configuration file, in XML format.
@@ -42,28 +57,25 @@ located:
     The certificate and key for HTTPS GUI connections. These may be replaced
     with a custom certificate for HTTPS as desired.
 
-:file:`csrftokens.txt`
-    A list of recently issued CSRF tokens (for protection against browser cross
-    site request forgery).
-
-The database is stored either in the same directory as the config (usually the
-default), but may also be located in one of the following directories (Unix-like
-platforms only):
+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``).
 
-* If a database exists in the old default location, that location is
-  still used.
-* If ``$XDG_DATA_HOME`` is set, use ``$XDG_DATA_HOME/syncthing``.
-* If ``~/.local/share/syncthing`` exists, use that location.
-* Use the old default location (same as config).
-
-The location of the database can be changed using the ``--data`` flag. The
-``--home`` flag sets both config and database locations at the same time.
-The database contains the following files:
+The database directory contains the following files, among others:
 
 :file:`index-{*}.db`
     A directory holding the database with metadata and hashes of the files
     currently on disk and available from peers.
 
+:file:`syncthing.log`
+    Log output, on some systems.
+
+:file:`audit-{*}.log`
+    Audit log data, when enabled.
+
+:file:`panic-{*}.log`
+    Crash log data, when required.
+
 
 Config File Format
 ------------------

diff --git a/users/faq-parts/troubleshooting.rst b/users/faq-parts/troubleshooting.rst
@@ -127,8 +127,8 @@ How can I view the history of changes?
 The web GUI contains a ``Recent Changes`` button under the device list which
 displays changes since the last (re)start of Syncthing. With the ``--audit``
 option you can enable a persistent, detailed log of changes and most
-activities, which contains a ``JSON`` formatted  sequence of events in the
-``~/.config/syncthing/audit-_date_-_time_.log`` file.
+activities, which contains a JSON-formatted sequence of events in the
+``~/.local/state/syncthing/audit-_date_-_time_.log`` file.
 
 Does the audit log contain every change?
 ----------------------------------------
@@ -168,18 +168,18 @@ or unmount a filesystem, then syncthing must know whether you have really delete
 your files. Therefore, syncthing always checks that the ``.stfolder`` is present.
 
 When this error appears, syncthing assumes that the folder has encountered some type of error
-and will stop syncing it until the ``.stfolder`` reappears. Once that happens, all changes made 
+and will stop syncing it until the ``.stfolder`` reappears. Once that happens, all changes made
 to the folder locally will be synced (i.e. missing files will be considered deletions).
 
-- If you get this error message, check the folder in question on your storage. If you have 
+- If you get this error message, check the folder in question on your storage. If you have
   unmounted the folder (or a parent of it), you must remount it for syncthing to resume syncing
-  this folder. 
+  this folder.
 
 - If you have moved the folder, you must either move it back to its original location, or remove the
   folder from within the syncthing UI and re-add it at its new location.
 
 - If the folder is present on disk, with all of its children files and directories, but the ``.stfolder``
-  is still missing: 
+  is still missing:
 
   It is possible that a file cleaning software has removed the ``.stfolder``. Some software
   removes empty folders, and the ``.stfolder`` is often empty. This happens particularly often on Android.

diff --git a/users/syncthing.rst b/users/syncthing.rst
@@ -118,7 +118,8 @@ Options
 .. cmdoption:: --home=<dir>
 
     Set common configuration and data directory. The default configuration
-    directory is ``$HOME/.config/syncthing`` (Unix-like),
+    directory is ``$XDG_STATE_HOME/syncthing`` or
+    ``$HOME/.local/state/syncthing`` (Unix-like),
     ``$HOME/Library/Application Support/Syncthing`` (Mac) and
     ``%LOCALAPPDATA%\Syncthing`` (Windows).