NixOS Wiki

Syncthing: Difference between revisions

← Older edit
VisualWikitext
Jfly (talk | contribs)
5 edits
→Configuration: Simpler secrets example, don't imply that people should copy these things to the store.
→Disable default sync folder: Simplify code by using command-line argument instead of env var
 
(3 intermediate revisions by 2 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 the 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 if you don't want plaintext credentials in your configuration.nix file)
   # Optional: GUI credentials (can be set in the browser instead)
  # or the password hash can be generated with "syncthing generate --config <path> --gui-password=<password>"
   settings.gui = {
   settings.gui = {
     user = "myuser";
     user = "myuser";
Line 16: Line 41:
</syntaxhighlight>
</syntaxhighlight>


You can confirm Syncthing runs by visiting http://127.0.0.1:8384/ and authenticating 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>
<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>
 
== Tips and tricks ==


=== Sync folders and remote hosts ===
=== Sync folders and remote hosts ===
Line 24: Line 78:
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 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">
The share <code>Sensitive</code> is shared unencrypted with <code>device1</code>, and encrypted with <code>device2</code>:
<syntaxhighlight lang="nix">
services.syncthing = {
services.syncthing = {
   settings = {
   settings = {
Line 62: Line 117:
};
};
</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 = "/run/secrets/path/to/key.pem";
  cert = "/run/secrets/path/to/cert.pem";
    cert = "/run/secrets/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 --config 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>


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


=== Disable default sync folder ===
== Troubleshooting ==
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>


== See also ==
== See also ==


* Home-Manager service https://github.com/nix-community/home-manager/blob/master/modules/services/syncthing.nix
* [[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]
[[Category: Applications]]
* [[Comparison of secret managing schemes]] – Compare different ways to manage secrets declaratively on NixOS, including for use with Syncthing.
* [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.
 
== References ==
 
[[Category:Applications]]
[[Category:File synchronization]]
[[Category:Web Applications]]
[[Category:Web Applications]]
Retrieved from "https://wiki.nixos.org/wiki/Syncthing"