From f2ea09ecbe1fa1da32eaa6e036d64ac324a2986f Mon Sep 17 00:00:00 2001 From: pennae Date: Tue, 30 Aug 2022 14:08:50 +0200 Subject: nixos/*: convert options with listings minor rendering changes. --- nixos/modules/hardware/tuxedo-keyboard.nix | 14 +++++----- nixos/modules/misc/label.nix | 24 ++++++++--------- nixos/modules/misc/nixpkgs.nix | 18 ++++++------- nixos/modules/services/backup/duplicity.nix | 8 +++--- nixos/modules/services/databases/cockroachdb.nix | 6 ++--- nixos/modules/services/development/zammad.nix | 10 ++++---- nixos/modules/services/hardware/lcd.nix | 12 ++++----- nixos/modules/services/logging/awstats.nix | 12 ++++----- nixos/modules/services/matrix/dendrite.nix | 14 +++++----- nixos/modules/services/misc/gitit.nix | 8 +++--- nixos/modules/services/misc/sssd.nix | 14 +++++----- .../monitoring/prometheus/exporters/dovecot.nix | 10 ++++---- .../monitoring/prometheus/exporters/mail.nix | 8 +++--- .../monitoring/prometheus/exporters/openldap.nix | 8 +++--- .../monitoring/prometheus/exporters/postgres.nix | 10 ++++---- .../network-filesystems/litestream/default.nix | 8 +++--- nixos/modules/services/networking/3proxy.nix | 12 ++++----- .../services/networking/firefox-syncserver.nix | 10 ++++---- .../services/networking/hylafax/options.nix | 12 ++++----- nixos/modules/services/networking/murmur.nix | 14 +++++----- nixos/modules/services/networking/ncdns.nix | 28 ++++++++++---------- nixos/modules/services/networking/nix-serve.nix | 8 +++--- nixos/modules/services/security/hockeypuck.nix | 10 ++++---- nixos/modules/services/security/privacyidea.nix | 14 +++++----- nixos/modules/services/security/vault.nix | 10 ++++---- .../services/security/vaultwarden/default.nix | 30 +++++++++++----------- nixos/modules/services/web-apps/discourse.nix | 10 ++++---- nixos/modules/services/web-apps/hedgedoc.nix | 14 +++++----- nixos/modules/services/web-servers/molly-brown.nix | 6 ++--- nixos/modules/system/activation/top-level.nix | 10 ++++---- nixos/modules/virtualisation/lxcfs.nix | 6 ++--- nixos/modules/virtualisation/lxd.nix | 8 +++--- 32 files changed, 192 insertions(+), 194 deletions(-) (limited to 'nixos/modules') diff --git a/nixos/modules/hardware/tuxedo-keyboard.nix b/nixos/modules/hardware/tuxedo-keyboard.nix index 7bcabde48900c..3ae876bd1f18b 100644 --- a/nixos/modules/hardware/tuxedo-keyboard.nix +++ b/nixos/modules/hardware/tuxedo-keyboard.nix @@ -8,23 +8,23 @@ let in { options.hardware.tuxedo-keyboard = { - enable = mkEnableOption '' + enable = mkEnableOption (lib.mdDoc '' Enables the tuxedo-keyboard driver. - To configure the driver, pass the options to the configuration. + To configure the driver, pass the options to the {option}`boot.kernelParams` configuration. There are several parameters you can change. It's best to check at the source code description which options are supported. - You can find all the supported parameters at: + You can find all the supported parameters at: - In order to use the custom lighting with the maximumg brightness and a color of 0xff0a0a one would put pass like this: + In order to use the `custom` lighting with the maximumg brightness and a color of `0xff0a0a` one would put pass {option}`boot.kernelParams` like this: - + ``` boot.kernelParams = [ "tuxedo_keyboard.mode=0" "tuxedo_keyboard.brightness=255" "tuxedo_keyboard.color_left=0xff0a0a" ]; - - ''; + ``` + ''); }; config = mkIf cfg.enable diff --git a/nixos/modules/misc/label.nix b/nixos/modules/misc/label.nix index e51e935c5c27f..0c29d13aab1df 100644 --- a/nixos/modules/misc/label.nix +++ b/nixos/modules/misc/label.nix @@ -12,7 +12,7 @@ in nixos.label = mkOption { type = types.strMatching "[a-zA-Z0-9:_\\.-]*"; - description = '' + description = lib.mdDoc '' NixOS version name to be used in the names of generated outputs and boot labels. @@ -20,26 +20,26 @@ in this is the option for you. It can only contain letters, numbers and the following symbols: - :, _, . and -. + `:`, `_`, `.` and `-`. - The default is separated by - "-" + "-" + NIXOS_LABEL_VERSION environment + The default is {option}`system.nixos.tags` separated by + "-" + "-" + {env}`NIXOS_LABEL_VERSION` environment variable (defaults to the value of - ). + {option}`system.nixos.version`). - Can be overriden by setting NIXOS_LABEL. + Can be overriden by setting {env}`NIXOS_LABEL`. Useful for not loosing track of configurations built from different nixos branches/revisions, e.g.: - + ``` #!/bin/sh today=`date +%Y%m%d` branch=`(cd nixpkgs ; git branch 2>/dev/null | sed -n '/^\* / { s|^\* ||; p; }')` revision=`(cd nixpkgs ; git rev-parse HEAD)` export NIXOS_LABEL_VERSION="$today.$branch-''${revision:0:7}" nixos-rebuild switch - + ``` ''; }; @@ -47,19 +47,19 @@ in type = types.listOf types.str; default = []; example = [ "with-xen" ]; - description = '' + description = lib.mdDoc '' Strings to prefix to the default - . + {option}`system.nixos.label`. Useful for not loosing track of configurations built with different options, e.g.: - + ``` { system.nixos.tags = [ "with-xen" ]; virtualisation.xen.enable = true; } - + ``` ''; }; diff --git a/nixos/modules/misc/nixpkgs.nix b/nixos/modules/misc/nixpkgs.nix index 127f37b0df04c..80b8ef591d3ae 100644 --- a/nixos/modules/misc/nixpkgs.nix +++ b/nixos/modules/misc/nixpkgs.nix @@ -311,26 +311,26 @@ in defaultText = lib.literalMD '' Traditionally `builtins.currentSystem`, but unset when invoking NixOS through `lib.nixosSystem`. ''; - description = '' + description = lib.mdDoc '' This option does not need to be specified for NixOS configurations - with a recently generated hardware-configuration.nix. + with a recently generated `hardware-configuration.nix`. Specifies the Nix platform type on which NixOS should be built. - It is better to specify nixpkgs.localSystem instead. - + It is better to specify `nixpkgs.localSystem` instead. + ``` { nixpkgs.system = ..; } - + ``` is the same as - + ``` { nixpkgs.localSystem.system = ..; } - - See nixpkgs.localSystem for more information. + ``` + See `nixpkgs.localSystem` for more information. - Ignored when nixpkgs.pkgs, nixpkgs.localSystem or nixpkgs.hostPlatform is set. + Ignored when `nixpkgs.pkgs`, `nixpkgs.localSystem` or `nixpkgs.hostPlatform` is set. ''; }; }; diff --git a/nixos/modules/services/backup/duplicity.nix b/nixos/modules/services/backup/duplicity.nix index 22ee6652d1a36..05ec997ab66b0 100644 --- a/nixos/modules/services/backup/duplicity.nix +++ b/nixos/modules/services/backup/duplicity.nix @@ -54,15 +54,15 @@ in secretFile = mkOption { type = types.nullOr types.path; default = null; - description = '' + description = lib.mdDoc '' Path of a file containing secrets (gpg passphrase, access key...) in the format of EnvironmentFile as described by - systemd.exec5. For example: - + {manpage}`systemd.exec(5)`. For example: + ``` PASSPHRASE=«...» AWS_ACCESS_KEY_ID=«...» AWS_SECRET_ACCESS_KEY=«...» - + ``` ''; }; diff --git a/nixos/modules/services/databases/cockroachdb.nix b/nixos/modules/services/databases/cockroachdb.nix index 380058a8f5590..26ccb030b3df2 100644 --- a/nixos/modules/services/databases/cockroachdb.nix +++ b/nixos/modules/services/databases/cockroachdb.nix @@ -58,7 +58,7 @@ in locality = mkOption { type = types.nullOr types.str; default = null; - description = '' + description = lib.mdDoc '' An ordered, comma-separated list of key-value pairs that describe the topography of the machine. Topography might include country, datacenter or rack designations. Data is automatically replicated to @@ -68,12 +68,12 @@ in like datacenter. The tiers and order must be the same on all nodes. Including more tiers is better than including fewer. For example: - + ``` country=us,region=us-west,datacenter=us-west-1b,rack=12 country=ca,region=ca-east,datacenter=ca-east-2,rack=4 planet=earth,province=manitoba,colo=secondary,power=3 - + ``` ''; }; diff --git a/nixos/modules/services/development/zammad.nix b/nixos/modules/services/development/zammad.nix index 55374a0ec90e8..23f2e501903aa 100644 --- a/nixos/modules/services/development/zammad.nix +++ b/nixos/modules/services/development/zammad.nix @@ -149,20 +149,20 @@ in type = types.nullOr types.path; default = null; example = "/run/keys/secret_key_base"; - description = '' + description = lib.mdDoc '' The path to a file containing the - secret_key_base secret. + `secret_key_base` secret. - Zammad uses secret_key_base to encrypt + Zammad uses `secret_key_base` to encrypt the cookie store, which contains session data, and to digest user auth tokens. Needs to be a 64 byte long string of hexadecimal characters. You can generate one by running - + ``` openssl rand -hex 64 >/path/to/secret_key_base_file - + ``` This should be a string, not a nix path, since nix paths are copied into the world-readable nix store. diff --git a/nixos/modules/services/hardware/lcd.nix b/nixos/modules/services/hardware/lcd.nix index 7eb5f58d9fbbb..8d682d137f44c 100644 --- a/nixos/modules/services/hardware/lcd.nix +++ b/nixos/modules/services/hardware/lcd.nix @@ -61,20 +61,20 @@ in with lib; { usbPermissions = mkOption { type = bool; default = false; - description = '' + description = lib.mdDoc '' Set group-write permissions on a USB device. A USB connected LCD panel will most likely require having its permissions modified for lcdd to write to it. Enabling this option sets group-write permissions on the device identified by - and - . In order to find the - values, you can run the lsusb command. Example + {option}`services.hardware.lcd.usbVid` and + {option}`services.hardware.lcd.usbPid`. In order to find the + values, you can run the {command}`lsusb` command. Example output: - + ``` Bus 005 Device 002: ID 0403:c630 Future Technology Devices International, Ltd lcd2usb interface - + ``` In this case the vendor id is 0403 and the product id is c630. ''; diff --git a/nixos/modules/services/logging/awstats.nix b/nixos/modules/services/logging/awstats.nix index e9bc5d5bd973e..708775bfcf03a 100644 --- a/nixos/modules/services/logging/awstats.nix +++ b/nixos/modules/services/logging/awstats.nix @@ -25,26 +25,26 @@ let logFile = mkOption { type = types.str; example = "/var/log/nginx/access.log"; - description = '' + description = lib.mdDoc '' The log file to be scanned. For mail, set this to - + ``` journalctl $OLD_CURSOR -u postfix.service | ''${pkgs.perl}/bin/perl ''${pkgs.awstats.out}/share/awstats/tools/maillogconvert.pl standard | - + ``` ''; }; logFormat = mkOption { type = types.str; default = "1"; - description = '' + description = lib.mdDoc '' The log format being used. For mail, set this to - + ``` %time2 %email %email_r %host %host_r %method %url %code %bytesd - + ``` ''; }; diff --git a/nixos/modules/services/matrix/dendrite.nix b/nixos/modules/services/matrix/dendrite.nix index 51eaa4f1271b8..9279af246f41e 100644 --- a/nixos/modules/services/matrix/dendrite.nix +++ b/nixos/modules/services/matrix/dendrite.nix @@ -50,26 +50,26 @@ in type = lib.types.nullOr lib.types.path; example = "/var/lib/dendrite/registration_secret"; default = null; - description = '' - Environment file as defined in systemd.exec5. + description = lib.mdDoc '' + Environment file as defined in {manpage}`systemd.exec(5)`. Secrets may be passed to the service without adding them to the world-readable Nix store, by specifying placeholder variables as the option value in Nix and setting these variables accordingly in the environment file. Currently only used for the registration secret to allow secure registration when client_api.registration_disabled is true. - + ``` # snippet of dendrite-related config services.dendrite.settings.client_api.registration_shared_secret = "$REGISTRATION_SHARED_SECRET"; - + ``` - + ``` # content of the environment file REGISTRATION_SHARED_SECRET=verysecretpassword - + ``` Note that this file needs to be available on the host on which - dendrite is running. + `dendrite` is running. ''; }; loadCredential = lib.mkOption { diff --git a/nixos/modules/services/misc/gitit.nix b/nixos/modules/services/misc/gitit.nix index 9e3fc4422a016..c958e05370afa 100644 --- a/nixos/modules/services/misc/gitit.nix +++ b/nixos/modules/services/misc/gitit.nix @@ -348,14 +348,14 @@ let mimeTypesFile = mkOption { type = types.path; default = "/etc/mime/types.info"; - description = '' + description = lib.mdDoc '' Specifies the path of a file containing mime type mappings. Each line of the file should contain two fields, separated by whitespace. The first field is the mime type, the second is a file extension. For example: - -video/x-ms-wmx wmx - + ``` + video/x-ms-wmx wmx + ``` If the file is not found, some simple defaults will be used. ''; }; diff --git a/nixos/modules/services/misc/sssd.nix b/nixos/modules/services/misc/sssd.nix index 1d1ce5ee62329..edd5750a4a478 100644 --- a/nixos/modules/services/misc/sssd.nix +++ b/nixos/modules/services/misc/sssd.nix @@ -54,25 +54,23 @@ in { environmentFile = mkOption { type = types.nullOr types.path; default = null; - description = '' - Environment file as defined in - systemd.exec5 - . + description = lib.mdDoc '' + Environment file as defined in {manpage}`systemd.exec(5)`. Secrets may be passed to the service without adding them to the world-readable Nix store, by specifying placeholder variables as the option value in Nix and setting these variables accordingly in the environment file. - + ``` # snippet of sssd-related config [domain/LDAP] ldap_default_authtok = $SSSD_LDAP_DEFAULT_AUTHTOK - + ``` - + ``` # contents of the environment file SSSD_LDAP_DEFAULT_AUTHTOK=verysecretpassword - + ``` ''; }; }; diff --git a/nixos/modules/services/monitoring/prometheus/exporters/dovecot.nix b/nixos/modules/services/monitoring/prometheus/exporters/dovecot.nix index 80a2f92881d75..6fb438353a4c4 100644 --- a/nixos/modules/services/monitoring/prometheus/exporters/dovecot.nix +++ b/nixos/modules/services/monitoring/prometheus/exporters/dovecot.nix @@ -19,19 +19,19 @@ in type = types.path; default = "/var/run/dovecot/stats"; example = "/var/run/dovecot2/old-stats"; - description = '' + description = lib.mdDoc '' Path under which the stats socket is placed. The user/group under which the exporter runs, should be able to access the socket in order to scrape the metrics successfully. Please keep in mind that the stats module has changed in - Dovecot 2.3+ which - is not compatible with this exporter. + [Dovecot 2.3+](https://wiki2.dovecot.org/Upgrading/2.3) which + is not [compatible with this exporter](https://github.com/kumina/dovecot_exporter/issues/8). The following extra config has to be passed to Dovecot to ensure that recent versions work with this exporter: - + ``` { services.prometheus.exporters.dovecot.enable = true; services.prometheus.exporters.dovecot.socketPath = "/var/run/dovecot2/old-stats"; @@ -60,7 +60,7 @@ in } '''; } - + ``` ''; }; scopes = mkOption { diff --git a/nixos/modules/services/monitoring/prometheus/exporters/mail.nix b/nixos/modules/services/monitoring/prometheus/exporters/mail.nix index 4ebe7128e2a09..129c73eba4adf 100644 --- a/nixos/modules/services/monitoring/prometheus/exporters/mail.nix +++ b/nixos/modules/services/monitoring/prometheus/exporters/mail.nix @@ -112,14 +112,14 @@ let detectionDir = "/path/to/Maildir/new"; } ] ''; - description = '' + description = lib.mdDoc '' List of servers that should be probed. - Note: if your mailserver has rspamd8 configured, + *Note:* if your mailserver has {manpage}`rspamd(8)` configured, it can happen that emails from this exporter are marked as spam. It's possible to work around the issue with a config like this: - + ``` { services.rspamd.locals."multimap.conf".text = ''' ALLOWLIST_PROMETHEUS { @@ -130,7 +130,7 @@ let } '''; } - + ``` ''; }; }; diff --git a/nixos/modules/services/monitoring/prometheus/exporters/openldap.nix b/nixos/modules/services/monitoring/prometheus/exporters/openldap.nix index 6f77c05562d72..aee3ae5bb2d4c 100644 --- a/nixos/modules/services/monitoring/prometheus/exporters/openldap.nix +++ b/nixos/modules/services/monitoring/prometheus/exporters/openldap.nix @@ -10,16 +10,16 @@ in { ldapCredentialFile = mkOption { type = types.path; example = "/run/keys/ldap_pass"; - description = '' + description = lib.mdDoc '' Environment file to contain the credentials to authenticate against - openldap. + `openldap`. The file should look like this: - + ``` --- ldapUser: "cn=monitoring,cn=Monitor" ldapPass: "secret" - + ``` ''; }; protocol = mkOption { diff --git a/nixos/modules/services/monitoring/prometheus/exporters/postgres.nix b/nixos/modules/services/monitoring/prometheus/exporters/postgres.nix index 5e8dd21af85f8..755d771ecdff4 100644 --- a/nixos/modules/services/monitoring/prometheus/exporters/postgres.nix +++ b/nixos/modules/services/monitoring/prometheus/exporters/postgres.nix @@ -36,8 +36,8 @@ in type = types.nullOr types.path; default = null; example = "/root/prometheus-postgres-exporter.env"; - description = '' - Environment file as defined in systemd.exec5. + description = lib.mdDoc '' + Environment file as defined in {manpage}`systemd.exec(5)`. Secrets may be passed to the service without adding them to the world-readable Nix store, by specifying placeholder variables as @@ -46,7 +46,7 @@ in Environment variables from this file will be interpolated into the config file using envsubst with this syntax: - $ENVIRONMENT ''${VARIABLE} + `$ENVIRONMENT ''${VARIABLE}` The main use is to set the DATA_SOURCE_NAME that contains the postgres password @@ -54,10 +54,10 @@ in note that contents from this file will override dataSourceName if you have set it from nix. - + ``` # Content of the environment file DATA_SOURCE_NAME=postgresql://username:password@localhost:5432/postgres?sslmode=disable - + ``` Note that this file needs to be available on the host on which this exporter is running. diff --git a/nixos/modules/services/network-filesystems/litestream/default.nix b/nixos/modules/services/network-filesystems/litestream/default.nix index 7db91f644e8ac..884ffa50e7c67 100644 --- a/nixos/modules/services/network-filesystems/litestream/default.nix +++ b/nixos/modules/services/network-filesystems/litestream/default.nix @@ -40,8 +40,8 @@ in type = types.nullOr types.path; default = null; example = "/run/secrets/litestream"; - description = '' - Environment file as defined in systemd.exec5. + description = lib.mdDoc '' + Environment file as defined in {manpage}`systemd.exec(5)`. Secrets may be passed to the service without adding them to the world-readable Nix store, by specifying placeholder variables as @@ -54,11 +54,11 @@ in variable values. If no value is set then it will be replaced with an empty string. - + ``` # Content of the environment file LITESTREAM_ACCESS_KEY_ID=AKIAxxxxxxxxxxxxxxxx LITESTREAM_SECRET_ACCESS_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/xxxxxxxxx - + ``` Note that this file needs to be available on the host on which this exporter is running. diff --git a/nixos/modules/services/networking/3proxy.nix b/nixos/modules/services/networking/3proxy.nix index bd390ecf405b8..1b2eb6a318ad5 100644 --- a/nixos/modules/services/networking/3proxy.nix +++ b/nixos/modules/services/networking/3proxy.nix @@ -18,26 +18,26 @@ in { type = types.nullOr types.path; default = null; example = "/var/lib/3proxy/3proxy.passwd"; - description = '' + description = lib.mdDoc '' Load users and passwords from this file. Example users file with plain-text passwords: - + ``` test1:CL:password1 test2:CL:password2 - + ``` Example users file with md5-crypted passwords: - + ``` test1:CR:$1$tFkisVd2$1GA8JXkRmTXdLDytM/i3a1 test2:CR:$1$rkpibm5J$Aq1.9VtYAn0JrqZ8M.1ME. - + ``` You can generate md5-crypted passwords via https://unix4lyfe.org/crypt/ Note that htpasswd tool generates incompatible md5-crypted passwords. - Consult documentation for more information. + Consult [documentation](https://github.com/z3APA3A/3proxy/wiki/How-To-%28incomplete%29#USERS) for more information. ''; }; services = mkOption { diff --git a/nixos/modules/services/networking/firefox-syncserver.nix b/nixos/modules/services/networking/firefox-syncserver.nix index 0f689a5e15ed0..fa8e4fcaed2f5 100644 --- a/nixos/modules/services/networking/firefox-syncserver.nix +++ b/nixos/modules/services/networking/firefox-syncserver.nix @@ -34,22 +34,22 @@ in { options = { services.firefox-syncserver = { - enable = lib.mkEnableOption '' + enable = lib.mkEnableOption (lib.mdDoc '' the Firefox Sync storage service. Out of the box this will not be very useful unless you also configure at least one service and one nodes by inserting them into the mysql database manually, e.g. by running - + ``` INSERT INTO `services` (`id`, `service`, `pattern`) VALUES ('1', 'sync-1.5', '{node}/1.5/{uid}'); INSERT INTO `nodes` (`id`, `service`, `node`, `available`, `current_load`, `capacity`, `downed`, `backoff`) VALUES ('1', '1', 'https://mydomain.tld', '1', '0', '10', '0', '0'); - + ``` - does this automatically when enabled - ''; + {option}`${opt.singleNode.enable}` does this automatically when enabled + ''); package = lib.mkOption { type = lib.types.package; diff --git a/nixos/modules/services/networking/hylafax/options.nix b/nixos/modules/services/networking/hylafax/options.nix index 8b39aea08411c..82c144236f3b8 100644 --- a/nixos/modules/services/networking/hylafax/options.nix +++ b/nixos/modules/services/networking/hylafax/options.nix @@ -172,23 +172,23 @@ in userAccessFile = mkOption { type = path; default = "/etc/hosts.hfaxd"; - description = '' - The hosts.hfaxd + description = lib.mdDoc '' + The {file}`hosts.hfaxd` file entry in the spooling area will be symlinked to the location given here. This file must exist and be - readable only by the uucp user. + readable only by the `uucp` user. See hosts.hfaxd(5) for details. This configuration permits access for all users: - + ``` environment.etc."hosts.hfaxd" = { mode = "0600"; user = "uucp"; text = ".*"; }; - + ``` Note that host-based access can be controlled with - ; + {option}`config.systemd.sockets.hylafax-hfaxd.listenStreams`; by default, only 127.0.0.1 is permitted to connect. ''; }; diff --git a/nixos/modules/services/networking/murmur.nix b/nixos/modules/services/networking/murmur.nix index 73787f433b45c..32498ca25ea83 100644 --- a/nixos/modules/services/networking/murmur.nix +++ b/nixos/modules/services/networking/murmur.nix @@ -261,25 +261,25 @@ in type = types.nullOr types.path; default = null; example = "/var/lib/murmur/murmurd.env"; - description = '' - Environment file as defined in systemd.exec5. + description = lib.mdDoc '' + Environment file as defined in {manpage}`systemd.exec(5)`. Secrets may be passed to the service without adding them to the world-readable Nix store, by specifying placeholder variables as the option value in Nix and setting these variables accordingly in the environment file. - + ``` # snippet of murmur-related config services.murmur.password = "$MURMURD_PASSWORD"; - + ``` - + ``` # content of the environment file MURMURD_PASSWORD=verysecretpassword - + ``` Note that this file needs to be available on the host on which - murmur is running. + `murmur` is running. ''; }; }; diff --git a/nixos/modules/services/networking/ncdns.nix b/nixos/modules/services/networking/ncdns.nix index c9101fef8eb71..1d494332095f4 100644 --- a/nixos/modules/services/networking/ncdns.nix +++ b/nixos/modules/services/networking/ncdns.nix @@ -78,16 +78,16 @@ in default = config.networking.hostName; defaultText = literalExpression "config.networking.hostName"; example = "example.com"; - description = '' + description = lib.mdDoc '' The hostname of this ncdns instance, which defaults to the machine hostname. If specified, ncdns lists the hostname as an NS record at the zone apex: - + ``` bit. IN NS ns1.example.com. - + ``` If unset ncdns will generate an internal psuedo-hostname under the zone, which will resolve to the value of - . + {option}`services.ncdns.identity.address`. If you are only using ncdns locally you can ignore this. ''; }; @@ -123,13 +123,13 @@ in dnssec.keys.public = mkOption { type = types.path; default = defaultFiles.public; - description = '' + description = lib.mdDoc '' Path to the file containing the KSK public key. - The key can be generated using the dnssec-keygen - command, provided by the package bind as follows: - + The key can be generated using the `dnssec-keygen` + command, provided by the package `bind` as follows: + ``` $ dnssec-keygen -a RSASHA256 -3 -b 2048 -f KSK bit - + ``` ''; }; @@ -144,13 +144,13 @@ in dnssec.keys.zonePublic = mkOption { type = types.path; default = defaultFiles.zonePublic; - description = '' + description = lib.mdDoc '' Path to the file containing the ZSK public key. - The key can be generated using the dnssec-keygen - command, provided by the package bind as follows: - + The key can be generated using the `dnssec-keygen` + command, provided by the package `bind` as follows: + ``` $ dnssec-keygen -a RSASHA256 -3 -b 2048 bit - + ``` ''; }; diff --git a/nixos/modules/services/networking/nix-serve.nix b/nixos/modules/services/networking/nix-serve.nix index deb91ca2f314c..dba2f1386b6f9 100644 --- a/nixos/modules/services/networking/nix-serve.nix +++ b/nixos/modules/services/networking/nix-serve.nix @@ -35,15 +35,15 @@ in secretKeyFile = mkOption { type = types.nullOr types.str; default = null; - description = '' + description = lib.mdDoc '' The path to the file used for signing derivation data. Generate with: - + ``` nix-store --generate-binary-cache-key key-name secret-key-file public-key-file - + ``` - For more details see nix-store1. + For more details see {manpage}`nix-store(1)`. ''; }; diff --git a/nixos/modules/services/security/hockeypuck.nix b/nixos/modules/services/security/hockeypuck.nix index d3fdaf9b99737..127134bc5dba5 100644 --- a/nixos/modules/services/security/hockeypuck.nix +++ b/nixos/modules/services/security/hockeypuck.nix @@ -37,10 +37,10 @@ in { }; } ''; - description = '' + description = lib.mdDoc '' Configuration file for hockeypuck, here you can override - certain settings (loglevel and - openpgp.db.dsn) by just setting those values. + certain settings (`loglevel` and + `openpgp.db.dsn`) by just setting those values. For other settings you need to use lib.mkForce to override them. @@ -49,7 +49,7 @@ in { the database yourself. Example: - + ``` services.postgresql = { enable = true; ensureDatabases = [ "hockeypuck" ]; @@ -58,7 +58,7 @@ in { ensurePermissions."DATABASE hockeypuck" = "ALL PRIVILEGES"; }]; }; - + ``` ''; }; }; diff --git a/nixos/modules/services/security/privacyidea.nix b/nixos/modules/services/security/privacyidea.nix index 26d9a8835bd39..5cd338ebf7fe0 100644 --- a/nixos/modules/services/security/privacyidea.nix +++ b/nixos/modules/services/security/privacyidea.nix @@ -72,19 +72,19 @@ in type = types.nullOr types.path; default = null; example = "/root/privacyidea.env"; - description = '' + description = lib.mdDoc '' File to load as environment file. Environment variables from this file will be interpolated into the config file - using envsubst which is helpful for specifying + using `envsubst` which is helpful for specifying secrets: - - { = "$SECRET"; } - + ``` + { services.privacyidea.secretKey = "$SECRET"; } + ``` The environment-file can now specify the actual secret key: - + ``` SECRET=veryverytopsecret - + ``` ''; }; diff --git a/nixos/modules/services/security/vault.nix b/nixos/modules/services/security/vault.nix index 73943458829df..7b9e31a8d990f 100644 --- a/nixos/modules/services/security/vault.nix +++ b/nixos/modules/services/security/vault.nix @@ -141,17 +141,17 @@ in extraSettingsPaths = mkOption { type = types.listOf types.path; default = []; - description = '' + description = lib.mdDoc '' Configuration files to load besides the immutable one defined by the NixOS module. This can be used to avoid putting credentials in the Nix store, which can be read by any user. Each path can point to a JSON- or HCL-formatted file, or a directory - to be scanned for files with .hcl or - .json extensions. + to be scanned for files with `.hcl` or + `.json` extensions. To upload the confidential file with NixOps, use for example: - + ``` ''; }; }; diff --git a/nixos/modules/services/security/vaultwarden/default.nix b/nixos/modules/services/security/vaultwarden/default.nix index fd8b00ffc5e2a..59983de1a5a2e 100644 --- a/nixos/modules/services/security/vaultwarden/default.nix +++ b/nixos/modules/services/security/vaultwarden/default.nix @@ -125,31 +125,31 @@ in { type = with types; nullOr path; default = null; example = "/var/lib/vaultwarden.env"; - description = '' - Additional environment file as defined in systemd.exec5. + description = lib.mdDoc '' + Additional environment file as defined in {manpage}`systemd.exec(5)`. - Secrets like ADMIN_TOKEN and SMTP_PASSWORD + Secrets like {env}`ADMIN_TOKEN` and {env}`SMTP_PASSWORD` may be passed to the service without adding them to the world-readable Nix store. Note that this file needs to be available on the host on which - vaultwarden is running. + `vaultwarden` is running. As a concrete example, to make the Admin UI available (from which new users can be invited initially), - the secret ADMIN_TOKEN needs to be defined as described - here. - Setting environmentFile to /var/lib/vaultwarden.env + the secret {env}`ADMIN_TOKEN` needs to be defined as described + [here](https://github.com/dani-garcia/vaultwarden/wiki/Enabling-admin-page). + Setting `environmentFile` to `/var/lib/vaultwarden.env` and ensuring permissions with e.g. - chown vaultwarden:vaultwarden /var/lib/vaultwarden.env - (the vaultwarden user will only exist after activating with - enable = true; before this), we can set the contents of the file to have + `chown vaultwarden:vaultwarden /var/lib/vaultwarden.env` + (the `vaultwarden` user will only exist after activating with + `enable = true;` before this), we can set the contents of the file to have contents such as: - -# Admin secret token, see -# https://github.com/dani-garcia/vaultwarden/wiki/Enabling-admin-page -ADMIN_TOKEN=...copy-paste a unique generated secret token here... - + ``` + # Admin secret token, see + # https://github.com/dani-garcia/vaultwarden/wiki/Enabling-admin-page + ADMIN_TOKEN=...copy-paste a unique generated secret token here... + ``` ''; }; diff --git a/nixos/modules/services/web-apps/discourse.nix b/nixos/modules/services/web-apps/discourse.nix index 156a5cf9f8316..66b22ec87db12 100644 --- a/nixos/modules/services/web-apps/discourse.nix +++ b/nixos/modules/services/web-apps/discourse.nix @@ -57,20 +57,20 @@ in type = with lib.types; nullOr path; default = null; example = "/run/keys/secret_key_base"; - description = '' + description = lib.mdDoc '' The path to a file containing the - secret_key_base secret. + `secret_key_base` secret. - Discourse uses secret_key_base to encrypt + Discourse uses `secret_key_base` to encrypt the cookie store, which contains session data, and to digest user auth tokens. Needs to be a 64 byte long string of hexadecimal characters. You can generate one by running - + ``` openssl rand -hex 64 >/path/to/secret_key_base_file - + ``` This should be a string, not a nix path, since nix paths are copied into the world-readable nix store. diff --git a/nixos/modules/services/web-apps/hedgedoc.nix b/nixos/modules/services/web-apps/hedgedoc.nix index 9371eae31dfef..e26dee68615e0 100644 --- a/nixos/modules/services/web-apps/hedgedoc.nix +++ b/nixos/modules/services/web-apps/hedgedoc.nix @@ -990,27 +990,27 @@ in type = with types; nullOr path; default = null; example = "/var/lib/hedgedoc/hedgedoc.env"; - description = '' - Environment file as defined in systemd.exec5. + description = lib.mdDoc '' + Environment file as defined in {manpage}`systemd.exec(5)`. Secrets may be passed to the service without adding them to the world-readable Nix store, by specifying placeholder variables as the option value in Nix and setting these variables accordingly in the environment file. - + ``` # snippet of HedgeDoc-related config services.hedgedoc.configuration.dbURL = "postgres://hedgedoc:\''${DB_PASSWORD}@db-host:5432/hedgedocdb"; services.hedgedoc.configuration.minio.secretKey = "$MINIO_SECRET_KEY"; - + ``` - + ``` # content of the environment file DB_PASSWORD=verysecretdbpassword MINIO_SECRET_KEY=verysecretminiokey - + ``` Note that this file needs to be available on the host on which - HedgeDoc is running. + `HedgeDoc` is running. ''; }; diff --git a/nixos/modules/services/web-servers/molly-brown.nix b/nixos/modules/services/web-servers/molly-brown.nix index feefb90d4f468..6d7ca0c12ef70 100644 --- a/nixos/modules/services/web-servers/molly-brown.nix +++ b/nixos/modules/services/web-servers/molly-brown.nix @@ -34,16 +34,16 @@ in { certPath = mkOption { type = types.path; example = "/var/lib/acme/example.com/cert.pem"; - description = '' + description = lib.mdDoc '' Path to TLS certificate. An ACME certificate and key may be shared with an HTTP server, but only if molly-brown has permissions allowing it to read such keys. As an example: - + ``` systemd.services.molly-brown.serviceConfig.SupplementaryGroups = [ config.security.acme.certs."example.com".group ]; - + ``` ''; }; diff --git a/nixos/modules/system/activation/top-level.nix b/nixos/modules/system/activation/top-level.nix index d3379a7f53694..b71ddf95dc500 100644 --- a/nixos/modules/system/activation/top-level.nix +++ b/nixos/modules/system/activation/top-level.nix @@ -164,17 +164,17 @@ in specialisation = mkOption { default = {}; example = lib.literalExpression "{ fewJobsManyCores.configuration = { nix.settings = { core = 0; max-jobs = 1; }; }; }"; - description = '' + description = lib.mdDoc '' Additional configurations to build. If - inheritParentConfig is true, the system + `inheritParentConfig` is true, the system will be based on the overall system configuration. To switch to a specialised configuration - (e.g. fewJobsManyCores) at runtime, run: + (e.g. `fewJobsManyCores`) at runtime, run: - + ``` sudo /run/current-system/specialisation/fewJobsManyCores/bin/switch-to-configuration test - + ``` ''; type = types.attrsOf (types.submodule ( local@{ ... }: let diff --git a/nixos/modules/virtualisation/lxcfs.nix b/nixos/modules/virtualisation/lxcfs.nix index 7d2879a95f4bf..fb0ba49f73044 100644 --- a/nixos/modules/virtualisation/lxcfs.nix +++ b/nixos/modules/virtualisation/lxcfs.nix @@ -15,13 +15,13 @@ in { mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' This enables LXCFS, a FUSE filesystem for LXC. To use lxcfs in include the following configuration in your container configuration: - + ``` virtualisation.lxc.defaultConfig = "lxc.include = ''${pkgs.lxcfs}/share/lxc/config/common.conf.d/00-lxcfs.conf"; - + ``` ''; }; }; diff --git a/nixos/modules/virtualisation/lxd.nix b/nixos/modules/virtualisation/lxd.nix index e81edf67f3c38..764bb5e3b40ed 100644 --- a/nixos/modules/virtualisation/lxd.nix +++ b/nixos/modules/virtualisation/lxd.nix @@ -18,17 +18,17 @@ in { enable = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' This option enables lxd, a daemon that manages containers. Users in the "lxd" group can interact with the daemon (e.g. to start or stop containers) using the - lxc command line tool, among others. + {command}`lxc` command line tool, among others. Most of the time, you'll also want to start lxcfs, so that containers can "see" the limits: - + ``` virtualisation.lxc.lxcfs.enable = true; - + ``` ''; }; -- cgit 1.4.1