swendel/nixpkgs
1
0
Fork 0
mirror of https://github.com/SebastianWendel/nixpkgs.git synced 2024-09-21 12:59:04 +02:00
Code Issues Packages Projects Releases Wiki Activity

nixos/syncthing: clean up option descriptions

Browse source
This commit is contained in:
Naïm Favier 2021-07-29 15:20:30 +02:00
parent e9b01c5c8e
commit f114215b14
No known key found for this signature in database
GPG key ID: 49B07322580B7EE2
1 changed files with 114 additions and 99 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

213
nixos/modules/services/networking/syncthing.nix
View file

@ -5,6 +5,7 @@ with lib;
let let
cfg = config.services.syncthing; cfg = config.services.syncthing;
defaultUser = "syncthing"; defaultUser = "syncthing";
defaultGroup = defaultUser;
devices = mapAttrsToList (name: device: { devices = mapAttrsToList (name: device: {
deviceID = device.id; deviceID = device.id;
@ -68,18 +69,15 @@ in {
options = { options = {
services.syncthing = { services.syncthing = {
enable = mkEnableOption '' enable = mkEnableOption
Syncthing - the self-hosted open-source alternative "Syncthing, a self-hosted open-source alternative to Dropbox and Bittorrent Sync";
to Dropbox and Bittorrent Sync. Initial interface will be
available on http://127.0.0.1:8384/.
'';
cert = mkOption { cert = mkOption {
type = types.nullOr types.str; type = types.nullOr types.str;
default = null; default = null;
description = '' description = ''
Path to users cert.pem file, will be copied into Syncthing's Path to the <literal>cert.pem</literal> file, which will be copied into Syncthing's
<literal>configDir</literal> <link linkend="opt-services.syncthing.configDir">configDir</link>.
''; '';
}; };
@ -87,8 +85,8 @@ in {
type = types.nullOr types.str; type = types.nullOr types.str;
default = null; default = null;
description = '' description = ''
Path to users key.pem file, will be copied into Syncthing's Path to the <literal>key.pem</literal> file, which will be copied into Syncthing's
<literal>configDir</literal> <link linkend="opt-services.syncthing.configDir">configDir</link>.
''; '';
}; };
@ -97,9 +95,9 @@ in {
default = true; default = true;
description = '' description = ''
Whether to delete the devices which are not configured via the Whether to delete the devices which are not configured via the
<literal>devices</literal> option. <link linkend="opt-services.syncthing.devices">devices</link> option.
If set to false, devices added via the webinterface will If set to <literal>false</literal>, devices added via the web
persist but will have to be deleted manually. interface will persist and will have to be deleted manually.
''; '';
}; };
@ -107,6 +105,10 @@ in {
default = {}; default = {};
description = '' description = ''
Peers/devices which Syncthing should communicate with. Peers/devices which Syncthing should communicate with.
Note that you can still add devices manually, but those changes
will be reverted on restart if <link linkend="opt-services.syncthing.overrideDevices">overrideDevices</link>
is enabled.
''; '';
example = { example = {
bigbox = { bigbox = {
@ -121,7 +123,7 @@ in {
type = types.str; type = types.str;
default = name; default = name;
description = '' description = ''
Name of the device The name of the device.
''; '';
}; };
@ -130,15 +132,14 @@ in {
default = []; default = [];
description = '' description = ''
The addresses used to connect to the device. The addresses used to connect to the device.
If this is let empty, dynamic configuration is attempted If this is left empty, dynamic configuration is attempted.
''; '';
}; };
id = mkOption { id = mkOption {
type = types.str; type = types.str;
description = '' description = ''
The id of the other peer, this is mandatory. It's documented at The device ID. See <link xlink:href="https://docs.syncthing.net/dev/device-ids.html"/>.
https://docs.syncthing.net/dev/device-ids.html
''; '';
}; };
@ -146,8 +147,9 @@ in {
type = types.bool; type = types.bool;
default = false; default = false;
description = '' description = ''
If the device should act as an introducer and be allowed Whether the device should act as an introducer and be allowed
to add folders on this computer. to add folders on this computer.
See <link xlink:href="https://docs.syncthing.net/users/introducer.html"/>.
''; '';
}; };
@ -160,9 +162,9 @@ in {
default = true; default = true;
description = '' description = ''
Whether to delete the folders which are not configured via the Whether to delete the folders which are not configured via the
<literal>folders</literal> option. <link linkend="opt-services.syncthing.folders">folders</link> option.
If set to false, folders added via the webinterface will persist If set to <literal>false</literal>, folders added via the web
but will have to be deleted manually. interface will persist and will have to be deleted manually.
''; '';
}; };
@ -170,6 +172,10 @@ in {
default = {}; default = {};
description = '' description = ''
Folders which should be shared by Syncthing. Folders which should be shared by Syncthing.
Note that you can still add devices manually, but those changes
will be reverted on restart if <link linkend="opt-services.syncthing.overrideDevices">overrideDevices</link>
is enabled.
''; '';
example = literalExample '' example = literalExample ''
{ {
@ -186,7 +192,7 @@ in {
type = types.bool; type = types.bool;
default = true; default = true;
description = '' description = ''
share this folder. Whether to share this folder.
This option is useful when you want to define all folders This option is useful when you want to define all folders
in one place, but not every machine should share all folders. in one place, but not every machine should share all folders.
''; '';
@ -204,7 +210,7 @@ in {
type = types.str; type = types.str;
default = name; default = name;
description = '' description = ''
The id of the folder. Must be the same on all devices. The ID of the folder. Must be the same on all devices.
''; '';
}; };
@ -220,8 +226,8 @@ in {
type = types.listOf types.str; type = types.listOf types.str;
default = []; default = [];
description = '' description = ''
The devices this folder should be shared with. Must be defined The devices this folder should be shared with. Each device must
in the <literal>devices</literal> attribute. be defined in the <link linkend="opt-services.syncthing.devices">devices</link> option.
''; '';
}; };
@ -230,56 +236,59 @@ in {
description = '' description = ''
How to keep changed/deleted files with Syncthing. How to keep changed/deleted files with Syncthing.
There are 4 different types of versioning with different parameters. There are 4 different types of versioning with different parameters.
See https://docs.syncthing.net/users/versioning.html See <link xlink:href="https://docs.syncthing.net/users/versioning.html"/>.
''; '';
example = [ example = literalExample ''
{ [
versioning = { {
type = "simple"; versioning = {
params.keep = "10"; type = "simple";
}; params.keep = "10";
}
{
versioning = {
type = "trashcan";
params.cleanoutDays = "1000";
};
}
{
versioning = {
type = "staggered";
params = {
cleanInterval = "3600";
maxAge = "31536000";
versionsPath = "/syncthing/backup";
}; };
}; }
} {
{ versioning = {
versioning = { type = "trashcan";
type = "external"; params.cleanoutDays = "1000";
params.versionsPath = pkgs.writers.writeBash "backup" '' };
folderpath="$1" }
filepath="$2" {
rm -rf "$folderpath/$filepath" versioning = {
''; type = "staggered";
}; params = {
} cleanInterval = "3600";
]; maxAge = "31536000";
versionsPath = "/syncthing/backup";
};
};
}
{
versioning = {
type = "external";
params.versionsPath = pkgs.writers.writeBash "backup" '''
folderpath="$1"
filepath="$2"
rm -rf "$folderpath/$filepath"
''';
};
}
]
'';
type = with types; nullOr (submodule { type = with types; nullOr (submodule {
options = { options = {
type = mkOption { type = mkOption {
type = enum [ "external" "simple" "staggered" "trashcan" ]; type = enum [ "external" "simple" "staggered" "trashcan" ];
description = '' description = ''
Type of versioning. The type of versioning.
See https://docs.syncthing.net/users/versioning.html See <link xlink:href="https://docs.syncthing.net/users/versioning.html"/>.
''; '';
}; };
params = mkOption { params = mkOption {
type = attrsOf (either str path); type = attrsOf (either str path);
description = '' description = ''
Parameters for versioning. Structure depends on versioning.type. The parameters for versioning. Structure depends on
See https://docs.syncthing.net/users/versioning.html <link linkend="opt-services.syncthing.folders._name_.versioning.type">versioning.type</link>.
See <link xlink:href="https://docs.syncthing.net/users/versioning.html"/>.
''; '';
}; };
}; };
@ -290,7 +299,7 @@ in {
type = types.int; type = types.int;
default = 3600; default = 3600;
description = '' description = ''
How often the folders should be rescaned for changes. How often the folder should be rescanned for changes.
''; '';
}; };
@ -298,8 +307,8 @@ in {
type = types.enum [ "sendreceive" "sendonly" "receiveonly" ]; type = types.enum [ "sendreceive" "sendonly" "receiveonly" ];
default = "sendreceive"; default = "sendreceive";
description = '' description = ''
Whether to send only changes from this folder, only receive them Whether to only send changes for this folder, only receive them
or propagate both. or both.
''; '';
}; };
@ -323,7 +332,7 @@ in {
type = types.bool; type = types.bool;
default = true; default = true;
description = '' description = ''
Whether to propagate permission changes. Whether to ignore permission changes.
''; '';
}; };
@ -331,9 +340,8 @@ in {
type = types.bool; type = types.bool;
default = false; default = false;
description = '' description = ''
Whether to delete files in destination. See <link Whether to skip deleting files that are deleted by peers.
xlink:href="https://docs.syncthing.net/advanced/folder-ignoredelete.html"> See <link xlink:href="https://docs.syncthing.net/advanced/folder-ignoredelete.html"/>.
upstream's docs</link>.
''; '';
}; };
}; };
@ -345,6 +353,7 @@ in {
default = {}; default = {};
description = '' description = ''
Extra configuration options for Syncthing. Extra configuration options for Syncthing.
See <link xlink:href="https://docs.syncthing.net/users/config.html"/>.
''; '';
example = { example = {
options.localAnnounceEnabled = false; options.localAnnounceEnabled = false;
@ -356,31 +365,35 @@ in {
type = types.str; type = types.str;
default = "127.0.0.1:8384"; default = "127.0.0.1:8384";
description = '' description = ''
Address to serve the GUI. The address to serve the web interface at.
''; '';
}; };
systemService = mkOption { systemService = mkOption {
type = types.bool; type = types.bool;
default = true; default = true;
description = "Auto launch Syncthing as a system service."; description = ''
Whether to auto-launch Syncthing as a system service.
'';
}; };
user = mkOption { user = mkOption {
type = types.str; type = types.str;
default = defaultUser; default = defaultUser;
example = "yourUser";
description = '' description = ''
Syncthing will be run under this user (user will be created if it doesn't exist. The user to run Syncthing as.
This can be your user name). By default, a user named <literal>${defaultUser}</literal> will be created.
''; '';
}; };
group = mkOption { group = mkOption {
type = types.str; type = types.str;
default = defaultUser; default = defaultGroup;
example = "yourGroup";
description = '' description = ''
Syncthing will be run under this group (group will not be created if it doesn't exist. The group to run Syncthing under.
This can be your user name). By default, a group named <literal>${defaultGroup}</literal> will be created.
''; '';
}; };
@ -389,52 +402,54 @@ in {
default = null; default = null;
example = "socks5://address.com:1234"; example = "socks5://address.com:1234";
description = '' description = ''
Overwrites all_proxy environment variable for the Syncthing process to Overwrites the all_proxy environment variable for the Syncthing process to
the given value. This is normaly used to let relay client connect the given value. This is normally used to let Syncthing connect
through SOCKS5 proxy server. through a SOCKS5 proxy server.
See <link xlink:href="https://docs.syncthing.net/users/proxying.html"/>.
''; '';
}; };
dataDir = mkOption { dataDir = mkOption {
type = types.path; type = types.path;
default = "/var/lib/syncthing"; default = "/var/lib/syncthing";
example = "/home/yourUser";
description = '' description = ''
Path where synced directories will exist. The path where synchronised directories will exist.
''; '';
}; };
configDir = mkOption { configDir = let
cond = versionAtLeast config.system.stateVersion "19.03";
in mkOption {
type = types.path; type = types.path;
description = '' description = ''
Path where the settings and keys will exist. The path where the settings and keys will exist.
''; '';
default = default = cfg.dataDir + (optionalString cond "/.config/syncthing");
let defaultText = literalExample "dataDir${optionalString cond " + \"/.config/syncthing\""}";
nixos = config.system.stateVersion;
cond = versionAtLeast nixos "19.03";
in cfg.dataDir + (optionalString cond "/.config/syncthing");
}; };
openDefaultPorts = mkOption { openDefaultPorts = mkOption {
type = types.bool; type = types.bool;
default = false; default = false;
example = literalExample "true"; example = true;
description = '' description = ''
Open the default ports in the firewall: Whether to open the default ports in the firewall: TCP 22000 for transfers
- TCP 22000 for transfers and UDP 21027 for discovery.
- UDP 21027 for discovery
If multiple users are running Syncthing on this machine, you will need to manually open a set of ports for each instance and leave this disabled. If multiple users are running Syncthing on this machine, you will need
Alternatively, if are running only a single instance on this machine using the default ports, enable this. to manually open a set of ports for each instance and leave this disabled.
Alternatively, if you are running only a single instance on this machine
using the default ports, enable this.
''; '';
}; };
package = mkOption { package = mkOption {
type = types.package; type = types.package;
default = pkgs.syncthing; default = pkgs.syncthing;
defaultText = "pkgs.syncthing"; defaultText = literalExample "pkgs.syncthing";
example = literalExample "pkgs.syncthing";
description = '' description = ''
Syncthing package to use. The Syncthing package to use.
''; '';
}; };
}; };
@ -443,7 +458,7 @@ in {
imports = [ imports = [
(mkRemovedOptionModule [ "services" "syncthing" "useInotify" ] '' (mkRemovedOptionModule [ "services" "syncthing" "useInotify" ] ''
This option was removed because Syncthing now has the inotify functionality included under the name "fswatcher". This option was removed because Syncthing now has the inotify functionality included under the name "fswatcher".
It can be enabled on a per-folder basis through the webinterface. It can be enabled on a per-folder basis through the web interface.
'') '')
] ++ map (o: ] ++ map (o:
mkRenamedOptionModule [ "services" "syncthing" "declarative" o ] [ "services" "syncthing" o ] mkRenamedOptionModule [ "services" "syncthing" "declarative" o ] [ "services" "syncthing" o ]
@ -470,8 +485,8 @@ in {
}; };
}; };
users.groups = mkIf (cfg.systemService && cfg.group == defaultUser) { users.groups = mkIf (cfg.systemService && cfg.group == defaultGroup) {
${defaultUser}.gid = ${defaultGroup}.gid =
config.ids.gids.syncthing; config.ids.gids.syncthing;
}; };