nordic-dev.net/nixpkgs
nordic-dev.net/nixpkgs
2
0
Fork 0
mirror of https://github.com/NixOS/nixpkgs.git synced 2025-02-20 02:55:39 +00:00
Code Issues Packages Projects Releases Wiki Activity

nixos/*: convert options with admonitions to MD

Browse Source 
rendering changes only slightly, most changes are in spacing.
This commit is contained in:
pennae 2022-08-30 02:30:04 +02:00
parent bd56368848
commit 722b99bc0e
50 changed files with 568 additions and 568 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

25
nixos/modules/programs/java.nix
View File

@ -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 ];
:::
'';
};

36
nixos/modules/security/dhparams.nix
View File

@ -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.
:::
'';
};

34
nixos/modules/security/systemd-confinement.nix
View File

@ -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.
:::
'';
};

20
nixos/modules/security/wrappers/default.nix
View File

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

12
nixos/modules/services/backup/duplicati.nix
View File

@ -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.
:::
'';
};

40
nixos/modules/services/databases/mysql.nix
View File

@ -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 ''
{

14
nixos/modules/services/databases/postgresql.nix
View File

@ -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 ''
{

8
nixos/modules/services/hardware/acpid.nix
View File

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

10
nixos/modules/services/hardware/bluetooth.nix
View File

@ -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.
:::
'';
};

16
nixos/modules/services/hardware/sane.nix
View File

@ -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 ]";
};

21
nixos/modules/services/mail/maddy.nix
View File

@ -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>
:::
'';
};

38
nixos/modules/services/misc/gitlab.nix
View File

@ -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.
executed. GitLab recommends `Number of CPU cores - 1`, but at least two.
<note>
<para>
Each worker consumes quite a bit of memory, so
be careful when increasing this.
</para>
</note>
::: {.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.
:::
'';
};

10
nixos/modules/services/misc/sdrplay.nix
View File

@ -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;
};

10
nixos/modules/services/misc/sourcehut/default.nix
View File

@ -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));

26
nixos/modules/services/misc/taskserver/default.nix
View File

@ -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.
'';
};

14
nixos/modules/services/network-filesystems/samba-wsdd.nix
View File

@ -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;

13
nixos/modules/services/network-filesystems/samba.nix
View File

@ -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;
:::
'';
};

14
nixos/modules/services/networking/adguardhome.nix
View File

@ -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.
:::
'';
};

14
nixos/modules/services/networking/headscale.nix
View File

@ -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>
:::
'';
};

8
nixos/modules/services/networking/libreswan.nix
View File

@ -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.
:::
'';
};

38
nixos/modules/services/networking/privoxy.nix
View File

@ -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.
certificate, using the `ca-cert-file`,
`ca-key-file` 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>
::: {.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.
:::
'';
};

12
nixos/modules/services/networking/prosody.nix
View File

@ -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>
:::
'';
};

43
nixos/modules/services/networking/searx.nix
View File

@ -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.
:::
'';
};

15
nixos/modules/services/networking/shorewall.nix
View File

@ -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 {

15
nixos/modules/services/networking/shorewall6.nix
View File

@ -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 {

82
nixos/modules/services/networking/wpa_supplicant.nix
View File

@ -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`.
:::
'';
};

14
nixos/modules/services/security/cfssl.nix
View File

@ -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.
:::
'';
};

44
nixos/modules/services/security/step-ca.nix
View File

@ -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.
:::
'';
};
};

16
nixos/modules/services/security/torify.nix
View File

@ -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.
:::
'';
};

28
nixos/modules/services/torrent/magnetico.nix
View File

@ -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>
{command}`htpasswd -bnBC 12 username password`
<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>
::: {.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`
'';
};

14
nixos/modules/services/video/epgstation/default.nix
View File

@ -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.
:::
'';
};

14
nixos/modules/services/video/mirakurun.nix
View File

@ -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.
:::
'';
};

14
nixos/modules/services/web-apps/dokuwiki.nix
View File

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

26
nixos/modules/services/web-apps/healthchecks.nix
View File

@ -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.
'';

7
nixos/modules/services/web-apps/invoiceplane.nix
View File

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

26
nixos/modules/services/web-apps/keycloak.nix
View File

@ -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 (&lt;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.
::: {.note}
In versions of Keycloak using Wildfly (&lt;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 <link xlink:href="https://www.keycloak.org/migration/migrating-to-quarkus"/>
for more information on migrating from Wildfly to Quarkus.
</para>
</note>
See <https://www.keycloak.org/migration/migrating-to-quarkus>
for more information on migrating from Wildfly to Quarkus.
:::
'';
};

18
nixos/modules/services/web-apps/nextcloud.nix
View File

@ -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.&lt;name&gt;.startAt`.
description = lib.mdDoc ''
When to run the update. See `systemd.services.<name>.startAt`.
'';
};
};

14
nixos/modules/services/web-apps/wordpress.nix
View File

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

8
nixos/modules/services/web-servers/apache-httpd/default.nix
View File

@ -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>
```
'';
};

28
nixos/modules/services/web-servers/apache-httpd/vhost-options.nix
View File

@ -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.&lt;name&gt;.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.
:::
'';
};

69
nixos/modules/services/web-servers/caddy/default.nix
View File

@ -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`.
:::
'';
};

7
nixos/modules/services/web-servers/phpfpm/default.nix
View File

@ -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";
};

28
nixos/modules/services/web-servers/uwsgi.nix
View File

@ -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.
:::
'';
};
};

10
nixos/modules/services/x11/xserver.nix
View File

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

12
nixos/modules/system/boot/initrd-openvpn.nix
View File

@ -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";
};

33
nixos/modules/system/boot/initrd-ssh.nix
View File

@ -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.
:::
'';
};

44
nixos/modules/system/boot/loader/grub/grub.nix
View File

@ -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>
:::
'';
};

16
nixos/modules/virtualisation/qemu-vm.nix
View File

@ -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.
:::
'';
};

34
nixos/modules/virtualisation/virtualbox-host.nix
View File

@ -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.
:::
'';
};

24
nixos/modules/virtualisation/vmware-host.nix
View File

@ -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>
::: {.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><para>
If that didn't work disable <literal>TRANSPARENT_HUGEPAGE</literal>,
<literal>COMPACTION</literal> configs and recompile kernel.
</para></note>
::: {.note}
If that didn't work disable `TRANSPARENT_HUGEPAGE`,
`COMPACTION` configs and recompile kernel.
:::
'';
};
package = mkOption {