Information on config location is confusing / wrong in documentation

[WildRikku]

What happened?

I was looking for the config file my Syncthing installation on my server is using. On the page "Command Line Operation" in the documentation (https://docs.syncthing.net/users/syncthing.html), the command line options --home, --config and --data are explained. My Syncthing is called without any of those so I figured the config must be in my home dir. However, the path given as default configuration location in the documentation is the state directory. This is wrong. I assume this is the default data directory. I found the config in ~/.config, which is a reasonable default, but this is not mentioned in the documentation.

It is also confusing that the Syncthing home can be the home dir in the Unix sense but does not have to be.

From the other parameters, I understand that config dir and data dir are two separate things and by default, they both reside in the home dir, in the according directories. The documentation should mention both paths within the home dir.

Syncthing version

syncthing v1.27.2-ds4 "Gold Grasshopper" (go1.22.2 linux-amd64) debian@debian 2025-07-21 04:55:34 UTC

Platform & operating system

Ubuntu Server 24.04 LTS

Edit: I found the configuration page in the documentation, where it is mentioned that this was changed in 1.27.0, which is after my initial installation. So that's why my files were not where they are supposed to be according to the CLI documentation. For one, I don't understand the change, since .config is the correct folder for configs. And then, the CLI documentation should also mention the change or at least link to the other page in the documentation.

Edit 2: I learned that Syncthing 2 has --paths which can show all the paths on the command line, this could also be mentioned on the documentation page for the configuration https://docs.syncthing.net/users/config.html

[acolomb]

My Syncthing is called without any of those so I figured the config must be in my home dir

That's unfortunately a misconception. How did you come to that conclusion? The "home" dir in fact has nothing to do with the UNIX concept of the same name.

Syncthing has device-specific "configuration" and a database to store, along with its device identity. The database might need to be moved separately for performance reasons, for which we have the --data switch. Everything else is considered for --config, which is not an adequate term for some parts. The --home switch simply sets both at the same time, similar to what other software does (e.g. GNUPGHOME).

The main reason for moving the files out of the $XDG_CONFIG_HOME (usually ~/.config/) was that people following the XDG specs expect things in that hierarchy to be sharable between different machines, like preferences for some application. Which is really dangerous in the case of Syncthing, as sharing the same device ID between multiple instances can lead to data loss. Yes, there are some preference options in the config.xml (like language and GUI theme), but it also describes the state of connections in the cluster. And especially the device cert.pem and key.pem are not "configuration" from the user's perspective, but constitute the identity of the running instance.

Feel free to suggest an improvement to the docs (pull request) where you think that additional options should be mentioned. But in essence, we already have the facts down correctly, just not in the places where you first looked.

[WildRikku]

That's unfortunately a misconception. How did you come to that conclusion?

It is literally stated in the documentation. According to https://docs.syncthing.net/users/config.html the default config dir is $HOME/.local/state/syncthing. What I meant precisely was: Since my Syncthing is started without parameters, I figured it must use the default location for the config, which is in /home/user.

Part of the rest of my issue was related to using an outdated Syncthing version.

Thanks for explaining the reason for the move to the state directory. Would you mind pointing out which part of the config.xml specifically defines the ID of the device the config belongs to? I indeed assumed the config.xml can be copied around since it defines known devices and known folders and those might be identical on several devices.

[acolomb]

Since my Syncthing is started without parameters, I figured it must use the default location for the config, which is in /home/user

But exactly this default location is not documented to be /home/user. Or where did you find that?

Would you mind pointing out which part of the config.xml specifically defines the ID of the device the config belongs to?

That's the thing, there is a <device id="..."> section in there, which looks just the same as for remote devices, and holds some options like the local device name. Most of them are disregarded for the local device however. You can't really tell which one it is without knowing the local device ID in advance, from the certificate. One slight hint is that the local device id is not listed in any folder as a sharing device, but that might also be the case for remote devices which simply have no shared folders configured yet. And that's also where the config is no longer identical between two mutually sharing devices.

[WildRikku]

Since my Syncthing is started without parameters, I figured it must use the default location for the config, which is in /home/user

But exactly this default location is not documented to be /home/user. Or where did you find that?

I put a link and a quote in my previous post. $HOME contains /home/user. What is your question?

Would you mind pointing out which part of the config.xml specifically defines the ID of the device the config belongs to?

That's the thing, there is a <device id="..."> section in there, which looks just the same as for remote devices, and holds some options like the local device name. Most of them are disregarded for the local device however. You can't really tell which one it is without knowing the local device ID in advance, from the certificate. One slight hint is that the local device id is not listed in any folder as a sharing device, but that might also be the case for remote devices which simply have no shared folders configured yet. And that's also where the config is no longer identical between two mutually sharing devices.

Ah, so the identification of the local device is not in the config, it's in the certificate. I see.

[acolomb]

I put a link and a quote in my previous post. $HOME contains /home/user. What is your question?

Trying to clarify whether you have misunderstood the quoted documentation. It says $XDG_STATE_HOME/syncthing/, which defaults to $HOME/.local/state/syncthing/ if not set explicitly. Of course $HOME is a parent of that default path. If your comment "figured it must use the default location for the config, which is in /home/user" was meant to say somewhere underneath the $HOME directory, then it's all clear. But I understood that you thought the $STHOMEDIR (equivalent to --home switch) would default to just $HOME if not specified, which is not what the documentation says.