Syncthing

Syncthing is a decentralized file synchronization service. You can use it to safely sync all files in a folder between different desktops/servers. In other Linux distributions, you configure it via its own web-GUI. In NixOS, you can partly or fully configure it using Nix.

Install

Syncthing is available as a standalone package: nix-env -iA nixos.syncthing

It can also be enabled as a service. Example:

services = {
    syncthing = {
        enable = true;
        user = "myusername";
        dataDir = "/home/myusername/Documents";    # Default folder for new synced folders
        configDir = "/home/myusername/Documents/.config/syncthing";   # Folder for Syncthing's settings and keys
    };
};

You can confirm Syncthing runs by visiting http://127.0.0.1:8384/ and following the official Getting Started guide: https://docs.syncthing.net/intro/getting-started.html

Declarative configuration

Note: using a declarative configuration will overwrite files in configDir.

You can declaratively set your Syncthing folders by using the services.syncthing.devices and services.syncthing.folders options:

(Note: Before NixOS 21.11, declarative configuration was done in the services.syncthing.declarative option, such as services.syncthing.declarative.folders = {};)

services = {
  syncthing = {
    enable = true;
    user = "myusername";
    dataDir = "/home/myusername/Documents";
    configDir = "/home/myusername/Documents/.config/syncthing";
    overrideDevices = true;     # overrides any devices added or deleted through the WebUI
    overrideFolders = true;     # overrides any folders added or deleted through the WebUI
    settings = {
      devices = {
        "device1" = { id = "DEVICE-ID-GOES-HERE"; };
        "device2" = { id = "DEVICE-ID-GOES-HERE"; };
      };
      folders = {
        "Documents" = {         # Name of folder in Syncthing, also the folder ID
          path = "/home/myusername/Documents";    # Which folder to add to Syncthing
          devices = [ "device1" "device2" ];      # Which devices to share the folder with
        };
        "Example" = {
          path = "/home/myusername/Example";
          devices = [ "device1" ];
          ignorePerms = false;  # By default, Syncthing doesn't sync file permissions. This line enables it for this folder.
        };
      };
    };
  };
};

Beware when adding additional settings via services.syncthing.settings, because sometimes you cannot use the key as in the documentation. For example, when setting the Sync Protocol Listen Address: The key in the documentation is listenAddress, however, because the value is a list the key used in services.syncthing.settings has to be listenAddresses (notice the extra es). See the following example:

settings = {
  options = {
    listenAddresses = [ # listenAddress in the syncthing documentation
      "relay://replay-server/?id=<device-id>"
    ];
    globalAnnounceServers = [ # globalAnnounceServer in the syncthing documentation
      "https://relay-server/?id=<device-id>"
    ];
  };
};

Firewall

You will probably have to open a few ports in the firewall:

   # Syncthing ports: 8384 for remote access to GUI
   # 22000 TCP and/or UDP for sync traffic
   # 21027/UDP for discovery
   # source: https://docs.syncthing.net/users/firewall.html
   networking.firewall.allowedTCPPorts = [ 8384 22000 ];
   networking.firewall.allowedUDPPorts = [ 22000 21027 ];

Syncthing uses port 22000 to facilitate discovery of nodes on the local area network. If this port is blocked by the firewall, nodes will have to go all the way to the announce servers, then use a bridge to tunnel through NAT. This is much slower than just sending data in a "node1 -> router -> node2" path.

Web GUI

If running a headless server, you should also change guiAddress to a publicly visible one (or just 0.0.0.0:8384, for example).

It is also a good idea to protect the web GUI with a username and password:

services.syncthing.settings.gui = {
    user = "username";
    password = "password";
};

Alternatively, you can leave the GUI inaccessible from the web and forward it using SSH:

$ ssh -L 9998:localhost:8384 user@syncthing-host

Then open up 127.0.0.1:9998 to administer the node.

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=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

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

Home-manager service

https://github.com/nix-community/home-manager/blob/master/modules/services/syncthing.nix