diff options
50 files changed, 574 insertions, 574 deletions
diff --git a/nixos/modules/programs/java.nix b/nixos/modules/programs/java.nix index 5994f53f76b7b..4f03c1f3ff258 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. - <note> - <para>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: - </para> - <programlisting> - environment.variables.JAVA_HOME = ''${pkgs.jdk.home}/lib/openjdk; - environment.systemPackages = [ pkgs.jdk ]; - </programlisting> - </note> + + ::: {.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 93c9066dc95c2..9fed7e012b1ed 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 - <literal>config.security.dhparams.params.«name».path</literal>. + `config.security.dhparams.params.«name».path`. - <note><para>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.</para></note> + said service is started. + ::: - <warning><para>If you are removing all dhparams from this list, you - have to leave <option>security.dhparams.enable</option> 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 - <option>security.dhparams.stateful</option> is - <literal>true</literal>.</para></warning> + {option}`security.dhparams.stateful` is + `true`. + ::: - <note><title>For module implementers:</title><para>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</option>.</para></note> + {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 - <option>security.dhparams.path</option>. Otherwise the files are + {option}`security.dhparams.path`. Otherwise the files are created within the Nix store. - <note><para>If this is <literal>false</literal> the resulting store + ::: {.note} + If this is `false` the resulting store path will be non-deterministic and will be rebuilt every time the - <literal>openssl</literal> package changes.</para></note> + `openssl` package changes. + ::: ''; }; diff --git a/nixos/modules/security/systemd-confinement.nix b/nixos/modules/security/systemd-confinement.nix index f5ed3d281a5fb..be04741f4d061 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: "<option>serviceConfig.${optName}</option>"; - 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</option>. + {option}`confinement.fullUnit`. - <note><para>The store paths listed in <option>path</option> are - <emphasis role="strong">not</emphasis> 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.</para></note> + above. + ::: ''; }; @@ -74,20 +76,20 @@ in { options.confinement.mode = lib.mkOption { type = types.enum [ "full-apivfs" "chroot-only" ]; default = "full-apivfs"; - description = '' - The value <literal>full-apivfs</literal> (the default) sets up - private <filename class="directory">/dev</filename>, <filename - class="directory">/proc</filename>, <filename - class="directory">/sys</filename> and <filename - class="directory">/tmp</filename> 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 <literal>chroot-only</literal>, only the file + If this is set to `chroot-only`, only the file system name space is set up along with the call to - <citerefentry><refentrytitle>chroot</refentrytitle><manvolnum>2</manvolnum></citerefentry>. + {manpage}`chroot(2)`. - <note><para>This doesn't cover network namespaces and is solely for - file system level isolation.</para></note> + ::: {.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 0e358eb4bd8d7..45aee7c973394 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 - <citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry> + {manpage}`capabilities(7)` manual page. - <note><para> - <literal>cap_setpcap</literal>, 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. - </para></note> + ::: {.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 7100cad6cf0c9..47f0b618c8d9c 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. - <note><para> - 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. - </para></note> + ::: {.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 6f2d812ef7dc7..ec4524e9061db 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><para> + ::: {.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. - </para></note> + ::: ''; }; group = mkOption { type = types.str; default = "mysql"; - description = '' + description = lib.mdDoc '' Group account under which MySQL runs. - <note><para> + ::: {.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. - </para></note> + ::: ''; }; dataDir = mkOption { type = types.path; example = "/var/lib/mysql"; - description = '' + description = lib.mdDoc '' The data directory for MySQL. - <note><para> - If left as the default value of <literal>/var/lib/mysql</literal> 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. - </para></note> + ::: ''; }; @@ -107,20 +107,18 @@ in settings = mkOption { type = format.type; default = {}; - description = '' + description = lib.mdDoc '' MySQL configuration. Refer to - <link xlink:href="https://dev.mysql.com/doc/refman/5.7/en/server-system-variables.html"/>, - <link xlink:href="https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html"/>, - and <link xlink:href="https://mariadb.com/kb/en/server-system-variables/"/> + <https://dev.mysql.com/doc/refman/5.7/en/server-system-variables.html>, + <https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html>, + and <https://mariadb.com/kb/en/server-system-variables/> for details on supported values. - <note> - <para> - MySQL configuration options such as <literal>--quick</literal> should be treated as - boolean options and provided values such as <literal>true</literal>, <literal>false</literal>, - <literal>1</literal>, or <literal>0</literal>. See the provided example below. - </para> - </note> + ::: {.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 3d632eabfc619..e84116635a375 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 - <link xlink:href="https://www.postgresql.org/docs/11/config-setting.html#CONFIG-SETTING-CONFIGURATION-FILE"/> - for an overview of <literal>postgresql.conf</literal>. + <https://www.postgresql.org/docs/11/config-setting.html#CONFIG-SETTING-CONFIGURATION-FILE> + for an overview of `postgresql.conf`. - <note><para> - 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. - </para></note> + ::: {.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 c07fef11cc2fd..821f4ef205fc5 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. - <note><para> - Handler can be a single command. - </para></note> + ::: {.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 30dd15412e2e8..8b90c1913bc51 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. - <note><para> - Use the <literal>pkgs.bluezFull</literal> package to enable all - bluez plugins. - </para></note> + ::: {.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 de496a829f3ad..5455cf56e8aa8 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. - <note><para> - Users in the "scanner" group will gain access to the scanner, or the "lp" group if it's also a printer. - </para></note> + ::: {.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. - <note><para> - The example contains the package for HP scanners. - </para></note> + ::: {.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 97384c391281d..eeb113e204c6e 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><para> + ::: {.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. - </para></note> + ::: ''; }; group = mkOption { default = "maddy"; type = with types; uniq string; - description = '' + description = lib.mdDoc '' Group account under which maddy runs. - <note><para> + ::: {.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. - </para></note> + ::: ''; }; @@ -203,14 +203,15 @@ in { config = mkOption { type = with types; nullOr lines; default = defaultConfig; - description = '' + description = lib.mdDoc '' Server configuration, see - <link xlink:href="https://maddy.email">https://maddy.email</link> 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><para> + + ::: {.note} This should not be used in a production environment. - </para></note> + ::: ''; }; diff --git a/nixos/modules/services/misc/gitlab.nix b/nixos/modules/services/misc/gitlab.nix index aa2a05900f872..42f46289c8632 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 <literal>Number of CPU cores - 1</literal>, but at least two. - - <note> - <para> - Each worker consumes quite a bit of memory, so - be careful when increasing this. - </para> - </note> + executed. GitLab recommends `Number of CPU cores - 1`, but at least two. + + ::: {.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. - <note> - <para> - Each thread consumes memory and contributes to Global VM - Lock contention, so be careful when increasing this. - </para> - </note> + ::: {.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. - <note> - <para> - Each thread consumes memory and contributes to Global VM - Lock contention, so be careful when increasing this. - </para> - </note> + ::: {.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 2801108f08280..2d5333e3885b8 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. - <note><para> - To enable integration with SoapySDR and GUI applications like gqrx create an overlay containing - <literal>soapysdr-with-plugins = super.soapysdr.override { extraPackages = [ super.soapysdrplay ]; };</literal> - </para></note> + ::: {.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 56017f5f8be84..dd0e016a1da7d 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><para> + ::: {.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 <link xlink:href="https://man.sr.ht/builds.sr.ht/configuration.md#security-model"/>. - </para></warning> - ''; + See <https://man.sr.ht/builds.sr.ht/configuration.md#security-model>. + ::: + ''); 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 ad4ab93a872a1..aeefd657f4d02 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 + '' - <note><para> + description = lib.mdDoc '' + ${desc} + + ::: {.note} Setting this option will prevent automatic CA creation and handling. - </para></note> + ::: ''; }; @@ -35,13 +37,13 @@ let ''; }; - mkAutoDesc = preamble: '' + mkAutoDesc = preamble: lib.mdDoc '' ${preamble} - <note><para> + ::: {.note} This option is for the automatically handled CA and will be ignored if any - of the <option>services.taskserver.pki.manual.*</option> options are set. - </para></note> + 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 <literal>null</literal> 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 <link xlink:href="${url}">in the NixOS manual</link>. + 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 <link xlink:href="${url}"/> 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 38980593e7682..e28fe4cf9c4d2 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. - <note> - <para>If you use the firewall consider adding the following:</para> - <programlisting> + + ::: {.note} + If you use the firewall consider adding the following: + networking.firewall.allowedTCPPorts = [ 5357 ]; networking.firewall.allowedUDPPorts = [ 3702 ]; - </programlisting> - </note> - ''; + ::: + ''); 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 7a07b043859b8..1310a374abd0b 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. - <note> - <para>If you use the firewall consider adding the following:</para> - <programlisting> - services.samba.openFirewall = true; - </programlisting> - </note> + ::: {.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 9e014cd3d72ac..13b6f6efcd6d1 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 - <link xlink:href="https://github.com/AdguardTeam/AdGuardHome/wiki/Configuration#configuration-file"/> + <https://github.com/AdguardTeam/AdGuardHome/wiki/Configuration#configuration-file> for details on supported values. - <note><para> - On start and if <option>mutableSettings</option> is <literal>true</literal>, - these options are merged into the configuration file on start, taking - precedence over configuration changes made on the web interface. - </para></note> + ::: {.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 f2687809f7d4b..0334c5a00bab5 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><para> + + ::: {.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. - </para></note> + ::: ''; }; group = mkOption { default = "headscale"; type = types.str; - description = '' + description = lib.mdDoc '' Group under which headscale runs. - <note><para> + + ::: {.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. - </para></note> + ::: ''; }; diff --git a/nixos/modules/services/networking/libreswan.nix b/nixos/modules/services/networking/libreswan.nix index 41a0aca028301..b5df31c28d7cd 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. - <note><para> - The policy name must match the one of connection it needs to apply to. - </para></note> + ::: {.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 ddb1d816c8156..78d02aaa11250 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 <literal>ca-cert-file</literal>, - <literal>ca-key-file</literal> settings. - - <warning><para> - 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</option>. - </para></warning> + certificate, using the `ca-cert-file`, + `ca-key-file` settings. + + ::: {.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 <literal>inspectHttps</literal> 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. - <note><para>The format is that of the <literal>tmpfiles.d(5)</literal> - Age parameter.</para></note> + ::: {.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 - <link xlink:href="https://www.privoxy.org/user-manual/config.html"/> + <https://www.privoxy.org/user-manual/config.html> for available settings and documentation. - <note><para> - Repeated settings can be represented by using a list. - </para></note> + ::: {.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 f32c7adbd2c37..6cd4678ae4ace 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><para> + ::: {.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. - </para></note> + ::: ''; }; group = mkOption { type = types.str; default = "prosody"; - description = '' + description = lib.mdDoc '' Group account under which prosody runs. - <note><para> + ::: {.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. - </para></note> + ::: ''; }; diff --git a/nixos/modules/services/networking/searx.nix b/nixos/modules/services/networking/searx.nix index 238479864f880..e594d0083d4f1 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 <xref linkend="opt-services.searx.environmentFile"/>) - using the syntax <literal>@VARIABLE_NAME@</literal>. - <note> - <para> - For available settings, see the Searx - <link xlink:href="https://searx.github.io/searx/admin/settings.html">docs</link>. - </para> - </note> + (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 - <xref linkend="opt-services.searx.settings"/>. - <warning> - <para> - This file, along with any secret key it contains, will be copied - into the world-readable Nix store. - </para> - </warning> + [](#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. - <warning> - <para> - The built-in HTTP server logs all queries by default. - </para> - </warning> + + ::: {.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 795295d1628f1..ba59d71120da5 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. - <warning> - <para> - Enabling this service WILL disable the existing NixOS - firewall! Default firewall rules provided by packages are not - considered at the moment. - </para> - </warning> + + ::: {.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 1d6d84eb89b3d..e54be290bfb39 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. - <warning> - <para> - Enabling this service WILL disable the existing NixOS - firewall! Default firewall rules provided by packages are not - considered at the moment. - </para> - </warning> + + ::: {.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 ccf6f27918670..6c58bcfbbf189 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 <command>wpa_supplicant</command> 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. - <note><para> - A separate wpa_supplicant instance will be started for each interface. - </para></note> + ::: {.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 <literal>wpa_supplicant_gui</literal>) 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 <literal>varname=value</literal> + description = lib.mdDoc '' + File consisting of lines of the form `varname=value` to define variables for the wireless configuration. - See section "EnvironmentFile=" in <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> 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 <option>networking.wireless.networks</option> - with the syntax <literal>@varname@</literal>. Example: + referring to them in option {option}`networking.wireless.networks` + with the syntax `@varname@`. Example: - <programlisting> + ``` # content of /run/secrets/wireless.env PSK_HOME=mypassword PASS_WORK=myworkpassword - </programlisting> + ``` - <programlisting> + ``` # wireless-related configuration networking.wireless.environmentFile = "/run/secrets/wireless.env"; networking.wireless.networks = { @@ -250,7 +250,7 @@ in { password="@PASS_WORK@" '''; }; - </programlisting> + ``` ''; }; @@ -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. - <warning><para> - Be aware that this will be written to the nix store - in plaintext! Use an environment variable instead. - </para></warning> + ::: {.warning} + Be aware that this will be written to the nix store + in plaintext! Use an environment variable instead. + ::: - <note><para> - Mutually exclusive with <varname>pskRaw</varname>. - </para></note> + ::: {.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. - <warning><para> - Be aware that this will be written to the nix store - in plaintext! Use an environment variable instead. - </para></warning> + ::: {.warning} + Be aware that this will be written to the nix store + in plaintext! Use an environment variable instead. + ::: - <note><para> - Mutually exclusive with <varname>psk</varname>. - </para></note> + ::: {.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 - <citerefentry><refentrytitle>wpa_supplicant.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> + {manpage}`wpa_supplicant.conf(5)` for example configurations. - <warning><para> - Be aware that this will be written to the nix store - in plaintext! Use an environment variable for secrets. - </para></warning> + ::: {.warning} + Be aware that this will be written to the nix store + in plaintext! Use an environment variable for secrets. + ::: - <note><para> - Mutually exclusive with <varname>psk</varname> and - <varname>pskRaw</varname>. - </para></note> + ::: {.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 006b31b186880..202db98e222c0 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. - <note><para> - 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. - </para></note> + ::: {.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 8cbab5af09777..433f162ecb86e 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 <filename>ca.json</filename>. See - <link xlink:href="https://smallstep.com/docs/step-ca/configuration">the step-ca manual</link> + 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 <literal>step ca init</literal> - to generate <filename>ca.json</filename> and then import it using - <literal>builtins.fromJSON</literal>. - <link xlink:href="https://smallstep.com/docs/step-cli/basic-crypto-operations#run-an-offline-x509-certificate-authority">This article</link> + 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 <filename>/var/lib/step-ca/db</filename>. + You need to change the database storage path to {file}`/var/lib/step-ca/db`. - <warning> - <para> - The <option>services.step-ca.settings.address</option> option - will be ignored and overwritten by - <option>services.step-ca.address</option> and - <option>services.step-ca.port</option>. - </para> - </warning> + ::: {.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. - <warning> - <para> - 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. - </para> - </warning> + ::: {.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 770e445d733fe..4d311adebcaea 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. - <important> - <para>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) - <literal>torsocks</literal> wrapper which does pretty much - exactly the same thing as this.</para> - </important> + ::: {.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 b43389c5d0b01..b681c58dfe2ad 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 <literal>username:hash</literal>. 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 - <command>htpasswd</command> tool from the <literal>apacheHttpd</literal> + {command}`htpasswd` tool from the `apacheHttpd` package may be used to generate the hash: - <command>htpasswd -bnBC 12 username password</command> - - <warning> - <para> - The hashes will be stored world-readable in the nix store. - Consider using the <literal>credentialsFile</literal> option if you - don't want this. - </para> - </warning> + {command}`htpasswd -bnBC 12 username password` + + ::: {.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 - <literal>username:hash </literal>, 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 <command>htpasswd</command> tool from the <literal>apacheHttpd</literal> + The {command}`htpasswd` tool from the `apacheHttpd` package may be used to generate the hash: - <command>htpasswd -bnBC 12 username password</command> + {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 ebd71724d18a5..3d1d7a27c216c 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. - <warning> - <para> - 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. - </para> - </warning> + ::: {.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 18aaedc410f88..5484515e7cb4f 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. - <warning> - <para> - 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. - </para> - </warning> + ::: {.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 ea1d5c837d5f6..e719d11e4d2ef 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. - <note><para>These plugins need to be packaged before use, see example.</para></note> + + ::: {.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. - <note><para>These templates need to be packaged before use, see example.</para></note> + + ::: {.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 b3380b88f6138..2c55f5ec8ebb5 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><para> + ::: {.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. - </para></note> + ::: ''; }; group = mkOption { default = defaultUser; type = types.str; - description = '' + description = lib.mdDoc '' Group account under which healthchecks runs. - <note><para> + ::: {.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. - </para></note> + ::: ''; }; @@ -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><para> + ::: {.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. - </para></note> + ::: ''; }; settings = lib.mkOption { - description = '' - Environment variables which are read by healthchecks <literal>(local)_settings.py</literal>. + 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 <link xlink:href="">https://healthchecks.io/docs/self_hosted_configuration/</link> + See <https://healthchecks.io/docs/self_hosted_configuration/> for a full documentation of settings. - We add two variables to this list inside the packages <literal>local_settings.py.</literal> + 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 72027523ef348..156cc238e89af 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. - <note><para>These templates need to be packaged before use, see example.</para></note> + + ::: {.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 82684f5e52085..301efe7e5d94f 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 <literal>/</literal> for serving + description = lib.mdDoc '' + The path relative to `/` for serving resources. - <note> - <para> - In versions of Keycloak using Wildfly (<17), - this defaulted to <literal>/auth</literal>. If - upgrading from the Wildfly version of Keycloak, - i.e. a NixOS version before 22.05, you'll likely - want to set this to <literal>/auth</literal> to - keep compatibility with your clients. - - See <link xlink:href="https://www.keycloak.org/migration/migrating-to-quarkus"/> - for more information on migrating from Wildfly to Quarkus. - </para> - </note> + ::: {.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 <https://www.keycloak.org/migration/migrating-to-quarkus> + 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 6ed5f066be505..fdbaa90ebb7a3 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 = '' - <warning> - <para>This option exists since Nextcloud 21! If older versions are used, - this will throw an eval-error!</para> - </warning> + description = lib.mdDoc '' + ::: {.warning} + This option exists since Nextcloud 21! If older versions are used, + this will throw an eval-error! + ::: - <link xlink:href="https://www.iso.org/iso-3166-country-codes.html">ISO 3611-1</link> + [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. <literal>DE</literal> set, the <literal>+49</literal> 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.<name>.startAt`. ''; }; }; diff --git a/nixos/modules/services/web-apps/wordpress.nix b/nixos/modules/services/web-apps/wordpress.nix index c841ded353e7c..f2e78d028559b 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. - <note><para>These plugins need to be packaged before use, see example.</para></note> + + ::: {.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. - <note><para>These themes need to be packaged before use, see example.</para></note> + + ::: {.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 346e2b5a92703..6b43d46fdead0 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 - <literal>root</literal> add the following configuration: - <programlisting> + `root` add the following configuration: + ``` systemd.services.httpd.serviceConfig.User = lib.mkForce "root"; - </programlisting> + ``` ''; }; 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 4f84cad735147..5b7b752884e41 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. - <note> - <para> - This option overrides <literal>addSSL</literal>, <literal>forceSSL</literal> and <literal>onlySSL</literal>. - </para> - <para> - If you only want to set the addresses manually and not the ports, take a look at <literal>listenAddresses</literal>. - </para> - </note> + + ::: {.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. - <note><para> - 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 <literal>locations.<name>.alias</literal> option. - </para></note> + ::: {.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.<name>.alias` option. + ::: ''; }; diff --git a/nixos/modules/services/web-servers/caddy/default.nix b/nixos/modules/services/web-servers/caddy/default.nix index e5ad99c29853e..e364cb33be303 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. - <note><para> - 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. - </para></note> + ::: {.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. - <note><para> - 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. - </para></note> + ::: {.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. - <note> - <para> - 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. - </para> - <para> - Caddy v2 replaced <literal>CADDYPATH</literal> with XDG directories. - See <link xlink:href="https://caddyserver.com/docs/conventions#file-locations"/>. - </para> - </note> + ::: {.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 <https://caddyserver.com/docs/conventions#file-locations>. + ::: ''; }; logDir = mkOption { type = types.path; default = "/var/log/caddy"; - description = '' + description = lib.mdDoc '' Directory for storing Caddy access logs. - <note><para> - 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. - </para></note> + ::: {.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 <link xlink:href="https://caddyserver.com/docs/config-adapters"/> + See <https://caddyserver.com/docs/config-adapters> for the full list. - <note><para> - Any value other than <literal>caddyfile</literal> is only valid when - providing your own <option>configFile</option>. - </para></note> + ::: {.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 e24c77d056a29..0bd1d5b29b316 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. - <note><para>This option is read-only and managed by NixOS.</para></note> + + ::: {.note} + This option is read-only and managed by NixOS. + ::: ''; example = "${runtimeDir}/<name>.sock"; }; diff --git a/nixos/modules/services/web-servers/uwsgi.nix b/nixos/modules/services/web-servers/uwsgi.nix index af6c6c0661246..510582feaae10 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 - <literal>capabilities(7)</literal> for available values. - <note> - <para> - 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. - </para> - <para> - When in Emperor mode, any capability to be inherited by a vassal must - be specified again in the vassal configuration using <literal>cap</literal>. - See the uWSGI <link xlink:href="https://uwsgi-docs.readthedocs.io/en/latest/Capabilities.html">docs</link> - for more information. - </para> - </note> + `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 9666fe2d6f753..83a71dcf23e00 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>output</option> 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 - <option>primary</option> to <literal>true</literal>. + {option}`primary` to `true`. - <note><para>Only one monitor is allowed to be primary.</para></note> + ::: {.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 9f476e07208a7..b41e7524320e2 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. - <warning> - <para> - Unless your bootloader supports initrd secrets, this configuration - is stored insecurely in the global Nix store. - </para> - </warning> + ::: {.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 171c51308a791..256aa608ac434 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 - <citerefentry><refentrytitle>ssh-keygen</refentrytitle><manvolnum>1</manvolnum></citerefentry> + {manpage}`ssh-keygen(1)` as root: - <programlisting> + ``` 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 - </programlisting> - - <warning> - <para> - 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! - </para> - <para> - 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. - </para> - </warning> + ``` + + ::: {.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 0af7f9729b08c..1b075133ff40c 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 <literal>null</literal> to run GRUB in text mode. + Set to `null` to run GRUB in text mode. - <note><para> + ::: {.note} For grub 1: It must be a 640x480, 14-colour image in XPM format, optionally compressed with - <command>gzip</command> or <command>bzip2</command>. - </para></note> + {command}`gzip` or {command}`bzip2`. + ::: - <note><para> + ::: {.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. - </para></note> + ::: ''; }; @@ -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><para> + ::: {.note} This options has no effect for GRUB 1. - </para></note> + ::: ''; }; entryOptions = mkOption { default = "--class nixos --unrestricted"; type = types.nullOr types.str; - description = '' + description = lib.mdDoc '' Options applied to the primary NixOS menu entry. - <note><para> + ::: {.note} This options has no effect for GRUB 1. - </para></note> + ::: ''; }; subEntryOptions = mkOption { default = "--class nixos"; type = types.nullOr types.str; - description = '' + description = lib.mdDoc '' Options applied to the secondary NixOS submenu entry. - <note><para> + ::: {.note} This options has no effect for GRUB 1. - </para></note> + ::: ''; }; @@ -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><para> + ::: {.note} This options has no effect for GRUB 1. - </para></note> + ::: ''; }; 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><para> + ::: {.note} This options has no effect for GRUB 1. - </para></note> + ::: ''; }; diff --git a/nixos/modules/virtualisation/qemu-vm.nix b/nixos/modules/virtualisation/qemu-vm.nix index 21ffdd139d20f..7d9ec58758038 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. - <warning><para> - 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. - </para></warning> + ::: {.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. + ::: - <note><para>Currently QEMU supports only IPv4 forwarding.</para></note> + ::: {.note} + Currently QEMU supports only IPv4 forwarding. + ::: ''; }; diff --git a/nixos/modules/virtualisation/virtualbox-host.nix b/nixos/modules/virtualisation/virtualbox-host.nix index 4e47febed1be8..5a2ec4939d99d 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. - <note><para> - In order to pass USB devices from the host to the guests, the user - needs to be in the <literal>vboxusers</literal> group. - </para></note> + ::: {.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. - <important><para> - You must set <literal>nixpkgs.config.allowUnfree = true</literal> in - order to use this. This requires you accept the VirtualBox PUEL. - </para></important> + ::: {.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. - <important><para> - Disabling this can put your system's security at risk, as local users - in the vboxusers group can tamper with the VirtualBox device files. - </para></important> + ::: {.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 b4869f0210dc3..e1d695640be1a 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. - <important><para> - <literal>vmware-vmx</literal> will cause kcompactd0 due to - <literal>Transparent Hugepages</literal> feature in kernel. - Apply <literal>[ "transparent_hugepage=never" ]</literal> in - option <option>boot.kernelParams</option> to disable them. - </para></important> - - <note><para> - If that didn't work disable <literal>TRANSPARENT_HUGEPAGE</literal>, - <literal>COMPACTION</literal> configs and recompile kernel. - </para></note> + ::: {.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. + ::: + + ::: {.note} + If that didn't work disable `TRANSPARENT_HUGEPAGE`, + `COMPACTION` configs and recompile kernel. + ::: ''; }; package = mkOption { |