Set Up a Safe Syncthing Folder and Ignore Rules on Debian

By the end of this guide, Syncthing will have a named folder to share, a repeatable way to locate its configuration, and an ordered .stignore file that keeps unwanted files out of synchronisation. Allow about 20 minutes for a first setup, plus the time needed for the initial scan and transfer.

Before you start

You need Syncthing installed on this Debian machine and a second device that you control. Decide on a directory for the files, such as /home/ALICE/Sync/notes. Replace ALICE and the example device ID below with your own values. The commands are ordinary user commands unless marked as requiring elevated privileges.

This guide was checked with the installed package's syncthing v1.27.2-ds4. The local manpage is labelled v1.27.0, so rely on syncthing --help if a later package changes a command. The 1.27 configuration documentation matters here: on Unix-like systems the new default is $XDG_STATE_HOME/syncthing, or $HOME/.local/state/syncthing when the former is unset. Older installations may still use $HOME/.config/syncthing.

1. Find the paths and device ID

Run the path query before editing anything. It tells you where this installation keeps config.xml, the device certificate, database, logs and default sync directory.

syncthing --paths
syncthing --device-id
syncthing --version

On a fresh installation, --device-id can fail because cert.pem does not exist yet. That is expected until Syncthing has generated its identity. The version command should print a line similar to:

syncthing v1.27.2-ds4 "Gold Grasshopper" (go1.22.2 linux-amd64)

2. Generate the initial configuration

If this is a new user account, generate the configuration explicitly. This creates the device key and certificate, writes config.xml, and then exits. The default folder can also be suppressed so that you add only the folders you intend to share.

syncthing generate --no-default-folder

Verify that the identity now exists:

syncthing --device-id

The output is a hyphenated device ID. Add this machine to the other device using its Syncthing interface or configuration. A device ID identifies a key pair, not a user account. Never paste the private key into a ticket or chat.

If you generated the configuration in the wrong directory, stop before sharing anything. Remove only that newly created, unused directory after checking its path, then run the command again with --home=/absolute/path. Do not remove an existing Syncthing directory: it contains the identity and database.

3. Start Syncthing and add a folder

Start Syncthing as the account that owns the files. Avoid sudo syncthing unless you have a specific, documented reason; running it as root creates a separate root-owned identity and can make later file access confusing.

syncthing --no-browser

The process stays in the foreground and prints the GUI address among its early log messages. On this installation the usual local address is http://127.0.0.1:8384. Open that address from the same machine, then set a GUI username and a strong password before exposing the GUI beyond localhost.

Add the other device by its device ID, accept the pairing on both sides, then add a folder. Use a stable folder ID such as notes, choose a label such as Shared notes, and set its local path to:

/home/ALICE/Sync/notes

Choose the folder mode deliberately. Send and Receive accepts changes in both directions. Send Only prevents this machine from accepting remote file changes. Receive Only prevents it from sending local changes onward. These modes protect against some classes of mistake, but they are not a backup: a deletion can still be propagated according to the folder's mode and history.

printf 'syncthing test\n' > /home/ALICE/Sync/notes/syncthing-test.txt
sha256sum /home/ALICE/Sync/notes/syncthing-test.txt

When the second device reports the file as up to date, remove the test file through the normal file manager or shell. If it was accidentally a real file, restore it from your backup before allowing synchronisation to settle. Syncthing is a synchroniser, not an undelete tool.

4. Add ordered ignore rules

Create .stignore in the root of the synced folder, not in Syncthing's configuration directory. The file itself is never synchronised. Patterns are relative to the folder root, and the first matching pattern decides the result. A leading ! includes a match that an earlier rule would otherwise ignore, so put specific exceptions before broad rules where needed.

// macOS metadata can be removed when it blocks an empty directory
(?d).DS_Store

// editor and build noise
*.swp
build/

// local secrets: keep these on this device
*.key
*.pem
!public.pem

The * wildcard does not cross a directory separator. Use ** when it must cross directories. A pattern such as /private.txt matches only the folder root, while private.txt can match that name below the root as well. A directory pattern ending in / matches its contents but not the directory itself, so omit the final slash when the directory entry must also match.

Do not assume that an ignore rule deletes files already present on a peer. It changes what Syncthing considers for synchronisation. The (?d) prefix permits removal of an ignored file when it is preventing an otherwise empty directory from being removed. Use it only for disposable operating-system files.

To share a common rule set, .stignore can include another file with a line such as:

#include shared-ignore.txt

The included file must exist, and it must not be included more than once. An included file may itself include another file, with nested paths resolved relative to the file doing the include. Remember that the patterns still apply from the synced folder root.

5. Check changes and recover cleanly

After editing .stignore, use the GUI's folder scan or wait for the watcher to notice the change. If a file unexpectedly disappears from the synchronised view, stop the affected folder in the GUI before deleting or rewriting rules. Move a questionable file to a directory outside the synced folder, then correct the rule and rescan. Restore it only after confirming the corrected rule.

If Syncthing reports a configuration error, do not delete the database as a first response. Check the XML and the service log, and compare the folder path and device IDs. The --reset-database option forces a full rescan and resynchronisation, and the manpage warns that mounted folders must already be mounted. Use it only while Syncthing is stopped and only after a backup and a clear reason.

For automation, the local CLI exposes the running instance through the GUI/API. Discover its exact commands with:

syncthing cli --help
syncthing cli show --help
syncthing cli operations --help

These commands depend on a running instance and its API authentication. Keep the API bound to a trusted address, protect its key, and do not place credentials in shell history.

Done means

• syncthing --paths identifies the configuration and database locations you expect.
• syncthing --device-id prints this machine's identity after initial generation.
• The intended devices are paired by device ID, with GUI authentication configured.
• The test file arrived on the peer and was removed deliberately.
• .stignore is in the folder root, uses ordered rules, and keeps secrets out of synchronisation.
• You know how to stop a folder and restore a file before changing a rule that behaves unexpectedly.