Syncthing
Syncthing is a free and open-source decentralized file synchronization application that allows for secure, continuous, and private syncing of files between computers. Unlike cloud-based services, Syncthing operates peer-to-peer, so your data remains on your devices unless you choose to share it. It is cross-platform, offering native support for Linux, macOS, Windows, BSD, and mobile devices.[1]
Installation
Shell
To temporarily use Syncthing in a shell environment without modifying your system configuration, you can run:
nix-shell -p syncthing --run syncthing
This provides Syncthing in your current shell without adding it to your system configuration. You can open the web interface at http://127.0.0.1:8384/ to configure and use it.
System setup
To install Syncthing as a system service that runs in the background and survives reboots, add the following to your /etc/nixos/configuration.nix
:
# Example for /etc/nixos/configuration.nix
services.syncthing = {
enable = true;
openDefaultPorts = true; # Open ports in the firewall for Syncthing
};
Once you've rebuilt your system, Syncthing will be available as a system service. You can visit http://127.0.0.1:8384/ to configure it through the web interface.
Configuration
Basic
Basic Syncthing features can be configured directly within the services.syncthing
attribute set:
services.syncthing = {
enable = true;
openDefaultPorts = true;
# Optional: GUI credentials (can be set in the browser instead)
settings.gui = {
user = "myuser";
password = "mypassword";
};
};
Advanced
For more advanced configuration with multiple devices and folders, you can declaratively configure devices and shared folders:[2]
services.syncthing = {
enable = true;
openDefaultPorts = true;
settings = {
gui = {
user = "myuser";
password = "mypassword";
};
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" ];
ignorePerms = false; # Enable file permission syncing
};
};
};
};
Tips and tricks
Sync folders and remote hosts
The following configuration will trust the remote hosts device1
and device2
by adding their id
s. 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 = "/run/secrets/path/to/key.pem";
cert = "/run/secrets/path/to/cert.pem";
# ... other configuration
};
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
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 using the --no-default-folder
command-line option[3]:
services.syncthing.extraFlags = [ "--no-default-folder" ]; # Don't create default ~/Sync folder
Troubleshooting
See also
- Home Manager – Use Syncthing declaratively at the user level: Syncthing module in Home Manager
- Comparison of secret managing schemes – Compare different ways to manage secrets declaratively on NixOS, including for use with Syncthing.
- Syncthing in NixOS Manual – Official documentation for configuring services like Syncthing.
- Syncthing User Documentation – In-depth official guide on Syncthing features, configuration, and troubleshooting.
- Syncthing discussions on Discourse – Community tips, troubleshooting, and advanced use cases.