NixOS Wiki

Syncthing: Difference between revisions

← Older edit
VisualWikitext
Onny (talk | contribs)
261 edits
Cleanup
→Disable default sync folder: Simplify code by using command-line argument instead of env var
 
(10 intermediate revisions by 8 users not shown)
Line 1: Line 1:
[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.
<languages/>
== Setup ==
[https://syncthing.net/ 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.<ref>https://syncthing.net/</ref>
To enable Syncthing, add following to your system configuration:


== Installation ==
==== Shell ====
To temporarily use Syncthing in a shell environment without modifying your system configuration, you can run:
<syntaxhighlight lang="bash">
nix-shell -p syncthing --run syncthing
</syntaxhighlight>
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 <code>/etc/nixos/configuration.nix</code>:
<syntaxhighlight lang="nix">
# Example for /etc/nixos/configuration.nix
services.syncthing = {
  enable = true;
  openDefaultPorts = true; # Open ports in the firewall for Syncthing
};
</syntaxhighlight>
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 <code>services.syncthing</code> attribute set:
<syntaxhighlight lang="nix">
<syntaxhighlight lang="nix">
services.syncthing = {
services.syncthing = {
   enable = true;
   enable = true;
   openDefaultPorts = true;
   openDefaultPorts = true;
  # Optional: GUI credentials (can be set in the browser instead)
   settings.gui = {
   settings.gui = {
     user = "myuser";
     user = "myuser";
Line 14: Line 41:
</syntaxhighlight>
</syntaxhighlight>


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


== Configuration ==
For more advanced configuration with multiple devices and folders, you can declaratively configure devices and shared folders:<ref>https://docs.syncthing.net/users/config.html</ref>
Follow the official ''[https://docs.syncthing.net/intro/getting-started.html Getting Started]'' guide to get started.
<syntaxhighlight lang="nix">
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
      };
    };
  };
};
</syntaxhighlight>


Note: using a declarative configuration will overwrite files in <code>configDir</code>.
== Tips and tricks ==


Note: every available option can be sourced from here https://mynixos.com/nixpkgs/options/services.syncthing
=== Sync folders and remote hosts ===


You can declaratively set your Syncthing folders by using the <code>services.syncthing.devices</code> and <code>services.syncthing.folders</code> options:
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.


The share <code>Sensitive</code> is shared unencrypted with <code>device1</code>, and encrypted with <code>device2</code>:
<syntaxhighlight lang="nix">
<syntaxhighlight lang="nix">
services = {
services.syncthing = {
   syncthing = {
   settings = {
     enable = true;
     devices = {
    user = "myusername";
       "device1" = { id = "DEVICE-ID-GOES-HERE"; };
    dataDir = "/home/myusername/Documents";
      "device2" = { id = "DEVICE-ID-GOES-HERE"; };
    configDir = "/home/myusername/Documents/.config/syncthing";
    };
    overrideDevices = true;    # overrides any devices added or deleted through the WebUI
    folders = {
    overrideFolders = true;    # overrides any folders added or deleted through the WebUI
      "Documents" = {
    settings = {
        path = "/home/myusername/Documents";
       devices = {
        devices = [ "device1" "device2" ];
        "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
      "Sensitive" = {
          path = "/home/myusername/Example";
        path = "/home/myusername/Sensitive";
          devices = [ "device1" ];
        devices = [
           ignorePerms = false; # By default, Syncthing doesn't sync file permissions. This line enables it for this folder.
          # 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";
          }
         ];
       };
       };
     };
     };
   };
   };
};
};
</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>


=== 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:
<syntaxhighlight lang="nix">
<syntaxhighlight lang="nix">
services = {
services.syncthing = {
   syncthing = {
   key = "/run/secrets/path/to/key.pem";
    key = "${</path/to/key.pem>}";
  cert = "/run/secrets/path/to/cert.pem";
    cert = "${</path/to/cert.pem>}";
  # ... other configuration
    ...
};
};
</syntaxhighlight>This will ensure your node has a stable ID.
</syntaxhighlight>
 
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]].
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:
To generate a new key.cert and key.pem for a deployment, you can use the -generate argument:
<syntaxhighlight lang="bash">$ nix-shell -p syncthing --run "syncthing -generate=myconfig"
<syntaxhighlight lang="bash">
$ 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: 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: 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
2024/04/23 11:41:17 INFO: Default folder created and/or linked to new config
$ ls myconfig/
$ ls myconfig/
cert.pem  config.xml  key.pem</syntaxhighlight>
cert.pem  config.xml  key.pem
</syntaxhighlight>
 
=== 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 <code>--no-default-folder</code> command-line option<ref>https://docs.syncthing.net/users/syncthing.html#cmdoption-no-default-folder</ref>:
<syntaxhighlight lang="nix">
services.syncthing.extraFlags = [ "--no-default-folder" ]; # Don't create default ~/Sync folder
</syntaxhighlight>
 
== Troubleshooting ==
 
== See also ==


== Disable default sync folder ==
* [[Home Manager]] – Use Syncthing declaratively at the user level: [https://github.com/nix-community/home-manager/blob/master/modules/services/syncthing.nix Syncthing module in Home Manager]
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:
* [[Comparison of secret managing schemes]] – Compare different ways to manage secrets declaratively on NixOS, including for use with Syncthing.
<syntaxhighlight lang="nix">systemd.services.syncthing.environment.STNODEFAULTFOLDER = "true"; # Don't create default ~/Sync folder</syntaxhighlight>
* [https://nixos.org/manual/nixos/stable/index.html#sec-services Syncthing in NixOS Manual] – Official documentation for configuring services like Syncthing.
* [https://docs.syncthing.net Syncthing User Documentation] – In-depth official guide on Syncthing features, configuration, and troubleshooting.
* [https://discourse.nixos.org/search?q=syncthing Syncthing discussions on Discourse] – Community tips, troubleshooting, and advanced use cases.


== Home-manager service ==
== References ==


https://github.com/nix-community/home-manager/blob/master/modules/services/syncthing.nix
[[Category:Applications]]
[[Category: Applications]]
[[Category:File synchronization]]
[[Category:Web Applications]]
Retrieved from "https://wiki.nixos.org/wiki/Syncthing"