Skip to content

Syncthing — Config Backup

🟪 tests

currently in  testing

Syncthing's own configuration (device keys, folder definitions) must be backed up separately — it is not included in the folders it syncs.

What gets backed up

  • cert.pem — device certificate (identity)
  • key.pem — private key
  • config.xml — all folder and device definitions

Reference setup

Export destination: ~/.local/state/syncthing-export/ Export interval: every 15 minutes via systemd timer (st-config-export.timer) Module: 91_syncthing_config_backup.sh

How it works

  1. A systemd timer runs an export script every 15 minutes
  2. The script atomically copies the three files to the export directory

  3. A dedicated Syncthing folder (st-config-backup) syncs the export directory:

  4. Source: Send Only

  5. Relay: Receive Encrypted
  6. Secondary: Receive Only + staggered versioning

This means the config backup is itself protected by the same topology as all other folders.

Setup steps

1. Export script

Save as ~/.local/bin/st-config-export.sh:

#!/bin/bash
# Atomic snapshot of Syncthing identity files to a stable staging directory.
# Runs via systemd user timer; the staging dir is shared via ST (sendonly).
# Only cert.pem, key.pem, config.xml — the minimum needed for disaster recovery.
set -euo pipefail

SRC="$HOME/.local/state/syncthing"
STAGING="$HOME/.local/state/syncthing-export"
TMP="$(mktemp -d "${STAGING}.tmp.XXXXXX")"

trap 'rm -rf "$TMP"' EXIT

mkdir -p "$STAGING"
cp "$SRC/cert.pem"   "$TMP/cert.pem"
cp "$SRC/key.pem"    "$TMP/key.pem"
cp "$SRC/config.xml" "$TMP/config.xml"

# Atomic swap: replace staging contents without touching the dir inode
# (ST watches the dir; a rename of the dir itself would confuse it)
for f in cert.pem key.pem config.xml; do
    mv -f "$TMP/$f" "$STAGING/$f"
done

echo "$(date -Iseconds) st-config-export: snapshot written to $STAGING"

2. Systemd timer

Save as ~/.config/systemd/user/st-config-export.service:

[Unit]
Description=Syncthing config snapshot (cert + key + config.xml)
After=syncthing.service

[Service]
Type=oneshot
ExecStart=%h/.local/bin/st-config-export.sh

Save as ~/.config/systemd/user/st-config-export.timer:

[Unit]
Description=Syncthing config snapshot — every 15 min

[Timer]
OnBootSec=2min
OnUnitActiveSec=15min
Persistent=true

[Install]
WantedBy=timers.target

Enable and start:

chmod +x ~/.local/bin/st-config-export.sh
systemctl --user daemon-reload
systemctl --user enable --now st-config-export.timer

3. Syncthing folder

Add ~/.local/state/syncthing-export/ as a Syncthing folder named st-config-backup. Share it with relay (receiveencrypted) and secondary (receiveonly + staggered).

Restore

To restore Syncthing config on a new or rebuilt source:

  1. Get the backup from the secondary mirror at ~/mirror/st-config-backup/
  2. Stop Syncthing
  3. Copy cert.pem, key.pem, config.xml to ~/.local/share/syncthing/
  4. Start Syncthing — device ID and all folder definitions are restored

Full restore procedure (to be verified against a live test):

  1. Get the backup from the secondary: ~/mirror/st-config-backup/ (or decrypt from relay if secondary is unavailable — provide encryption password)
  2. systemctl --user stop syncthing
  3. cp cert.pem key.pem config.xml ~/.local/share/syncthing/
  4. systemctl --user start syncthing
  5. Syncthing reconnects with the original Device ID; all folders begin resyncing from relay and/or secondary

Verify: GUI shows the original Device ID and all folders reappear.

← Syncthing — Overview · Syncthing — Encrypted Relay Node →

tf5-7hk · v2026-05-16 · Export created: 2026-06-11 15:09 UTC