diff --git a/nixos/modules/programs/java.nix b/nixos/modules/programs/java.nix index 5994f53f76b7..4f03c1f3ff25 100644 --- a/nixos/modules/programs/java.nix +++ b/nixos/modules/programs/java.nix @@ -15,20 +15,19 @@ in programs.java = { - enable = mkEnableOption "java" // { - description = '' + enable = mkEnableOption (lib.mdDoc "java") // { + description = lib.mdDoc '' Install and setup the Java development kit. - - This adds JAVA_HOME to the global environment, by sourcing the - jdk's setup-hook on shell init. It is equivalent to starting a shell - through 'nix-shell -p jdk', or roughly the following system-wide - configuration: - - - environment.variables.JAVA_HOME = ''${pkgs.jdk.home}/lib/openjdk; - environment.systemPackages = [ pkgs.jdk ]; - - + + ::: {.note} + This adds JAVA_HOME to the global environment, by sourcing the + jdk's setup-hook on shell init. It is equivalent to starting a shell + through 'nix-shell -p jdk', or roughly the following system-wide + configuration: + + environment.variables.JAVA_HOME = ''${pkgs.jdk.home}/lib/openjdk; + environment.systemPackages = [ pkgs.jdk ]; + ::: ''; }; diff --git a/nixos/modules/security/dhparams.nix b/nixos/modules/security/dhparams.nix index 93c9066dc95c..9fed7e012b1e 100644 --- a/nixos/modules/security/dhparams.nix +++ b/nixos/modules/security/dhparams.nix @@ -56,45 +56,53 @@ in { in attrsOf (coercedTo int coerce (submodule paramsSubmodule)); default = {}; example = lib.literalExpression "{ nginx.bits = 3072; }"; - description = '' + description = lib.mdDoc '' Diffie-Hellman parameters to generate. The value is the size (in bits) of the DH params to generate. The generated DH params path can be found in - config.security.dhparams.params.«name».path. + `config.security.dhparams.params.«name».path`. - The name of the DH params is taken as being the name of + ::: {.note} + The name of the DH params is taken as being the name of the service it serves and the params will be generated before the - said service is started. + said service is started. + ::: - If you are removing all dhparams from this list, you - have to leave for at + ::: {.warning} + If you are removing all dhparams from this list, you + have to leave {option}`security.dhparams.enable` for at least one activation in order to have them be cleaned up. This also means if you rollback to a version without any dhparams the existing ones won't be cleaned up. Of course this only applies if - is - true. + {option}`security.dhparams.stateful` is + `true`. + ::: - For module implementers:It's recommended + ::: {.note} + **For module implementers:** It's recommended to not set a specific bit size here, so that users can easily override this by setting - . + {option}`security.dhparams.defaultBitSize`. + ::: ''; }; stateful = mkOption { type = types.bool; default = true; - description = '' + description = lib.mdDoc '' Whether generation of Diffie-Hellman parameters should be stateful or not. If this is enabled, PEM-encoded files for Diffie-Hellman parameters are placed in the directory specified by - . Otherwise the files are + {option}`security.dhparams.path`. Otherwise the files are created within the Nix store. - If this is false the resulting store + ::: {.note} + If this is `false` the resulting store path will be non-deterministic and will be rebuilt every time the - openssl package changes. + `openssl` package changes. + ::: ''; }; diff --git a/nixos/modules/security/systemd-confinement.nix b/nixos/modules/security/systemd-confinement.nix index f5ed3d281a5f..be04741f4d06 100644 --- a/nixos/modules/security/systemd-confinement.nix +++ b/nixos/modules/security/systemd-confinement.nix @@ -38,8 +38,8 @@ in { type = types.listOf (types.either types.str types.package); default = []; description = let - mkScOption = optName: ""; - in '' + mkScOption = optName: "{option}`serviceConfig.${optName}`"; + in lib.mdDoc '' Additional packages or strings with context to add to the closure of the chroot. By default, this includes all the packages from the ${lib.concatMapStringsSep ", " mkScOption [ @@ -47,12 +47,14 @@ in { "ExecStopPost" ]} and ${mkScOption "ExecStart"} options. If you want to have all the dependencies of this systemd unit, you can use - . + {option}`confinement.fullUnit`. - The store paths listed in are - not included in the closure as + ::: {.note} + The store paths listed in {option}`path` are + **not** included in the closure as well as paths from other options except those listed - above. + above. + ::: ''; }; @@ -74,20 +76,20 @@ in { options.confinement.mode = lib.mkOption { type = types.enum [ "full-apivfs" "chroot-only" ]; default = "full-apivfs"; - description = '' - The value full-apivfs (the default) sets up - private /dev, /proc, /sys and /tmp file systems in a separate user + description = lib.mdDoc '' + The value `full-apivfs` (the default) sets up + private {file}`/dev`, {file}`/proc`, + {file}`/sys` and {file}`/tmp` file systems in a separate user name space. - If this is set to chroot-only, only the file + If this is set to `chroot-only`, only the file system name space is set up along with the call to - chroot2. + {manpage}`chroot(2)`. - This doesn't cover network namespaces and is solely for - file system level isolation. + ::: {.note} + This doesn't cover network namespaces and is solely for + file system level isolation. + ::: ''; }; diff --git a/nixos/modules/security/wrappers/default.nix b/nixos/modules/security/wrappers/default.nix index 0e358eb4bd8d..45aee7c97339 100644 --- a/nixos/modules/security/wrappers/default.nix +++ b/nixos/modules/security/wrappers/default.nix @@ -51,20 +51,20 @@ let options.capabilities = lib.mkOption { type = lib.types.commas; default = ""; - description = '' + description = lib.mdDoc '' A comma-separated list of capabilities to be given to the wrapper program. For capabilities supported by the system check the - capabilities7 + {manpage}`capabilities(7)` manual page. - - cap_setpcap, which is required for the wrapper - program to be able to raise caps into the Ambient set is NOT raised - to the Ambient set so that the real program cannot modify its own - capabilities!! This may be too restrictive for cases in which the - real program needs cap_setpcap but it at least leans on the side - security paranoid vs. too relaxed. - + ::: {.note} + `cap_setpcap`, which is required for the wrapper + program to be able to raise caps into the Ambient set is NOT raised + to the Ambient set so that the real program cannot modify its own + capabilities!! This may be too restrictive for cases in which the + real program needs cap_setpcap but it at least leans on the side + security paranoid vs. too relaxed. + ::: ''; }; options.setuid = lib.mkOption diff --git a/nixos/modules/services/backup/duplicati.nix b/nixos/modules/services/backup/duplicati.nix index 7100cad6cf0c..47f0b618c8d9 100644 --- a/nixos/modules/services/backup/duplicati.nix +++ b/nixos/modules/services/backup/duplicati.nix @@ -21,14 +21,14 @@ in dataDir = mkOption { type = types.str; default = "/var/lib/duplicati"; - description = '' + description = lib.mdDoc '' The directory where Duplicati stores its data files. - - If left as the default value this directory will automatically be created - before the Duplicati server starts, otherwise you are responsible for ensuring - the directory exists with appropriate ownership and permissions. - + ::: {.note} + If left as the default value this directory will automatically be created + before the Duplicati server starts, otherwise you are responsible for ensuring + the directory exists with appropriate ownership and permissions. + ::: ''; }; diff --git a/nixos/modules/services/databases/mysql.nix b/nixos/modules/services/databases/mysql.nix index 6f2d812ef7dc..ec4524e9061d 100644 --- a/nixos/modules/services/databases/mysql.nix +++ b/nixos/modules/services/databases/mysql.nix @@ -44,41 +44,41 @@ in user = mkOption { type = types.str; default = "mysql"; - description = '' + description = lib.mdDoc '' User account under which MySQL runs. - + ::: {.note} If left as the default value this user will automatically be created on system activation, otherwise you are responsible for ensuring the user exists before the MySQL service starts. - + ::: ''; }; group = mkOption { type = types.str; default = "mysql"; - description = '' + description = lib.mdDoc '' Group account under which MySQL runs. - + ::: {.note} If left as the default value this group will automatically be created on system activation, otherwise you are responsible for ensuring the user exists before the MySQL service starts. - + ::: ''; }; dataDir = mkOption { type = types.path; example = "/var/lib/mysql"; - description = '' + description = lib.mdDoc '' The data directory for MySQL. - - If left as the default value of /var/lib/mysql this directory will automatically be created before the MySQL + ::: {.note} + If left as the default value of `/var/lib/mysql` this directory will automatically be created before the MySQL server starts, otherwise you are responsible for ensuring the directory exists with appropriate ownership and permissions. - + ::: ''; }; @@ -107,20 +107,18 @@ in settings = mkOption { type = format.type; default = {}; - description = '' + description = lib.mdDoc '' MySQL configuration. Refer to - , - , - and + , + , + and for details on supported values. - - - MySQL configuration options such as --quick should be treated as - boolean options and provided values such as true, false, - 1, or 0. See the provided example below. - - + ::: {.note} + MySQL configuration options such as `--quick` should be treated as + boolean options and provided values such as `true`, `false`, + `1`, or `0`. See the provided example below. + ::: ''; example = literalExpression '' { diff --git a/nixos/modules/services/databases/postgresql.nix b/nixos/modules/services/databases/postgresql.nix index 3d632eabfc61..e84116635a37 100644 --- a/nixos/modules/services/databases/postgresql.nix +++ b/nixos/modules/services/databases/postgresql.nix @@ -230,15 +230,15 @@ in settings = mkOption { type = with types; attrsOf (oneOf [ bool float int str ]); default = {}; - description = '' + description = lib.mdDoc '' PostgreSQL configuration. Refer to - - for an overview of postgresql.conf. + + for an overview of `postgresql.conf`. - - String values will automatically be enclosed in single quotes. Single quotes will be - escaped with two single quotes as described by the upstream documentation linked above. - + ::: {.note} + String values will automatically be enclosed in single quotes. Single quotes will be + escaped with two single quotes as described by the upstream documentation linked above. + ::: ''; example = literalExpression '' { diff --git a/nixos/modules/services/hardware/acpid.nix b/nixos/modules/services/hardware/acpid.nix index c07fef11cc2f..821f4ef205fc 100644 --- a/nixos/modules/services/hardware/acpid.nix +++ b/nixos/modules/services/hardware/acpid.nix @@ -72,12 +72,12 @@ in }; }); - description = '' + description = lib.mdDoc '' Event handlers. - - Handler can be a single command. - + ::: {.note} + Handler can be a single command. + ::: ''; default = {}; example = { diff --git a/nixos/modules/services/hardware/bluetooth.nix b/nixos/modules/services/hardware/bluetooth.nix index 30dd15412e2e..8b90c1913bc5 100644 --- a/nixos/modules/services/hardware/bluetooth.nix +++ b/nixos/modules/services/hardware/bluetooth.nix @@ -51,13 +51,13 @@ in default = pkgs.bluez; defaultText = literalExpression "pkgs.bluez"; example = literalExpression "pkgs.bluezFull"; - description = '' + description = lib.mdDoc '' Which BlueZ package to use. - - Use the pkgs.bluezFull package to enable all - bluez plugins. - + ::: {.note} + Use the `pkgs.bluezFull` package to enable all + bluez plugins. + ::: ''; }; diff --git a/nixos/modules/services/hardware/sane.nix b/nixos/modules/services/hardware/sane.nix index de496a829f3a..5455cf56e8aa 100644 --- a/nixos/modules/services/hardware/sane.nix +++ b/nixos/modules/services/hardware/sane.nix @@ -48,12 +48,12 @@ in hardware.sane.enable = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Enable support for SANE scanners. - - Users in the "scanner" group will gain access to the scanner, or the "lp" group if it's also a printer. - + ::: {.note} + Users in the "scanner" group will gain access to the scanner, or the "lp" group if it's also a printer. + ::: ''; }; @@ -66,12 +66,12 @@ in hardware.sane.extraBackends = mkOption { type = types.listOf types.path; default = []; - description = '' + description = lib.mdDoc '' Packages providing extra SANE backends to enable. - - The example contains the package for HP scanners. - + ::: {.note} + The example contains the package for HP scanners. + ::: ''; example = literalExpression "[ pkgs.hplipWithPlugin ]"; }; diff --git a/nixos/modules/services/mail/maddy.nix b/nixos/modules/services/mail/maddy.nix index 97384c391281..eeb113e204c6 100644 --- a/nixos/modules/services/mail/maddy.nix +++ b/nixos/modules/services/mail/maddy.nix @@ -144,28 +144,28 @@ in { user = mkOption { default = "maddy"; type = with types; uniq string; - description = '' + description = lib.mdDoc '' User account under which maddy runs. - + ::: {.note} If left as the default value this user will automatically be created on system activation, otherwise the sysadmin is responsible for ensuring the user exists before the maddy service starts. - + ::: ''; }; group = mkOption { default = "maddy"; type = with types; uniq string; - description = '' + description = lib.mdDoc '' Group account under which maddy runs. - + ::: {.note} If left as the default value this group will automatically be created on system activation, otherwise the sysadmin is responsible for ensuring the group exists before the maddy service starts. - + ::: ''; }; @@ -203,14 +203,15 @@ in { config = mkOption { type = with types; nullOr lines; default = defaultConfig; - description = '' + description = lib.mdDoc '' Server configuration, see - https://maddy.email for + [https://maddy.email](https://maddy.email) for more information. The default configuration of this module will setup minimal maddy instance for mail transfer without TLS encryption. - + + ::: {.note} This should not be used in a production environment. - + ::: ''; }; diff --git a/nixos/modules/services/misc/gitlab.nix b/nixos/modules/services/misc/gitlab.nix index aa2a05900f87..42f46289c863 100644 --- a/nixos/modules/services/misc/gitlab.nix +++ b/nixos/modules/services/misc/gitlab.nix @@ -748,17 +748,15 @@ in { type = types.int; default = 2; apply = x: builtins.toString x; - description = '' + description = lib.mdDoc '' The number of worker processes Puma should spawn. This controls the amount of parallel Ruby code can be - executed. GitLab recommends Number of CPU cores - 1, but at least two. + executed. GitLab recommends `Number of CPU cores - 1`, but at least two. - - - Each worker consumes quite a bit of memory, so - be careful when increasing this. - - + ::: {.note} + Each worker consumes quite a bit of memory, so + be careful when increasing this. + ::: ''; }; @@ -766,16 +764,14 @@ in { type = types.int; default = 0; apply = x: builtins.toString x; - description = '' + description = lib.mdDoc '' The minimum number of threads Puma should use per worker. - - - Each thread consumes memory and contributes to Global VM - Lock contention, so be careful when increasing this. - - + ::: {.note} + Each thread consumes memory and contributes to Global VM + Lock contention, so be careful when increasing this. + ::: ''; }; @@ -783,19 +779,17 @@ in { type = types.int; default = 4; apply = x: builtins.toString x; - description = '' + description = lib.mdDoc '' The maximum number of threads Puma should use per worker. This limits how many threads Puma will automatically spawn in response to requests. In contrast to workers, threads will never be able to run Ruby code in parallel, but give higher IO parallelism. - - - Each thread consumes memory and contributes to Global VM - Lock contention, so be careful when increasing this. - - + ::: {.note} + Each thread consumes memory and contributes to Global VM + Lock contention, so be careful when increasing this. + ::: ''; }; diff --git a/nixos/modules/services/misc/sdrplay.nix b/nixos/modules/services/misc/sdrplay.nix index 2801108f0828..2d5333e3885b 100644 --- a/nixos/modules/services/misc/sdrplay.nix +++ b/nixos/modules/services/misc/sdrplay.nix @@ -5,13 +5,13 @@ with lib; enable = mkOption { default = false; example = true; - description = '' + description = lib.mdDoc '' Whether to enable the SDRplay API service and udev rules. - - To enable integration with SoapySDR and GUI applications like gqrx create an overlay containing - soapysdr-with-plugins = super.soapysdr.override { extraPackages = [ super.soapysdrplay ]; }; - + ::: {.note} + To enable integration with SoapySDR and GUI applications like gqrx create an overlay containing + `soapysdr-with-plugins = super.soapysdr.override { extraPackages = [ super.soapysdrplay ]; };` + ::: ''; type = lib.types.bool; }; diff --git a/nixos/modules/services/misc/sourcehut/default.nix b/nixos/modules/services/misc/sourcehut/default.nix index 56017f5f8be8..dd0e016a1da7 100644 --- a/nixos/modules/services/misc/sourcehut/default.nix +++ b/nixos/modules/services/misc/sourcehut/default.nix @@ -668,17 +668,17 @@ in }; builds = { - enableWorker = mkEnableOption '' + enableWorker = mkEnableOption (lib.mdDoc '' worker for builds.sr.ht - + ::: {.warning} For smaller deployments, job runners can be installed alongside the master server but even if you only build your own software, integration with other services may cause you to run untrusted builds (e.g. automatic testing of patches via listssrht). - See . - - ''; + See . + ::: + ''); images = mkOption { type = with types; attrsOf (attrsOf (attrsOf package)); diff --git a/nixos/modules/services/misc/taskserver/default.nix b/nixos/modules/services/misc/taskserver/default.nix index ad4ab93a872a..aeefd657f4d0 100644 --- a/nixos/modules/services/misc/taskserver/default.nix +++ b/nixos/modules/services/misc/taskserver/default.nix @@ -10,10 +10,12 @@ let mkManualPkiOption = desc: mkOption { type = types.nullOr types.path; default = null; - description = desc + '' - + description = lib.mdDoc '' + ${desc} + + ::: {.note} Setting this option will prevent automatic CA creation and handling. - + ::: ''; }; @@ -35,13 +37,13 @@ let ''; }; - mkAutoDesc = preamble: '' + mkAutoDesc = preamble: lib.mdDoc '' ${preamble} - + ::: {.note} This option is for the automatically handled CA and will be ignored if any - of the options are set. - + of the {option}`services.taskserver.pki.manual.*` options are set. + ::: ''; mkExpireOption = desc: mkOption { @@ -50,7 +52,7 @@ let example = 365; apply = val: if val == null then -1 else val; description = mkAutoDesc '' - The expiration time of ${desc} in days or null for no + The expiration time of ${desc} in days or `null` for no expiration time. ''; }; @@ -140,11 +142,11 @@ in { default = false; description = let url = "https://nixos.org/manual/nixos/stable/index.html#module-services-taskserver"; - in '' + in lib.mdDoc '' Whether to enable the Taskwarrior server. More instructions about NixOS in conjuction with Taskserver can be - found in the NixOS manual. + found [in the NixOS manual](${url}). ''; }; @@ -172,9 +174,9 @@ in { example = "NORMAL:-VERS-SSL3.0"; description = let url = "https://gnutls.org/manual/html_node/Priority-Strings.html"; - in '' + in lib.mdDoc '' List of GnuTLS ciphers to use. See the GnuTLS documentation about - priority strings at for full details. + priority strings at <${url}> for full details. ''; }; diff --git a/nixos/modules/services/network-filesystems/samba-wsdd.nix b/nixos/modules/services/network-filesystems/samba-wsdd.nix index 38980593e768..e28fe4cf9c4d 100644 --- a/nixos/modules/services/network-filesystems/samba-wsdd.nix +++ b/nixos/modules/services/network-filesystems/samba-wsdd.nix @@ -8,17 +8,17 @@ let in { options = { services.samba-wsdd = { - enable = mkEnableOption '' + enable = mkEnableOption (lib.mdDoc '' Enable Web Services Dynamic Discovery host daemon. This enables (Samba) hosts, like your local NAS device, to be found by Web Service Discovery Clients like Windows. - - If you use the firewall consider adding the following: - + + ::: {.note} + If you use the firewall consider adding the following: + networking.firewall.allowedTCPPorts = [ 5357 ]; networking.firewall.allowedUDPPorts = [ 3702 ]; - - - ''; + ::: + ''); interface = mkOption { type = types.nullOr types.str; default = null; diff --git a/nixos/modules/services/network-filesystems/samba.nix b/nixos/modules/services/network-filesystems/samba.nix index 7a07b043859b..1310a374abd0 100644 --- a/nixos/modules/services/network-filesystems/samba.nix +++ b/nixos/modules/services/network-filesystems/samba.nix @@ -80,16 +80,15 @@ in enable = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Whether to enable Samba, which provides file and print services to Windows clients through the SMB/CIFS protocol. - - If you use the firewall consider adding the following: - - services.samba.openFirewall = true; - - + ::: {.note} + If you use the firewall consider adding the following: + + services.samba.openFirewall = true; + ::: ''; }; diff --git a/nixos/modules/services/networking/adguardhome.nix b/nixos/modules/services/networking/adguardhome.nix index 9e014cd3d72a..13b6f6efcd6d 100644 --- a/nixos/modules/services/networking/adguardhome.nix +++ b/nixos/modules/services/networking/adguardhome.nix @@ -64,16 +64,16 @@ in { settings = mkOption { type = (pkgs.formats.yaml { }).type; default = { }; - description = '' + description = lib.mdDoc '' AdGuard Home configuration. Refer to - + for details on supported values. - - On start and if is true, - these options are merged into the configuration file on start, taking - precedence over configuration changes made on the web interface. - + ::: {.note} + On start and if {option}`mutableSettings` is `true`, + these options are merged into the configuration file on start, taking + precedence over configuration changes made on the web interface. + ::: ''; }; diff --git a/nixos/modules/services/networking/headscale.nix b/nixos/modules/services/networking/headscale.nix index f2687809f7d4..0334c5a00bab 100644 --- a/nixos/modules/services/networking/headscale.nix +++ b/nixos/modules/services/networking/headscale.nix @@ -26,26 +26,28 @@ in user = mkOption { default = "headscale"; type = types.str; - description = '' + description = lib.mdDoc '' User account under which headscale runs. - + + ::: {.note} If left as the default value this user will automatically be created on system activation, otherwise you are responsible for ensuring the user exists before the headscale service starts. - + ::: ''; }; group = mkOption { default = "headscale"; type = types.str; - description = '' + description = lib.mdDoc '' Group under which headscale runs. - + + ::: {.note} If left as the default value this group will automatically be created on system activation, otherwise you are responsible for ensuring the user exists before the headscale service starts. - + ::: ''; }; diff --git a/nixos/modules/services/networking/libreswan.nix b/nixos/modules/services/networking/libreswan.nix index 41a0aca02830..b5df31c28d7c 100644 --- a/nixos/modules/services/networking/libreswan.nix +++ b/nixos/modules/services/networking/libreswan.nix @@ -93,12 +93,12 @@ in '''; } ''; - description = '' + description = lib.mdDoc '' A set of policies to apply to the IPsec connections. - - The policy name must match the one of connection it needs to apply to. - + ::: {.note} + The policy name must match the one of connection it needs to apply to. + ::: ''; }; diff --git a/nixos/modules/services/networking/privoxy.nix b/nixos/modules/services/networking/privoxy.nix index ddb1d816c815..78d02aaa1125 100644 --- a/nixos/modules/services/networking/privoxy.nix +++ b/nixos/modules/services/networking/privoxy.nix @@ -67,21 +67,21 @@ in inspectHttps = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Whether to configure Privoxy to inspect HTTPS requests, meaning all encrypted traffic will be filtered as well. This works by decrypting and re-encrypting the requests using a per-domain generated certificate. To issue per-domain certificates, Privoxy must be provided with a CA - certificate, using the ca-cert-file, - ca-key-file settings. + certificate, using the `ca-cert-file`, + `ca-key-file` settings. - - The CA certificate must also be added to the system trust roots, - otherwise browsers will reject all Privoxy certificates as invalid. - You can do so by using the option - . - + ::: {.warning} + The CA certificate must also be added to the system trust roots, + otherwise browsers will reject all Privoxy certificates as invalid. + You can do so by using the option + {option}`security.pki.certificateFiles`. + ::: ''; }; @@ -89,8 +89,8 @@ in type = ageType; default = "10d"; example = "12h"; - description = '' - If inspectHttps is enabled, the time generated HTTPS + description = lib.mdDoc '' + If `inspectHttps` is enabled, the time generated HTTPS certificates will be stored in a temporary directory for reuse. Once the lifetime has expired the directory will cleared and the certificate will have to be generated again, on-demand. @@ -98,8 +98,10 @@ in Depending on the traffic, you may want to reduce the lifetime to limit the disk usage, since Privoxy itself never deletes the certificates. - The format is that of the tmpfiles.d(5) - Age parameter. + ::: {.note} + The format is that of the `tmpfiles.d(5)` + Age parameter. + ::: ''; }; @@ -179,15 +181,15 @@ in # debug 64 } ''; - description = '' + description = lib.mdDoc '' This option is mapped to the main Privoxy configuration file. Check out the Privoxy user manual at - + for available settings and documentation. - - Repeated settings can be represented by using a list. - + ::: {.note} + Repeated settings can be represented by using a list. + ::: ''; }; diff --git a/nixos/modules/services/networking/prosody.nix b/nixos/modules/services/networking/prosody.nix index f32c7adbd2c3..6cd4678ae4ac 100644 --- a/nixos/modules/services/networking/prosody.nix +++ b/nixos/modules/services/networking/prosody.nix @@ -529,28 +529,28 @@ in user = mkOption { type = types.str; default = "prosody"; - description = '' + description = lib.mdDoc '' User account under which prosody runs. - + ::: {.note} If left as the default value this user will automatically be created on system activation, otherwise you are responsible for ensuring the user exists before the prosody service starts. - + ::: ''; }; group = mkOption { type = types.str; default = "prosody"; - description = '' + description = lib.mdDoc '' Group account under which prosody runs. - + ::: {.note} If left as the default value this group will automatically be created on system activation, otherwise you are responsible for ensuring the group exists before the prosody service starts. - + ::: ''; }; diff --git a/nixos/modules/services/networking/searx.nix b/nixos/modules/services/networking/searx.nix index 238479864f88..e594d0083d4f 100644 --- a/nixos/modules/services/networking/searx.nix +++ b/nixos/modules/services/networking/searx.nix @@ -81,35 +81,33 @@ in }; } ''; - description = '' + description = lib.mdDoc '' Searx settings. These will be merged with (taking precedence over) the default configuration. It's also possible to refer to environment variables - (defined in ) - using the syntax @VARIABLE_NAME@. - - - For available settings, see the Searx - docs. - - + (defined in [](#opt-services.searx.environmentFile)) + using the syntax `@VARIABLE_NAME@`. + + ::: {.note} + For available settings, see the Searx + [docs](https://searx.github.io/searx/admin/settings.html). + ::: ''; }; settingsFile = mkOption { type = types.path; default = "${runDir}/settings.yml"; - description = '' + description = lib.mdDoc '' The path of the Searx server settings.yml file. If no file is specified, a default file is used (default config file has debug mode enabled). Note: setting this options overrides - . - - - This file, along with any secret key it contains, will be copied - into the world-readable Nix store. - - + [](#opt-services.searx.settings). + + ::: {.warning} + This file, along with any secret key it contains, will be copied + into the world-readable Nix store. + ::: ''; }; @@ -123,15 +121,14 @@ in runInUwsgi = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Whether to run searx in uWSGI as a "vassal", instead of using its built-in HTTP server. This is the recommended mode for public or large instances, but is unecessary for LAN or local-only use. - - - The built-in HTTP server logs all queries by default. - - + + ::: {.warning} + The built-in HTTP server logs all queries by default. + ::: ''; }; diff --git a/nixos/modules/services/networking/shorewall.nix b/nixos/modules/services/networking/shorewall.nix index 795295d1628f..ba59d71120da 100644 --- a/nixos/modules/services/networking/shorewall.nix +++ b/nixos/modules/services/networking/shorewall.nix @@ -8,15 +8,14 @@ in { enable = lib.mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Whether to enable Shorewall IPv4 Firewall. - - - Enabling this service WILL disable the existing NixOS - firewall! Default firewall rules provided by packages are not - considered at the moment. - - + + ::: {.warning} + Enabling this service WILL disable the existing NixOS + firewall! Default firewall rules provided by packages are not + considered at the moment. + ::: ''; }; package = lib.mkOption { diff --git a/nixos/modules/services/networking/shorewall6.nix b/nixos/modules/services/networking/shorewall6.nix index 1d6d84eb89b3..e54be290bfb3 100644 --- a/nixos/modules/services/networking/shorewall6.nix +++ b/nixos/modules/services/networking/shorewall6.nix @@ -8,15 +8,14 @@ in { enable = lib.mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Whether to enable Shorewall IPv6 Firewall. - - - Enabling this service WILL disable the existing NixOS - firewall! Default firewall rules provided by packages are not - considered at the moment. - - + + ::: {.warning} + Enabling this service WILL disable the existing NixOS + firewall! Default firewall rules provided by packages are not + considered at the moment. + ::: ''; }; package = lib.mkOption { diff --git a/nixos/modules/services/networking/wpa_supplicant.nix b/nixos/modules/services/networking/wpa_supplicant.nix index ccf6f2791867..6c58bcfbbf18 100644 --- a/nixos/modules/services/networking/wpa_supplicant.nix +++ b/nixos/modules/services/networking/wpa_supplicant.nix @@ -170,13 +170,13 @@ in { type = types.listOf types.str; default = []; example = [ "wlan0" "wlan1" ]; - description = '' - The interfaces wpa_supplicant will use. If empty, it will + description = lib.mdDoc '' + The interfaces {command}`wpa_supplicant` will use. If empty, it will automatically use all wireless interfaces. - - A separate wpa_supplicant instance will be started for each interface. - + ::: {.note} + A separate wpa_supplicant instance will be started for each interface. + ::: ''; }; @@ -186,7 +186,7 @@ in { description = lib.mdDoc "Force a specific wpa_supplicant driver."; }; - allowAuxiliaryImperativeNetworks = mkEnableOption "support for imperative & declarative networks" // { + allowAuxiliaryImperativeNetworks = mkEnableOption (lib.mdDoc "support for imperative & declarative networks") // { description = '' Whether to allow configuring networks "imperatively" (e.g. via wpa_supplicant_gui) and declaratively via @@ -222,24 +222,24 @@ in { type = types.nullOr types.path; default = null; example = "/run/secrets/wireless.env"; - description = '' - File consisting of lines of the form varname=value + description = lib.mdDoc '' + File consisting of lines of the form `varname=value` to define variables for the wireless configuration. - See section "EnvironmentFile=" in systemd.exec5 for a syntax reference. + See section "EnvironmentFile=" in {manpage}`systemd.exec(5)` for a syntax reference. Secrets (PSKs, passwords, etc.) can be provided without adding them to the world-readable Nix store by defining them in the environment file and - referring to them in option - with the syntax @varname@. Example: + referring to them in option {option}`networking.wireless.networks` + with the syntax `@varname@`. Example: - + ``` # content of /run/secrets/wireless.env PSK_HOME=mypassword PASS_WORK=myworkpassword - + ``` - + ``` # wireless-related configuration networking.wireless.environmentFile = "/run/secrets/wireless.env"; networking.wireless.networks = { @@ -250,7 +250,7 @@ in { password="@PASS_WORK@" '''; }; - + ``` ''; }; @@ -260,36 +260,36 @@ in { psk = mkOption { type = types.nullOr types.str; default = null; - description = '' + description = lib.mdDoc '' The network's pre-shared key in plaintext defaulting to being a network without any authentication. - - Be aware that this will be written to the nix store - in plaintext! Use an environment variable instead. - + ::: {.warning} + Be aware that this will be written to the nix store + in plaintext! Use an environment variable instead. + ::: - - Mutually exclusive with pskRaw. - + ::: {.note} + Mutually exclusive with {var}`pskRaw`. + ::: ''; }; pskRaw = mkOption { type = types.nullOr types.str; default = null; - description = '' + description = lib.mdDoc '' The network's pre-shared key in hex defaulting to being a network without any authentication. - - Be aware that this will be written to the nix store - in plaintext! Use an environment variable instead. - + ::: {.warning} + Be aware that this will be written to the nix store + in plaintext! Use an environment variable instead. + ::: - - Mutually exclusive with psk. - + ::: {.note} + Mutually exclusive with {var}`psk`. + ::: ''; }; @@ -343,21 +343,21 @@ in { identity="user@example.com" password="@EXAMPLE_PASSWORD@" ''; - description = '' + description = lib.mdDoc '' Use this option to configure advanced authentication methods like EAP. See - wpa_supplicant.conf5 + {manpage}`wpa_supplicant.conf(5)` for example configurations. - - Be aware that this will be written to the nix store - in plaintext! Use an environment variable for secrets. - + ::: {.warning} + Be aware that this will be written to the nix store + in plaintext! Use an environment variable for secrets. + ::: - - Mutually exclusive with psk and - pskRaw. - + ::: {.note} + Mutually exclusive with {var}`psk` and + {var}`pskRaw`. + ::: ''; }; diff --git a/nixos/modules/services/security/cfssl.nix b/nixos/modules/services/security/cfssl.nix index 006b31b18688..202db98e222c 100644 --- a/nixos/modules/services/security/cfssl.nix +++ b/nixos/modules/services/security/cfssl.nix @@ -11,15 +11,15 @@ in { dataDir = mkOption { default = "/var/lib/cfssl"; type = types.path; - description = '' + description = lib.mdDoc '' The work directory for CFSSL. - - If left as the default value this directory will automatically be - created before the CFSSL server starts, otherwise you are - responsible for ensuring the directory exists with appropriate - ownership and permissions. - + ::: {.note} + If left as the default value this directory will automatically be + created before the CFSSL server starts, otherwise you are + responsible for ensuring the directory exists with appropriate + ownership and permissions. + ::: ''; }; diff --git a/nixos/modules/services/security/step-ca.nix b/nixos/modules/services/security/step-ca.nix index 8cbab5af0977..433f162ecb86 100644 --- a/nixos/modules/services/security/step-ca.nix +++ b/nixos/modules/services/security/step-ca.nix @@ -34,42 +34,38 @@ in }; settings = lib.mkOption { type = with lib.types; attrsOf anything; - description = '' - Settings that go into ca.json. See - the step-ca manual + description = lib.mdDoc '' + Settings that go into {file}`ca.json`. See + [the step-ca manual](https://smallstep.com/docs/step-ca/configuration) for more information. The easiest way to - configure this module would be to run step ca init - to generate ca.json and then import it using - builtins.fromJSON. - This article + configure this module would be to run `step ca init` + to generate {file}`ca.json` and then import it using + `builtins.fromJSON`. + [This article](https://smallstep.com/docs/step-cli/basic-crypto-operations#run-an-offline-x509-certificate-authority) may also be useful if you want to customize certain aspects of certificate generation for your CA. - You need to change the database storage path to /var/lib/step-ca/db. + You need to change the database storage path to {file}`/var/lib/step-ca/db`. - - - The option - will be ignored and overwritten by - and - . - - + ::: {.warning} + The {option}`services.step-ca.settings.address` option + will be ignored and overwritten by + {option}`services.step-ca.address` and + {option}`services.step-ca.port`. + ::: ''; }; intermediatePasswordFile = lib.mkOption { type = lib.types.path; example = "/run/keys/smallstep-password"; - description = '' + description = lib.mdDoc '' Path to the file containing the password for the intermediate certificate private key. - - - Make sure to use a quoted absolute path instead of a path literal - to prevent it from being copied to the globally readable Nix - store. - - + ::: {.warning} + Make sure to use a quoted absolute path instead of a path literal + to prevent it from being copied to the globally readable Nix + store. + ::: ''; }; }; diff --git a/nixos/modules/services/security/torify.nix b/nixos/modules/services/security/torify.nix index 770e445d733f..4d311adebcae 100644 --- a/nixos/modules/services/security/torify.nix +++ b/nixos/modules/services/security/torify.nix @@ -27,16 +27,16 @@ in enable = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Whether to build tsocks wrapper script to relay application traffic via Tor. - - You shouldn't use this unless you know what you're - doing because your installation of Tor already comes with - its own superior (doesn't leak DNS queries) - torsocks wrapper which does pretty much - exactly the same thing as this. - + ::: {.important} + You shouldn't use this unless you know what you're + doing because your installation of Tor already comes with + its own superior (doesn't leak DNS queries) + `torsocks` wrapper which does pretty much + exactly the same thing as this. + ::: ''; }; diff --git a/nixos/modules/services/torrent/magnetico.nix b/nixos/modules/services/torrent/magnetico.nix index b43389c5d0b0..b681c58dfe2a 100644 --- a/nixos/modules/services/torrent/magnetico.nix +++ b/nixos/modules/services/torrent/magnetico.nix @@ -116,43 +116,41 @@ in { myuser = "$2y$12$YE01LZ8jrbQbx6c0s2hdZO71dSjn2p/O9XsYJpz.5968yCysUgiaG"; } ''; - description = '' + description = lib.mdDoc '' The credentials to access the web interface, in case authentication is - enabled, in the format username:hash. If unset no + enabled, in the format `username:hash`. If unset no authentication will be required. Usernames must start with a lowercase ([a-z]) ASCII character, might contain non-consecutive underscores except at the end, and consists of small-case a-z characters and digits 0-9. The - htpasswd tool from the apacheHttpd + {command}`htpasswd` tool from the `apacheHttpd` package may be used to generate the hash: - htpasswd -bnBC 12 username password + {command}`htpasswd -bnBC 12 username password` - - - The hashes will be stored world-readable in the nix store. - Consider using the credentialsFile option if you - don't want this. - - + ::: {.warning} + The hashes will be stored world-readable in the nix store. + Consider using the `credentialsFile` option if you + don't want this. + ::: ''; }; web.credentialsFile = mkOption { type = types.nullOr types.path; default = null; - description = '' + description = lib.mdDoc '' The path to the file holding the credentials to access the web interface. If unset no authentication will be required. The file must constain user names and password hashes in the format - username:hash , one for each line. Usernames must + `username:hash `, one for each line. Usernames must start with a lowecase ([a-z]) ASCII character, might contain non-consecutive underscores except at the end, and consists of small-case a-z characters and digits 0-9. - The htpasswd tool from the apacheHttpd + The {command}`htpasswd` tool from the `apacheHttpd` package may be used to generate the hash: - htpasswd -bnBC 12 username password + {command}`htpasswd -bnBC 12 username password` ''; }; diff --git a/nixos/modules/services/video/epgstation/default.nix b/nixos/modules/services/video/epgstation/default.nix index ebd71724d18a..3d1d7a27c216 100644 --- a/nixos/modules/services/video/epgstation/default.nix +++ b/nixos/modules/services/video/epgstation/default.nix @@ -101,16 +101,14 @@ in openFirewall = lib.mkOption { type = lib.types.bool; default = false; - description = '' + description = lib.mdDoc '' Open ports in the firewall for the EPGStation web interface. - - - Exposing EPGStation to the open internet is generally advised - against. Only use it inside a trusted local network, or consider - putting it behind a VPN if you want remote access. - - + ::: {.warning} + Exposing EPGStation to the open internet is generally advised + against. Only use it inside a trusted local network, or consider + putting it behind a VPN if you want remote access. + ::: ''; }; diff --git a/nixos/modules/services/video/mirakurun.nix b/nixos/modules/services/video/mirakurun.nix index 18aaedc410f8..5484515e7cb4 100644 --- a/nixos/modules/services/video/mirakurun.nix +++ b/nixos/modules/services/video/mirakurun.nix @@ -38,16 +38,14 @@ in openFirewall = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Open ports in the firewall for Mirakurun. - - - Exposing Mirakurun to the open internet is generally advised - against. Only use it inside a trusted local network, or - consider putting it behind a VPN if you want remote access. - - + ::: {.warning} + Exposing Mirakurun to the open internet is generally advised + against. Only use it inside a trusted local network, or + consider putting it behind a VPN if you want remote access. + ::: ''; }; diff --git a/nixos/modules/services/web-apps/dokuwiki.nix b/nixos/modules/services/web-apps/dokuwiki.nix index ea1d5c837d5f..e719d11e4d2e 100644 --- a/nixos/modules/services/web-apps/dokuwiki.nix +++ b/nixos/modules/services/web-apps/dokuwiki.nix @@ -160,9 +160,12 @@ let plugins = mkOption { type = types.listOf types.path; default = []; - description = '' + description = lib.mdDoc '' List of path(s) to respective plugin(s) which are copied from the 'plugin' directory. - These plugins need to be packaged before use, see example. + + ::: {.note} + These plugins need to be packaged before use, see example. + ::: ''; example = literalExpression '' let @@ -188,9 +191,12 @@ let templates = mkOption { type = types.listOf types.path; default = []; - description = '' + description = lib.mdDoc '' List of path(s) to respective template(s) which are copied from the 'tpl' directory. - These templates need to be packaged before use, see example. + + ::: {.note} + These templates need to be packaged before use, see example. + ::: ''; example = literalExpression '' let diff --git a/nixos/modules/services/web-apps/healthchecks.nix b/nixos/modules/services/web-apps/healthchecks.nix index b3380b88f613..2c55f5ec8ebb 100644 --- a/nixos/modules/services/web-apps/healthchecks.nix +++ b/nixos/modules/services/web-apps/healthchecks.nix @@ -43,28 +43,28 @@ in user = mkOption { default = defaultUser; type = types.str; - description = '' + description = lib.mdDoc '' User account under which healthchecks runs. - + ::: {.note} If left as the default value this user will automatically be created on system activation, otherwise you are responsible for ensuring the user exists before the healthchecks service starts. - + ::: ''; }; group = mkOption { default = defaultUser; type = types.str; - description = '' + description = lib.mdDoc '' Group account under which healthchecks runs. - + ::: {.note} If left as the default value this group will automatically be created on system activation, otherwise you are responsible for ensuring the group exists before the healthchecks service starts. - + ::: ''; }; @@ -83,28 +83,28 @@ in dataDir = mkOption { type = types.str; default = "/var/lib/healthchecks"; - description = '' + description = lib.mdDoc '' The directory used to store all data for healthchecks. - + ::: {.note} If left as the default value this directory will automatically be created before the healthchecks server starts, otherwise you are responsible for ensuring the directory exists with appropriate ownership and permissions. - + ::: ''; }; settings = lib.mkOption { - description = '' - Environment variables which are read by healthchecks (local)_settings.py. + description = lib.mdDoc '' + Environment variables which are read by healthchecks `(local)_settings.py`. Settings which are explictly covered in options bewlow, are type-checked and/or transformed before added to the environment, everything else is passed as a string. - See https://healthchecks.io/docs/self_hosted_configuration/ + See for a full documentation of settings. - We add two variables to this list inside the packages local_settings.py. + We add two variables to this list inside the packages `local_settings.py.` - STATIC_ROOT to set a state directory for dynamically generated static files. - SECRET_KEY_FILE to read SECRET_KEY from a file at runtime and keep it out of /nix/store. ''; diff --git a/nixos/modules/services/web-apps/invoiceplane.nix b/nixos/modules/services/web-apps/invoiceplane.nix index 72027523ef34..156cc238e89a 100644 --- a/nixos/modules/services/web-apps/invoiceplane.nix +++ b/nixos/modules/services/web-apps/invoiceplane.nix @@ -124,9 +124,12 @@ let invoiceTemplates = mkOption { type = types.listOf types.path; default = []; - description = '' + description = lib.mdDoc '' List of path(s) to respective template(s) which are copied from the 'invoice_templates/pdf' directory. - These templates need to be packaged before use, see example. + + ::: {.note} + These templates need to be packaged before use, see example. + ::: ''; example = literalExpression '' let diff --git a/nixos/modules/services/web-apps/keycloak.nix b/nixos/modules/services/web-apps/keycloak.nix index 82684f5e5208..301efe7e5d94 100644 --- a/nixos/modules/services/web-apps/keycloak.nix +++ b/nixos/modules/services/web-apps/keycloak.nix @@ -314,23 +314,21 @@ in type = str; default = ""; example = "/auth"; - description = '' - The path relative to / for serving + description = lib.mdDoc '' + The path relative to `/` for serving resources. - - - In versions of Keycloak using Wildfly (<17), - this defaulted to /auth. If - upgrading from the Wildfly version of Keycloak, - i.e. a NixOS version before 22.05, you'll likely - want to set this to /auth to - keep compatibility with your clients. + ::: {.note} + In versions of Keycloak using Wildfly (<17), + this defaulted to `/auth`. If + upgrading from the Wildfly version of Keycloak, + i.e. a NixOS version before 22.05, you'll likely + want to set this to `/auth` to + keep compatibility with your clients. - See - for more information on migrating from Wildfly to Quarkus. - - + See + for more information on migrating from Wildfly to Quarkus. + ::: ''; }; diff --git a/nixos/modules/services/web-apps/nextcloud.nix b/nixos/modules/services/web-apps/nextcloud.nix index 6ed5f066be50..fdbaa90ebb7a 100644 --- a/nixos/modules/services/web-apps/nextcloud.nix +++ b/nixos/modules/services/web-apps/nextcloud.nix @@ -371,16 +371,16 @@ in { default = null; type = types.nullOr types.str; example = "DE"; - description = '' - - This option exists since Nextcloud 21! If older versions are used, - this will throw an eval-error! - + description = lib.mdDoc '' + ::: {.warning} + This option exists since Nextcloud 21! If older versions are used, + this will throw an eval-error! + ::: - ISO 3611-1 + [ISO 3611-1](https://www.iso.org/iso-3166-country-codes.html) country codes for automatic phone-number detection without a country code. - With e.g. DE set, the +49 can be omitted for + With e.g. `DE` set, the `+49` can be omitted for phone-numbers. ''; }; @@ -519,8 +519,8 @@ in { type = with types; either str (listOf str); default = "05:00:00"; example = "Sun 14:00:00"; - description = '' - When to run the update. See `systemd.services.<name>.startAt`. + description = lib.mdDoc '' + When to run the update. See `systemd.services..startAt`. ''; }; }; diff --git a/nixos/modules/services/web-apps/wordpress.nix b/nixos/modules/services/web-apps/wordpress.nix index c841ded353e7..f2e78d028559 100644 --- a/nixos/modules/services/web-apps/wordpress.nix +++ b/nixos/modules/services/web-apps/wordpress.nix @@ -97,9 +97,12 @@ let plugins = mkOption { type = types.listOf types.path; default = []; - description = '' + description = lib.mdDoc '' List of path(s) to respective plugin(s) which are copied from the 'plugins' directory. - These plugins need to be packaged before use, see example. + + ::: {.note} + These plugins need to be packaged before use, see example. + ::: ''; example = literalExpression '' let @@ -124,9 +127,12 @@ let themes = mkOption { type = types.listOf types.path; default = []; - description = '' + description = lib.mdDoc '' List of path(s) to respective theme(s) which are copied from the 'theme' directory. - These themes need to be packaged before use, see example. + + ::: {.note} + These themes need to be packaged before use, see example. + ::: ''; example = literalExpression '' let diff --git a/nixos/modules/services/web-servers/apache-httpd/default.nix b/nixos/modules/services/web-servers/apache-httpd/default.nix index 346e2b5a9270..6b43d46fdead 100644 --- a/nixos/modules/services/web-servers/apache-httpd/default.nix +++ b/nixos/modules/services/web-servers/apache-httpd/default.nix @@ -484,14 +484,14 @@ in user = mkOption { type = types.str; default = "wwwrun"; - description = '' + description = lib.mdDoc '' User account under which httpd children processes run. If you require the main httpd process to run as - root add the following configuration: - + `root` add the following configuration: + ``` systemd.services.httpd.serviceConfig.User = lib.mkForce "root"; - + ``` ''; }; diff --git a/nixos/modules/services/web-servers/apache-httpd/vhost-options.nix b/nixos/modules/services/web-servers/apache-httpd/vhost-options.nix index 4f84cad73514..5b7b752884e4 100644 --- a/nixos/modules/services/web-servers/apache-httpd/vhost-options.nix +++ b/nixos/modules/services/web-servers/apache-httpd/vhost-options.nix @@ -45,16 +45,14 @@ in { ip = "192.154.1.1"; port = 80; } { ip = "*"; port = 8080; } ]; - description = '' + description = lib.mdDoc '' Listen addresses and ports for this virtual host. - - - This option overrides addSSL, forceSSL and onlySSL. - - - If you only want to set the addresses manually and not the ports, take a look at listenAddresses. - - + + ::: {.note} + This option overrides `addSSL`, `forceSSL` and `onlySSL`. + + If you only want to set the addresses manually and not the ports, take a look at `listenAddresses`. + ::: ''; }; @@ -202,14 +200,14 @@ in file = "/home/eelco/some-file.png"; } ]; - description = '' + description = lib.mdDoc '' This option provides a simple way to serve individual, static files. - - This option has been deprecated and will be removed in a future - version of NixOS. You can achieve the same result by making use of - the locations.<name>.alias option. - + ::: {.note} + This option has been deprecated and will be removed in a future + version of NixOS. You can achieve the same result by making use of + the `locations..alias` option. + ::: ''; }; diff --git a/nixos/modules/services/web-servers/caddy/default.nix b/nixos/modules/services/web-servers/caddy/default.nix index e5ad99c29853..e364cb33be30 100644 --- a/nixos/modules/services/web-servers/caddy/default.nix +++ b/nixos/modules/services/web-servers/caddy/default.nix @@ -57,28 +57,28 @@ in user = mkOption { default = "caddy"; type = types.str; - description = '' + description = lib.mdDoc '' User account under which caddy runs. - - If left as the default value this user will automatically be created - on system activation, otherwise you are responsible for - ensuring the user exists before the Caddy service starts. - + ::: {.note} + If left as the default value this user will automatically be created + on system activation, otherwise you are responsible for + ensuring the user exists before the Caddy service starts. + ::: ''; }; group = mkOption { default = "caddy"; type = types.str; - description = '' + description = lib.mdDoc '' Group account under which caddy runs. - - If left as the default value this user will automatically be created - on system activation, otherwise you are responsible for - ensuring the user exists before the Caddy service starts. - + ::: {.note} + If left as the default value this user will automatically be created + on system activation, otherwise you are responsible for + ensuring the user exists before the Caddy service starts. + ::: ''; }; @@ -94,34 +94,31 @@ in dataDir = mkOption { type = types.path; default = "/var/lib/caddy"; - description = '' + description = lib.mdDoc '' The data directory for caddy. - - - If left as the default value this directory will automatically be created - before the Caddy server starts, otherwise you are responsible for ensuring - the directory exists with appropriate ownership and permissions. - - - Caddy v2 replaced CADDYPATH with XDG directories. - See . - - + ::: {.note} + If left as the default value this directory will automatically be created + before the Caddy server starts, otherwise you are responsible for ensuring + the directory exists with appropriate ownership and permissions. + + Caddy v2 replaced `CADDYPATH` with XDG directories. + See . + ::: ''; }; logDir = mkOption { type = types.path; default = "/var/log/caddy"; - description = '' + description = lib.mdDoc '' Directory for storing Caddy access logs. - - If left as the default value this directory will automatically be created - before the Caddy server starts, otherwise the sysadmin is responsible for - ensuring the directory exists with appropriate ownership and permissions. - + ::: {.note} + If left as the default value this directory will automatically be created + before the Caddy server starts, otherwise the sysadmin is responsible for + ensuring the directory exists with appropriate ownership and permissions. + ::: ''; }; @@ -163,15 +160,15 @@ in default = "caddyfile"; example = "nginx"; type = types.str; - description = '' + description = lib.mdDoc '' Name of the config adapter to use. - See + See for the full list. - - Any value other than caddyfile is only valid when - providing your own . - + ::: {.note} + Any value other than `caddyfile` is only valid when + providing your own {option}`configFile`. + ::: ''; }; diff --git a/nixos/modules/services/web-servers/phpfpm/default.nix b/nixos/modules/services/web-servers/phpfpm/default.nix index e24c77d056a2..0bd1d5b29b31 100644 --- a/nixos/modules/services/web-servers/phpfpm/default.nix +++ b/nixos/modules/services/web-servers/phpfpm/default.nix @@ -40,9 +40,12 @@ let socket = mkOption { type = types.str; readOnly = true; - description = '' + description = lib.mdDoc '' Path to the unix socket file on which to accept FastCGI requests. - This option is read-only and managed by NixOS. + + ::: {.note} + This option is read-only and managed by NixOS. + ::: ''; example = "${runtimeDir}/.sock"; }; diff --git a/nixos/modules/services/web-servers/uwsgi.nix b/nixos/modules/services/web-servers/uwsgi.nix index af6c6c066124..510582feaae1 100644 --- a/nixos/modules/services/web-servers/uwsgi.nix +++ b/nixos/modules/services/web-servers/uwsgi.nix @@ -167,22 +167,20 @@ in { "CAP_NET_RAW" # open raw sockets ] ''; - description = '' + description = lib.mdDoc '' Grant capabilities to the uWSGI instance. See the - capabilities(7) for available values. - - - uWSGI runs as an unprivileged user (even as Emperor) with the minimal - capabilities required. This option can be used to add fine-grained - permissions without running the service as root. - - - When in Emperor mode, any capability to be inherited by a vassal must - be specified again in the vassal configuration using cap. - See the uWSGI docs - for more information. - - + `capabilities(7)` for available values. + + ::: {.note} + uWSGI runs as an unprivileged user (even as Emperor) with the minimal + capabilities required. This option can be used to add fine-grained + permissions without running the service as root. + + When in Emperor mode, any capability to be inherited by a vassal must + be specified again in the vassal configuration using `cap`. + See the uWSGI [docs](https://uwsgi-docs.readthedocs.io/en/latest/Capabilities.html) + for more information. + ::: ''; }; }; diff --git a/nixos/modules/services/x11/xserver.nix b/nixos/modules/services/x11/xserver.nix index 9666fe2d6f75..83a71dcf23e0 100644 --- a/nixos/modules/services/x11/xserver.nix +++ b/nixos/modules/services/x11/xserver.nix @@ -431,23 +431,25 @@ in firstPrimary = head heads // { primary = true; }; newHeads = singleton firstPrimary ++ tail heads; in if heads != [] && !hasPrimary then newHeads else heads; - description = '' + description = lib.mdDoc '' Multiple monitor configuration, just specify a list of XRandR outputs. The individual elements should be either simple strings or an attribute set of output options. If the element is a string, it is denoting the physical output for a monitor, if it's an attribute set, you must at least provide the - option. + {option}`output` option. The monitors will be mapped from left to right in the order of the list. By default, the first monitor will be set as the primary monitor if none of the elements contain an option that has set - to true. + {option}`primary` to `true`. - Only one monitor is allowed to be primary. + ::: {.note} + Only one monitor is allowed to be primary. + ::: Be careful using this option with multiple graphic adapters or with drivers that have poor support for XRandR, unexpected things might diff --git a/nixos/modules/system/boot/initrd-openvpn.nix b/nixos/modules/system/boot/initrd-openvpn.nix index 9f476e07208a..b41e7524320e 100644 --- a/nixos/modules/system/boot/initrd-openvpn.nix +++ b/nixos/modules/system/boot/initrd-openvpn.nix @@ -25,15 +25,13 @@ in boot.initrd.network.openvpn.configuration = mkOption { type = types.path; # Same type as boot.initrd.secrets - description = '' + description = lib.mdDoc '' The configuration file for OpenVPN. - - - Unless your bootloader supports initrd secrets, this configuration - is stored insecurely in the global Nix store. - - + ::: {.warning} + Unless your bootloader supports initrd secrets, this configuration + is stored insecurely in the global Nix store. + ::: ''; example = literalExpression "./configuration.ovpn"; }; diff --git a/nixos/modules/system/boot/initrd-ssh.nix b/nixos/modules/system/boot/initrd-ssh.nix index 171c51308a79..256aa608ac43 100644 --- a/nixos/modules/system/boot/initrd-ssh.nix +++ b/nixos/modules/system/boot/initrd-ssh.nix @@ -47,32 +47,29 @@ in "/etc/secrets/initrd/ssh_host_rsa_key" "/etc/secrets/initrd/ssh_host_ed25519_key" ]; - description = '' + description = lib.mdDoc '' Specify SSH host keys to import into the initrd. To generate keys, use - ssh-keygen1 + {manpage}`ssh-keygen(1)` as root: - + ``` ssh-keygen -t rsa -N "" -f /etc/secrets/initrd/ssh_host_rsa_key ssh-keygen -t ed25519 -N "" -f /etc/secrets/initrd/ssh_host_ed25519_key - + ``` - - - Unless your bootloader supports initrd secrets, these keys - are stored insecurely in the global Nix store. Do NOT use - your regular SSH host private keys for this purpose or - you'll expose them to regular users! - - - Additionally, even if your initrd supports secrets, if - you're using initrd SSH to unlock an encrypted disk then - using your regular host keys exposes the private keys on - your unencrypted boot partition. - - + ::: {.warning} + Unless your bootloader supports initrd secrets, these keys + are stored insecurely in the global Nix store. Do NOT use + your regular SSH host private keys for this purpose or + you'll expose them to regular users! + + Additionally, even if your initrd supports secrets, if + you're using initrd SSH to unlock an encrypted disk then + using your regular host keys exposes the private keys on + your unencrypted boot partition. + ::: ''; }; diff --git a/nixos/modules/system/boot/loader/grub/grub.nix b/nixos/modules/system/boot/loader/grub/grub.nix index 0af7f9729b08..1b075133ff40 100644 --- a/nixos/modules/system/boot/loader/grub/grub.nix +++ b/nixos/modules/system/boot/loader/grub/grub.nix @@ -417,23 +417,23 @@ in splashImage = mkOption { type = types.nullOr types.path; example = literalExpression "./my-background.png"; - description = '' + description = lib.mdDoc '' Background image used for GRUB. - Set to null to run GRUB in text mode. + Set to `null` to run GRUB in text mode. - + ::: {.note} For grub 1: It must be a 640x480, 14-colour image in XPM format, optionally compressed with - gzip or bzip2. - + {command}`gzip` or {command}`bzip2`. + ::: - + ::: {.note} For grub 2: File must be one of .png, .tga, .jpg, or .jpeg. JPEG images must not be progressive. The image will be scaled if necessary to fit the screen. - + ::: ''; }; @@ -441,36 +441,36 @@ in type = types.nullOr types.str; example = "#7EBAE4"; default = null; - description = '' + description = lib.mdDoc '' Background color to be used for GRUB to fill the areas the image isn't filling. - + ::: {.note} This options has no effect for GRUB 1. - + ::: ''; }; entryOptions = mkOption { default = "--class nixos --unrestricted"; type = types.nullOr types.str; - description = '' + description = lib.mdDoc '' Options applied to the primary NixOS menu entry. - + ::: {.note} This options has no effect for GRUB 1. - + ::: ''; }; subEntryOptions = mkOption { default = "--class nixos"; type = types.nullOr types.str; - description = '' + description = lib.mdDoc '' Options applied to the secondary NixOS submenu entry. - + ::: {.note} This options has no effect for GRUB 1. - + ::: ''; }; @@ -478,24 +478,24 @@ in type = types.nullOr types.path; example = literalExpression "pkgs.nixos-grub2-theme"; default = null; - description = '' + description = lib.mdDoc '' Grub theme to be used. - + ::: {.note} This options has no effect for GRUB 1. - + ::: ''; }; splashMode = mkOption { type = types.enum [ "normal" "stretch" ]; default = "stretch"; - description = '' + description = lib.mdDoc '' Whether to stretch the image or show the image in the top-left corner unstretched. - + ::: {.note} This options has no effect for GRUB 1. - + ::: ''; }; diff --git a/nixos/modules/virtualisation/qemu-vm.nix b/nixos/modules/virtualisation/qemu-vm.nix index 21ffdd139d20..7d9ec5875803 100644 --- a/nixos/modules/virtualisation/qemu-vm.nix +++ b/nixos/modules/virtualisation/qemu-vm.nix @@ -510,17 +510,19 @@ in ] ''; description = - '' + lib.mdDoc '' When using the SLiRP user networking (default), this option allows to forward ports to/from the host/guest. - - If the NixOS firewall on the virtual machine is enabled, you also - have to open the guest ports to enable the traffic between host and - guest. - + ::: {.warning} + If the NixOS firewall on the virtual machine is enabled, you also + have to open the guest ports to enable the traffic between host and + guest. + ::: - Currently QEMU supports only IPv4 forwarding. + ::: {.note} + Currently QEMU supports only IPv4 forwarding. + ::: ''; }; diff --git a/nixos/modules/virtualisation/virtualbox-host.nix b/nixos/modules/virtualisation/virtualbox-host.nix index 4e47febed1be..5a2ec4939d99 100644 --- a/nixos/modules/virtualisation/virtualbox-host.nix +++ b/nixos/modules/virtualisation/virtualbox-host.nix @@ -18,25 +18,25 @@ in { options.virtualisation.virtualbox.host = { - enable = mkEnableOption "VirtualBox" // { - description = '' + enable = mkEnableOption (lib.mdDoc "VirtualBox") // { + description = lib.mdDoc '' Whether to enable VirtualBox. - - In order to pass USB devices from the host to the guests, the user - needs to be in the vboxusers group. - + ::: {.note} + In order to pass USB devices from the host to the guests, the user + needs to be in the `vboxusers` group. + ::: ''; }; - enableExtensionPack = mkEnableOption "VirtualBox extension pack" // { - description = '' + enableExtensionPack = mkEnableOption (lib.mdDoc "VirtualBox extension pack") // { + description = lib.mdDoc '' Whether to install the Oracle Extension Pack for VirtualBox. - - You must set nixpkgs.config.allowUnfree = true in - order to use this. This requires you accept the VirtualBox PUEL. - + ::: {.important} + You must set `nixpkgs.config.allowUnfree = true` in + order to use this. This requires you accept the VirtualBox PUEL. + ::: ''; }; @@ -60,15 +60,15 @@ in enableHardening = mkOption { type = types.bool; default = true; - description = '' + description = lib.mdDoc '' Enable hardened VirtualBox, which ensures that only the binaries in the system path get access to the devices exposed by the kernel modules instead of all users in the vboxusers group. - - Disabling this can put your system's security at risk, as local users - in the vboxusers group can tamper with the VirtualBox device files. - + ::: {.important} + Disabling this can put your system's security at risk, as local users + in the vboxusers group can tamper with the VirtualBox device files. + ::: ''; }; diff --git a/nixos/modules/virtualisation/vmware-host.nix b/nixos/modules/virtualisation/vmware-host.nix index b4869f0210dc..e1d695640be1 100644 --- a/nixos/modules/virtualisation/vmware-host.nix +++ b/nixos/modules/virtualisation/vmware-host.nix @@ -20,21 +20,21 @@ in { options = with lib; { virtualisation.vmware.host = { - enable = mkEnableOption "VMware" // { - description = '' + enable = mkEnableOption (lib.mdDoc "VMware") // { + description = lib.mdDoc '' This enables VMware host virtualisation for running VMs. - - vmware-vmx will cause kcompactd0 due to - Transparent Hugepages feature in kernel. - Apply [ "transparent_hugepage=never" ] in - option to disable them. - + ::: {.important} + `vmware-vmx` will cause kcompactd0 due to + `Transparent Hugepages` feature in kernel. + Apply `[ "transparent_hugepage=never" ]` in + option {option}`boot.kernelParams` to disable them. + ::: - - If that didn't work disable TRANSPARENT_HUGEPAGE, - COMPACTION configs and recompile kernel. - + ::: {.note} + If that didn't work disable `TRANSPARENT_HUGEPAGE`, + `COMPACTION` configs and recompile kernel. + ::: ''; }; package = mkOption {