Syncthing: Difference between revisions

From NixOS Wiki
← Older edit
VisualWikitext
MTL (talk | contribs)
1 edit
m Remove guidance to expose the admin port outside the firewall. This is insecure, as that's a sensitive interface.
Tags: Mobile edit Mobile web edit
Ponder (talk | contribs)
11 edits
m Missing small words
 
(7 intermediate revisions by one other user not shown)
Line 1: Line 1:
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.
[https://syncthing.net Syncthing] is a decentralized file synchronization service. You can use it to safely sync all files in a folder between different desktops/servers.
== Install ==
== Setup ==
Syncthing is available as a standalone package: <code>nix-env -iA nixos.syncthing</code>
To enable Syncthing, add the following to your system configuration:


It can also be enabled as a service. Example:
<syntaxhighlight lang="nix">
 
services.syncthing = {
<syntaxHighlight lang="nix">
  enable = true;
services = {
  openDefaultPorts = true;
    syncthing = {
  settings.gui = {
        enable = true;
    user = "myuser";
        user = "myusername";
    password = "mypassword";
        dataDir = "/home/myusername/Documents";   # Default folder for new synced folders
   };
        configDir = "/home/myusername/Documents/.config/syncthing";  # Folder for Syncthing's settings and keys
    };
};
};
</syntaxHighlight>
</syntaxhighlight>


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
You can confirm Syncthing runs by visiting http://127.0.0.1:8384/ and authenticating using the credentials above.


== Declarative configuration ==
== Configuration ==
Note: using a declarative configuration will overwrite files in <code>configDir</code>.


Note: every available option can be sourced from here https://mynixos.com/nixpkgs/options/services.syncthing
=== Sync folders and trusted remote hosts ===
 
The following configuration will trust the remote hosts <code>device1</code> and <code>device2</code> by adding their <code>id</code>s. The shares <code>Documents</code> and <code>Example</code> are added to the local node, defined by their local file paths and list of allowed devices.<syntaxhighlight lang="nix">
You can declaratively set your Syncthing folders by using the <code>services.syncthing.devices</code> and <code>services.syncthing.folders</code> options:
services.syncthing = {
 
   settings = {
(Note: Before NixOS 21.11, declarative configuration was done in the <code>services.syncthing.declarative</code> option, such as <code>services.syncthing.declarative.folders = {};</code>)
     devices = {
 
       "device1" = { id = "DEVICE-ID-GOES-HERE"; };
<syntaxhighlight lang="nix">
      "device2" = { id = "DEVICE-ID-GOES-HERE"; };
services = {
    };
   syncthing = {
    folders = {
     enable = true;
      "Documents" = {
    user = "myusername";
        path = "/home/myusername/Documents";
    dataDir = "/home/myusername/Documents";
        devices = [ "device1" "device2" ];
    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 = {
       "Example" = {
        "Documents" = {         # Folder ID in Syncthing, also the name of folder (label) by default
         path = "/home/myusername/Example";
          path = "/home/myusername/Documents";    # Which folder to add to Syncthing
        devices = [ "device1" ];
          devices = [ "device1" "device2" ];      # Which devices to share the folder with
        # By default, Syncthing doesn't sync file permissions. This line enables it for this folder.
        };
         ignorePerms = false;
         "Example" = {
          label = "Private";                      # Optional label for the folder
          path = "/home/myusername/Example";
          devices = [ "device1" ];
          ignorePerms = false;  # By default, Syncthing doesn't sync file permissions. This line enables it for this folder.
         };
       };
       };
     };
     };
   };
   };
};
};
</syntaxhighlight>Beware when adding additional settings via <code>services.syncthing.settings</code>, because sometimes you cannot use the key as in the documentation. For example, when setting the ''Sync Protocol Listen Address'': The key in the [https://docs.syncthing.net/users/config.html#config-file-format documentation] is <code>listenAddress</code>, however, because the value is a list the key used in <code>services.syncthing.settings</code> has to be <code>listenAddresses</code> (notice the extra <code>es</code>). See the following example:<syntaxhighlight lang="nix">
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>"
    ];
  };
};
</syntaxhighlight>
</syntaxhighlight>
=== Firewall ===
You will probably have to open a few ports in the firewall:
<syntaxHighlight lang="nix">
  # 22000 TCP and/or UDP for sync traffic
  # 21027/UDP for discovery
  # source: https://docs.syncthing.net/users/firewall.html
  networking.firewall.allowedTCPPorts = [ 22000 ];
  networking.firewall.allowedUDPPorts = [ 22000 21027 ];
</syntaxHighlight>
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:
<syntaxHighlight lang="nix">
services.syncthing.settings.gui = {
    user = "username";
    password = "password";
};
</syntaxHighlight>
Alternatively, you can leave the GUI inaccessible from the web and forward it using SSH:
<syntaxhighlight lang="bash">$ ssh -L 9998:localhost:8384 user@syncthing-host</syntaxhighlight>Then open up [http://127.0.0.1:9998 127.0.0.1:9998] to administer the node.
=== Declarative node IDs ===
=== 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:
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:
Line 117: Line 62:
cert.pem  config.xml  key.pem</syntaxhighlight>
cert.pem  config.xml  key.pem</syntaxhighlight>


== Disable default sync folder ==
== 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:
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:
<syntaxhighlight lang="nix">systemd.services.syncthing.environment.STNODEFAULTFOLDER = "true"; # Don't create default ~/Sync folder</syntaxhighlight>
<syntaxhighlight lang="nix">systemd.services.syncthing.environment.STNODEFAULTFOLDER = "true"; # Don't create default ~/Sync folder</syntaxhighlight>


== Home-manager service ==
== See also ==


https://github.com/nix-community/home-manager/blob/master/modules/services/syncthing.nix
* Home-Manager service https://github.com/nix-community/home-manager/blob/master/modules/services/syncthing.nix
[[Category: Applications]]
[[Category: Applications]]

Latest revision as of 18:04, 14 October 2024

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;
  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 trusted 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.

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;
      };
    };
  };
};

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

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

See also

Retrieved from "https://wiki.nixos.org/w/index.php?title=Syncthing&oldid=17800"