Syncthing: Difference between revisions

Revision as of 17:35, 27 May 2025

Syncthing is a decentralized file synchronization service. You can use it to safely sync all files in a folder between different desktops/servers.

Setup

To enable Syncthing, add the following to your system configuration:

services.syncthing = {
  enable = true;
  openDefaultPorts = true;
  # Optional: GUI credentials (can be set in the browser instead if you don't want plaintext credentials in your configuration.nix file)
  # or the password hash can be generated with "syncthing generate --config <path> --gui-password=<password>"
  settings.gui = {
    user = "myuser";
    password = "mypassword";
  };
};

You can confirm Syncthing runs by visiting http://127.0.0.1:8384/ and authenticating using the credentials above.

Configuration

Sync folders and remote hosts

The following configuration will trust the remote hosts device1 and device2 by adding their ids. The shares Documents and Example are added to the local node, defined by their local file paths and list of allowed devices.

The share Sensitive is shared unencrypted with device1, and encrypted with device2.

services.syncthing = {
  settings = {
    devices = {
      "device1" = { id = "DEVICE-ID-GOES-HERE"; };
      "device2" = { id = "DEVICE-ID-GOES-HERE"; };
    };
    folders = {
      "Documents" = {
        path = "/home/myusername/Documents";
        devices = [ "device1" "device2" ];
      };
      "Example" = {
        path = "/home/myusername/Example";
        devices = [ "device1" ];
        # By default, Syncthing doesn't sync file permissions. This line enables it for this folder.
        ignorePerms = false;
      };
      "Sensitive" = {
        path = "/home/myusername/Sensitive";
        devices = [
          # We trust this device to have access
          # to the decrypted contents of this folder.
          "device1"
          # We do not trust this device, but we want to have another
          # (encrypted) copy of the data for redundancy/backup/sync purposes.
          {
            name = "device2";
            # encryptionPasswordFile is a path to a file containing the encryption password.
            # See below for information about managing secrets on NixOS.
            encryptionPasswordFile = "/run/secrets/st-sensitive-password";
          }
        ];
      };
    };
  };
};

Declarative node IDs

If you set up Syncthing with the above configuration, you will still need to manually accept the connection from your other devices. If you want to make this automatic, you must also set the key.pem and cert.pem options:

services = {
  syncthing = {
    key = "${</path/to/key.pem>}";
    cert = "${</path/to/cert.pem>}";
    ...
};

This will ensure your node has a stable ID.

You can optionally include the key.pem and cert.pem files in the NixOS configuration using a tool like sops-nix. See Comparison of secret managing schemes.

To generate a new key.cert and key.pem for a deployment, you can use the -generate argument:

$ nix-shell -p syncthing --run "syncthing generate --config myconfig/"
2024/04/23 11:41:17 INFO: Generating ECDSA key and certificate for syncthing...
2024/04/23 11:41:17 INFO: Device ID: DMWVMM6-MKEQVB4-I4UZTRH-5A6E24O-XHQTL3K-AAI5R5L-MXNMUGX-QTGRHQ2
2024/04/23 11:41:17 INFO: Default folder created and/or linked to new config
$ ls myconfig/
cert.pem  config.xml  key.pem

Tips and tricks

Disable default sync folder

Syncthing creates a 'Sync' folder in your home directory every time it regenerates a configuration, even if your declarative configuration does not have this folder. You can disable that by setting the STNODEFAULTFOLDER environment variable:

systemd.services.syncthing.environment.STNODEFAULTFOLDER = "true"; # Don't create default ~/Sync folder