diff --git a/nixos/modules/config/i18n.nix b/nixos/modules/config/i18n.nix index dad06c1b44cd..f73f10f0f369 100644 --- a/nixos/modules/config/i18n.nix +++ b/nixos/modules/config/i18n.nix @@ -71,11 +71,11 @@ with lib; )) ''; example = ["en_US.UTF-8/UTF-8" "nl_NL.UTF-8/UTF-8" "nl_NL/ISO-8859-1"]; - description = '' + description = lib.mdDoc '' List of locales that the system should support. The value - "all" means that all locales supported by + `"all"` means that all locales supported by Glibc will be installed. A full list of supported locales - can be found at . + can be found at . ''; }; diff --git a/nixos/modules/config/resolvconf.nix b/nixos/modules/config/resolvconf.nix index ef291ce5aaf1..76605a063a47 100644 --- a/nixos/modules/config/resolvconf.nix +++ b/nixos/modules/config/resolvconf.nix @@ -83,9 +83,9 @@ in dnsExtensionMechanism = mkOption { type = types.bool; default = true; - description = '' - Enable the edns0 option in resolv.conf. With - that option set, glibc supports use of the extension mechanisms for + description = lib.mdDoc '' + Enable the `edns0` option in {file}`resolv.conf`. With + that option set, `glibc` supports use of the extension mechanisms for DNS (EDNS) specified in RFC 2671. The most popular user of that feature is DNSSEC, which does not work without it. ''; diff --git a/nixos/modules/config/shells-environment.nix b/nixos/modules/config/shells-environment.nix index 3dc202327c2d..2fda71749c09 100644 --- a/nixos/modules/config/shells-environment.nix +++ b/nixos/modules/config/shells-environment.nix @@ -109,11 +109,11 @@ in environment.shellAliases = mkOption { example = { l = null; ll = "ls -l"; }; - description = '' + description = lib.mdDoc '' An attribute set that maps aliases (the top level attribute names in this option) to command strings or directly to build outputs. The aliases are added to all users' shells. - Aliases mapped to null are ignored. + Aliases mapped to `null` are ignored. ''; type = with types; attrsOf (nullOr (either str path)); }; diff --git a/nixos/modules/config/system-environment.nix b/nixos/modules/config/system-environment.nix index a299fdceaf1c..1e05ab7d0f2b 100644 --- a/nixos/modules/config/system-environment.nix +++ b/nixos/modules/config/system-environment.nix @@ -16,7 +16,7 @@ in environment.sessionVariables = mkOption { default = {}; - description = '' + description = lib.mdDoc '' A set of environment variables used in the global environment. These variables will be set by PAM early in the login process. @@ -25,12 +25,12 @@ in colon characters. Note, due to limitations in the PAM format values may not - contain the " character. + contain the `"` character. Also, these variables are merged into - and it is + [](#opt-environment.variables) and it is therefore not possible to use PAM style variables such as - @{HOME}. + `@{HOME}`. ''; type = with types; attrsOf (either str (listOf str)); apply = mapAttrs (n: v: if isList v then concatStringsSep ":" v else v); diff --git a/nixos/modules/config/users-groups.nix b/nixos/modules/config/users-groups.nix index 2e5984b55cc1..915687d1799a 100644 --- a/nixos/modules/config/users-groups.nix +++ b/nixos/modules/config/users-groups.nix @@ -100,17 +100,17 @@ let isNormalUser = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Indicates whether this is an account for a “real” user. This - automatically sets to - users, to - true, to - /home/«username», - to true, - and to - false. - Exactly one of isNormalUser and - isSystemUser must be true. + automatically sets {option}`group` to + `users`, {option}`createHome` to + `true`, {option}`home` to + {file}`/home/«username»`, + {option}`useDefaultShell` to `true`, + and {option}`isSystemUser` to + `false`. + Exactly one of `isNormalUser` and + `isSystemUser` must be true. ''; }; @@ -151,12 +151,12 @@ let pamMount = mkOption { type = with types; attrsOf str; default = {}; - description = '' + description = lib.mdDoc '' Attributes for user's entry in - pam_mount.conf.xml. - Useful attributes might include path, - options, fstype, and server. - See + {file}`pam_mount.conf.xml`. + Useful attributes might include `path`, + `options`, `fstype`, and `server`. + See for more information. ''; }; @@ -166,12 +166,12 @@ let default = pkgs.shadow; defaultText = literalExpression "pkgs.shadow"; example = literalExpression "pkgs.bashInteractive"; - description = '' + description = lib.mdDoc '' The path to the user's shell. Can use shell derivations, - like pkgs.bashInteractive. Don’t + like `pkgs.bashInteractive`. Don’t forget to enable your shell in - programs if necessary, - like programs.zsh.enable = true;. + `programs` if necessary, + like `programs.zsh.enable = true;`. ''; }; diff --git a/nixos/modules/hardware/logitech.nix b/nixos/modules/hardware/logitech.nix index 1c3556320e39..70ca59a7dd3f 100644 --- a/nixos/modules/hardware/logitech.nix +++ b/nixos/modules/hardware/logitech.nix @@ -32,7 +32,7 @@ in devices = mkOption { type = types.listOf types.str; default = [ "0a07" "c222" "c225" "c227" "c251" ]; - description = '' + description = lib.mdDoc '' List of USB device ids supported by g15daemon. You most likely do not need to change this. diff --git a/nixos/modules/hardware/video/uvcvideo/default.nix b/nixos/modules/hardware/video/uvcvideo/default.nix index 5d1699e63955..6cfb8cc6ad29 100644 --- a/nixos/modules/hardware/video/uvcvideo/default.nix +++ b/nixos/modules/hardware/video/uvcvideo/default.nix @@ -34,15 +34,15 @@ in packages = mkOption { type = types.listOf types.path; example = literalExpression "[ pkgs.tiscamera ]"; - description = '' - List of packages containing uvcvideo dynamic controls + description = lib.mdDoc '' + List of packages containing {command}`uvcvideo` dynamic controls rules. All files found in - «pkg»/share/uvcdynctrl/data + {file}`«pkg»/share/uvcdynctrl/data` will be included. - Note that these will serve as input to the libwebcam - package which through its own udev rule will register - the dynamic controls from specified packages to the uvcvideo + Note that these will serve as input to the {command}`libwebcam` + package which through its own {command}`udev` rule will register + the dynamic controls from specified packages to the {command}`uvcvideo` driver. ''; apply = map getBin; diff --git a/nixos/modules/programs/adb.nix b/nixos/modules/programs/adb.nix index 634031939207..e5b0abd9fcfe 100644 --- a/nixos/modules/programs/adb.nix +++ b/nixos/modules/programs/adb.nix @@ -11,10 +11,10 @@ with lib; enable = mkOption { default = false; type = types.bool; - description = '' + description = lib.mdDoc '' Whether to configure system to use Android Debug Bridge (adb). To grant access to a user, it must be part of adbusers group: - users.users.alice.extraGroups = ["adbusers"]; + `users.users.alice.extraGroups = ["adbusers"];` ''; }; }; diff --git a/nixos/modules/programs/firejail.nix b/nixos/modules/programs/firejail.nix index b9a0f9a69113..417eff91d3c7 100644 --- a/nixos/modules/programs/firejail.nix +++ b/nixos/modules/programs/firejail.nix @@ -69,12 +69,12 @@ in { }; } ''; - description = '' + description = lib.mdDoc '' Wrap the binaries in firejail and place them in the global path. You will get file collisions if you put the actual application binary in the global environment (such as by adding the application package to - environment.systemPackages), and applications started via + `environment.systemPackages`), and applications started via .desktop files are not wrapped if they specify the absolute path to the binary. ''; diff --git a/nixos/modules/programs/gphoto2.nix b/nixos/modules/programs/gphoto2.nix index 373b53495f75..f31b1863963d 100644 --- a/nixos/modules/programs/gphoto2.nix +++ b/nixos/modules/programs/gphoto2.nix @@ -11,11 +11,11 @@ with lib; enable = mkOption { default = false; type = types.bool; - description = '' + description = lib.mdDoc '' Whether to configure system to use gphoto2. To grant digital camera access to a user, the user must be part of the camera group: - users.users.alice.extraGroups = ["camera"]; + `users.users.alice.extraGroups = ["camera"];` ''; }; }; diff --git a/nixos/modules/programs/neovim.nix b/nixos/modules/programs/neovim.nix index 2c39456895f3..85963159a725 100644 --- a/nixos/modules/programs/neovim.nix +++ b/nixos/modules/programs/neovim.nix @@ -72,9 +72,9 @@ in { }; } ''; - description = '' + description = lib.mdDoc '' Generate your init file from your list of plugins and custom commands. - Neovim will then be wrapped to load nvim -u /nix/store/«hash»-vimrc + Neovim will then be wrapped to load {command}`nvim -u /nix/store/«hash»-vimrc` ''; }; diff --git a/nixos/modules/programs/nncp.nix b/nixos/modules/programs/nncp.nix index f40e888dad8c..a58748d2fe62 100644 --- a/nixos/modules/programs/nncp.nix +++ b/nixos/modules/programs/nncp.nix @@ -33,24 +33,24 @@ in { secrets = mkOption { type = with types; listOf str; example = [ "/run/keys/nncp.hjson" ]; - description = '' + description = lib.mdDoc '' A list of paths to NNCP configuration files that should not be in the Nix store. These files are layered on top of the values at - . + [](#opt-programs.nncp.settings). ''; }; settings = mkOption { type = settingsFormat.type; - description = '' + description = lib.mdDoc '' NNCP configuration, see - . + . At runtime these settings will be overlayed by the contents of - into the file - ${nncpCfgFile}. Node keypairs go in - secrets, do not specify them in - settings as they will be leaked into - /nix/store! + [](#opt-programs.nncp.secrets) into the file + `${nncpCfgFile}`. Node keypairs go in + `secrets`, do not specify them in + `settings` as they will be leaked into + `/nix/store`! ''; default = { }; }; diff --git a/nixos/modules/programs/turbovnc.nix b/nixos/modules/programs/turbovnc.nix index eb09c554290f..a0e4a36cfd99 100644 --- a/nixos/modules/programs/turbovnc.nix +++ b/nixos/modules/programs/turbovnc.nix @@ -15,14 +15,14 @@ in ensureHeadlessSoftwareOpenGL = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Whether to set up NixOS such that TurboVNC's built-in software OpenGL implementation works. - This will enable so that OpenGL + This will enable {option}`hardware.opengl.enable` so that OpenGL programs can find Mesa's llvmpipe drivers. - Setting this option to false does not mean that software + Setting this option to `false` does not mean that software OpenGL won't work; it may still work depending on your system configuration. diff --git a/nixos/modules/security/acme/default.nix b/nixos/modules/security/acme/default.nix index 4bc3d8e743d3..a1d8c533304a 100644 --- a/nixos/modules/security/acme/default.nix +++ b/nixos/modules/security/acme/default.nix @@ -504,8 +504,8 @@ let reloadServices = mkOption { type = types.listOf types.str; inherit (defaultAndText "reloadServices" []) default defaultText; - description = '' - The list of systemd services to call systemctl try-reload-or-restart + description = lib.mdDoc '' + The list of systemd services to call `systemctl try-reload-or-restart` on. ''; }; diff --git a/nixos/modules/security/doas.nix b/nixos/modules/security/doas.nix index 2641548221a9..4d15ed9a8025 100644 --- a/nixos/modules/security/doas.nix +++ b/nixos/modules/security/doas.nix @@ -62,19 +62,19 @@ in wheelNeedsPassword = mkOption { type = with types; bool; default = true; - description = '' - Whether users of the wheel group must provide a password to - run commands as super user via doas. + description = lib.mdDoc '' + Whether users of the `wheel` group must provide a password to + run commands as super user via {command}`doas`. ''; }; extraRules = mkOption { default = []; - description = '' + description = lib.mdDoc '' Define specific rules to be set in the - /etc/doas.conf file. More specific rules should + {file}`/etc/doas.conf` file. More specific rules should come after more general ones in order to yield the expected behavior. - You can use mkBefore and/or mkAfter to ensure + You can use `mkBefore` and/or `mkAfter` to ensure this is the case when configuration options are merged. ''; example = literalExpression '' @@ -113,8 +113,8 @@ in noPass = mkOption { type = with types; bool; default = false; - description = '' - If true, the user is not required to enter a + description = lib.mdDoc '' + If `true`, the user is not required to enter a password. ''; }; @@ -122,18 +122,18 @@ in noLog = mkOption { type = with types; bool; default = false; - description = '' - If true, successful executions will not be logged + description = lib.mdDoc '' + If `true`, successful executions will not be logged to - syslogd8. + {manpage}`syslogd(8)`. ''; }; persist = mkOption { type = with types; bool; default = false; - description = '' - If true, do not ask for a password again for some + description = lib.mdDoc '' + If `true`, do not ask for a password again for some time after the user successfully authenticates. ''; }; @@ -141,10 +141,10 @@ in keepEnv = mkOption { type = with types; bool; default = false; - description = '' - If true, environment variables other than those + description = lib.mdDoc '' + If `true`, environment variables other than those listed in - doas1 + {manpage}`doas(1)` are kept when creating the environment for the new process. ''; }; @@ -152,18 +152,18 @@ in setEnv = mkOption { type = with types; listOf str; default = []; - description = '' + description = lib.mdDoc '' Keep or set the specified variables. Variables may also be removed with a leading '-' or set using - variable=value. If the first character of - value is a '$', the value to be set is taken from + `variable=value`. If the first character of + `value` is a '$', the value to be set is taken from the existing environment variable of the indicated name. This option is processed after the default environment has been created. - NOTE: All rules have setenv { SSH_AUTH_SOCK } by - default. To prevent SSH_AUTH_SOCK from being - inherited, add "-SSH_AUTH_SOCK" anywhere in this + NOTE: All rules have `setenv { SSH_AUTH_SOCK }` by + default. To prevent `SSH_AUTH_SOCK` from being + inherited, add `"-SSH_AUTH_SOCK"` anywhere in this list. ''; }; @@ -183,23 +183,23 @@ in runAs = mkOption { type = with types; nullOr str; default = null; - description = '' + description = lib.mdDoc '' Which user or group the specified command is allowed to run as. - When set to null (the default), all users are + When set to `null` (the default), all users are allowed. A user can be specified using just the username: - "foo". It is also possible to only allow running as - a specific group with ":bar". + `"foo"`. It is also possible to only allow running as + a specific group with `":bar"`. ''; }; cmd = mkOption { type = with types; nullOr str; default = null; - description = '' + description = lib.mdDoc '' The command the user is allowed to run. When set to - null (the default), all commands are allowed. + `null` (the default), all commands are allowed. NOTE: It is best practice to specify absolute paths. If a relative path is specified, only a restricted PATH will be @@ -210,9 +210,9 @@ in args = mkOption { type = with types; nullOr (listOf str); default = null; - description = '' + description = lib.mdDoc '' Arguments that must be provided to the command. When set to - [], the command must be run without any arguments. + `[]`, the command must be run without any arguments. ''; }; }; diff --git a/nixos/modules/security/misc.nix b/nixos/modules/security/misc.nix index 3c83ff8d7739..6833452a570e 100644 --- a/nixos/modules/security/misc.nix +++ b/nixos/modules/security/misc.nix @@ -52,7 +52,7 @@ with lib; security.allowSimultaneousMultithreading = mkOption { type = types.bool; default = true; - description = '' + description = lib.mdDoc '' Whether to allow SMT/hyperthreading. Disabling SMT means that only physical CPU cores will be usable at runtime, potentially at significant performance cost. @@ -62,7 +62,7 @@ with lib; e.g., shared caches). This attack vector is unproven. Disabling SMT is a supplement to the L1 data cache flushing mitigation - (see ) + (see [](#opt-security.virtualisation.flushL1DataCache)) versus malicious VM guests (SMT could "bring back" previously flushed data). ''; diff --git a/nixos/modules/security/pam.nix b/nixos/modules/security/pam.nix index 8a70e5f3adbd..2d0f25689784 100644 --- a/nixos/modules/security/pam.nix +++ b/nixos/modules/security/pam.nix @@ -807,14 +807,14 @@ in default = config.krb5.enable; defaultText = literalExpression "config.krb5.enable"; type = types.bool; - description = '' - Enables Kerberos PAM modules (pam-krb5, - pam-ccreds). + description = lib.mdDoc '' + Enables Kerberos PAM modules (`pam-krb5`, + `pam-ccreds`). If set, users can authenticate with their Kerberos password. This requires a valid Kerberos configuration - (config.krb5.enable should be set to - true). + (`config.krb5.enable` should be set to + `true`). Note that the Kerberos PAM modules are not necessary when using SSS to handle Kerberos authentication. @@ -826,12 +826,12 @@ in enable = mkOption { default = false; type = types.bool; - description = '' - Enables P11 PAM (pam_p11) module. + description = lib.mdDoc '' + Enables P11 PAM (`pam_p11`) module. If set, users can log in with SSH keys and PKCS#11 tokens. - More information can be found here. + More information can be found [here](https://github.com/OpenSC/pam_p11). ''; }; @@ -858,71 +858,71 @@ in enable = mkOption { default = false; type = types.bool; - description = '' - Enables U2F PAM (pam-u2f) module. + description = lib.mdDoc '' + Enables U2F PAM (`pam-u2f`) module. If set, users listed in - $XDG_CONFIG_HOME/Yubico/u2f_keys (or - $HOME/.config/Yubico/u2f_keys if XDG variable is + {file}`$XDG_CONFIG_HOME/Yubico/u2f_keys` (or + {file}`$HOME/.config/Yubico/u2f_keys` if XDG variable is not set) are able to log in with the associated U2F key. The path can - be changed using option. + be changed using {option}`security.pam.u2f.authFile` option. File format is: - username:first_keyHandle,first_public_key: second_keyHandle,second_public_key - This file can be generated using pamu2fcfg command. + `username:first_keyHandle,first_public_key: second_keyHandle,second_public_key` + This file can be generated using {command}`pamu2fcfg` command. - More information can be found here. + More information can be found [here](https://developers.yubico.com/pam-u2f/). ''; }; authFile = mkOption { default = null; type = with types; nullOr path; - description = '' - By default pam-u2f module reads the keys from - $XDG_CONFIG_HOME/Yubico/u2f_keys (or - $HOME/.config/Yubico/u2f_keys if XDG variable is + description = lib.mdDoc '' + By default `pam-u2f` module reads the keys from + {file}`$XDG_CONFIG_HOME/Yubico/u2f_keys` (or + {file}`$HOME/.config/Yubico/u2f_keys` if XDG variable is not set). If you want to change auth file locations or centralize database (for - example use /etc/u2f-mappings) you can set this + example use {file}`/etc/u2f-mappings`) you can set this option. File format is: - username:first_keyHandle,first_public_key: second_keyHandle,second_public_key - This file can be generated using pamu2fcfg command. + `username:first_keyHandle,first_public_key: second_keyHandle,second_public_key` + This file can be generated using {command}`pamu2fcfg` command. - More information can be found here. + More information can be found [here](https://developers.yubico.com/pam-u2f/). ''; }; appId = mkOption { default = null; type = with types; nullOr str; - description = '' - By default pam-u2f module sets the application - ID to pam://$HOSTNAME. + description = lib.mdDoc '' + By default `pam-u2f` module sets the application + ID to `pam://$HOSTNAME`. - When using pamu2fcfg, you can specify your - application ID with the -i flag. + When using {command}`pamu2fcfg`, you can specify your + application ID with the `-i` flag. - More information can be found here + More information can be found [here](https://developers.yubico.com/pam-u2f/Manuals/pam_u2f.8.html) ''; }; origin = mkOption { default = null; type = with types; nullOr str; - description = '' - By default pam-u2f module sets the origin - to pam://$HOSTNAME. + description = lib.mdDoc '' + By default `pam-u2f` module sets the origin + to `pam://$HOSTNAME`. Setting origin to an host independent value will allow you to reuse credentials across machines - When using pamu2fcfg, you can specify your - application ID with the -o flag. + When using {command}`pamu2fcfg`, you can specify your + application ID with the `-o` flag. - More information can be found here + More information can be found [here](https://developers.yubico.com/pam-u2f/Manuals/pam_u2f.8.html) ''; }; @@ -978,17 +978,17 @@ in enable = mkOption { default = false; type = types.bool; - description = '' - Enables Uber's USSH PAM (pam-ussh) module. + description = lib.mdDoc '' + Enables Uber's USSH PAM (`pam-ussh`) module. - This is similar to pam-ssh-agent, except that + This is similar to `pam-ssh-agent`, except that the presence of a CA-signed SSH key with a valid principal is checked instead. Note that this module must both be enabled using this option and on a - per-PAM-service level as well (using usshAuth). + per-PAM-service level as well (using `usshAuth`). - More information can be found here. + More information can be found [here](https://github.com/uber/pam-ussh). ''; }; @@ -1067,16 +1067,16 @@ in enable = mkOption { default = false; type = types.bool; - description = '' - Enables Yubico PAM (yubico-pam) module. + description = lib.mdDoc '' + Enables Yubico PAM (`yubico-pam`) module. If set, users listed in - ~/.yubico/authorized_yubikeys + {file}`~/.yubico/authorized_yubikeys` are able to log in with the associated Yubikey tokens. The file must have only one line: - username:yubikey_token_id1:yubikey_token_id2 - More information can be found here. + `username:yubikey_token_id1:yubikey_token_id2` + More information can be found [here](https://developers.yubico.com/yubico-pam/). ''; }; control = mkOption { @@ -1111,7 +1111,7 @@ in mode = mkOption { default = "client"; type = types.enum [ "client" "challenge-response" ]; - description = '' + description = lib.mdDoc '' Mode of operation. Use "client" for online validation with a YubiKey validation service such as @@ -1121,16 +1121,16 @@ in Challenge-Response configurations. See the man-page ykpamcfg(1) for further details on how to configure offline Challenge-Response validation. - More information can be found here. + More information can be found [here](https://developers.yubico.com/yubico-pam/Authentication_Using_Challenge-Response.html). ''; }; challengeResponsePath = mkOption { default = null; type = types.nullOr types.path; - description = '' + description = lib.mdDoc '' If not null, set the path used by yubico pam module where the challenge expected response is stored. - More information can be found here. + More information can be found [here](https://developers.yubico.com/yubico-pam/Authentication_Using_Challenge-Response.html). ''; }; }; diff --git a/nixos/modules/security/pam_mount.nix b/nixos/modules/security/pam_mount.nix index ae314abd86c6..11cc13a8cbeb 100644 --- a/nixos/modules/security/pam_mount.nix +++ b/nixos/modules/security/pam_mount.nix @@ -31,9 +31,9 @@ in extraVolumes = mkOption { type = types.listOf types.str; default = []; - description = '' + description = lib.mdDoc '' List of volume definitions for pam_mount. - For more information, visit . + For more information, visit . ''; }; @@ -63,20 +63,20 @@ in type = types.int; default = 0; example = 1; - description = '' + description = lib.mdDoc '' Sets the Debug-Level. 0 disables debugging, 1 enables pam_mount tracing, and 2 additionally enables tracing in mount.crypt. The default is 0. - For more information, visit . + For more information, visit . ''; }; logoutWait = mkOption { type = types.int; default = 0; - description = '' + description = lib.mdDoc '' Amount of microseconds to wait until killing remaining processes after final logout. - For more information, visit . + For more information, visit . ''; }; diff --git a/nixos/modules/security/pam_usb.nix b/nixos/modules/security/pam_usb.nix index 71e2af8f3a51..4275c26c6bda 100644 --- a/nixos/modules/security/pam_usb.nix +++ b/nixos/modules/security/pam_usb.nix @@ -17,9 +17,9 @@ in enable = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Enable USB login for all login systems that support it. For - more information, visit . + more information, visit . ''; }; diff --git a/nixos/modules/security/sudo.nix b/nixos/modules/security/sudo.nix index c1a69aedde45..faa99a31a6d6 100644 --- a/nixos/modules/security/sudo.nix +++ b/nixos/modules/security/sudo.nix @@ -55,19 +55,19 @@ in type = types.bool; default = true; description = - '' - Whether users of the wheel group must - provide a password to run commands as super user via sudo. + lib.mdDoc '' + Whether users of the `wheel` group must + provide a password to run commands as super user via {command}`sudo`. ''; }; security.sudo.execWheelOnly = mkOption { type = types.bool; default = false; - description = '' - Only allow members of the wheel group to execute sudo by + description = lib.mdDoc '' + Only allow members of the `wheel` group to execute sudo by setting the executable's permissions accordingly. - This prevents users that are not members of wheel from + This prevents users that are not members of `wheel` from exploiting vulnerabilities in sudo such as CVE-2021-3156. ''; }; @@ -139,12 +139,12 @@ in runAs = mkOption { type = with types; str; default = "ALL:ALL"; - description = '' + description = lib.mdDoc '' Under which user/group the specified command is allowed to run. - A user can be specified using just the username: "foo". - It is also possible to specify a user/group combination using "foo:bar" - or to only allow running as a specific group with ":bar". + A user can be specified using just the username: `"foo"`. + It is also possible to specify a user/group combination using `"foo:bar"` + or to only allow running as a specific group with `":bar"`. ''; }; diff --git a/nixos/modules/services/backup/restic.nix b/nixos/modules/services/backup/restic.nix index 76d7f093f21c..56958bf949d6 100644 --- a/nixos/modules/services/backup/restic.nix +++ b/nixos/modules/services/backup/restic.nix @@ -227,7 +227,7 @@ in type = types.package; default = pkgs.restic; defaultText = literalExpression "pkgs.restic"; - description = '' + description = lib.mdDoc '' Restic package to use. ''; }; diff --git a/nixos/modules/services/backup/syncoid.nix b/nixos/modules/services/backup/syncoid.nix index 6e71eaa5b9a8..cbfbc59bf5b2 100644 --- a/nixos/modules/services/backup/syncoid.nix +++ b/nixos/modules/services/backup/syncoid.nix @@ -192,7 +192,7 @@ in target = mkOption { type = types.str; example = "user@server:pool/dataset"; - description = '' + description = lib.mdDoc '' Target ZFS dataset. Can be either local («pool/dataset») or remote («user@server:pool/dataset»). diff --git a/nixos/modules/services/backup/zrepl.nix b/nixos/modules/services/backup/zrepl.nix index 7b31b0da0369..ea858a8b77db 100644 --- a/nixos/modules/services/backup/zrepl.nix +++ b/nixos/modules/services/backup/zrepl.nix @@ -22,8 +22,8 @@ in settings = mkOption { default = { }; - description = '' - Configuration for zrepl. See + description = lib.mdDoc '' + Configuration for zrepl. See for more information. ''; type = types.submodule { diff --git a/nixos/modules/services/continuous-integration/github-runner.nix b/nixos/modules/services/continuous-integration/github-runner.nix index 2c753b514c5b..540033823687 100644 --- a/nixos/modules/services/continuous-integration/github-runner.nix +++ b/nixos/modules/services/continuous-integration/github-runner.nix @@ -18,11 +18,11 @@ in enable = mkOption { default = false; example = true; - description = '' + description = lib.mdDoc '' Whether to enable GitHub Actions runner. Note: GitHub recommends using self-hosted runners with private repositories only. Learn more here: - About self-hosted runners. + [About self-hosted runners](https://docs.github.com/en/actions/hosting-your-own-runners/about-self-hosted-runners). ''; type = lib.types.bool; }; diff --git a/nixos/modules/services/continuous-integration/gitlab-runner.nix b/nixos/modules/services/continuous-integration/gitlab-runner.nix index 03d3d2d16e3b..9f076e2d7a23 100644 --- a/nixos/modules/services/continuous-integration/gitlab-runner.nix +++ b/nixos/modules/services/continuous-integration/gitlab-runner.nix @@ -113,15 +113,15 @@ in configFile = mkOption { type = types.nullOr types.path; default = null; - description = '' + description = lib.mdDoc '' Configuration file for gitlab-runner. - takes precedence over . - and will be ignored too. + {option}`configFile` takes precedence over {option}`services`. + {option}`checkInterval` and {option}`concurrent` will be ignored too. - This option is deprecated, please use instead. - You can use and - + This option is deprecated, please use {option}`services` instead. + You can use {option}`registrationConfigFile` and + {option}`registrationFlags` for settings not covered by this module. ''; }; @@ -130,16 +130,16 @@ in freeformType = (pkgs.formats.json { }).type; }; default = { }; - description = '' + description = lib.mdDoc '' Global gitlab-runner configuration. See - + for supported values. ''; }; gracefulTermination = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Finish all remaining jobs before stopping. If not set gitlab-runner will stop immediatly without waiting for jobs to finish, which will lead to failed builds. @@ -149,7 +149,7 @@ in type = types.str; default = "infinity"; example = "5min 20s"; - description = '' + description = lib.mdDoc '' Time to wait until a graceful shutdown is turned into a forceful one. ''; }; @@ -158,17 +158,17 @@ in default = pkgs.gitlab-runner; defaultText = literalExpression "pkgs.gitlab-runner"; example = literalExpression "pkgs.gitlab-runner_1_11"; - description = "Gitlab Runner package to use."; + description = lib.mdDoc "Gitlab Runner package to use."; }; extraPackages = mkOption { type = types.listOf types.package; default = [ ]; - description = '' + description = lib.mdDoc '' Extra packages to add to PATH for the gitlab-runner process. ''; }; services = mkOption { - description = "GitLab Runner services."; + description = lib.mdDoc "GitLab Runner services."; default = { }; example = literalExpression '' { @@ -250,17 +250,17 @@ in options = { registrationConfigFile = mkOption { type = types.path; - description = '' + description = lib.mdDoc '' Absolute path to a file with environment variables used for gitlab-runner registration. A list of all supported environment variables can be found in - gitlab-runner register --help. + `gitlab-runner register --help`. Ones that you probably want to set is - CI_SERVER_URL=<CI server URL> + `CI_SERVER_URL=` - REGISTRATION_TOKEN=<registration secret> + `REGISTRATION_TOKEN=` WARNING: make sure to use quoted absolute path, or it is going to be copied to Nix Store. @@ -270,10 +270,10 @@ in type = types.listOf types.str; default = [ ]; example = [ "--docker-helper-image my/gitlab-runner-helper" ]; - description = '' + description = lib.mdDoc '' Extra command-line flags passed to - gitlab-runner register. - Execute gitlab-runner register --help + `gitlab-runner register`. + Execute `gitlab-runner register --help` for a list of supported flags. ''; }; @@ -281,32 +281,32 @@ in type = types.attrsOf types.str; default = { }; example = { NAME = "value"; }; - description = '' + description = lib.mdDoc '' Custom environment variables injected to build environment. - For secrets you can use - with RUNNER_ENV variable set. + For secrets you can use {option}`registrationConfigFile` + with `RUNNER_ENV` variable set. ''; }; description = mkOption { type = types.nullOr types.str; default = null; - description = '' + description = lib.mdDoc '' Name/description of the runner. ''; }; executor = mkOption { type = types.str; default = "docker"; - description = '' + description = lib.mdDoc '' Select executor, eg. shell, docker, etc. - See runner documentation for more information. + See [runner documentation](https://docs.gitlab.com/runner/executors/README.html) for more information. ''; }; buildsDir = mkOption { type = types.nullOr types.path; default = null; example = "/var/lib/gitlab-runner/builds"; - description = '' + description = lib.mdDoc '' Absolute path to a directory where builds will be stored in context of selected executor (Locally, Docker, SSH). ''; @@ -315,14 +315,14 @@ in type = types.nullOr types.str; default = null; example = "http://gitlab.example.local"; - description = '' + description = lib.mdDoc '' Overwrite the URL for the GitLab instance. Used if the Runner can’t connect to GitLab on the URL GitLab exposes itself. ''; }; dockerImage = mkOption { type = types.nullOr types.str; default = null; - description = '' + description = lib.mdDoc '' Docker image to be used. ''; }; @@ -330,7 +330,7 @@ in type = types.listOf types.str; default = [ ]; example = [ "/var/run/docker.sock:/var/run/docker.sock" ]; - description = '' + description = lib.mdDoc '' Bind-mount a volume and create it if it doesn't exist prior to mounting. ''; @@ -338,14 +338,14 @@ in dockerDisableCache = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Disable all container caching. ''; }; dockerPrivileged = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Give extended privileges to container. ''; }; @@ -353,7 +353,7 @@ in type = types.listOf types.str; default = [ ]; example = [ "other-host:127.0.0.1" ]; - description = '' + description = lib.mdDoc '' Add a custom host-to-IP mapping. ''; }; @@ -361,7 +361,7 @@ in type = types.listOf types.str; default = [ ]; example = [ "ruby:*" "python:*" "php:*" "my.registry.tld:5000/*:*" ]; - description = '' + description = lib.mdDoc '' Whitelist allowed images. ''; }; @@ -369,21 +369,21 @@ in type = types.listOf types.str; default = [ ]; example = [ "postgres:9" "redis:*" "mysql:*" ]; - description = '' + description = lib.mdDoc '' Whitelist allowed services. ''; }; preCloneScript = mkOption { type = types.nullOr types.path; default = null; - description = '' + description = lib.mdDoc '' Runner-specific command script executed before code is pulled. ''; }; preBuildScript = mkOption { type = types.nullOr types.path; default = null; - description = '' + description = lib.mdDoc '' Runner-specific command script executed after code is pulled, just before build executes. ''; @@ -391,7 +391,7 @@ in postBuildScript = mkOption { type = types.nullOr types.path; default = null; - description = '' + description = lib.mdDoc '' Runner-specific command script executed after code is pulled and just after build executes. ''; @@ -399,22 +399,22 @@ in tagList = mkOption { type = types.listOf types.str; default = [ ]; - description = '' + description = lib.mdDoc '' Tag list. ''; }; runUntagged = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Register to run untagged builds; defaults to - true when is empty. + `true` when {option}`tagList` is empty. ''; }; limit = mkOption { type = types.int; default = 0; - description = '' + description = lib.mdDoc '' Limit how many jobs can be handled concurrently by this service. 0 (default) simply means don't limit. ''; @@ -422,14 +422,14 @@ in requestConcurrency = mkOption { type = types.int; default = 0; - description = '' + description = lib.mdDoc '' Limit number of concurrent requests for new jobs from GitLab. ''; }; maximumTimeout = mkOption { type = types.int; default = 0; - description = '' + description = lib.mdDoc '' What is the maximum timeout (in seconds) that will be set for job when using this Runner. 0 (default) simply means don't limit. ''; @@ -437,7 +437,7 @@ in protected = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' When set to true Runner will only run on pipelines triggered on protected branches. ''; @@ -445,9 +445,9 @@ in debugTraceDisabled = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' When set to true Runner will disable the possibility of - using the CI_DEBUG_TRACE feature. + using the `CI_DEBUG_TRACE` feature. ''; }; }; diff --git a/nixos/modules/services/databases/firebird.nix b/nixos/modules/services/databases/firebird.nix index a26f1ff8258f..4aaf4ca12aa6 100644 --- a/nixos/modules/services/databases/firebird.nix +++ b/nixos/modules/services/databases/firebird.nix @@ -47,9 +47,9 @@ in defaultText = literalExpression "pkgs.firebird"; type = types.package; example = literalExpression "pkgs.firebird_3"; - description = '' - Which Firebird package to be installed: pkgs.firebird_3 - For SuperServer use override: pkgs.firebird_3.override { superServer = true; }; + description = lib.mdDoc '' + Which Firebird package to be installed: `pkgs.firebird_3` + For SuperServer use override: `pkgs.firebird_3.override { superServer = true; };` ''; }; diff --git a/nixos/modules/services/databases/mysql.nix b/nixos/modules/services/databases/mysql.nix index 1e6a6b844a37..1a096d2a88a4 100644 --- a/nixos/modules/services/databases/mysql.nix +++ b/nixos/modules/services/databases/mysql.nix @@ -201,7 +201,7 @@ in ensurePermissions = mkOption { type = types.attrsOf types.str; default = {}; - description = '' + description = lib.mdDoc '' Permissions to ensure for the user, specified as attribute set. The attribute names specify the database and tables to grant the permissions for, separated by a dot. You may use wildcards here. @@ -210,8 +210,8 @@ in For more information on how to specify the target and on which privileges exist, see the - GRANT syntax. - The attributes are used as GRANT ''${attrName} ON ''${attrValue}. + [GRANT syntax](https://mariadb.com/kb/en/library/grant/). + The attributes are used as `GRANT ''${attrName} ON ''${attrValue}`. ''; example = literalExpression '' { diff --git a/nixos/modules/services/databases/neo4j.nix b/nixos/modules/services/databases/neo4j.nix index ad659ccd82e8..d1be4034ddac 100644 --- a/nixos/modules/services/databases/neo4j.nix +++ b/nixos/modules/services/databases/neo4j.nix @@ -139,14 +139,14 @@ in { constrainLoadCsv = mkOption { type = types.bool; default = true; - description = '' + description = lib.mdDoc '' Sets the root directory for file URLs used with the Cypher - LOAD CSV clause to be that defined by - . It restricts + `LOAD CSV` clause to be that defined by + {option}`directories.imports`. It restricts access to only those files within that directory and its subdirectories. - Setting this option to false introduces + Setting this option to `false` introduces possible security problems. ''; }; @@ -154,14 +154,14 @@ in { defaultListenAddress = mkOption { type = types.str; default = "127.0.0.1"; - description = '' + description = lib.mdDoc '' Default network interface to listen for incoming connections. To listen for connections on all interfaces, use "0.0.0.0". Specifies the default IP address and address part of connector - specific options. To bind specific + specific {option}`listenAddress` options. To bind specific connectors to a specific network interfaces, specify the entire - option for that connector. + {option}`listenAddress` option for that connector. ''; }; @@ -225,18 +225,18 @@ in { sslPolicy = mkOption { type = types.str; default = "legacy"; - description = '' + description = lib.mdDoc '' Neo4j SSL policy for BOLT traffic. The legacy policy is a special policy which is not defined in the policy configuration section, but rather derives from - and - associated files (by default: neo4j.key and - neo4j.cert). Its use will be deprecated. + {option}`directories.certificates` and + associated files (by default: {file}`neo4j.key` and + {file}`neo4j.cert`). Its use will be deprecated. Note: This connector must be configured to support/require SSL/TLS for the legacy policy to actually be utilized. See - . + {option}`bolt.tlsLevel`. ''; }; @@ -254,19 +254,19 @@ in { type = types.path; default = "${cfg.directories.home}/certificates"; defaultText = literalExpression ''"''${config.${opt.directories.home}}/certificates"''; - description = '' + description = lib.mdDoc '' Directory for storing certificates to be used by Neo4j for TLS connections. When setting this directory to something other than its default, ensure the directory's existence, and that read/write permissions are - given to the Neo4j daemon user neo4j. + given to the Neo4j daemon user `neo4j`. Note that changing this directory from its default will prevent the directory structure required for each SSL policy from being automatically generated. A policy's directory structure as defined by - its , and - must then be setup manually. The + its {option}`baseDirectory`,{option}`revokedDir` and + {option}`trustedDir` must then be setup manually. The existence of these directories is mandatory, as well as the presence of the certificate file and the private key. Ensure the correct permissions are set on these directories and files. @@ -277,13 +277,13 @@ in { type = types.path; default = "${cfg.directories.home}/data"; defaultText = literalExpression ''"''${config.${opt.directories.home}}/data"''; - description = '' + description = lib.mdDoc '' Path of the data directory. You must not configure more than one Neo4j installation to use the same data directory. When setting this directory to something other than its default, ensure the directory's existence, and that read/write permissions are - given to the Neo4j daemon user neo4j. + given to the Neo4j daemon user `neo4j`. ''; }; @@ -302,15 +302,15 @@ in { type = types.path; default = "${cfg.directories.home}/import"; defaultText = literalExpression ''"''${config.${opt.directories.home}}/import"''; - description = '' + description = lib.mdDoc '' The root directory for file URLs used with the Cypher - LOAD CSV clause. Only meaningful when - is set to - true. + `LOAD CSV` clause. Only meaningful when + {option}`constrainLoadCvs` is set to + `true`. When setting this directory to something other than its default, ensure the directory's existence, and that read permission is - given to the Neo4j daemon user neo4j. + given to the Neo4j daemon user `neo4j`. ''; }; @@ -318,14 +318,14 @@ in { type = types.path; default = "${cfg.directories.home}/plugins"; defaultText = literalExpression ''"''${config.${opt.directories.home}}/plugins"''; - description = '' + description = lib.mdDoc '' Path of the database plugin directory. Compiled Java JAR files that contain database procedures will be loaded if they are placed in this directory. When setting this directory to something other than its default, ensure the directory's existence, and that read permission is - given to the Neo4j daemon user neo4j. + given to the Neo4j daemon user `neo4j`. ''; }; }; @@ -377,14 +377,14 @@ in { sslPolicy = mkOption { type = types.str; default = "legacy"; - description = '' + description = lib.mdDoc '' Neo4j SSL policy for HTTPS traffic. The legacy policy is a special policy which is not defined in the policy configuration section, but rather derives from - and - associated files (by default: neo4j.key and - neo4j.cert). Its use will be deprecated. + {option}`directories.certificates` and + associated files (by default: {file}`neo4j.key` and + {file}`neo4j.cert`). Its use will be deprecated. ''; }; }; @@ -407,7 +407,7 @@ in { allowKeyGeneration = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Allows the generation of a private key and associated self-signed certificate. Only performed when both objects cannot be found for this policy. It is recommended to turn this off again after keys @@ -415,7 +415,7 @@ in { The public certificate is required to be duplicated to the directory holding trusted certificates as defined by the - option. + {option}`trustedDir` option. Keys should in general be generated and distributed offline by a trusted certificate authority and not by utilizing this mode. @@ -426,16 +426,16 @@ in { type = types.path; default = "${cfg.directories.certificates}/${name}"; defaultText = literalExpression ''"''${config.${opt.directories.certificates}}/''${name}"''; - description = '' + description = lib.mdDoc '' The mandatory base directory for cryptographic objects of this policy. This path is only automatically generated when this - option as well as are + option as well as {option}`directories.certificates` are left at their default. Ensure read/write permissions are given - to the Neo4j daemon user neo4j. + to the Neo4j daemon user `neo4j`. It is also possible to override each individual configuration with absolute paths. See the - and + {option}`privateKey` and {option}`publicCertificate` policy options. ''; }; @@ -470,15 +470,15 @@ in { publicCertificate = mkOption { type = types.str; default = "public.crt"; - description = '' + description = lib.mdDoc '' The name of public X.509 certificate (chain) file in PEM format - for this policy to be found in the , + for this policy to be found in the {option}`baseDirectory`, or the absolute path to the certificate file. It is mandatory that a certificate can be found or generated. The public certificate is required to be duplicated to the directory holding trusted certificates as defined by the - option. + {option}`trustedDir` option. ''; }; @@ -522,18 +522,18 @@ in { type = types.path; default = "${config.baseDirectory}/trusted"; defaultText = literalExpression ''"''${config.${options.baseDirectory}}/trusted"''; - description = '' + description = lib.mdDoc '' Path to directory of X.509 certificates in PEM format for trusted parties. Must be an absolute path. The existence of this directory is mandatory and will need to be created manually when: setting this option to something other than its default; setting - either this policy's or - to something other than + either this policy's {option}`baseDirectory` or + {option}`directories.certificates` to something other than their default. Ensure read/write permissions are given to the - Neo4j daemon user neo4j. + Neo4j daemon user `neo4j`. The public certificate as defined by - is required to be duplicated + {option}`publicCertificate` is required to be duplicated to this directory. ''; }; diff --git a/nixos/modules/services/databases/openldap.nix b/nixos/modules/services/databases/openldap.nix index 94fc155000e2..7a59de372f24 100644 --- a/nixos/modules/services/databases/openldap.nix +++ b/nixos/modules/services/databases/openldap.nix @@ -88,7 +88,7 @@ in { enable = mkOption { type = types.bool; default = false; - description = "Whether to enable the ldap server."; + description = lib.mdDoc "Whether to enable the ldap server."; }; package = mkOption { @@ -173,9 +173,9 @@ in { configDir = mkOption { type = types.nullOr types.path; default = null; - description = '' + description = lib.mdDoc '' Use this config directory instead of generating one from the - settings option. Overrides all NixOS settings. + `settings` option. Overrides all NixOS settings. ''; example = "/var/lib/openldap/slapd.d"; }; @@ -183,9 +183,9 @@ in { mutableConfig = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Whether to allow writable on-line configuration. If - true, the NixOS settings will only be used to + `true`, the NixOS settings will only be used to initialize the OpenLDAP configuration if it does not exist, and are subsequently ignored. ''; diff --git a/nixos/modules/services/databases/pgmanage.nix b/nixos/modules/services/databases/pgmanage.nix index 79c958b246c7..9ce2265a4dee 100644 --- a/nixos/modules/services/databases/pgmanage.nix +++ b/nixos/modules/services/databases/pgmanage.nix @@ -62,11 +62,11 @@ in { nuc-server = "hostaddr=192.168.0.100 port=5432 dbname=postgres"; mini-server = "hostaddr=127.0.0.1 port=5432 dbname=postgres sslmode=require"; }; - description = '' + description = lib.mdDoc '' pgmanage requires at least one PostgreSQL server be defined. Detailed information about PostgreSQL connection strings is available at: - + Note that you should not specify your user name or password. That information will be entered on the login screen. If you specify a diff --git a/nixos/modules/services/databases/postgresql.nix b/nixos/modules/services/databases/postgresql.nix index 8225a9aaba61..d0135647d6af 100644 --- a/nixos/modules/services/databases/postgresql.nix +++ b/nixos/modules/services/databases/postgresql.nix @@ -149,7 +149,7 @@ in ensurePermissions = mkOption { type = types.attrsOf types.str; default = {}; - description = '' + description = lib.mdDoc '' Permissions to ensure for the user, specified as an attribute set. The attribute names specify the database and tables to grant the permissions for. The attribute values specify the permissions to grant. You may specify one or @@ -157,8 +157,8 @@ in For more information on how to specify the target and on which privileges exist, see the - GRANT syntax. - The attributes are used as GRANT ''${attrValue} ON ''${attrName}. + [GRANT syntax](https://www.postgresql.org/docs/current/sql-grant.html). + The attributes are used as `GRANT ''${attrValue} ON ''${attrName}`. ''; example = literalExpression '' { diff --git a/nixos/modules/services/databases/victoriametrics.nix b/nixos/modules/services/databases/victoriametrics.nix index 4e002b3df7c7..f87a5862f641 100644 --- a/nixos/modules/services/databases/victoriametrics.nix +++ b/nixos/modules/services/databases/victoriametrics.nix @@ -28,10 +28,10 @@ let cfg = config.services.victoriametrics; in extraOptions = mkOption { type = types.listOf types.str; default = []; - description = '' + description = lib.mdDoc '' Extra options to pass to VictoriaMetrics. See the README: - - or victoriametrics -help for more + + or {command}`victoriametrics -help` for more information. ''; }; diff --git a/nixos/modules/services/games/asf.nix b/nixos/modules/services/games/asf.nix index 6939e15c207d..b7892900376f 100644 --- a/nixos/modules/services/games/asf.nix +++ b/nixos/modules/services/games/asf.nix @@ -136,8 +136,8 @@ in }; settings = mkOption { type = types.attrs; - description = '' - Additional settings that are documented here. + description = lib.mdDoc '' + Additional settings that are documented [here](https://github.com/JustArchiNET/ArchiSteamFarm/wiki/Configuration#bot-config). ''; default = { }; }; diff --git a/nixos/modules/services/hardware/kanata.nix b/nixos/modules/services/hardware/kanata.nix index f8250afa4a00..c7cd3c9d2eb9 100644 --- a/nixos/modules/services/hardware/kanata.nix +++ b/nixos/modules/services/hardware/kanata.nix @@ -10,7 +10,7 @@ let device = mkOption { type = types.str; example = "/dev/input/by-id/usb-0000_0000-event-kbd"; - description = "Path to the keyboard device."; + description = lib.mdDoc "Path to the keyboard device."; }; config = mkOption { type = types.lines; @@ -33,18 +33,18 @@ let ;; tap within 100ms for capslk, hold more than 100ms for lctl cap (tap-hold 100 100 caps lctl)) ''; - description = '' + description = lib.mdDoc '' Configuration other than defcfg. - See for more information. + See for more information. ''; }; extraDefCfg = mkOption { type = types.lines; default = ""; example = "danger-enable-cmd yes"; - description = '' + description = lib.mdDoc '' Configuration of defcfg other than linux-dev. - See for more information. + See for more information. ''; }; }; @@ -131,7 +131,7 @@ in default = pkgs.kanata; defaultText = lib.literalExpression "pkgs.kanata"; example = lib.literalExpression "pkgs.kanata-with-cmd"; - description = '' + description = lib.mdDoc '' kanata package to use. If you enable danger-enable-cmd, pkgs.kanata-with-cmd should be used. ''; @@ -139,7 +139,7 @@ in keyboards = mkOption { type = types.attrsOf (types.submodule keyboard); default = { }; - description = "Keyboard configurations."; + description = lib.mdDoc "Keyboard configurations."; }; }; diff --git a/nixos/modules/services/hardware/udev.nix b/nixos/modules/services/hardware/udev.nix index f745e2f7f606..1723cb508485 100644 --- a/nixos/modules/services/hardware/udev.nix +++ b/nixos/modules/services/hardware/udev.nix @@ -209,11 +209,11 @@ in packages = mkOption { type = types.listOf types.path; default = []; - description = '' - List of packages containing udev rules. + description = lib.mdDoc '' + List of packages containing {command}`udev` rules. All files found in - «pkg»/etc/udev/rules.d and - «pkg»/lib/udev/rules.d + {file}`«pkg»/etc/udev/rules.d` and + {file}`«pkg»/lib/udev/rules.d` will be included. ''; apply = map getBin; @@ -281,15 +281,15 @@ in networking.usePredictableInterfaceNames = mkOption { default = true; type = types.bool; - description = '' - Whether to assign predictable names to network interfaces. + description = lib.mdDoc '' + Whether to assign [predictable names to network interfaces](http://www.freedesktop.org/wiki/Software/systemd/PredictableNetworkInterfaceNames). If enabled, interfaces are assigned names that contain topology information - (e.g. wlp3s0) and thus should be stable + (e.g. `wlp3s0`) and thus should be stable across reboots. If disabled, names depend on the order in which interfaces are discovered by the kernel, which may change randomly across reboots; for instance, you may find - eth0 and eth1 flipping + `eth0` and `eth1` flipping unpredictably. ''; }; diff --git a/nixos/modules/services/logging/filebeat.nix b/nixos/modules/services/logging/filebeat.nix index 045cd1147ead..3dc9df372ac5 100644 --- a/nixos/modules/services/logging/filebeat.nix +++ b/nixos/modules/services/logging/filebeat.nix @@ -31,20 +31,20 @@ in }; inputs = mkOption { - description = '' + description = lib.mdDoc '' Inputs specify how Filebeat locates and processes input data. - This is like services.filebeat.settings.filebeat.inputs, + This is like `services.filebeat.settings.filebeat.inputs`, but structured as an attribute set. This has the benefit that multiple NixOS modules can contribute settings to a single filebeat input. An input type can be specified multiple times by choosing a - different <name> for each, but setting - + different `` for each, but setting + [](#opt-services.filebeat.inputs._name_.type) to the same value. - See . + See . ''; default = {}; type = types.attrsOf (types.submodule ({ name, ... }: { @@ -77,24 +77,24 @@ in }; modules = mkOption { - description = '' + description = lib.mdDoc '' Filebeat modules provide a quick way to get started processing common log formats. They contain default configurations, Elasticsearch ingest pipeline definitions, and Kibana dashboards to help you implement and deploy a log monitoring solution. - This is like services.filebeat.settings.filebeat.modules, + This is like `services.filebeat.settings.filebeat.modules`, but structured as an attribute set. This has the benefit that multiple NixOS modules can contribute settings to a single filebeat module. A module can be specified multiple times by choosing a - different <name> for each, but setting - + different `` for each, but setting + [](#opt-services.filebeat.modules._name_.module) to the same value. - See . + See . ''; default = {}; type = types.attrsOf (types.submodule ({ name, ... }: { diff --git a/nixos/modules/services/logging/logrotate.nix b/nixos/modules/services/logging/logrotate.nix index a6eb08ac5eac..53230cc51e59 100644 --- a/nixos/modules/services/logging/logrotate.nix +++ b/nixos/modules/services/logging/logrotate.nix @@ -276,9 +276,9 @@ in defaultText = '' A configuration file automatically generated by NixOS. ''; - description = '' + description = lib.mdDoc '' Override the configuration file used by MySQL. By default, - NixOS generates one automatically from . + NixOS generates one automatically from [](#opt-services.logrotate.settings). ''; example = literalExpression '' pkgs.writeText "logrotate.conf" ''' @@ -346,11 +346,11 @@ in extraConfig = mkOption { default = ""; type = types.lines; - description = '' + description = lib.mdDoc '' Extra contents to append to the logrotate configuration file. Refer to - for details. + for details. This setting has been deprecated in favor of - logrotate settings. + [logrotate settings](#opt-services.logrotate.settings). ''; }; }; diff --git a/nixos/modules/services/mail/mailman.nix b/nixos/modules/services/mail/mailman.nix index c3eb61bd20d7..c76d40a68c3c 100644 --- a/nixos/modules/services/mail/mailman.nix +++ b/nixos/modules/services/mail/mailman.nix @@ -112,9 +112,9 @@ in { bindPasswordFile = mkOption { type = types.str; example = "/run/secrets/ldap-bind"; - description = '' + description = lib.mdDoc '' Path to the file containing the bind password of the servie account - defined by . + defined by [](#opt-services.mailman.ldap.bindDn). ''; }; superUserGroup = mkOption { diff --git a/nixos/modules/services/mail/nullmailer.nix b/nixos/modules/services/mail/nullmailer.nix index c37001e35bfa..336c76c98508 100644 --- a/nixos/modules/services/mail/nullmailer.nix +++ b/nixos/modules/services/mail/nullmailer.nix @@ -38,11 +38,11 @@ with lib; remotesFile = mkOption { type = types.nullOr types.str; default = null; - description = '' - Path to the remotes control file. This file contains a + description = lib.mdDoc '' + Path to the `remotes` control file. This file contains a list of remote servers to which to send each message. - See man 8 nullmailer-send for syntax and available + See `man 8 nullmailer-send` for syntax and available options. ''; }; @@ -153,17 +153,17 @@ with lib; remotes = mkOption { type = types.nullOr types.str; default = null; - description = '' + description = lib.mdDoc '' A list of remote servers to which to send each message. Each line contains a remote host name or address followed by an optional protocol string, separated by white space. - See man 8 nullmailer-send for syntax and available + See `man 8 nullmailer-send` for syntax and available options. WARNING: This is stored world-readable in the nix store. If you need to specify any secret credentials here, consider using the - remotesFile option instead. + `remotesFile` option instead. ''; }; diff --git a/nixos/modules/services/mail/postfixadmin.nix b/nixos/modules/services/mail/postfixadmin.nix index 27b5c60ec072..b86428770cb2 100644 --- a/nixos/modules/services/mail/postfixadmin.nix +++ b/nixos/modules/services/mail/postfixadmin.nix @@ -13,12 +13,12 @@ in enable = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Whether to enable postfixadmin. Also enables nginx virtual host management. - Further nginx configuration can be done by adapting services.nginx.virtualHosts.<name>. - See for further information. + Further nginx configuration can be done by adapting `services.nginx.virtualHosts.`. + See [](#opt-services.nginx.virtualHosts) for further information. ''; }; diff --git a/nixos/modules/services/mail/public-inbox.nix b/nixos/modules/services/mail/public-inbox.nix index 6f33283b548b..a81dd1cdb37b 100644 --- a/nixos/modules/services/mail/public-inbox.nix +++ b/nixos/modules/services/mail/public-inbox.nix @@ -23,10 +23,10 @@ let port = mkOption { type = with types; nullOr (either str port); default = defaultPort; - description = '' + description = lib.mdDoc '' Listening port. Beware that public-inbox uses well-known ports number to decide whether to enable TLS or not. - Set to null and use systemd.sockets.public-inbox-${proto}d.listenStreams + Set to null and use `systemd.sockets.public-inbox-${proto}d.listenStreams` if you need a more advanced listening. ''; }; @@ -239,11 +239,11 @@ in type = with types; nullOr (either str port); default = 80; example = "/run/public-inbox-httpd.sock"; - description = '' + description = lib.mdDoc '' Listening port or systemd's ListenStream= entry to be used as a reverse proxy, eg. in nginx: - locations."/inbox".proxyPass = "http://unix:''${config.services.public-inbox.http.port}:/inbox"; - Set to null and use systemd.sockets.public-inbox-httpd.listenStreams + `locations."/inbox".proxyPass = "http://unix:''${config.services.public-inbox.http.port}:/inbox";` + Set to null and use `systemd.sockets.public-inbox-httpd.listenStreams` if you need a more advanced listening. ''; }; diff --git a/nixos/modules/services/mail/roundcube.nix b/nixos/modules/services/mail/roundcube.nix index 3b6c06d19e86..d8adf53e48a9 100644 --- a/nixos/modules/services/mail/roundcube.nix +++ b/nixos/modules/services/mail/roundcube.nix @@ -14,12 +14,12 @@ in enable = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Whether to enable roundcube. Also enables nginx virtual host management. - Further nginx configuration can be done by adapting services.nginx.virtualHosts.<name>. - See for further information. + Further nginx configuration can be done by adapting `services.nginx.virtualHosts.`. + See [](#opt-services.nginx.virtualHosts) for further information. ''; }; @@ -99,11 +99,11 @@ in maxAttachmentSize = mkOption { type = types.int; default = 18; - description = '' + description = lib.mdDoc '' The maximum attachment size in MB. Note: Since roundcube only uses 70% of max upload values configured in php - 30% is added automatically to . + 30% is added automatically to [](#opt-services.roundcube.maxAttachmentSize). ''; apply = configuredMaxAttachmentSize: "${toString (configuredMaxAttachmentSize * 1.3)}M"; }; diff --git a/nixos/modules/services/mail/sympa.nix b/nixos/modules/services/mail/sympa.nix index 0a2a885a80f6..0014701d5831 100644 --- a/nixos/modules/services/mail/sympa.nix +++ b/nixos/modules/services/mail/sympa.nix @@ -86,9 +86,9 @@ in type = str; default = "en_US"; example = "cs"; - description = '' + description = lib.mdDoc '' Default Sympa language. - See + See for available options. ''; }; @@ -136,9 +136,9 @@ in example = { default_max_list_members = 3; }; - description = '' - The robot.conf configuration file as key value set. - See + description = lib.mdDoc '' + The {file}`robot.conf` configuration file as key value set. + See for list of configuration parameters. ''; }; @@ -285,9 +285,9 @@ in viewlogs_page_size = 50; } ''; - description = '' - The sympa.conf configuration file as key value set. - See + description = lib.mdDoc '' + The {file}`sympa.conf` configuration file as key value set. + See for list of configuration parameters. ''; }; diff --git a/nixos/modules/services/matrix/appservice-discord.nix b/nixos/modules/services/matrix/appservice-discord.nix index 87a706ae95ef..c72a2123a923 100644 --- a/nixos/modules/services/matrix/appservice-discord.nix +++ b/nixos/modules/services/matrix/appservice-discord.nix @@ -40,16 +40,16 @@ in { }; } ''; - description = '' - config.yaml configuration as a Nix attribute set. + description = lib.mdDoc '' + {file}`config.yaml` configuration as a Nix attribute set. Configuration options should match those described in - config.sample.yaml. + [config.sample.yaml](https://github.com/Half-Shot/matrix-appservice-discord/blob/master/config/config.sample.yaml). - and + {option}`config.bridge.domain` and {option}`config.bridge.homeserverUrl` should be set to match the public host name of the Matrix homeserver for webhooks and avatars to work. - Secret tokens should be specified using + Secret tokens should be specified using {option}`environmentFile` instead of this world-readable attribute set. ''; }; diff --git a/nixos/modules/services/matrix/mautrix-facebook.nix b/nixos/modules/services/matrix/mautrix-facebook.nix index 384a4f4a706f..dfdf6e250215 100644 --- a/nixos/modules/services/matrix/mautrix-facebook.nix +++ b/nixos/modules/services/matrix/mautrix-facebook.nix @@ -75,12 +75,12 @@ in { }; } ''; - description = '' - config.yaml configuration as a Nix attribute set. + description = lib.mdDoc '' + {file}`config.yaml` configuration as a Nix attribute set. Configuration options should match those described in - example-config.yaml. + [example-config.yaml](https://github.com/mautrix/facebook/blob/master/mautrix_facebook/example-config.yaml). - Secret tokens should be specified using + Secret tokens should be specified using {option}`environmentFile` instead of this world-readable attribute set. ''; }; diff --git a/nixos/modules/services/matrix/mautrix-telegram.nix b/nixos/modules/services/matrix/mautrix-telegram.nix index 492ed1b24bce..196100a531ad 100644 --- a/nixos/modules/services/matrix/mautrix-telegram.nix +++ b/nixos/modules/services/matrix/mautrix-telegram.nix @@ -78,12 +78,12 @@ in { }; } ''; - description = '' - config.yaml configuration as a Nix attribute set. + description = lib.mdDoc '' + {file}`config.yaml` configuration as a Nix attribute set. Configuration options should match those described in - example-config.yaml. + [example-config.yaml](https://github.com/tulir/mautrix-telegram/blob/master/example-config.yaml). - Secret tokens should be specified using + Secret tokens should be specified using {option}`environmentFile` instead of this world-readable attribute set. ''; }; diff --git a/nixos/modules/services/misc/autorandr.nix b/nixos/modules/services/misc/autorandr.nix index a77535cca49e..036bb4f41bef 100644 --- a/nixos/modules/services/misc/autorandr.nix +++ b/nixos/modules/services/misc/autorandr.nix @@ -27,9 +27,9 @@ let options = { fingerprint = mkOption { type = types.attrsOf types.str; - description = '' + description = lib.mdDoc '' Output name to EDID mapping. - Use autorandr --fingerprint to get current setup values. + Use `autorandr --fingerprint` to get current setup values. ''; default = { }; }; diff --git a/nixos/modules/services/misc/bees.nix b/nixos/modules/services/misc/bees.nix index 2adc9f2a1fa6..37f90c682221 100644 --- a/nixos/modules/services/misc/bees.nix +++ b/nixos/modules/services/misc/bees.nix @@ -11,7 +11,7 @@ let fsOptions = with types; { options.spec = mkOption { type = str; - description = '' + description = lib.mdDoc '' Description of how to identify the filesystem to be duplicated by this instance of bees. Note that deduplication crosses subvolumes; one must not configure multiple instances for subvolumes of the same filesystem @@ -28,7 +28,7 @@ let options.hashTableSizeMB = mkOption { type = types.addCheck types.int (n: mod n 16 == 0); default = 1024; # 1GB; default from upstream beesd script - description = '' + description = lib.mdDoc '' Hash table size in MB; must be a multiple of 16. A larger ratio of index size to storage size means smaller blocks of diff --git a/nixos/modules/services/misc/etcd.nix b/nixos/modules/services/misc/etcd.nix index d0c82d726023..3343e94778a2 100644 --- a/nixos/modules/services/misc/etcd.nix +++ b/nixos/modules/services/misc/etcd.nix @@ -125,9 +125,9 @@ in { }; extraConf = mkOption { - description = '' + description = lib.mdDoc '' Etcd extra configuration. See - + ''; type = types.attrsOf types.str; default = {}; diff --git a/nixos/modules/services/misc/klipper.nix b/nixos/modules/services/misc/klipper.nix index 52913369bbcd..b34ca6f8c5d2 100644 --- a/nixos/modules/services/misc/klipper.nix +++ b/nixos/modules/services/misc/klipper.nix @@ -71,7 +71,7 @@ in }; firmwares = mkOption { - description = "Firmwares klipper should manage"; + description = lib.mdDoc "Firmwares klipper should manage"; default = { }; type = with types; attrsOf (submodule { diff --git a/nixos/modules/services/misc/sssd.nix b/nixos/modules/services/misc/sssd.nix index 3f6b96258f16..70afbe0433ae 100644 --- a/nixos/modules/services/misc/sssd.nix +++ b/nixos/modules/services/misc/sssd.nix @@ -42,7 +42,7 @@ in { kcm = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Whether to use SSS as a Kerberos Cache Manager (KCM). Kerberos will be configured to cache credentials in SSS. ''; diff --git a/nixos/modules/services/monitoring/cadvisor.nix b/nixos/modules/services/monitoring/cadvisor.nix index 7374b1ece495..d5e440310162 100644 --- a/nixos/modules/services/monitoring/cadvisor.nix +++ b/nixos/modules/services/monitoring/cadvisor.nix @@ -66,16 +66,16 @@ in { storageDriverPasswordFile = mkOption { type = types.str; - description = '' + description = lib.mdDoc '' File that contains the cadvisor storage driver password. - takes precedence over + {option}`storageDriverPasswordFile` takes precedence over {option}`storageDriverPassword` - Warning: when is non-empty this defaults to a file in the - world-readable Nix store that contains the value of . + Warning: when {option}`storageDriverPassword` is non-empty this defaults to a file in the + world-readable Nix store that contains the value of {option}`storageDriverPassword`. It's recommended to override this with a path not in the Nix store. - Tip: use nixops key management + Tip: use [nixops key management](https://nixos.org/nixops/manual/#idm140737318306400) ''; }; @@ -88,10 +88,10 @@ in { extraOptions = mkOption { type = types.listOf types.str; default = []; - description = '' + description = lib.mdDoc '' Additional cadvisor options. - See for available options. + See for available options. ''; }; }; diff --git a/nixos/modules/services/monitoring/graphite.nix b/nixos/modules/services/monitoring/graphite.nix index 0905b4b57fb9..8edb2ca09974 100644 --- a/nixos/modules/services/monitoring/graphite.nix +++ b/nixos/modules/services/monitoring/graphite.nix @@ -251,9 +251,9 @@ in { extraConfig = mkOption { default = {}; - description = '' + description = lib.mdDoc '' Extra seyren configuration. See - + ''; type = types.attrsOf types.str; example = literalExpression '' diff --git a/nixos/modules/services/monitoring/metricbeat.nix b/nixos/modules/services/monitoring/metricbeat.nix index 0968d25c2ad2..14066da1be81 100644 --- a/nixos/modules/services/monitoring/metricbeat.nix +++ b/nixos/modules/services/monitoring/metricbeat.nix @@ -32,17 +32,17 @@ in }; modules = mkOption { - description = '' + description = lib.mdDoc '' Metricbeat modules are responsible for reading metrics from the various sources. - This is like services.metricbeat.settings.metricbeat.modules, + This is like `services.metricbeat.settings.metricbeat.modules`, but structured as an attribute set. This has the benefit that multiple NixOS modules can contribute settings to a single metricbeat module. - A module can be specified multiple times by choosing a different <name> - for each, but setting to the same value. + A module can be specified multiple times by choosing a different `` + for each, but setting [](#opt-services.metricbeat.modules._name_.module) to the same value. - See . + See . ''; default = {}; type = types.attrsOf (types.submodule ({ name, ... }: { diff --git a/nixos/modules/services/monitoring/munin.nix b/nixos/modules/services/monitoring/munin.nix index 3455d0d3d4a6..9461bd3f35b8 100644 --- a/nixos/modules/services/monitoring/munin.nix +++ b/nixos/modules/services/monitoring/munin.nix @@ -138,29 +138,29 @@ in enable = mkOption { default = false; type = types.bool; - description = '' + description = lib.mdDoc '' Enable Munin Node agent. Munin node listens on 0.0.0.0 and by default accepts connections only from 127.0.0.1 for security reasons. - See . + See . ''; }; extraConfig = mkOption { default = ""; type = types.lines; - description = '' - munin-node.conf extra configuration. See - + description = lib.mdDoc '' + {file}`munin-node.conf` extra configuration. See + ''; }; extraPluginConfig = mkOption { default = ""; type = types.lines; - description = '' - plugin-conf.d extra plugin configuration. See - + description = lib.mdDoc '' + {file}`plugin-conf.d` extra plugin configuration. See + ''; example = '' [fail2ban_*] @@ -266,11 +266,11 @@ in extraGlobalConfig = mkOption { default = ""; type = types.lines; - description = '' - munin.conf extra global configuration. - See . + description = lib.mdDoc '' + {file}`munin.conf` extra global configuration. + See . Useful to setup notifications, see - + ''; example = '' contact.email.command mail -s "Munin notification for ''${var:host}" someone@example.com @@ -280,10 +280,10 @@ in hosts = mkOption { default = ""; type = types.lines; - description = '' + description = lib.mdDoc '' Definitions of hosts of nodes to collect data from. Needs at least one host for cron to succeed. See - + ''; example = literalExpression '' ''' diff --git a/nixos/modules/services/monitoring/netdata.nix b/nixos/modules/services/monitoring/netdata.nix index 661b38b4c5a2..e20eaf3b1440 100644 --- a/nixos/modules/services/monitoring/netdata.nix +++ b/nixos/modules/services/monitoring/netdata.nix @@ -114,13 +114,13 @@ in { example = literalExpression '' [ "/path/to/plugins.d" ] ''; - description = '' + description = lib.mdDoc '' Extra paths to add to the netdata global "plugins directory" option. Useful for when you want to include your own collection scripts. Details about writing a custom netdata plugin are available at: - + Cannot be combined with configText. ''; diff --git a/nixos/modules/services/monitoring/parsedmarc.nix b/nixos/modules/services/monitoring/parsedmarc.nix index 60ebbd6f7525..b0858184b5fc 100644 --- a/nixos/modules/services/monitoring/parsedmarc.nix +++ b/nixos/modules/services/monitoring/parsedmarc.nix @@ -29,11 +29,11 @@ in enable = lib.mkOption { type = lib.types.bool; default = false; - description = '' + description = lib.mdDoc '' Whether Postfix and Dovecot should be set up to receive mail locally. parsedmarc will be configured to watch the local inbox as the automatically created user specified in - + [](#opt-services.parsedmarc.provision.localMail.recipientName) ''; }; @@ -68,13 +68,13 @@ in geoIp = lib.mkOption { type = lib.types.bool; default = true; - description = '' - Whether to enable and configure the geoipupdate + description = lib.mdDoc '' + Whether to enable and configure the [geoipupdate](#opt-services.geoipupdate.enable) service to automatically fetch GeoIP databases. Not crucial, but recommended for full functionality. - To finish the setup, you need to manually set the and - + To finish the setup, you need to manually set the [](#opt-services.geoipupdate.settings.AccountID) and + [](#opt-services.geoipupdate.settings.LicenseKey) options. ''; }; @@ -95,11 +95,11 @@ in config.${opt.provision.elasticsearch} && config.${options.services.grafana.enable} ''; apply = x: x && cfg.provision.elasticsearch; - description = '' + description = lib.mdDoc '' Whether the automatically provisioned Elasticsearch instance should be added as a grafana datasource. Has no effect unless - + [](#opt-services.parsedmarc.provision.elasticsearch) is also enabled. ''; }; @@ -206,12 +206,12 @@ in password = lib.mkOption { type = with lib.types; nullOr (either path (attrsOf path)); default = null; - description = '' + description = lib.mdDoc '' The IMAP server password. Always handled as a secret whether the value is - wrapped in a { _secret = ...; } - attrset or not (refer to for + wrapped in a `{ _secret = ...; }` + attrset or not (refer to [](#opt-services.parsedmarc.settings) for details). ''; apply = x: if isAttrs x || x == null then x else { _secret = x; }; @@ -270,12 +270,12 @@ in password = lib.mkOption { type = with lib.types; nullOr (either path (attrsOf path)); default = null; - description = '' + description = lib.mdDoc '' The SMTP server password. Always handled as a secret whether the value is - wrapped in a { _secret = ...; } - attrset or not (refer to for + wrapped in a `{ _secret = ...; }` + attrset or not (refer to [](#opt-services.parsedmarc.settings) for details). ''; apply = x: if isAttrs x || x == null then x else { _secret = x; }; @@ -322,13 +322,13 @@ in password = lib.mkOption { type = with lib.types; nullOr (either path (attrsOf path)); default = null; - description = '' + description = lib.mdDoc '' The password to use when connecting to Elasticsearch, if required. Always handled as a secret whether the value is - wrapped in a { _secret = ...; } - attrset or not (refer to for + wrapped in a `{ _secret = ...; }` + attrset or not (refer to [](#opt-services.parsedmarc.settings) for details). ''; apply = x: if isAttrs x || x == null then x else { _secret = x; }; diff --git a/nixos/modules/services/networking/biboumi.nix b/nixos/modules/services/networking/biboumi.nix index 7e6033008832..24e0c0328fe6 100644 --- a/nixos/modules/services/networking/biboumi.nix +++ b/nixos/modules/services/networking/biboumi.nix @@ -83,13 +83,13 @@ in }; options.password = mkOption { type = with types; nullOr str; - description = '' + description = lib.mdDoc '' The password used to authenticate the XMPP component to your XMPP server. This password must be configured in the XMPP server, associated with the external component on - hostname. + [hostname](#opt-services.biboumi.settings.hostname). - Set it to null and use credentialsFile + Set it to null and use [credentialsFile](#opt-services.biboumi.credentialsFile) if you do not want this password to go into the Nix store. ''; }; @@ -155,12 +155,12 @@ in credentialsFile = mkOption { type = types.path; - description = '' + description = lib.mdDoc '' Path to a configuration file to be merged with the settings. Beware not to surround "=" with spaces when setting biboumi's options in this file. Useful to merge a file which is better kept out of the Nix store because it contains sensible data like - password. + [password](#opt-services.biboumi.settings.password). ''; default = "/dev/null"; example = "/run/keys/biboumi.cfg"; diff --git a/nixos/modules/services/networking/bird-lg.nix b/nixos/modules/services/networking/bird-lg.nix index 9f06bfcdc51e..1440deb62b44 100644 --- a/nixos/modules/services/networking/bird-lg.nix +++ b/nixos/modules/services/networking/bird-lg.nix @@ -136,8 +136,8 @@ in extraArgs = mkOption { type = types.lines; default = ""; - description = '' - Extra parameters documented here. + description = lib.mdDoc '' + Extra parameters documented [here](https://github.com/xddxdd/bird-lg-go#frontend). ''; }; }; @@ -183,8 +183,8 @@ in extraArgs = mkOption { type = types.lines; default = ""; - description = '' - Extra parameters documented here. + description = lib.mdDoc '' + Extra parameters documented [here](https://github.com/xddxdd/bird-lg-go#proxy). ''; }; }; diff --git a/nixos/modules/services/networking/bird.nix b/nixos/modules/services/networking/bird.nix index 4a738daf9586..7708aaa476f6 100644 --- a/nixos/modules/services/networking/bird.nix +++ b/nixos/modules/services/networking/bird.nix @@ -13,18 +13,18 @@ in enable = mkEnableOption "BIRD Internet Routing Daemon"; config = mkOption { type = types.lines; - description = '' + description = lib.mdDoc '' BIRD Internet Routing Daemon configuration file. - + ''; }; checkConfig = mkOption { type = types.bool; default = true; - description = '' + description = lib.mdDoc '' Whether the config should be checked at build time. When the config can't be checked during build time, for example when it includes - other files, either disable this option or use preCheckConfig to create + other files, either disable this option or use `preCheckConfig` to create the included files before checking. ''; }; @@ -34,9 +34,9 @@ in example = '' echo "cost 100;" > include.conf ''; - description = '' + description = lib.mdDoc '' Commands to execute before the config file check. The file to be checked will be - available as bird2.conf in the current directory. + available as `bird2.conf` in the current directory. Files created with this option will not be available at service runtime, only during build time checking. diff --git a/nixos/modules/services/networking/coredns.nix b/nixos/modules/services/networking/coredns.nix index 966957f1a0f7..deaba69e99fa 100644 --- a/nixos/modules/services/networking/coredns.nix +++ b/nixos/modules/services/networking/coredns.nix @@ -17,9 +17,9 @@ in { } ''; type = types.lines; - description = '' + description = lib.mdDoc '' Verbatim Corefile to use. - See for details. + See for details. ''; }; diff --git a/nixos/modules/services/networking/ghostunnel.nix b/nixos/modules/services/networking/ghostunnel.nix index ce5d386edc35..79cf80e57bef 100644 --- a/nixos/modules/services/networking/ghostunnel.nix +++ b/nixos/modules/services/networking/ghostunnel.nix @@ -49,28 +49,28 @@ let }; cert = mkOption { - description = '' + description = lib.mdDoc '' Path to certificate (PEM with certificate chain). - Not required if keystore is set. + Not required if `keystore` is set. ''; type = types.nullOr types.str; default = null; }; key = mkOption { - description = '' + description = lib.mdDoc '' Path to certificate private key (PEM with private key). - Not required if keystore is set. + Not required if `keystore` is set. ''; type = types.nullOr types.str; default = null; }; cacert = mkOption { - description = '' - Path to CA bundle file (PEM/X509). Uses system trust store if null. + description = lib.mdDoc '' + Path to CA bundle file (PEM/X509). Uses system trust store if `null`. ''; type = types.nullOr types.str; }; @@ -124,7 +124,7 @@ let }; extraArguments = mkOption { - description = "Extra arguments to pass to ghostunnel server"; + description = lib.mdDoc "Extra arguments to pass to `ghostunnel server`"; type = types.separatedString " "; default = ""; }; diff --git a/nixos/modules/services/networking/hans.nix b/nixos/modules/services/networking/hans.nix index bff39a5ab2a8..ffb2ee841c64 100644 --- a/nixos/modules/services/networking/hans.nix +++ b/nixos/modules/services/networking/hans.nix @@ -19,11 +19,11 @@ in services.hans = { clients = mkOption { default = {}; - description = '' + description = lib.mdDoc '' Each attribute of this option defines a systemd service that runs hans. Many or none may be defined. The name of each service is - hans-«name» + `hans-«name»` where «name» is the name of the corresponding attribute name. ''; diff --git a/nixos/modules/services/networking/iodine.nix b/nixos/modules/services/networking/iodine.nix index 9749c7285132..ea2fa3ac4be4 100644 --- a/nixos/modules/services/networking/iodine.nix +++ b/nixos/modules/services/networking/iodine.nix @@ -28,11 +28,11 @@ in services.iodine = { clients = mkOption { default = {}; - description = '' + description = lib.mdDoc '' Each attribute of this option defines a systemd service that runs iodine. Many or none may be defined. The name of each service is - iodine-«name» + `iodine-«name»` where «name» is the name of the corresponding attribute name. ''; diff --git a/nixos/modules/services/networking/kea.nix b/nixos/modules/services/networking/kea.nix index d9d6e3f42ceb..d674a97391c9 100644 --- a/nixos/modules/services/networking/kea.nix +++ b/nixos/modules/services/networking/kea.nix @@ -54,11 +54,11 @@ in configFile = mkOption { type = nullOr path; default = null; - description = '' - Kea Control Agent configuration as a path, see . + description = lib.mdDoc '' + Kea Control Agent configuration as a path, see . - Takes preference over settings. - Most users should prefer using settings instead. + Takes preference over [settings](#opt-services.kea.ctrl-agent.settings). + Most users should prefer using [settings](#opt-services.kea.ctrl-agent.settings) instead. ''; }; @@ -93,11 +93,11 @@ in configFile = mkOption { type = nullOr path; default = null; - description = '' - Kea DHCP4 configuration as a path, see . + description = lib.mdDoc '' + Kea DHCP4 configuration as a path, see . - Takes preference over settings. - Most users should prefer using settings instead. + Takes preference over [settings](#opt-services.kea.dhcp4.settings). + Most users should prefer using [settings](#opt-services.kea.dhcp4.settings) instead. ''; }; @@ -153,11 +153,11 @@ in configFile = mkOption { type = nullOr path; default = null; - description = '' - Kea DHCP6 configuration as a path, see . + description = lib.mdDoc '' + Kea DHCP6 configuration as a path, see . - Takes preference over settings. - Most users should prefer using settings instead. + Takes preference over [settings](#opt-services.kea.dhcp6.settings). + Most users should prefer using [settings](#opt-services.kea.dhcp6.settings) instead. ''; }; @@ -214,11 +214,11 @@ in configFile = mkOption { type = nullOr path; default = null; - description = '' - Kea DHCP-DDNS configuration as a path, see . + description = lib.mdDoc '' + Kea DHCP-DDNS configuration as a path, see . - Takes preference over settings. - Most users should prefer using settings instead. + Takes preference over [settings](#opt-services.kea.dhcp-ddns.settings). + Most users should prefer using [settings](#opt-services.kea.dhcp-ddns.settings) instead. ''; }; diff --git a/nixos/modules/services/networking/ncdns.nix b/nixos/modules/services/networking/ncdns.nix index 3527b9e18575..958231963c68 100644 --- a/nixos/modules/services/networking/ncdns.nix +++ b/nixos/modules/services/networking/ncdns.nix @@ -176,10 +176,10 @@ in certstore.nssdbdir = "../../home/alice/.pki/nssdb"; } ''; - description = '' + description = lib.mdDoc '' ncdns settings. Use this option to configure ncds settings not exposed in a NixOS option or to bypass one. - See the example ncdns.conf file at + See the example ncdns.conf file at for the available options. ''; }; diff --git a/nixos/modules/services/networking/networkmanager.nix b/nixos/modules/services/networking/networkmanager.nix index 563892cb3655..e77fa97d240e 100644 --- a/nixos/modules/services/networking/networkmanager.nix +++ b/nixos/modules/services/networking/networkmanager.nix @@ -387,12 +387,12 @@ in { enableStrongSwan = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Enable the StrongSwan plugin. If you enable this option the - networkmanager_strongswan plugin will be added to - the option + `networkmanager_strongswan` plugin will be added to + the {option}`networking.networkmanager.plugins` option so you don't need to to that yourself. ''; }; diff --git a/nixos/modules/services/networking/nntp-proxy.nix b/nixos/modules/services/networking/nntp-proxy.nix index 1a776aae617b..4dd2922e83f1 100644 --- a/nixos/modules/services/networking/nntp-proxy.nix +++ b/nixos/modules/services/networking/nntp-proxy.nix @@ -167,9 +167,9 @@ in passwordHash = mkOption { type = types.str; example = "$6$GtzE7FrpE$wwuVgFYU.TZH4Rz.Snjxk9XGua89IeVwPQ/fEUD8eujr40q5Y021yhn0aNcsQ2Ifw.BLclyzvzgegopgKcneL0"; - description = '' + description = lib.mdDoc '' SHA-512 password hash (can be generated by - mkpasswd -m sha-512 <password>) + `mkpasswd -m sha-512 `) ''; }; diff --git a/nixos/modules/services/networking/nsd.nix b/nixos/modules/services/networking/nsd.nix index a372d3b207c4..cf2afcacc528 100644 --- a/nixos/modules/services/networking/nsd.nix +++ b/nixos/modules/services/networking/nsd.nix @@ -392,8 +392,8 @@ let requestXFR = mkOption { type = types.listOf types.str; default = []; - description = '' - Format: [AXFR|UDP] <ip-address> <key-name | NOKEY> + description = lib.mdDoc '' + Format: `[AXFR|UDP] ` ''; }; diff --git a/nixos/modules/services/networking/ntp/ntpd.nix b/nixos/modules/services/networking/ntp/ntpd.nix index 490d1619f118..a9dae2c8667a 100644 --- a/nixos/modules/services/networking/ntp/ntpd.nix +++ b/nixos/modules/services/networking/ntp/ntpd.nix @@ -40,17 +40,17 @@ in enable = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Whether to synchronise your machine's time using ntpd, as a peer in the NTP network. - Disables systemd.timesyncd if enabled. + Disables `systemd.timesyncd` if enabled. ''; }; restrictDefault = mkOption { type = types.listOf types.str; - description = '' + description = lib.mdDoc '' The restriction flags to be set by default. The default flags prevent external hosts from using ntpd as a DDoS @@ -63,7 +63,7 @@ in restrictSource = mkOption { type = types.listOf types.str; - description = '' + description = lib.mdDoc '' The restriction flags to be set on source. The default flags allow peers to be added by ntpd from configured diff --git a/nixos/modules/services/networking/openconnect.nix b/nixos/modules/services/networking/openconnect.nix index c72941459750..469f0a3bc3bb 100644 --- a/nixos/modules/services/networking/openconnect.nix +++ b/nixos/modules/services/networking/openconnect.nix @@ -38,10 +38,10 @@ let # set an authentication cookie, because they have to be requested # for every new connection and would only work once. passwordFile = mkOption { - description = '' + description = lib.mdDoc '' File containing the password to authenticate with. This - is passed to openconnect via the - --passwd-on-stdin option. + is passed to `openconnect` via the + `--passwd-on-stdin` option. ''; default = null; example = "/var/lib/secrets/openconnect-passwd"; @@ -63,13 +63,13 @@ let }; extraOptions = mkOption { - description = '' + description = lib.mdDoc '' Extra config to be appended to the interface config. It should contain long-format options as would be accepted on the command - line by openconnect + line by `openconnect` (see https://www.infradead.org/openconnect/manual.html). - Non-key-value options like deflate can be used by - declaring them as booleans, i. e. deflate = true;. + Non-key-value options like `deflate` can be used by + declaring them as booleans, i. e. `deflate = true;`. ''; default = { }; example = { diff --git a/nixos/modules/services/networking/openvpn.nix b/nixos/modules/services/networking/openvpn.nix index ce0f0f90fc91..492a0936fdbb 100644 --- a/nixos/modules/services/networking/openvpn.nix +++ b/nixos/modules/services/networking/openvpn.nix @@ -115,11 +115,11 @@ in } ''; - description = '' + description = lib.mdDoc '' Each attribute of this option defines a systemd service that runs an OpenVPN instance. These can be OpenVPN servers or clients. The name of each systemd service is - openvpn-«name».service, + `openvpn-«name».service`, where «name» is the corresponding attribute name. ''; diff --git a/nixos/modules/services/networking/pleroma.nix b/nixos/modules/services/networking/pleroma.nix index 03868c8cc769..de9d0821c63a 100644 --- a/nixos/modules/services/networking/pleroma.nix +++ b/nixos/modules/services/networking/pleroma.nix @@ -34,7 +34,7 @@ in { configs = mkOption { type = with types; listOf str; - description = '' + description = lib.mdDoc '' Pleroma public configuration. This list gets appended from left to @@ -42,9 +42,9 @@ in { configuration imperatively, meaning you can override a setting by appending a new str to this NixOS option list. - DO NOT STORE ANY PLEROMA SECRET - HERE, use - services.pleroma.secretConfigFile + *DO NOT STORE ANY PLEROMA SECRET + HERE*, use + [services.pleroma.secretConfigFile](#opt-services.pleroma.secretConfigFile) instead. This setting is going to be stored in a file part of diff --git a/nixos/modules/services/networking/ssh/sshd.nix b/nixos/modules/services/networking/ssh/sshd.nix index cbc4e303b641..6da83eb7de10 100644 --- a/nixos/modules/services/networking/ssh/sshd.nix +++ b/nixos/modules/services/networking/ssh/sshd.nix @@ -257,12 +257,12 @@ in authorizedKeysFiles = mkOption { type = types.listOf types.str; default = []; - description = '' + description = lib.mdDoc '' Specify the rules for which files to read on the host. This is an advanced option. If you're looking to configure user - keys, you can generally use - or . + keys, you can generally use [](#opt-users.users._name_.openssh.authorizedKeys.keys) + or [](#opt-users.users._name_.openssh.authorizedKeys.keyFiles). These are paths relative to the host root file system or home directories and they are subject to certain token expansion rules. @@ -298,13 +298,13 @@ in "curve25519-sha256@libssh.org" "diffie-hellman-group-exchange-sha256" ]; - description = '' + description = lib.mdDoc '' Allowed key exchange algorithms Uses the lower bound recommended in both - + and - + ''; }; @@ -318,13 +318,13 @@ in "aes192-ctr" "aes128-ctr" ]; - description = '' + description = lib.mdDoc '' Allowed ciphers Defaults to recommended settings from both - + and - + ''; }; @@ -338,13 +338,13 @@ in "hmac-sha2-256" "umac-128@openssh.com" ]; - description = '' + description = lib.mdDoc '' Allowed MACs Defaults to recommended settings from both - + and - + ''; }; diff --git a/nixos/modules/services/networking/wireguard.nix b/nixos/modules/services/networking/wireguard.nix index 994a0cf9ec1e..9017c53f4e56 100644 --- a/nixos/modules/services/networking/wireguard.nix +++ b/nixos/modules/services/networking/wireguard.nix @@ -118,11 +118,11 @@ let default = null; type = with types; nullOr str; example = "container"; - description = ''The pre-existing network namespace in which the + description = lib.mdDoc ''The pre-existing network namespace in which the WireGuard interface is created, and which retains the socket even if the - interface is moved via . When - null, the interface is created in the init namespace. - See documentation. + interface is moved via {option}`interfaceNamespace`. When + `null`, the interface is created in the init namespace. + See [documentation](https://www.wireguard.com/netns/). ''; }; @@ -130,11 +130,11 @@ let default = null; type = with types; nullOr str; example = "init"; - description = ''The pre-existing network namespace the WireGuard - interface is moved to. The special value init means - the init namespace. When null, the interface is not + description = lib.mdDoc ''The pre-existing network namespace the WireGuard + interface is moved to. The special value `init` means + the init namespace. When `null`, the interface is not moved. - See documentation. + See [documentation](https://www.wireguard.com/netns/). ''; }; }; diff --git a/nixos/modules/services/networking/yggdrasil.nix b/nixos/modules/services/networking/yggdrasil.nix index e99f31b0eaa4..266149cf2211 100644 --- a/nixos/modules/services/networking/yggdrasil.nix +++ b/nixos/modules/services/networking/yggdrasil.nix @@ -64,21 +64,21 @@ in { type = types.nullOr types.str; default = null; example = "wheel"; - description = "Group to grant access to the Yggdrasil control socket. If null, only root can access the socket."; + description = lib.mdDoc "Group to grant access to the Yggdrasil control socket. If `null`, only root can access the socket."; }; openMulticastPort = mkOption { type = bool; default = false; - description = '' + description = lib.mdDoc '' Whether to open the UDP port used for multicast peer discovery. The NixOS firewall blocks link-local communication, so in order to make local peering work you - will also need to set LinkLocalTCPPort in your - yggdrasil configuration ( or - ) to a port number other than 0, + will also need to set `LinkLocalTCPPort` in your + yggdrasil configuration ({option}`config` or + {option}`configFile`) to a port number other than 0, and then add that port to - . + {option}`networking.firewall.allowedTCPPorts`. ''; }; diff --git a/nixos/modules/services/security/privacyidea.nix b/nixos/modules/services/security/privacyidea.nix index 4be3a90b649f..29c499e33ab5 100644 --- a/nixos/modules/services/security/privacyidea.nix +++ b/nixos/modules/services/security/privacyidea.nix @@ -215,9 +215,9 @@ in environmentFile = mkOption { default = null; type = types.nullOr types.str; - description = '' + description = lib.mdDoc '' Environment file containing secrets to be substituted into - . + [](#opt-services.privacyidea.ldap-proxy.settings). ''; }; }; diff --git a/nixos/modules/services/security/tor.nix b/nixos/modules/services/security/tor.nix index 0516d207707a..84f577c3853b 100644 --- a/nixos/modules/services/security/tor.nix +++ b/nixos/modules/services/security/tor.nix @@ -476,11 +476,11 @@ in }; clientNames = mkOption { type = with types; nonEmptyListOf (strMatching "[A-Za-z0-9+-_]+"); - description = '' + description = lib.mdDoc '' Only clients that are listed here are authorized to access the hidden service. - Generated authorization data can be found in ${stateDir}/onion/$name/hostname. + Generated authorization data can be found in {file}`${stateDir}/onion/$name/hostname`. Clients need to put this authorization data in their configuration file using - . + [](#opt-services.tor.settings.HidServAuth). ''; }; }; diff --git a/nixos/modules/services/security/vault.nix b/nixos/modules/services/security/vault.nix index e4777910b6d3..ef9829630296 100644 --- a/nixos/modules/services/security/vault.nix +++ b/nixos/modules/services/security/vault.nix @@ -116,13 +116,13 @@ in storageConfig = mkOption { type = types.nullOr types.lines; default = null; - description = '' + description = lib.mdDoc '' HCL configuration to insert in the storageBackend section. Confidential values should not be specified here because this option's value is written to the Nix store, which is publicly readable. Provide credentials and such in a separate file using - . + [](#opt-services.vault.extraSettingsPaths). ''; }; diff --git a/nixos/modules/services/system/dbus.nix b/nixos/modules/services/system/dbus.nix index 65b40c56a3be..def04d944f05 100644 --- a/nixos/modules/services/system/dbus.nix +++ b/nixos/modules/services/system/dbus.nix @@ -38,17 +38,17 @@ in packages = mkOption { type = types.listOf types.path; default = [ ]; - description = '' + description = lib.mdDoc '' Packages whose D-Bus configuration files should be included in the configuration of the D-Bus system-wide or session-wide message bus. Specifically, files in the following directories will be included into their respective DBus configuration paths: - «pkg»/etc/dbus-1/system.d - «pkg»/share/dbus-1/system.d - «pkg»/share/dbus-1/system-services - «pkg»/etc/dbus-1/session.d - «pkg»/share/dbus-1/session.d - «pkg»/share/dbus-1/services + {file}`«pkg»/etc/dbus-1/system.d` + {file}`«pkg»/share/dbus-1/system.d` + {file}`«pkg»/share/dbus-1/system-services` + {file}`«pkg»/etc/dbus-1/session.d` + {file}`«pkg»/share/dbus-1/session.d` + {file}`«pkg»/share/dbus-1/services` ''; }; diff --git a/nixos/modules/services/system/earlyoom.nix b/nixos/modules/services/system/earlyoom.nix index 3e361fce00f9..b2e2d21002ce 100644 --- a/nixos/modules/services/system/earlyoom.nix +++ b/nixos/modules/services/system/earlyoom.nix @@ -32,32 +32,32 @@ in freeMemKillThreshold = mkOption { type = types.nullOr (types.ints.between 1 100); default = null; - description = '' + description = lib.mdDoc '' Minimum available memory (in percent) before sending SIGKILL. - If unset, this defaults to half of . + If unset, this defaults to half of {option}`freeMemThreshold`. - See the description of . + See the description of [](#opt-services.earlyoom.freeMemThreshold). ''; }; freeSwapThreshold = mkOption { type = types.ints.between 1 100; default = 10; - description = '' + description = lib.mdDoc '' Minimum free swap space (in percent) before sending SIGTERM. - See the description of . + See the description of [](#opt-services.earlyoom.freeMemThreshold). ''; }; freeSwapKillThreshold = mkOption { type = types.nullOr (types.ints.between 1 100); default = null; - description = '' + description = lib.mdDoc '' Minimum free swap space (in percent) before sending SIGKILL. - If unset, this defaults to half of . + If unset, this defaults to half of {option}`freeSwapThreshold`. - See the description of . + See the description of [](#opt-services.earlyoom.freeMemThreshold). ''; }; diff --git a/nixos/modules/services/torrent/transmission.nix b/nixos/modules/services/torrent/transmission.nix index 1641f1ad184e..6a038dc0a32c 100644 --- a/nixos/modules/services/torrent/transmission.nix +++ b/nixos/modules/services/torrent/transmission.nix @@ -55,13 +55,13 @@ in type = types.path; default = "${cfg.home}/${incompleteDir}"; defaultText = literalExpression ''"''${config.${opt.home}}/${incompleteDir}"''; - description = '' + description = lib.mdDoc '' When enabled with services.transmission.home - , + [](#opt-services.transmission.settings.incomplete-dir-enabled), new torrents will download the files to this directory. When complete, the files will be moved to download-dir - . + [](#opt-services.transmission.settings.download-dir). ''; }; options.incomplete-dir-enabled = mkOption { @@ -82,17 +82,17 @@ in options.peer-port-random-high = mkOption { type = types.port; default = 65535; - description = '' + description = lib.mdDoc '' The maximum peer port to listen to for incoming connections - when is enabled. + when [](#opt-services.transmission.settings.peer-port-random-on-start) is enabled. ''; }; options.peer-port-random-low = mkOption { type = types.port; default = 65535; - description = '' + description = lib.mdDoc '' The minimal peer port to listen to for incoming connections - when is enabled. + when [](#opt-services.transmission.settings.peer-port-random-on-start) is enabled. ''; }; options.peer-port-random-on-start = mkOption { @@ -117,9 +117,9 @@ in options.script-torrent-done-enabled = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Whether to run - + [](#opt-services.transmission.settings.script-torrent-done-filename) at torrent completion. ''; }; @@ -156,15 +156,15 @@ in options.watch-dir-enabled = mkOption { type = types.bool; default = false; - description = ''Whether to enable the - . + description = lib.mdDoc ''Whether to enable the + [](#opt-services.transmission.settings.watch-dir). ''; }; options.trash-original-torrent-files = mkOption { type = types.bool; default = false; - description = ''Whether to delete torrents added from the - . + description = lib.mdDoc ''Whether to delete torrents added from the + [](#opt-services.transmission.settings.watch-dir). ''; }; }; @@ -174,26 +174,26 @@ in type = with types; nullOr str; default = null; example = "770"; - description = '' - If not null, is used as the permissions - set by systemd.activationScripts.transmission-daemon - on the directories , - . - and . + description = lib.mdDoc '' + If not `null`, is used as the permissions + set by `systemd.activationScripts.transmission-daemon` + on the directories [](#opt-services.transmission.settings.download-dir), + [](#opt-services.transmission.settings.incomplete-dir). + and [](#opt-services.transmission.settings.watch-dir). Note that you may also want to change - . + [](#opt-services.transmission.settings.umask). ''; }; home = mkOption { type = types.path; default = "/var/lib/transmission"; - description = '' - The directory where Transmission will create ${settingsDir}. - as well as ${downloadsDir}/ unless - is changed, - and ${incompleteDir}/ unless - is changed. + description = lib.mdDoc '' + The directory where Transmission will create `${settingsDir}`. + as well as `${downloadsDir}/` unless + [](#opt-services.transmission.settings.download-dir) is changed, + and `${incompleteDir}/` unless + [](#opt-services.transmission.settings.incomplete-dir) is changed. ''; }; @@ -211,10 +211,10 @@ in credentialsFile = mkOption { type = types.path; - description = '' + description = lib.mdDoc '' Path to a JSON file to be merged with the settings. Useful to merge a file which is better kept out of the Nix store - to set secret config parameters like rpc-password. + to set secret config parameters like `rpc-password`. ''; default = "/dev/null"; example = "/var/lib/secrets/transmission/settings.json"; diff --git a/nixos/modules/services/web-apps/dokuwiki.nix b/nixos/modules/services/web-apps/dokuwiki.nix index 49865b962d10..a148dec8199a 100644 --- a/nixos/modules/services/web-apps/dokuwiki.nix +++ b/nixos/modules/services/web-apps/dokuwiki.nix @@ -260,14 +260,14 @@ in webserver = mkOption { type = types.enum [ "nginx" "caddy" ]; default = "nginx"; - description = '' + description = lib.mdDoc '' Whether to use nginx or caddy for virtual host management. - Further nginx configuration can be done by adapting services.nginx.virtualHosts.<name>. - See for further information. + Further nginx configuration can be done by adapting `services.nginx.virtualHosts.`. + See [](#opt-services.nginx.virtualHosts) for further information. - Further apache2 configuration can be done by adapting services.httpd.virtualHosts.<name>. - See for further information. + Further apache2 configuration can be done by adapting `services.httpd.virtualHosts.`. + See [](#opt-services.httpd.virtualHosts) for further information. ''; }; diff --git a/nixos/modules/services/web-apps/hedgedoc.nix b/nixos/modules/services/web-apps/hedgedoc.nix index 4e1a21259847..6f579b365cfe 100644 --- a/nixos/modules/services/web-apps/hedgedoc.nix +++ b/nixos/modules/services/web-apps/hedgedoc.nix @@ -150,9 +150,9 @@ in addDefaults = true; } ''; - description = '' + description = lib.mdDoc '' Specify the Content Security Policy which is passed to Helmet. - For configuration details see . + For configuration details see . ''; }; protocolUseSSL = mkOption { diff --git a/nixos/modules/services/web-apps/keycloak.nix b/nixos/modules/services/web-apps/keycloak.nix index 110df53effda..c1091bc09a06 100644 --- a/nixos/modules/services/web-apps/keycloak.nix +++ b/nixos/modules/services/web-apps/keycloak.nix @@ -210,13 +210,13 @@ in name = mkOption { type = str; default = "keycloak"; - description = '' + description = lib.mdDoc '' Database name to use when connecting to an external or manually provisioned database; has no effect when a local database is automatically provisioned. - To use this with a local database, set to - false and create the database and user + To use this with a local database, set [](#opt-services.keycloak.database.createLocally) to + `false` and create the database and user manually. ''; }; @@ -224,13 +224,13 @@ in username = mkOption { type = str; default = "keycloak"; - description = '' + description = lib.mdDoc '' Username to use when connecting to an external or manually provisioned database; has no effect when a local database is automatically provisioned. - To use this with a local database, set to - false and create the database and user + To use this with a local database, set [](#opt-services.keycloak.database.createLocally) to + `false` and create the database and user manually. ''; }; @@ -415,21 +415,21 @@ in } ''; - description = '' + description = lib.mdDoc '' Configuration options corresponding to parameters set in - conf/keycloak.conf. + {file}`conf/keycloak.conf`. - Most available options are documented at . + Most available options are documented at . Options containing secret data should be set to an attribute - set containing the attribute _secret - a + set containing the attribute `_secret` - a string pointing to a file containing the value the option should be set to. See the example to get a better picture of this: in the resulting - conf/keycloak.conf file, the - https-key-store-password key will be set + {file}`conf/keycloak.conf` file, the + `https-key-store-password` key will be set to the contents of the - /run/keys/store_password file. + {file}`/run/keys/store_password` file. ''; }; }; diff --git a/nixos/modules/services/web-apps/mastodon.nix b/nixos/modules/services/web-apps/mastodon.nix index 00c30d73bb6f..d0594ff74192 100644 --- a/nixos/modules/services/web-apps/mastodon.nix +++ b/nixos/modules/services/web-apps/mastodon.nix @@ -197,14 +197,14 @@ in { }; vapidPublicKeyFile = lib.mkOption { - description = '' + description = lib.mdDoc '' Path to file containing the public key used for Web Push Voluntary Application Server Identification. A new keypair can be generated by running: - nix build -f '<nixpkgs>' mastodon; cd result; bin/rake webpush:generate_keys + `nix build -f '' mastodon; cd result; bin/rake webpush:generate_keys` - If does not + If {option}`mastodon.vapidPrivateKeyFile`does not exist, it and this file will be created with a new keypair. ''; default = "/var/lib/mastodon/secrets/vapid-public-key"; @@ -218,11 +218,11 @@ in { }; secretKeyBaseFile = lib.mkOption { - description = '' + description = lib.mdDoc '' Path to file containing the secret key base. A new secret key base can be generated by running: - nix build -f '<nixpkgs>' mastodon; cd result; bin/rake secret + `nix build -f '' mastodon; cd result; bin/rake secret` If this file does not exist, it will be created with a new secret key base. ''; @@ -231,11 +231,11 @@ in { }; otpSecretFile = lib.mkOption { - description = '' + description = lib.mdDoc '' Path to file containing the OTP secret. A new OTP secret can be generated by running: - nix build -f '<nixpkgs>' mastodon; cd result; bin/rake secret + `nix build -f '' mastodon; cd result; bin/rake secret` If this file does not exist, it will be created with a new OTP secret. ''; @@ -244,12 +244,12 @@ in { }; vapidPrivateKeyFile = lib.mkOption { - description = '' + description = lib.mdDoc '' Path to file containing the private key used for Web Push Voluntary Application Server Identification. A new keypair can be generated by running: - nix build -f '<nixpkgs>' mastodon; cd result; bin/rake webpush:generate_keys + `nix build -f '' mastodon; cd result; bin/rake webpush:generate_keys` If this file does not exist, it will be created with a new private key. diff --git a/nixos/modules/services/web-apps/nextcloud.nix b/nixos/modules/services/web-apps/nextcloud.nix index a121401f7584..feee7494a71a 100644 --- a/nixos/modules/services/web-apps/nextcloud.nix +++ b/nixos/modules/services/web-apps/nextcloud.nix @@ -93,8 +93,8 @@ in { type = types.str; default = config.services.nextcloud.home; defaultText = literalExpression "config.services.nextcloud.home"; - description = '' - Data storage path of nextcloud. Will be by default. + description = lib.mdDoc '' + Data storage path of nextcloud. Will be [](#opt-services.nextcloud.home) by default. This folder will be populated with a config.php and data folder which contains the state of the instance (excl the database)."; ''; example = "/mnt/nextcloud-file"; @@ -102,10 +102,10 @@ in { extraApps = mkOption { type = types.attrsOf types.package; default = { }; - description = '' + description = lib.mdDoc '' Extra apps to install. Should be an attrSet of appid to packages generated by fetchNextcloudApp. The appid must be identical to the "id" value in the apps appinfo/info.xml. - Using this will disable the appstore to prevent Nextcloud from updating these apps (see ). + Using this will disable the appstore to prevent Nextcloud from updating these apps (see [](#opt-services.nextcloud.appstoreEnable)). ''; example = literalExpression '' { @@ -127,8 +127,8 @@ in { extraAppsEnable = mkOption { type = types.bool; default = true; - description = '' - Automatically enable the apps in every time nextcloud starts. + description = lib.mdDoc '' + Automatically enable the apps in [](#opt-services.nextcloud.extraApps) every time nextcloud starts. If set to false, apps need to be enabled in the Nextcloud user interface or with nextcloud-occ app:enable. ''; }; @@ -136,10 +136,10 @@ in { type = types.nullOr types.bool; default = null; example = true; - description = '' + description = lib.mdDoc '' Allow the installation of apps and app updates from the store. - Enabled by default unless there are packages in . - Set to true to force enable the store even if is used. + Enabled by default unless there are packages in [](#opt-services.nextcloud.extraApps). + Set to true to force enable the store even if [](#opt-services.nextcloud.extraApps) is used. Set to false to disable the installation of apps from the global appstore. App management is always enabled regardless of this setting. ''; }; @@ -585,9 +585,9 @@ in { hstsMaxAge = mkOption { type = types.ints.positive; default = 15552000; - description = '' - Value for the max-age directive of the HTTP - Strict-Transport-Security header. + description = lib.mdDoc '' + Value for the `max-age` directive of the HTTP + `Strict-Transport-Security` header. See section 6.1.1 of IETF RFC 6797 for detailed information on this directive and header. diff --git a/nixos/modules/services/web-apps/node-red.nix b/nixos/modules/services/web-apps/node-red.nix index 3e6e38c50db5..e5b0998d3c41 100644 --- a/nixos/modules/services/web-apps/node-red.nix +++ b/nixos/modules/services/web-apps/node-red.nix @@ -47,9 +47,9 @@ in type = types.path; default = "${cfg.package}/lib/node_modules/node-red/settings.js"; defaultText = literalExpression ''"''${package}/lib/node_modules/node-red/settings.js"''; - description = '' + description = lib.mdDoc '' Path to the JavaScript configuration file. - See + See for a configuration example. ''; }; diff --git a/nixos/modules/services/web-apps/trilium.nix b/nixos/modules/services/web-apps/trilium.nix index 75464b21fd41..bb1061cf278e 100644 --- a/nixos/modules/services/web-apps/trilium.nix +++ b/nixos/modules/services/web-apps/trilium.nix @@ -53,7 +53,7 @@ in noAuthentication = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' If set to true, no password is required to access the web frontend. ''; }; diff --git a/nixos/modules/services/x11/desktop-managers/plasma5.nix b/nixos/modules/services/x11/desktop-managers/plasma5.nix index fcc2976cd2c1..5c39de0dde74 100644 --- a/nixos/modules/services/x11/desktop-managers/plasma5.nix +++ b/nixos/modules/services/x11/desktop-managers/plasma5.nix @@ -170,7 +170,7 @@ in supportDDC = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Support setting monitor brightness via DDC. This is not needed for controlling brightness of the internal monitor diff --git a/nixos/modules/services/x11/display-managers/lightdm-greeters/mini.nix b/nixos/modules/services/x11/display-managers/lightdm-greeters/mini.nix index 00a47e7814f7..f4195c4c2dc3 100644 --- a/nixos/modules/services/x11/display-managers/lightdm-greeters/mini.nix +++ b/nixos/modules/services/x11/display-managers/lightdm-greeters/mini.nix @@ -55,12 +55,12 @@ in enable = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Whether to enable lightdm-mini-greeter as the lightdm greeter. Note that this greeter starts only the default X session. You can configure the default X session using - . + [](#opt-services.xserver.displayManager.defaultSession). ''; }; diff --git a/nixos/modules/services/x11/display-managers/lightdm-greeters/tiny.nix b/nixos/modules/services/x11/display-managers/lightdm-greeters/tiny.nix index e8f799e27295..8d6bfa98a7e4 100644 --- a/nixos/modules/services/x11/display-managers/lightdm-greeters/tiny.nix +++ b/nixos/modules/services/x11/display-managers/lightdm-greeters/tiny.nix @@ -17,12 +17,12 @@ in enable = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Whether to enable lightdm-tiny-greeter as the lightdm greeter. Note that this greeter starts only the default X session. You can configure the default X session using - . + [](#opt-services.xserver.displayManager.defaultSession). ''; }; diff --git a/nixos/modules/services/x11/window-managers/fvwm2.nix b/nixos/modules/services/x11/window-managers/fvwm2.nix index 909b3a475a9c..b5ef36f58d54 100644 --- a/nixos/modules/services/x11/window-managers/fvwm2.nix +++ b/nixos/modules/services/x11/window-managers/fvwm2.nix @@ -24,7 +24,7 @@ in gestures = mkOption { default = false; type = types.bool; - description = "Whether or not to enable libstroke for gesture support"; + description = lib.mdDoc "Whether or not to enable libstroke for gesture support"; }; }; }; diff --git a/nixos/modules/system/boot/initrd-network.nix b/nixos/modules/system/boot/initrd-network.nix index eff125971d08..a1017c3e2420 100644 --- a/nixos/modules/system/boot/initrd-network.nix +++ b/nixos/modules/system/boot/initrd-network.nix @@ -50,17 +50,17 @@ in boot.initrd.network.enable = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Add network connectivity support to initrd. The network may be - configured using the ip kernel parameter, - as described in the kernel documentation. + configured using the `ip` kernel parameter, + as described in [the kernel documentation](https://www.kernel.org/doc/Documentation/filesystems/nfs/nfsroot.txt). Otherwise, if - is enabled, an IP address + {option}`networking.useDHCP` is enabled, an IP address is acquired using DHCP. You should add the module(s) required for your network card to boot.initrd.availableKernelModules. - lspci -v | grep -iA8 'network\|ethernet' + `lspci -v | grep -iA8 'network\|ethernet'` will tell you which. ''; }; diff --git a/nixos/modules/system/boot/luksroot.nix b/nixos/modules/system/boot/luksroot.nix index 3b468f00aba8..bffa7010d2fc 100644 --- a/nixos/modules/system/boot/luksroot.nix +++ b/nixos/modules/system/boot/luksroot.nix @@ -548,11 +548,11 @@ in boot.initrd.luks.devices = mkOption { default = { }; example = { luksroot.device = "/dev/disk/by-uuid/430e9eff-d852-4f68-aa3b-2fa3599ebe08"; }; - description = '' + description = lib.mdDoc '' The encrypted disk that should be opened before the root filesystem is mounted. Both LVM-over-LUKS and LUKS-over-LVM setups are supported. The unencrypted devices can be accessed as - /dev/mapper/«name». + {file}`/dev/mapper/«name»`. ''; type = with types; attrsOf (submodule ( diff --git a/nixos/modules/system/boot/networkd.nix b/nixos/modules/system/boot/networkd.nix index 1849dcfe1e1e..efd6fabd2f3b 100644 --- a/nixos/modules/system/boot/networkd.nix +++ b/nixos/modules/system/boot/networkd.nix @@ -1904,11 +1904,11 @@ in }; extraArgs = mkOption { - description = '' + description = lib.mdDoc '' Extra command-line arguments to pass to systemd-networkd-wait-online. - These also affect per-interface systemd-network-wait-online@ services. + These also affect per-interface `systemd-network-wait-online@` services. - See systemd-networkd-wait-online.service8 for all available options. + See [{manpage}`systemd-networkd-wait-online.service(8)`](https://www.freedesktop.org/software/systemd/man/systemd-networkd-wait-online.service.html) for all available options. ''; type = with types; listOf str; default = []; diff --git a/nixos/modules/system/boot/systemd/logind.nix b/nixos/modules/system/boot/systemd/logind.nix index bd05c07e26f2..598016032136 100644 --- a/nixos/modules/system/boot/systemd/logind.nix +++ b/nixos/modules/system/boot/systemd/logind.nix @@ -26,14 +26,14 @@ in services.logind.killUserProcesses = mkOption { default = false; type = types.bool; - description = '' + description = lib.mdDoc '' Specifies whether the processes of a user should be killed when the user logs out. If true, the scope unit corresponding to the session and all processes inside that scope will be terminated. If false, the scope is "abandoned" (see - systemd.scope(5)), and processes are not killed. + [systemd.scope(5)](https://www.freedesktop.org/software/systemd/man/systemd.scope.html#)), and processes are not killed. - See logind.conf(5) + See [logind.conf(5)](https://www.freedesktop.org/software/systemd/man/logind.conf.html#KillUserProcesses=) for more details. ''; }; diff --git a/nixos/modules/system/boot/systemd/tmpfiles.nix b/nixos/modules/system/boot/systemd/tmpfiles.nix index 0d5adf596e18..e990e953b057 100644 --- a/nixos/modules/system/boot/systemd/tmpfiles.nix +++ b/nixos/modules/system/boot/systemd/tmpfiles.nix @@ -25,16 +25,16 @@ in default = []; example = literalExpression "[ pkgs.lvm2 ]"; apply = map getLib; - description = '' - List of packages containing systemd-tmpfiles rules. + description = lib.mdDoc '' + List of packages containing {command}`systemd-tmpfiles` rules. All files ending in .conf found in - «pkg»/lib/tmpfiles.d + {file}`«pkg»/lib/tmpfiles.d` will be included. If this folder does not exist or does not contain any files an error will be returned instead. - If a lib output is available, rules are searched there and only there. - If there is no lib output it will fall back to out + If a {file}`lib` output is available, rules are searched there and only there. + If there is no {file}`lib` output it will fall back to {file}`out` and if that does not exist either, the default output will be used. ''; }; diff --git a/nixos/modules/tasks/auto-upgrade.nix b/nixos/modules/tasks/auto-upgrade.nix index 46a30c53ea88..ca2690167830 100644 --- a/nixos/modules/tasks/auto-upgrade.nix +++ b/nixos/modules/tasks/auto-upgrade.nix @@ -25,10 +25,10 @@ in { type = types.enum ["switch" "boot"]; default = "switch"; example = "boot"; - description = '' + description = lib.mdDoc '' Whether to run - nixos-rebuild switch --upgrade or run - nixos-rebuild boot --upgrade + `nixos-rebuild switch --upgrade` or run + `nixos-rebuild boot --upgrade` ''; }; diff --git a/nixos/modules/tasks/scsi-link-power-management.nix b/nixos/modules/tasks/scsi-link-power-management.nix index 549c35fc5b8d..a5395657e992 100644 --- a/nixos/modules/tasks/scsi-link-power-management.nix +++ b/nixos/modules/tasks/scsi-link-power-management.nix @@ -25,7 +25,7 @@ in powerManagement.scsiLinkPolicy = mkOption { default = null; type = types.nullOr (types.enum allowedValues); - description = '' + description = lib.mdDoc '' SCSI link power management policy. The kernel default is "max_performance". diff --git a/nixos/modules/virtualisation/nixos-containers.nix b/nixos/modules/virtualisation/nixos-containers.nix index 1699b0bcea40..6b8c21336c6b 100644 --- a/nixos/modules/virtualisation/nixos-containers.nix +++ b/nixos/modules/virtualisation/nixos-containers.nix @@ -579,11 +579,11 @@ in privateNetwork = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Whether to give the container its own private virtual Ethernet interface. The interface is called - eth0, and is hooked up to the interface - ve-«container-name» + `eth0`, and is hooked up to the interface + `ve-«container-name»` on the host. If this option is not set, then the container shares the network interfaces of the host, and can bind to any port on any interface. @@ -728,12 +728,12 @@ in }; } ''; - description = '' + description = lib.mdDoc '' A set of NixOS system configurations to be run as lightweight containers. Each container appears as a service - container-«name» + `container-«name»` on the host system, allowing it to be started and stopped via - systemctl. + {command}`systemctl`. ''; };