diff options
Diffstat (limited to 'nixos/modules')
21 files changed, 798 insertions, 246 deletions
diff --git a/nixos/modules/i18n/input-method/default.xml b/nixos/modules/i18n/input-method/default.xml index 830ef88d6d9..117482fb0d5 100644 --- a/nixos/modules/i18n/input-method/default.xml +++ b/nixos/modules/i18n/input-method/default.xml @@ -5,7 +5,11 @@ xml:id="module-services-input-methods"> <title>Input Methods</title> <para> - Input methods are an operating system component that allows any data, such as keyboard strokes or mouse movements, to be received as input. In this way users can enter characters and symbols not found on their input devices. Using an input method is obligatory for any language that has more graphemes than there are keys on the keyboard. + Input methods are an operating system component that allows any data, such as + keyboard strokes or mouse movements, to be received as input. In this way + users can enter characters and symbols not found on their input devices. + Using an input method is obligatory for any language that has more graphemes + than there are keys on the keyboard. </para> <para> The following input methods are available in NixOS: @@ -36,7 +40,8 @@ <title>IBus</title> <para> - IBus is an Intelligent Input Bus. It provides full featured and user friendly input method user interface. + IBus is an Intelligent Input Bus. It provides full featured and user + friendly input method user interface. </para> <para> @@ -51,7 +56,8 @@ i18n.inputMethod = { </programlisting> <para> - <literal>i18n.inputMethod.ibus.engines</literal> is optional and can be used to add extra IBus engines. + <literal>i18n.inputMethod.ibus.engines</literal> is optional and can be used + to add extra IBus engines. </para> <para> @@ -61,7 +67,8 @@ i18n.inputMethod = { <itemizedlist> <listitem> <para> - Anthy (<literal>ibus-engines.anthy</literal>): Anthy is a system for Japanese input method. It converts Hiragana text to Kana Kanji mixed text. + Anthy (<literal>ibus-engines.anthy</literal>): Anthy is a system for + Japanese input method. It converts Hiragana text to Kana Kanji mixed text. </para> </listitem> <listitem> @@ -71,22 +78,28 @@ i18n.inputMethod = { </listitem> <listitem> <para> - m17n (<literal>ibus-engines.m17n</literal>): m17n is an input method that uses input methods and corresponding icons in the m17n database. + m17n (<literal>ibus-engines.m17n</literal>): m17n is an input method that + uses input methods and corresponding icons in the m17n database. </para> </listitem> <listitem> <para> - mozc (<literal>ibus-engines.mozc</literal>): A Japanese input method from Google. + mozc (<literal>ibus-engines.mozc</literal>): A Japanese input method from + Google. </para> </listitem> <listitem> <para> - Table (<literal>ibus-engines.table</literal>): An input method that load tables of input methods. + Table (<literal>ibus-engines.table</literal>): An input method that load + tables of input methods. </para> </listitem> <listitem> <para> - table-others (<literal>ibus-engines.table-others</literal>): Various table-based input methods. To use this, and any other table-based input methods, it must appear in the list of engines along with <literal>table</literal>. For example: + table-others (<literal>ibus-engines.table-others</literal>): Various + table-based input methods. To use this, and any other table-based input + methods, it must appear in the list of engines along with + <literal>table</literal>. For example: <programlisting> ibus.engines = with pkgs.ibus-engines; [ table table-others ]; </programlisting> @@ -95,13 +108,22 @@ ibus.engines = with pkgs.ibus-engines; [ table table-others ]; </itemizedlist> <para> - To use any input method, the package must be added in the configuration, as shown above, and also (after running <literal>nixos-rebuild</literal>) the input method must be added from IBus' preference dialog. + To use any input method, the package must be added in the configuration, as + shown above, and also (after running <literal>nixos-rebuild</literal>) the + input method must be added from IBus' preference dialog. </para> <simplesect xml:id="module-services-input-methods-troubleshooting"> <title>Troubleshooting</title> <para> - If IBus works in some applications but not others, a likely cause of this is that IBus is depending on a different version of <literal>glib</literal> to what the applications are depending on. This can be checked by running <literal>nix-store -q --requisites <path> | grep glib</literal>, where <literal><path></literal> is the path of either IBus or an application in the Nix store. The <literal>glib</literal> packages must match exactly. If they do not, uninstalling and reinstalling the application is a likely fix. + If IBus works in some applications but not others, a likely cause of this + is that IBus is depending on a different version of <literal>glib</literal> + to what the applications are depending on. This can be checked by running + <literal>nix-store -q --requisites <path> | grep glib</literal>, + where <literal><path></literal> is the path of either IBus or an + application in the Nix store. The <literal>glib</literal> packages must + match exactly. If they do not, uninstalling and reinstalling the + application is a likely fix. </para> </simplesect> </section> @@ -109,7 +131,8 @@ ibus.engines = with pkgs.ibus-engines; [ table table-others ]; <title>Fcitx</title> <para> - Fcitx is an input method framework with extension support. It has three built-in Input Method Engine, Pinyin, QuWei and Table-based input methods. + Fcitx is an input method framework with extension support. It has three + built-in Input Method Engine, Pinyin, QuWei and Table-based input methods. </para> <para> @@ -124,7 +147,8 @@ i18n.inputMethod = { </programlisting> <para> - <literal>i18n.inputMethod.fcitx.engines</literal> is optional and can be used to add extra Fcitx engines. + <literal>i18n.inputMethod.fcitx.engines</literal> is optional and can be + used to add extra Fcitx engines. </para> <para> @@ -134,12 +158,15 @@ i18n.inputMethod = { <itemizedlist> <listitem> <para> - Anthy (<literal>fcitx-engines.anthy</literal>): Anthy is a system for Japanese input method. It converts Hiragana text to Kana Kanji mixed text. + Anthy (<literal>fcitx-engines.anthy</literal>): Anthy is a system for + Japanese input method. It converts Hiragana text to Kana Kanji mixed text. </para> </listitem> <listitem> <para> - Chewing (<literal>fcitx-engines.chewing</literal>): Chewing is an intelligent Zhuyin input method. It is one of the most popular input methods among Traditional Chinese Unix users. + Chewing (<literal>fcitx-engines.chewing</literal>): Chewing is an + intelligent Zhuyin input method. It is one of the most popular input + methods among Traditional Chinese Unix users. </para> </listitem> <listitem> @@ -154,17 +181,20 @@ i18n.inputMethod = { </listitem> <listitem> <para> - m17n (<literal>fcitx-engines.m17n</literal>): m17n is an input method that uses input methods and corresponding icons in the m17n database. + m17n (<literal>fcitx-engines.m17n</literal>): m17n is an input method that + uses input methods and corresponding icons in the m17n database. </para> </listitem> <listitem> <para> - mozc (<literal>fcitx-engines.mozc</literal>): A Japanese input method from Google. + mozc (<literal>fcitx-engines.mozc</literal>): A Japanese input method from + Google. </para> </listitem> <listitem> <para> - table-others (<literal>fcitx-engines.table-others</literal>): Various table-based input methods. + table-others (<literal>fcitx-engines.table-others</literal>): Various + table-based input methods. </para> </listitem> </itemizedlist> @@ -173,7 +203,9 @@ i18n.inputMethod = { <title>Nabi</title> <para> - Nabi is an easy to use Korean X input method. It allows you to enter phonetic Korean characters (hangul) and pictographic Korean characters (hanja). + Nabi is an easy to use Korean X input method. It allows you to enter + phonetic Korean characters (hangul) and pictographic Korean characters + (hanja). </para> <para> @@ -190,7 +222,8 @@ i18n.inputMethod = { <title>Uim</title> <para> - Uim (short for "universal input method") is a multilingual input method framework. Applications can use it through so-called bridges. + Uim (short for "universal input method") is a multilingual input method + framework. Applications can use it through so-called bridges. </para> <para> @@ -204,7 +237,8 @@ i18n.inputMethod = { </programlisting> <para> - Note: The <xref linkend="opt-i18n.inputMethod.uim.toolbar"/> option can be used to choose uim toolbar. + Note: The <xref linkend="opt-i18n.inputMethod.uim.toolbar"/> option can be + used to choose uim toolbar. </para> </section> </chapter> diff --git a/nixos/modules/installer/cd-dvd/sd-image.nix b/nixos/modules/installer/cd-dvd/sd-image.nix index 0a015044155..a2a8e8ef752 100644 --- a/nixos/modules/installer/cd-dvd/sd-image.nix +++ b/nixos/modules/installer/cd-dvd/sd-image.nix @@ -174,8 +174,10 @@ in boot.postBootCommands = '' # On the first boot do some maintenance tasks if [ -f /nix-path-registration ]; then + set -euo pipefail + set -x # Figure out device names for the boot device and root filesystem. - rootPart=$(readlink -f /dev/disk/by-label/NIXOS_SD) + rootPart=$(${pkgs.utillinux}/bin/findmnt -n -o SOURCE /) bootDevice=$(lsblk -npo PKNAME $rootPart) # Resize the root partition and the filesystem to fit the disk diff --git a/nixos/modules/programs/digitalbitbox/doc.xml b/nixos/modules/programs/digitalbitbox/doc.xml index 871abddca4c..c63201628db 100644 --- a/nixos/modules/programs/digitalbitbox/doc.xml +++ b/nixos/modules/programs/digitalbitbox/doc.xml @@ -8,25 +8,37 @@ Digital Bitbox is a hardware wallet and second-factor authenticator. </para> <para> - The <literal>digitalbitbox</literal> programs module may be installed by setting <literal>programs.digitalbitbox</literal> to <literal>true</literal> in a manner similar to + The <literal>digitalbitbox</literal> programs module may be installed by + setting <literal>programs.digitalbitbox</literal> to <literal>true</literal> + in a manner similar to <programlisting> <xref linkend="opt-programs.digitalbitbox.enable"/> = true; </programlisting> - and bundles the <literal>digitalbitbox</literal> package (see <xref - linkend="sec-digitalbitbox-package" />), which contains the <literal>dbb-app</literal> and <literal>dbb-cli</literal> binaries, along with the hardware module (see <xref - linkend="sec-digitalbitbox-hardware-module" />) which sets up the necessary udev rules to access the device. + and bundles the <literal>digitalbitbox</literal> package (see + <xref + linkend="sec-digitalbitbox-package" />), which contains the + <literal>dbb-app</literal> and <literal>dbb-cli</literal> binaries, along + with the hardware module (see + <xref + linkend="sec-digitalbitbox-hardware-module" />) which sets up the + necessary udev rules to access the device. </para> <para> - Enabling the digitalbitbox module is pretty much the easiest way to get a Digital Bitbox device working on your system. + Enabling the digitalbitbox module is pretty much the easiest way to get a + Digital Bitbox device working on your system. </para> <para> - For more information, see <link xlink:href="https://digitalbitbox.com/start_linux" />. + For more information, see + <link xlink:href="https://digitalbitbox.com/start_linux" />. </para> <section xml:id="sec-digitalbitbox-package"> <title>Package</title> <para> - The binaries, <literal>dbb-app</literal> (a GUI tool) and <literal>dbb-cli</literal> (a CLI tool), are available through the <literal>digitalbitbox</literal> package which could be installed as follows: + The binaries, <literal>dbb-app</literal> (a GUI tool) and + <literal>dbb-cli</literal> (a CLI tool), are available through the + <literal>digitalbitbox</literal> package which could be installed as + follows: <programlisting> <xref linkend="opt-environment.systemPackages"/> = [ pkgs.digitalbitbox @@ -38,14 +50,17 @@ <title>Hardware</title> <para> - The digitalbitbox hardware package enables the udev rules for Digital Bitbox devices and may be installed as follows: + The digitalbitbox hardware package enables the udev rules for Digital Bitbox + devices and may be installed as follows: <programlisting> <xref linkend="opt-hardware.digitalbitbox.enable"/> = true; </programlisting> </para> <para> - In order to alter the udev rules, one may provide different values for the <literal>udevRule51</literal> and <literal>udevRule52</literal> attributes by means of overriding as follows: + In order to alter the udev rules, one may provide different values for the + <literal>udevRule51</literal> and <literal>udevRule52</literal> attributes + by means of overriding as follows: <programlisting> programs.digitalbitbox = { <link linkend="opt-programs.digitalbitbox.enable">enable</link> = true; diff --git a/nixos/modules/programs/plotinus.xml b/nixos/modules/programs/plotinus.xml index a0370f90a41..8fc8c22c6d7 100644 --- a/nixos/modules/programs/plotinus.xml +++ b/nixos/modules/programs/plotinus.xml @@ -5,19 +5,24 @@ xml:id="module-program-plotinus"> <title>Plotinus</title> <para> - <emphasis>Source:</emphasis> <filename>modules/programs/plotinus.nix</filename> + <emphasis>Source:</emphasis> + <filename>modules/programs/plotinus.nix</filename> </para> <para> - <emphasis>Upstream documentation:</emphasis> <link xlink:href="https://github.com/p-e-w/plotinus"/> + <emphasis>Upstream documentation:</emphasis> + <link xlink:href="https://github.com/p-e-w/plotinus"/> </para> <para> Plotinus is a searchable command palette in every modern GTK application. </para> <para> - When in a GTK 3 application and Plotinus is enabled, you can press <literal>Ctrl+Shift+P</literal> to open the command palette. The command palette provides a searchable list of of all menu items in the application. + When in a GTK 3 application and Plotinus is enabled, you can press + <literal>Ctrl+Shift+P</literal> to open the command palette. The command + palette provides a searchable list of of all menu items in the application. </para> <para> - To enable Plotinus, add the following to your <filename>configuration.nix</filename>: + To enable Plotinus, add the following to your + <filename>configuration.nix</filename>: <programlisting> <xref linkend="opt-programs.plotinus.enable"/> = true; </programlisting> diff --git a/nixos/modules/programs/zsh/oh-my-zsh.xml b/nixos/modules/programs/zsh/oh-my-zsh.xml index c5202d818c9..568c2de6557 100644 --- a/nixos/modules/programs/zsh/oh-my-zsh.xml +++ b/nixos/modules/programs/zsh/oh-my-zsh.xml @@ -5,13 +5,18 @@ xml:id="module-programs-zsh-ohmyzsh"> <title>Oh my ZSH</title> <para> - <literal><link xlink:href="https://ohmyz.sh/">oh-my-zsh</link></literal> is a framework to manage your <link xlink:href="https://www.zsh.org/">ZSH</link> configuration including completion scripts for several CLI tools or custom prompt themes. + <literal><link xlink:href="https://ohmyz.sh/">oh-my-zsh</link></literal> is a + framework to manage your <link xlink:href="https://www.zsh.org/">ZSH</link> + configuration including completion scripts for several CLI tools or custom + prompt themes. </para> <section xml:id="module-programs-oh-my-zsh-usage"> <title>Basic usage</title> <para> - The module uses the <literal>oh-my-zsh</literal> package with all available features. The initial setup using Nix expressions is fairly similar to the configuration format of <literal>oh-my-zsh</literal>. + The module uses the <literal>oh-my-zsh</literal> package with all available + features. The initial setup using Nix expressions is fairly similar to the + configuration format of <literal>oh-my-zsh</literal>. <programlisting> { programs.zsh.ohMyZsh = { @@ -21,18 +26,25 @@ }; } </programlisting> - For a detailed explanation of these arguments please refer to the <link xlink:href="https://github.com/robbyrussell/oh-my-zsh/wiki"><literal>oh-my-zsh</literal> docs</link>. + For a detailed explanation of these arguments please refer to the + <link xlink:href="https://github.com/robbyrussell/oh-my-zsh/wiki"><literal>oh-my-zsh</literal> + docs</link>. </para> <para> - The expression generates the needed configuration and writes it into your <literal>/etc/zshrc</literal>. + The expression generates the needed configuration and writes it into your + <literal>/etc/zshrc</literal>. </para> </section> <section xml:id="module-programs-oh-my-zsh-additions"> <title>Custom additions</title> <para> - Sometimes third-party or custom scripts such as a modified theme may be needed. <literal>oh-my-zsh</literal> provides the <link xlink:href="https://github.com/robbyrussell/oh-my-zsh/wiki/Customization#overriding-internals"><literal>ZSH_CUSTOM</literal></link> environment variable for this which points to a directory with additional scripts. + Sometimes third-party or custom scripts such as a modified theme may be + needed. <literal>oh-my-zsh</literal> provides the + <link xlink:href="https://github.com/robbyrussell/oh-my-zsh/wiki/Customization#overriding-internals"><literal>ZSH_CUSTOM</literal></link> + environment variable for this which points to a directory with additional + scripts. </para> <para> @@ -48,11 +60,16 @@ <title>Custom environments</title> <para> - There are several extensions for <literal>oh-my-zsh</literal> packaged in <literal>nixpkgs</literal>. One of them is <link xlink:href="https://github.com/spwhitt/nix-zsh-completions">nix-zsh-completions</link> which bundles completion scripts and a plugin for <literal>oh-my-zsh</literal>. + There are several extensions for <literal>oh-my-zsh</literal> packaged in + <literal>nixpkgs</literal>. One of them is + <link xlink:href="https://github.com/spwhitt/nix-zsh-completions">nix-zsh-completions</link> + which bundles completion scripts and a plugin for + <literal>oh-my-zsh</literal>. </para> <para> - Rather than using a single mutable path for <literal>ZSH_CUSTOM</literal>, it's also possible to generate this path from a list of Nix packages: + Rather than using a single mutable path for <literal>ZSH_CUSTOM</literal>, + it's also possible to generate this path from a list of Nix packages: <programlisting> { pkgs, ... }: { @@ -62,34 +79,53 @@ ]; } </programlisting> - Internally a single store path will be created using <literal>buildEnv</literal>. Please refer to the docs of <link xlink:href="https://nixos.org/nixpkgs/manual/#sec-building-environment"><literal>buildEnv</literal></link> for further reference. + Internally a single store path will be created using + <literal>buildEnv</literal>. Please refer to the docs of + <link xlink:href="https://nixos.org/nixpkgs/manual/#sec-building-environment"><literal>buildEnv</literal></link> + for further reference. </para> <para> - <emphasis>Please keep in mind that this is not compatible with <literal>programs.zsh.ohMyZsh.custom</literal> as it requires an immutable store path while <literal>custom</literal> shall remain mutable! An evaluation failure will be thrown if both <literal>custom</literal> and <literal>customPkgs</literal> are set.</emphasis> + <emphasis>Please keep in mind that this is not compatible with + <literal>programs.zsh.ohMyZsh.custom</literal> as it requires an immutable + store path while <literal>custom</literal> shall remain mutable! An + evaluation failure will be thrown if both <literal>custom</literal> and + <literal>customPkgs</literal> are set.</emphasis> </para> </section> <section xml:id="module-programs-oh-my-zsh-packaging-customizations"> <title>Package your own customizations</title> <para> - If third-party customizations (e.g. new themes) are supposed to be added to <literal>oh-my-zsh</literal> there are several pitfalls to keep in mind: + If third-party customizations (e.g. new themes) are supposed to be added to + <literal>oh-my-zsh</literal> there are several pitfalls to keep in mind: </para> <itemizedlist> <listitem> <para> - To comply with the default structure of <literal>ZSH</literal> the entire output needs to be written to <literal>$out/share/zsh.</literal> + To comply with the default structure of <literal>ZSH</literal> the entire + output needs to be written to <literal>$out/share/zsh.</literal> </para> </listitem> <listitem> <para> - Completion scripts are supposed to be stored at <literal>$out/share/zsh/site-functions</literal>. This directory is part of the <literal><link xlink:href="http://zsh.sourceforge.net/Doc/Release/Functions.html">fpath</link></literal> and the package should be compatible with pure <literal>ZSH</literal> setups. The module will automatically link the contents of <literal>site-functions</literal> to completions directory in the proper store path. + Completion scripts are supposed to be stored at + <literal>$out/share/zsh/site-functions</literal>. This directory is part + of the + <literal><link xlink:href="http://zsh.sourceforge.net/Doc/Release/Functions.html">fpath</link></literal> + and the package should be compatible with pure <literal>ZSH</literal> + setups. The module will automatically link the contents of + <literal>site-functions</literal> to completions directory in the proper + store path. </para> </listitem> <listitem> <para> - The <literal>plugins</literal> directory needs the structure <literal>pluginname/pluginname.plugin.zsh</literal> as structured in the <link xlink:href="https://github.com/robbyrussell/oh-my-zsh/tree/91b771914bc7c43dd7c7a43b586c5de2c225ceb7/plugins">upstream repo.</link> + The <literal>plugins</literal> directory needs the structure + <literal>pluginname/pluginname.plugin.zsh</literal> as structured in the + <link xlink:href="https://github.com/robbyrussell/oh-my-zsh/tree/91b771914bc7c43dd7c7a43b586c5de2c225ceb7/plugins">upstream + repo.</link> </para> </listitem> </itemizedlist> diff --git a/nixos/modules/security/acme.xml b/nixos/modules/security/acme.xml index 182d6e0cd51..9d0a1995e0f 100644 --- a/nixos/modules/security/acme.xml +++ b/nixos/modules/security/acme.xml @@ -5,13 +5,19 @@ xml:id="module-security-acme"> <title>SSL/TLS Certificates with ACME</title> <para> - NixOS supports automatic domain validation & certificate retrieval and renewal using the ACME protocol. This is currently only implemented by and for Let's Encrypt. The alternative ACME client <literal>simp_le</literal> is used under the hood. + NixOS supports automatic domain validation & certificate retrieval and + renewal using the ACME protocol. This is currently only implemented by and + for Let's Encrypt. The alternative ACME client <literal>simp_le</literal> is + used under the hood. </para> <section xml:id="module-security-acme-prerequisites"> <title>Prerequisites</title> <para> - You need to have a running HTTP server for verification. The server must have a webroot defined that can serve <filename>.well-known/acme-challenge</filename>. This directory must be writeable by the user that will run the ACME client. + You need to have a running HTTP server for verification. The server must + have a webroot defined that can serve + <filename>.well-known/acme-challenge</filename>. This directory must be + writeable by the user that will run the ACME client. </para> <para> @@ -39,7 +45,9 @@ http { <title>Configuring</title> <para> - To enable ACME certificate retrieval & renewal for a certificate for <literal>foo.example.com</literal>, add the following in your <filename>configuration.nix</filename>: + To enable ACME certificate retrieval & renewal for a certificate for + <literal>foo.example.com</literal>, add the following in your + <filename>configuration.nix</filename>: <programlisting> <xref linkend="opt-security.acme.certs"/>."foo.example.com" = { <link linkend="opt-security.acme.certs._name_.webroot">webroot</link> = "/var/www/challenges"; @@ -49,18 +57,26 @@ http { </para> <para> - The private key <filename>key.pem</filename> and certificate <filename>fullchain.pem</filename> will be put into <filename>/var/lib/acme/foo.example.com</filename>. + The private key <filename>key.pem</filename> and certificate + <filename>fullchain.pem</filename> will be put into + <filename>/var/lib/acme/foo.example.com</filename>. </para> - <para> - Refer to <xref linkend="ch-options" /> for all available configuration options for the <link linkend="opt-security.acme.certs">security.acme</link> module. + Refer to <xref linkend="ch-options" /> for all available configuration + options for the <link linkend="opt-security.acme.certs">security.acme</link> + module. </para> </section> <section xml:id="module-security-acme-nginx"> <title>Using ACME certificates in Nginx</title> <para> - NixOS supports fetching ACME certificates for you by setting <literal><link linkend="opt-services.nginx.virtualHosts._name_.enableACME">enableACME</link> = true;</literal> in a virtualHost config. We first create self-signed placeholder certificates in place of the real ACME certs. The placeholder certs are overwritten when the ACME certs arrive. For <literal>foo.example.com</literal> the config would look like. + NixOS supports fetching ACME certificates for you by setting + <literal><link linkend="opt-services.nginx.virtualHosts._name_.enableACME">enableACME</link> + = true;</literal> in a virtualHost config. We first create self-signed + placeholder certificates in place of the real ACME certs. The placeholder + certs are overwritten when the ACME certs arrive. For + <literal>foo.example.com</literal> the config would look like. </para> <programlisting> diff --git a/nixos/modules/security/hidepid.xml b/nixos/modules/security/hidepid.xml index 979d0215ab3..5a17cb1da41 100644 --- a/nixos/modules/security/hidepid.xml +++ b/nixos/modules/security/hidepid.xml @@ -9,13 +9,18 @@ <programlisting> <xref linkend="opt-security.hideProcessInformation"/> = true; </programlisting> - ensures that access to process information is restricted to the owning user. This implies, among other things, that command-line arguments remain private. Unless your deployment relies on unprivileged users being able to inspect the process information of other users, this option should be safe to enable. + ensures that access to process information is restricted to the owning user. + This implies, among other things, that command-line arguments remain private. + Unless your deployment relies on unprivileged users being able to inspect the + process information of other users, this option should be safe to enable. </para> <para> - Members of the <literal>proc</literal> group are exempt from process information hiding. + Members of the <literal>proc</literal> group are exempt from process + information hiding. </para> <para> - To allow a service <replaceable>foo</replaceable> to run without process information hiding, set + To allow a service <replaceable>foo</replaceable> to run without process + information hiding, set <programlisting> <link linkend="opt-systemd.services._name_.serviceConfig">systemd.services.<replaceable>foo</replaceable>.serviceConfig</link>.SupplementaryGroups = [ "proc" ]; </programlisting> diff --git a/nixos/modules/services/databases/foundationdb.xml b/nixos/modules/services/databases/foundationdb.xml index 33adfee3526..b0b1ebeab45 100644 --- a/nixos/modules/services/databases/foundationdb.xml +++ b/nixos/modules/services/databases/foundationdb.xml @@ -5,10 +5,12 @@ xml:id="module-services-foundationdb"> <title>FoundationDB</title> <para> - <emphasis>Source:</emphasis> <filename>modules/services/databases/foundationdb.nix</filename> + <emphasis>Source:</emphasis> + <filename>modules/services/databases/foundationdb.nix</filename> </para> <para> - <emphasis>Upstream documentation:</emphasis> <link xlink:href="https://apple.github.io/foundationdb/"/> + <emphasis>Upstream documentation:</emphasis> + <link xlink:href="https://apple.github.io/foundationdb/"/> </para> <para> <emphasis>Maintainer:</emphasis> Austin Seipp @@ -17,13 +19,15 @@ <emphasis>Available version(s):</emphasis> 5.1.x, 5.2.x, 6.0.x </para> <para> - FoundationDB (or "FDB") is an open source, distributed, transactional key-value store. + FoundationDB (or "FDB") is an open source, distributed, transactional + key-value store. </para> <section xml:id="module-services-foundationdb-configuring"> <title>Configuring and basic setup</title> <para> - To enable FoundationDB, add the following to your <filename>configuration.nix</filename>: + To enable FoundationDB, add the following to your + <filename>configuration.nix</filename>: <programlisting> services.foundationdb.enable = true; services.foundationdb.package = pkgs.foundationdb52; # FoundationDB 5.2.x @@ -31,11 +35,18 @@ services.foundationdb.package = pkgs.foundationdb52; # FoundationDB 5.2.x </para> <para> - The <option>services.foundationdb.package</option> option is required, and must always be specified. Due to the fact FoundationDB network protocols and on-disk storage formats may change between (major) versions, and upgrades must be explicitly handled by the user, you must always manually specify this yourself so that the NixOS module will use the proper version. Note that minor, bugfix releases are always compatible. + The <option>services.foundationdb.package</option> option is required, and + must always be specified. Due to the fact FoundationDB network protocols and + on-disk storage formats may change between (major) versions, and upgrades + must be explicitly handled by the user, you must always manually specify + this yourself so that the NixOS module will use the proper version. Note + that minor, bugfix releases are always compatible. </para> <para> - After running <command>nixos-rebuild</command>, you can verify whether FoundationDB is running by executing <command>fdbcli</command> (which is added to <option>environment.systemPackages</option>): + After running <command>nixos-rebuild</command>, you can verify whether + FoundationDB is running by executing <command>fdbcli</command> (which is + added to <option>environment.systemPackages</option>): <screen> <prompt>$ </prompt>sudo -u foundationdb fdbcli Using cluster file `/etc/foundationdb/fdb.cluster'. @@ -66,7 +77,11 @@ Cluster: </para> <para> - You can also write programs using the available client libraries. For example, the following Python program can be run in order to grab the cluster status, as a quick example. (This example uses <command>nix-shell</command> shebang support to automatically supply the necessary Python modules). + You can also write programs using the available client libraries. For + example, the following Python program can be run in order to grab the + cluster status, as a quick example. (This example uses + <command>nix-shell</command> shebang support to automatically supply the + necessary Python modules). <screen> <prompt>a@link> </prompt>cat fdb-status.py #! /usr/bin/env nix-shell @@ -96,56 +111,91 @@ FoundationDB available: True </para> <para> - FoundationDB is run under the <command>foundationdb</command> user and group by default, but this may be changed in the NixOS configuration. The systemd unit <command>foundationdb.service</command> controls the <command>fdbmonitor</command> process. + FoundationDB is run under the <command>foundationdb</command> user and group + by default, but this may be changed in the NixOS configuration. The systemd + unit <command>foundationdb.service</command> controls the + <command>fdbmonitor</command> process. </para> <para> - By default, the NixOS module for FoundationDB creates a single SSD-storage based database for development and basic usage. This storage engine is designed for SSDs and will perform poorly on HDDs; however it can handle far more data than the alternative "memory" engine and is a better default choice for most deployments. (Note that you can change the storage backend on-the-fly for a given FoundationDB cluster using <command>fdbcli</command>.) + By default, the NixOS module for FoundationDB creates a single SSD-storage + based database for development and basic usage. This storage engine is + designed for SSDs and will perform poorly on HDDs; however it can handle far + more data than the alternative "memory" engine and is a better default + choice for most deployments. (Note that you can change the storage backend + on-the-fly for a given FoundationDB cluster using + <command>fdbcli</command>.) </para> <para> - Furthermore, only 1 server process and 1 backup agent are started in the default configuration. See below for more on scaling to increase this. + Furthermore, only 1 server process and 1 backup agent are started in the + default configuration. See below for more on scaling to increase this. </para> <para> - FoundationDB stores all data for all server processes under <filename>/var/lib/foundationdb</filename>. You can override this using <option>services.foundationdb.dataDir</option>, e.g. + FoundationDB stores all data for all server processes under + <filename>/var/lib/foundationdb</filename>. You can override this using + <option>services.foundationdb.dataDir</option>, e.g. <programlisting> services.foundationdb.dataDir = "/data/fdb"; </programlisting> </para> <para> - Similarly, logs are stored under <filename>/var/log/foundationdb</filename> by default, and there is a corresponding <option>services.foundationdb.logDir</option> as well. + Similarly, logs are stored under <filename>/var/log/foundationdb</filename> + by default, and there is a corresponding + <option>services.foundationdb.logDir</option> as well. </para> </section> <section xml:id="module-services-foundationdb-scaling"> <title>Scaling processes and backup agents</title> <para> - Scaling the number of server processes is quite easy; simply specify <option>services.foundationdb.serverProcesses</option> to be the number of FoundationDB worker processes that should be started on the machine. + Scaling the number of server processes is quite easy; simply specify + <option>services.foundationdb.serverProcesses</option> to be the number of + FoundationDB worker processes that should be started on the machine. </para> <para> - FoundationDB worker processes typically require 4GB of RAM per-process at minimum for good performance, so this option is set to 1 by default since the maximum amount of RAM is unknown. You're advised to abide by this restriction, so pick a number of processes so that each has 4GB or more. + FoundationDB worker processes typically require 4GB of RAM per-process at + minimum for good performance, so this option is set to 1 by default since + the maximum amount of RAM is unknown. You're advised to abide by this + restriction, so pick a number of processes so that each has 4GB or more. </para> <para> - A similar option exists in order to scale backup agent processes, <option>services.foundationdb.backupProcesses</option>. Backup agents are not as performance/RAM sensitive, so feel free to experiment with the number of available backup processes. + A similar option exists in order to scale backup agent processes, + <option>services.foundationdb.backupProcesses</option>. Backup agents are + not as performance/RAM sensitive, so feel free to experiment with the number + of available backup processes. </para> </section> <section xml:id="module-services-foundationdb-clustering"> <title>Clustering</title> <para> - FoundationDB on NixOS works similarly to other Linux systems, so this section will be brief. Please refer to the full FoundationDB documentation for more on clustering. + FoundationDB on NixOS works similarly to other Linux systems, so this + section will be brief. Please refer to the full FoundationDB documentation + for more on clustering. </para> <para> - FoundationDB organizes clusters using a set of <emphasis>coordinators</emphasis>, which are just specially-designated worker processes. By default, every installation of FoundationDB on NixOS will start as its own individual cluster, with a single coordinator: the first worker process on <command>localhost</command>. + FoundationDB organizes clusters using a set of + <emphasis>coordinators</emphasis>, which are just specially-designated + worker processes. By default, every installation of FoundationDB on NixOS + will start as its own individual cluster, with a single coordinator: the + first worker process on <command>localhost</command>. </para> <para> - Coordinators are specified globally using the <command>/etc/foundationdb/fdb.cluster</command> file, which all servers and client applications will use to find and join coordinators. Note that this file <emphasis>can not</emphasis> be managed by NixOS so easily: FoundationDB is designed so that it will rewrite the file at runtime for all clients and nodes when cluster coordinators change, with clients transparently handling this without intervention. It is fundamentally a mutable file, and you should not try to manage it in any way in NixOS. + Coordinators are specified globally using the + <command>/etc/foundationdb/fdb.cluster</command> file, which all servers and + client applications will use to find and join coordinators. Note that this + file <emphasis>can not</emphasis> be managed by NixOS so easily: + FoundationDB is designed so that it will rewrite the file at runtime for all + clients and nodes when cluster coordinators change, with clients + transparently handling this without intervention. It is fundamentally a + mutable file, and you should not try to manage it in any way in NixOS. </para> <para> @@ -166,7 +216,9 @@ services.foundationdb.dataDir = "/data/fdb"; </itemizedlist> <para> - A node must already be a member of the cluster in order to properly be promoted to a coordinator, so you must always add it first if you wish to promote it. + A node must already be a member of the cluster in order to properly be + promoted to a coordinator, so you must always add it first if you wish to + promote it. </para> <para> @@ -181,26 +233,37 @@ services.foundationdb.dataDir = "/data/fdb"; </listitem> <listitem> <para> - Copy the <command>/etc/foundationdb/fdb.cluster</command> file from this server to all the other servers. Restart FoundationDB on all of these other servers, so they join the cluster. + Copy the <command>/etc/foundationdb/fdb.cluster</command> file from this + server to all the other servers. Restart FoundationDB on all of these + other servers, so they join the cluster. </para> </listitem> <listitem> <para> - All of these servers are now connected and working together in the cluster, under the chosen coordinator. + All of these servers are now connected and working together in the + cluster, under the chosen coordinator. </para> </listitem> </itemizedlist> <para> - At this point, you can add as many nodes as you want by just repeating the above steps. By default there will still be a single coordinator: you can use <command>fdbcli</command> to change this and add new coordinators. + At this point, you can add as many nodes as you want by just repeating the + above steps. By default there will still be a single coordinator: you can + use <command>fdbcli</command> to change this and add new coordinators. </para> <para> - As a convenience, FoundationDB can automatically assign coordinators based on the redundancy mode you wish to achieve for the cluster. Once all the nodes have been joined, simply set the replication policy, and then issue the <command>coordinators auto</command> command + As a convenience, FoundationDB can automatically assign coordinators based + on the redundancy mode you wish to achieve for the cluster. Once all the + nodes have been joined, simply set the replication policy, and then issue + the <command>coordinators auto</command> command </para> <para> - For example, assuming we have 3 nodes available, we can enable double redundancy mode, then auto-select coordinators. For double redundancy, 3 coordinators is ideal: therefore FoundationDB will make <emphasis>every</emphasis> node a coordinator automatically: + For example, assuming we have 3 nodes available, we can enable double + redundancy mode, then auto-select coordinators. For double redundancy, 3 + coordinators is ideal: therefore FoundationDB will make + <emphasis>every</emphasis> node a coordinator automatically: </para> <screen> @@ -209,33 +272,58 @@ services.foundationdb.dataDir = "/data/fdb"; </screen> <para> - This will transparently update all the servers within seconds, and appropriately rewrite the <command>fdb.cluster</command> file, as well as informing all client processes to do the same. + This will transparently update all the servers within seconds, and + appropriately rewrite the <command>fdb.cluster</command> file, as well as + informing all client processes to do the same. </para> </section> <section xml:id="module-services-foundationdb-connectivity"> <title>Client connectivity</title> <para> - By default, all clients must use the current <command>fdb.cluster</command> file to access a given FoundationDB cluster. This file is located by default in <command>/etc/foundationdb/fdb.cluster</command> on all machines with the FoundationDB service enabled, so you may copy the active one from your cluster to a new node in order to connect, if it is not part of the cluster. + By default, all clients must use the current <command>fdb.cluster</command> + file to access a given FoundationDB cluster. This file is located by default + in <command>/etc/foundationdb/fdb.cluster</command> on all machines with the + FoundationDB service enabled, so you may copy the active one from your + cluster to a new node in order to connect, if it is not part of the cluster. </para> </section> <section xml:id="module-services-foundationdb-authorization"> <title>Client authorization and TLS</title> <para> - By default, any user who can connect to a FoundationDB process with the correct cluster configuration can access anything. FoundationDB uses a pluggable design to transport security, and out of the box it supports a LibreSSL-based plugin for TLS support. This plugin not only does in-flight encryption, but also performs client authorization based on the given endpoint's certificate chain. For example, a FoundationDB server may be configured to only accept client connections over TLS, where the client TLS certificate is from organization <emphasis>Acme Co</emphasis> in the <emphasis>Research and Development</emphasis> unit. + By default, any user who can connect to a FoundationDB process with the + correct cluster configuration can access anything. FoundationDB uses a + pluggable design to transport security, and out of the box it supports a + LibreSSL-based plugin for TLS support. This plugin not only does in-flight + encryption, but also performs client authorization based on the given + endpoint's certificate chain. For example, a FoundationDB server may be + configured to only accept client connections over TLS, where the client TLS + certificate is from organization <emphasis>Acme Co</emphasis> in the + <emphasis>Research and Development</emphasis> unit. </para> <para> - Configuring TLS with FoundationDB is done using the <option>services.foundationdb.tls</option> options in order to control the peer verification string, as well as the certificate and its private key. + Configuring TLS with FoundationDB is done using the + <option>services.foundationdb.tls</option> options in order to control the + peer verification string, as well as the certificate and its private key. </para> <para> - Note that the certificate and its private key must be accessible to the FoundationDB user account that the server runs under. These files are also NOT managed by NixOS, as putting them into the store may reveal private information. + Note that the certificate and its private key must be accessible to the + FoundationDB user account that the server runs under. These files are also + NOT managed by NixOS, as putting them into the store may reveal private + information. </para> <para> - After you have a key and certificate file in place, it is not enough to simply set the NixOS module options -- you must also configure the <command>fdb.cluster</command> file to specify that a given set of coordinators use TLS. This is as simple as adding the suffix <command>:tls</command> to your cluster coordinator configuration, after the port number. For example, assuming you have a coordinator on localhost with the default configuration, simply specifying: + After you have a key and certificate file in place, it is not enough to + simply set the NixOS module options -- you must also configure the + <command>fdb.cluster</command> file to specify that a given set of + coordinators use TLS. This is as simple as adding the suffix + <command>:tls</command> to your cluster coordinator configuration, after the + port number. For example, assuming you have a coordinator on localhost with + the default configuration, simply specifying: </para> <programlisting> @@ -250,19 +338,36 @@ XXXXXX:XXXXXX@127.0.0.1:4500:tls <title>Backups and Disaster Recovery</title> <para> - The usual rules for doing FoundationDB backups apply on NixOS as written in the FoundationDB manual. However, one important difference is the security profile for NixOS: by default, the <command>foundationdb</command> systemd unit uses <emphasis>Linux namespaces</emphasis> to restrict write access to the system, except for the log directory, data directory, and the <command>/etc/foundationdb/</command> directory. This is enforced by default and cannot be disabled. + The usual rules for doing FoundationDB backups apply on NixOS as written in + the FoundationDB manual. However, one important difference is the security + profile for NixOS: by default, the <command>foundationdb</command> systemd + unit uses <emphasis>Linux namespaces</emphasis> to restrict write access to + the system, except for the log directory, data directory, and the + <command>/etc/foundationdb/</command> directory. This is enforced by default + and cannot be disabled. </para> <para> - However, a side effect of this is that the <command>fdbbackup</command> command doesn't work properly for local filesystem backups: FoundationDB uses a server process alongside the database processes to perform backups and copy the backups to the filesystem. As a result, this process is put under the restricted namespaces above: the backup process can only write to a limited number of paths. + However, a side effect of this is that the <command>fdbbackup</command> + command doesn't work properly for local filesystem backups: FoundationDB + uses a server process alongside the database processes to perform backups + and copy the backups to the filesystem. As a result, this process is put + under the restricted namespaces above: the backup process can only write to + a limited number of paths. </para> <para> - In order to allow flexible backup locations on local disks, the FoundationDB NixOS module supports a <option>services.foundationdb.extraReadWritePaths</option> option. This option takes a list of paths, and adds them to the systemd unit, allowing the processes inside the service to write (and read) the specified directories. + In order to allow flexible backup locations on local disks, the FoundationDB + NixOS module supports a + <option>services.foundationdb.extraReadWritePaths</option> option. This + option takes a list of paths, and adds them to the systemd unit, allowing + the processes inside the service to write (and read) the specified + directories. </para> <para> - For example, to create backups in <command>/opt/fdb-backups</command>, first set up the paths in the module options: + For example, to create backups in <command>/opt/fdb-backups</command>, first + set up the paths in the module options: </para> <programlisting> @@ -270,7 +375,11 @@ services.foundationdb.extraReadWritePaths = [ "/opt/fdb-backups" ]; </programlisting> <para> - Restart the FoundationDB service, and it will now be able to write to this directory (even if it does not yet exist.) Note: this path <emphasis>must</emphasis> exist before restarting the unit. Otherwise, systemd will not include it in the private FoundationDB namespace (and it will not add it dynamically at runtime). + Restart the FoundationDB service, and it will now be able to write to this + directory (even if it does not yet exist.) Note: this path + <emphasis>must</emphasis> exist before restarting the unit. Otherwise, + systemd will not include it in the private FoundationDB namespace (and it + will not add it dynamically at runtime). </para> <para> @@ -286,13 +395,17 @@ services.foundationdb.extraReadWritePaths = [ "/opt/fdb-backups" ]; <title>Known limitations</title> <para> - The FoundationDB setup for NixOS should currently be considered beta. FoundationDB is not new software, but the NixOS compilation and integration has only undergone fairly basic testing of all the available functionality. + The FoundationDB setup for NixOS should currently be considered beta. + FoundationDB is not new software, but the NixOS compilation and integration + has only undergone fairly basic testing of all the available functionality. </para> <itemizedlist> <listitem> <para> - There is no way to specify individual parameters for individual <command>fdbserver</command> processes. Currently, all server processes inherit all the global <command>fdbmonitor</command> settings. + There is no way to specify individual parameters for individual + <command>fdbserver</command> processes. Currently, all server processes + inherit all the global <command>fdbmonitor</command> settings. </para> </listitem> <listitem> @@ -311,14 +424,20 @@ services.foundationdb.extraReadWritePaths = [ "/opt/fdb-backups" ]; <title>Options</title> <para> - NixOS's FoundationDB module allows you to configure all of the most relevant configuration options for <command>fdbmonitor</command>, matching it quite closely. A complete list of options for the FoundationDB module may be found <link linkend="opt-services.foundationdb.enable">here</link>. You should also read the FoundationDB documentation as well. + NixOS's FoundationDB module allows you to configure all of the most relevant + configuration options for <command>fdbmonitor</command>, matching it quite + closely. A complete list of options for the FoundationDB module may be found + <link linkend="opt-services.foundationdb.enable">here</link>. You should + also read the FoundationDB documentation as well. </para> </section> <section xml:id="module-services-foundationdb-full-docs"> <title>Full documentation</title> <para> - FoundationDB is a complex piece of software, and requires careful administration to properly use. Full documentation for administration can be found here: <link xlink:href="https://apple.github.io/foundationdb/"/>. + FoundationDB is a complex piece of software, and requires careful + administration to properly use. Full documentation for administration can be + found here: <link xlink:href="https://apple.github.io/foundationdb/"/>. </para> </section> </chapter> diff --git a/nixos/modules/services/databases/postgresql.xml b/nixos/modules/services/databases/postgresql.xml index dc1bfb125a7..72d4a8249a3 100644 --- a/nixos/modules/services/databases/postgresql.xml +++ b/nixos/modules/services/databases/postgresql.xml @@ -7,10 +7,12 @@ <!-- FIXME: render nicely --> <!-- FIXME: source can be added automatically --> <para> - <emphasis>Source:</emphasis> <filename>modules/services/databases/postgresql.nix</filename> + <emphasis>Source:</emphasis> + <filename>modules/services/databases/postgresql.nix</filename> </para> <para> - <emphasis>Upstream documentation:</emphasis> <link xlink:href="http://www.postgresql.org/docs/"/> + <emphasis>Upstream documentation:</emphasis> + <link xlink:href="http://www.postgresql.org/docs/"/> </para> <!-- FIXME: more stuff, like maintainer? --> <para> @@ -21,12 +23,18 @@ <title>Configuring</title> <para> - To enable PostgreSQL, add the following to your <filename>configuration.nix</filename>: + To enable PostgreSQL, add the following to your + <filename>configuration.nix</filename>: <programlisting> <xref linkend="opt-services.postgresql.enable"/> = true; <xref linkend="opt-services.postgresql.package"/> = pkgs.postgresql_11; </programlisting> - Note that you are required to specify the desired version of PostgreSQL (e.g. <literal>pkgs.postgresql_11</literal>). Since upgrading your PostgreSQL version requires a database dump and reload (see below), NixOS cannot provide a default value for <xref linkend="opt-services.postgresql.package"/> such as the most recent release of PostgreSQL. + Note that you are required to specify the desired version of PostgreSQL + (e.g. <literal>pkgs.postgresql_11</literal>). Since upgrading your + PostgreSQL version requires a database dump and reload (see below), NixOS + cannot provide a default value for + <xref linkend="opt-services.postgresql.package"/> such as the most recent + release of PostgreSQL. </para> <!-- @@ -43,7 +51,9 @@ Type "help" for help. --> <para> - By default, PostgreSQL stores its databases in <filename>/var/lib/postgresql/$psqlSchema</filename>. You can override this using <xref linkend="opt-services.postgresql.dataDir"/>, e.g. + By default, PostgreSQL stores its databases in + <filename>/var/lib/postgresql/$psqlSchema</filename>. You can override this using + <xref linkend="opt-services.postgresql.dataDir"/>, e.g. <programlisting> <xref linkend="opt-services.postgresql.dataDir"/> = "/data/postgresql"; </programlisting> @@ -60,14 +70,18 @@ Type "help" for help. <title>Options</title> <para> - A complete list of options for the PostgreSQL module may be found <link linkend="opt-services.postgresql.enable">here</link>. + A complete list of options for the PostgreSQL module may be found + <link linkend="opt-services.postgresql.enable">here</link>. </para> </section> <section xml:id="module-services-postgres-plugins"> <title>Plugins</title> <para> - Plugins collection for each PostgreSQL version can be accessed with <literal>.pkgs</literal>. For example, for <literal>pkgs.postgresql_11</literal> package, its plugin collection is accessed by <literal>pkgs.postgresql_11.pkgs</literal>: + Plugins collection for each PostgreSQL version can be accessed with + <literal>.pkgs</literal>. For example, for + <literal>pkgs.postgresql_11</literal> package, its plugin collection is + accessed by <literal>pkgs.postgresql_11.pkgs</literal>: <screen> <prompt>$ </prompt>nix repl '<nixpkgs>' @@ -84,9 +98,8 @@ postgresql_11.pkgs.pg_partman postgresql_11.pkgs.pgroonga ... </screen> </para> - <para> - To add plugins via NixOS configuration, set <literal>services.postgresql.extraPlugins</literal>: + To add plugins via NixOS configuration, set <literal>services.postgresql.extraPlugins</literal>: <programlisting> <xref linkend="opt-services.postgresql.package"/> = pkgs.postgresql_11; <xref linkend="opt-services.postgresql.extraPlugins"/> = with pkgs.postgresql_11.pkgs; [ @@ -95,9 +108,10 @@ postgresql_11.pkgs.pg_partman postgresql_11.pkgs.pgroonga ]; </programlisting> </para> - <para> - You can build custom PostgreSQL-with-plugins (to be used outside of NixOS) using function <literal>.withPackages</literal>. For example, creating a custom PostgreSQL package in an overlay can look like: + You can build custom PostgreSQL-with-plugins (to be used outside of NixOS) using + function <literal>.withPackages</literal>. For example, creating a custom + PostgreSQL package in an overlay can look like: <programlisting> self: super: { postgresql_custom = self.postgresql_11.withPackages (ps: [ @@ -107,9 +121,8 @@ self: super: { } </programlisting> </para> - <para> - Here's a recipe on how to override a particular plugin through an overlay: + Here's a recipe on how to override a particular plugin through an overlay: <programlisting> self: super: { postgresql_11 = super.postgresql_11.override { this = self.postgresql_11; } // { diff --git a/nixos/modules/services/desktops/flatpak.xml b/nixos/modules/services/desktops/flatpak.xml index 3b2ccd12cf5..8f080b25022 100644 --- a/nixos/modules/services/desktops/flatpak.xml +++ b/nixos/modules/services/desktops/flatpak.xml @@ -5,33 +5,44 @@ xml:id="module-services-flatpak"> <title>Flatpak</title> <para> - <emphasis>Source:</emphasis> <filename>modules/services/desktop/flatpak.nix</filename> + <emphasis>Source:</emphasis> + <filename>modules/services/desktop/flatpak.nix</filename> </para> <para> - <emphasis>Upstream documentation:</emphasis> <link xlink:href="https://github.com/flatpak/flatpak/wiki"/> + <emphasis>Upstream documentation:</emphasis> + <link xlink:href="https://github.com/flatpak/flatpak/wiki"/> </para> <para> - Flatpak is a system for building, distributing, and running sandboxed desktop applications on Linux. + Flatpak is a system for building, distributing, and running sandboxed desktop + applications on Linux. </para> <para> - To enable Flatpak, add the following to your <filename>configuration.nix</filename>: + To enable Flatpak, add the following to your + <filename>configuration.nix</filename>: <programlisting> <xref linkend="opt-services.flatpak.enable"/> = true; </programlisting> </para> <para> - For the sandboxed apps to work correctly, desktop integration portals need to be installed. If you run GNOME, this will be handled automatically for you; in other cases, you will need to add something like the following to your <filename>configuration.nix</filename>: + For the sandboxed apps to work correctly, desktop integration portals need to + be installed. If you run GNOME, this will be handled automatically for you; + in other cases, you will need to add something like the following to your + <filename>configuration.nix</filename>: <programlisting> <xref linkend="opt-xdg.portal.extraPortals"/> = [ pkgs.xdg-desktop-portal-gtk ]; </programlisting> </para> <para> - Then, you will need to add a repository, for example, <link xlink:href="https://github.com/flatpak/flatpak/wiki">Flathub</link>, either using the following commands: + Then, you will need to add a repository, for example, + <link xlink:href="https://github.com/flatpak/flatpak/wiki">Flathub</link>, + either using the following commands: <screen> <prompt>$ </prompt>flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo <prompt>$ </prompt>flatpak update </screen> - or by opening the <link xlink:href="https://flathub.org/repo/flathub.flatpakrepo">repository file</link> in GNOME Software. + or by opening the + <link xlink:href="https://flathub.org/repo/flathub.flatpakrepo">repository + file</link> in GNOME Software. </para> <para> Finally, you can search and install programs: diff --git a/nixos/modules/services/editors/emacs.xml b/nixos/modules/services/editors/emacs.xml index 0213b8971c2..03483f69fa2 100644 --- a/nixos/modules/services/editors/emacs.xml +++ b/nixos/modules/services/editors/emacs.xml @@ -12,26 +12,41 @@ Adam Hoese @adisbladis --> <para> - <link xlink:href="https://www.gnu.org/software/emacs/">Emacs</link> is an extensible, customizable, self-documenting real-time display editor — and more. At its core is an interpreter for Emacs Lisp, a dialect of the Lisp programming language with extensions to support text editing. + <link xlink:href="https://www.gnu.org/software/emacs/">Emacs</link> is an + extensible, customizable, self-documenting real-time display editor — and + more. At its core is an interpreter for Emacs Lisp, a dialect of the Lisp + programming language with extensions to support text editing. </para> <para> - Emacs runs within a graphical desktop environment using the X Window System, but works equally well on a text terminal. Under <productname>macOS</productname>, a "Mac port" edition is available, which uses Apple's native GUI frameworks. + Emacs runs within a graphical desktop environment using the X Window System, + but works equally well on a text terminal. Under + <productname>macOS</productname>, a "Mac port" edition is available, which + uses Apple's native GUI frameworks. </para> <para> - <productname>Nixpkgs</productname> provides a superior environment for running <application>Emacs</application>. It's simple to create custom builds by overriding the default packages. Chaotic collections of Emacs Lisp code and extensions can be brought under control using declarative package management. <productname>NixOS</productname> even provides a <command>systemd</command> user service for automatically starting the Emacs daemon. + <productname>Nixpkgs</productname> provides a superior environment for + running <application>Emacs</application>. It's simple to create custom builds + by overriding the default packages. Chaotic collections of Emacs Lisp code + and extensions can be brought under control using declarative package + management. <productname>NixOS</productname> even provides a + <command>systemd</command> user service for automatically starting the Emacs + daemon. </para> <section xml:id="module-services-emacs-installing"> <title>Installing <application>Emacs</application></title> <para> - Emacs can be installed in the normal way for Nix (see <xref linkend="sec-package-management" />). In addition, a NixOS <emphasis>service</emphasis> can be enabled. + Emacs can be installed in the normal way for Nix (see + <xref linkend="sec-package-management" />). In addition, a NixOS + <emphasis>service</emphasis> can be enabled. </para> <section xml:id="module-services-emacs-releases"> <title>The Different Releases of Emacs</title> <para> - <productname>Nixpkgs</productname> defines several basic Emacs packages. The following are attributes belonging to the <varname>pkgs</varname> set: + <productname>Nixpkgs</productname> defines several basic Emacs packages. + The following are attributes belonging to the <varname>pkgs</varname> set: <variablelist> <varlistentry> <term> @@ -42,8 +57,10 @@ </term> <listitem> <para> - The latest stable version of Emacs 25 using the <link - xlink:href="http://www.gtk.org">GTK 2</link> widget toolkit. + The latest stable version of Emacs 25 using the + <link + xlink:href="http://www.gtk.org">GTK 2</link> + widget toolkit. </para> </listitem> </varlistentry> @@ -66,7 +83,8 @@ </term> <listitem> <para> - Emacs 25 with the "Mac port" patches, providing a more native look and feel under macOS. + Emacs 25 with the "Mac port" patches, providing a more native look and + feel under macOS. </para> </listitem> </varlistentry> @@ -74,7 +92,12 @@ </para> <para> - If those aren't suitable, then the following imitation Emacs editors are also available in Nixpkgs: <link xlink:href="https://www.gnu.org/software/zile/">Zile</link>, <link xlink:href="http://homepage.boetes.org/software/mg/">mg</link>, <link xlink:href="http://yi-editor.github.io/">Yi</link>, <link xlink:href="https://joe-editor.sourceforge.io/">jmacs</link>. + If those aren't suitable, then the following imitation Emacs editors are + also available in Nixpkgs: + <link xlink:href="https://www.gnu.org/software/zile/">Zile</link>, + <link xlink:href="http://homepage.boetes.org/software/mg/">mg</link>, + <link xlink:href="http://yi-editor.github.io/">Yi</link>, + <link xlink:href="https://joe-editor.sourceforge.io/">jmacs</link>. </para> </section> @@ -82,20 +105,36 @@ <title>Adding Packages to Emacs</title> <para> - Emacs includes an entire ecosystem of functionality beyond text editing, including a project planner, mail and news reader, debugger interface, calendar, and more. + Emacs includes an entire ecosystem of functionality beyond text editing, + including a project planner, mail and news reader, debugger interface, + calendar, and more. </para> <para> - Most extensions are gotten with the Emacs packaging system (<filename>package.el</filename>) from <link - xlink:href="https://elpa.gnu.org/">Emacs Lisp Package Archive (<acronym>ELPA</acronym>)</link>, <link xlink:href="https://melpa.org/"><acronym>MELPA</acronym></link>, <link xlink:href="https://stable.melpa.org/">MELPA Stable</link>, and <link xlink:href="http://orgmode.org/elpa.html">Org ELPA</link>. Nixpkgs is regularly updated to mirror all these archives. + Most extensions are gotten with the Emacs packaging system + (<filename>package.el</filename>) from + <link + xlink:href="https://elpa.gnu.org/">Emacs Lisp Package Archive + (<acronym>ELPA</acronym>)</link>, + <link xlink:href="https://melpa.org/"><acronym>MELPA</acronym></link>, + <link xlink:href="https://stable.melpa.org/">MELPA Stable</link>, and + <link xlink:href="http://orgmode.org/elpa.html">Org ELPA</link>. Nixpkgs is + regularly updated to mirror all these archives. </para> <para> - Under NixOS, you can continue to use <function>package-list-packages</function> and <function>package-install</function> to install packages. You can also declare the set of Emacs packages you need using the derivations from Nixpkgs. The rest of this section discusses declarative installation of Emacs packages through nixpkgs. + Under NixOS, you can continue to use + <function>package-list-packages</function> and + <function>package-install</function> to install packages. You can also + declare the set of Emacs packages you need using the derivations from + Nixpkgs. The rest of this section discusses declarative installation of + Emacs packages through nixpkgs. </para> <para> - The first step to declare the list of packages you want in your Emacs installation is to create a dedicated derivation. This can be done in a dedicated <filename>emacs.nix</filename> file such as: + The first step to declare the list of packages you want in your Emacs + installation is to create a dedicated derivation. This can be done in a + dedicated <filename>emacs.nix</filename> file such as: <example xml:id="ex-emacsNix"> <title>Nix expression to build Emacs with packages (<filename>emacs.nix</filename>)</title> <programlisting language="nix"> @@ -137,27 +176,36 @@ in <calloutlist> <callout arearefs="ex-emacsNix-1"> <para> - The first non-comment line in this file (<literal>{ pkgs ? ... }</literal>) indicates that the whole file represents a function. + The first non-comment line in this file (<literal>{ pkgs ? ... + }</literal>) indicates that the whole file represents a function. </para> </callout> <callout arearefs="ex-emacsNix-2"> <para> - The <varname>let</varname> expression below defines a <varname>myEmacs</varname> binding pointing to the current stable version of Emacs. This binding is here to separate the choice of the Emacs binary from the specification of the required packages. + The <varname>let</varname> expression below defines a + <varname>myEmacs</varname> binding pointing to the current stable + version of Emacs. This binding is here to separate the choice of the + Emacs binary from the specification of the required packages. </para> </callout> <callout arearefs="ex-emacsNix-3"> <para> - This generates an <varname>emacsWithPackages</varname> function. It takes a single argument: a function from a package set to a list of packages (the packages that will be available in Emacs). + This generates an <varname>emacsWithPackages</varname> function. It + takes a single argument: a function from a package set to a list of + packages (the packages that will be available in Emacs). </para> </callout> <callout arearefs="ex-emacsNix-4"> <para> - The rest of the file specifies the list of packages to install. In the example, two packages (<varname>magit</varname> and <varname>zerodark-theme</varname>) are taken from MELPA stable. + The rest of the file specifies the list of packages to install. In the + example, two packages (<varname>magit</varname> and + <varname>zerodark-theme</varname>) are taken from MELPA stable. </para> </callout> <callout arearefs="ex-emacsNix-5"> <para> - Two packages (<varname>undo-tree</varname> and <varname>zoom-frm</varname>) are taken from MELPA. + Two packages (<varname>undo-tree</varname> and + <varname>zoom-frm</varname>) are taken from MELPA. </para> </callout> <callout arearefs="ex-emacsNix-6"> @@ -167,14 +215,17 @@ in </callout> <callout arearefs="ex-emacsNix-7"> <para> - <varname>notmuch</varname> is taken from a nixpkgs derivation which contains an Emacs mode. + <varname>notmuch</varname> is taken from a nixpkgs derivation which + contains an Emacs mode. </para> </callout> </calloutlist> </para> <para> - The result of this configuration will be an <command>emacs</command> command which launches Emacs with all of your chosen packages in the <varname>load-path</varname>. + The result of this configuration will be an <command>emacs</command> + command which launches Emacs with all of your chosen packages in the + <varname>load-path</varname>. </para> <para> @@ -183,17 +234,23 @@ in <prompt>$ </prompt>nix-build emacs.nix <prompt>$ </prompt>./result/bin/emacs -q </screen> - and then typing <literal>M-x package-initialize</literal>. Check that you can use all the packages you want in this Emacs instance. For example, try switching to the zerodark theme through <literal>M-x load-theme <RET> zerodark <RET> y</literal>. + and then typing <literal>M-x package-initialize</literal>. Check that you + can use all the packages you want in this Emacs instance. For example, try + switching to the zerodark theme through <literal>M-x load-theme <RET> + zerodark <RET> y</literal>. </para> <tip> <para> - A few popular extensions worth checking out are: auctex, company, edit-server, flycheck, helm, iedit, magit, multiple-cursors, projectile, and yasnippet. + A few popular extensions worth checking out are: auctex, company, + edit-server, flycheck, helm, iedit, magit, multiple-cursors, projectile, + and yasnippet. </para> </tip> <para> - The list of available packages in the various ELPA repositories can be seen with the following commands: + The list of available packages in the various ELPA repositories can be seen + with the following commands: <example xml:id="module-services-emacs-querying-packages"> <title>Querying Emacs packages</title> <programlisting><![CDATA[ @@ -206,7 +263,10 @@ nix-env -f "<nixpkgs>" -qaP -A emacsPackages.orgPackages </para> <para> - If you are on NixOS, you can install this particular Emacs for all users by adding it to the list of system packages (see <xref linkend="sec-declarative-package-mgmt" />). Simply modify your file <filename>configuration.nix</filename> to make it contain: + If you are on NixOS, you can install this particular Emacs for all users by + adding it to the list of system packages (see + <xref linkend="sec-declarative-package-mgmt" />). Simply modify your file + <filename>configuration.nix</filename> to make it contain: <example xml:id="module-services-emacs-configuration-nix"> <title>Custom Emacs in <filename>configuration.nix</filename></title> <programlisting><![CDATA[ @@ -221,7 +281,9 @@ nix-env -f "<nixpkgs>" -qaP -A emacsPackages.orgPackages </para> <para> - In this case, the next <command>nixos-rebuild switch</command> will take care of adding your <command>emacs</command> to the <varname>PATH</varname> environment variable (see <xref linkend="sec-changing-config" />). + In this case, the next <command>nixos-rebuild switch</command> will take + care of adding your <command>emacs</command> to the <varname>PATH</varname> + environment variable (see <xref linkend="sec-changing-config" />). </para> <!-- fixme: i think the following is better done with config.nix @@ -229,7 +291,11 @@ https://nixos.org/nixpkgs/manual/#sec-modify-via-packageOverrides --> <para> - If you are not on NixOS or want to install this particular Emacs only for yourself, you can do so by adding it to your <filename>~/.config/nixpkgs/config.nix</filename> (see <link xlink:href="http://nixos.org/nixpkgs/manual/#sec-modify-via-packageOverrides">Nixpkgs manual</link>): + If you are not on NixOS or want to install this particular Emacs only for + yourself, you can do so by adding it to your + <filename>~/.config/nixpkgs/config.nix</filename> (see + <link xlink:href="http://nixos.org/nixpkgs/manual/#sec-modify-via-packageOverrides">Nixpkgs + manual</link>): <example xml:id="module-services-emacs-config-nix"> <title>Custom Emacs in <filename>~/.config/nixpkgs/config.nix</filename></title> <programlisting><![CDATA[ @@ -243,7 +309,9 @@ https://nixos.org/nixpkgs/manual/#sec-modify-via-packageOverrides </para> <para> - In this case, the next <literal>nix-env -f '<nixpkgs>' -iA myemacs</literal> will take care of adding your emacs to the <varname>PATH</varname> environment variable. + In this case, the next <literal>nix-env -f '<nixpkgs>' -iA + myemacs</literal> will take care of adding your emacs to the + <varname>PATH</varname> environment variable. </para> </section> @@ -251,7 +319,12 @@ https://nixos.org/nixpkgs/manual/#sec-modify-via-packageOverrides <title>Advanced Emacs Configuration</title> <para> - If you want, you can tweak the Emacs package itself from your <filename>emacs.nix</filename>. For example, if you want to have a GTK 3-based Emacs instead of the default GTK 2-based binary and remove the automatically generated <filename>emacs.desktop</filename> (useful is you only use <command>emacsclient</command>), you can change your file <filename>emacs.nix</filename> in this way: + If you want, you can tweak the Emacs package itself from your + <filename>emacs.nix</filename>. For example, if you want to have a + GTK 3-based Emacs instead of the default GTK 2-based binary and remove the + automatically generated <filename>emacs.desktop</filename> (useful is you + only use <command>emacsclient</command>), you can change your file + <filename>emacs.nix</filename> in this way: </para> <example xml:id="ex-emacsGtk3Nix"> @@ -275,7 +348,8 @@ in [...] </example> <para> - After building this file as shown in <xref linkend="ex-emacsNix" />, you will get an GTK 3-based Emacs binary pre-loaded with your favorite packages. + After building this file as shown in <xref linkend="ex-emacsNix" />, you + will get an GTK 3-based Emacs binary pre-loaded with your favorite packages. </para> </section> </section> @@ -283,18 +357,23 @@ in [...] <title>Running Emacs as a Service</title> <para> - <productname>NixOS</productname> provides an optional <command>systemd</command> service which launches <link xlink:href="https://www.gnu.org/software/emacs/manual/html_node/emacs/Emacs-Server.html"> Emacs daemon </link> with the user's login session. + <productname>NixOS</productname> provides an optional + <command>systemd</command> service which launches + <link xlink:href="https://www.gnu.org/software/emacs/manual/html_node/emacs/Emacs-Server.html"> + Emacs daemon </link> with the user's login session. </para> <para> - <emphasis>Source:</emphasis> <filename>modules/services/editors/emacs.nix</filename> + <emphasis>Source:</emphasis> + <filename>modules/services/editors/emacs.nix</filename> </para> <section xml:id="module-services-emacs-enabling"> <title>Enabling the Service</title> <para> - To install and enable the <command>systemd</command> user service for Emacs daemon, add the following to your <filename>configuration.nix</filename>: + To install and enable the <command>systemd</command> user service for Emacs + daemon, add the following to your <filename>configuration.nix</filename>: <programlisting> <xref linkend="opt-services.emacs.enable"/> = true; <xref linkend="opt-services.emacs.package"/> = import /home/cassou/.emacs.d { pkgs = pkgs; }; @@ -302,11 +381,16 @@ in [...] </para> <para> - The <varname>services.emacs.package</varname> option allows a custom derivation to be used, for example, one created by <function>emacsWithPackages</function>. + The <varname>services.emacs.package</varname> option allows a custom + derivation to be used, for example, one created by + <function>emacsWithPackages</function>. </para> <para> - Ensure that the Emacs server is enabled for your user's Emacs configuration, either by customizing the <varname>server-mode</varname> variable, or by adding <literal>(server-start)</literal> to <filename>~/.emacs.d/init.el</filename>. + Ensure that the Emacs server is enabled for your user's Emacs + configuration, either by customizing the <varname>server-mode</varname> + variable, or by adding <literal>(server-start)</literal> to + <filename>~/.emacs.d/init.el</filename>. </para> <para> @@ -324,7 +408,9 @@ in [...] <title>Starting the client</title> <para> - Ensure that the emacs server is enabled, either by customizing the <varname>server-mode</varname> variable, or by adding <literal>(server-start)</literal> to <filename>~/.emacs</filename>. + Ensure that the emacs server is enabled, either by customizing the + <varname>server-mode</varname> variable, or by adding + <literal>(server-start)</literal> to <filename>~/.emacs</filename>. </para> <para> @@ -343,15 +429,23 @@ emacsclient --create-frame --tty # opens a new frame on the current terminal <!--<title><command>emacsclient</command> as the Default Editor</title>--> <para> - If <xref linkend="opt-services.emacs.defaultEditor"/> is <literal>true</literal>, the <varname>EDITOR</varname> variable will be set to a wrapper script which launches <command>emacsclient</command>. + If <xref linkend="opt-services.emacs.defaultEditor"/> is + <literal>true</literal>, the <varname>EDITOR</varname> variable will be set + to a wrapper script which launches <command>emacsclient</command>. </para> <para> - Any setting of <varname>EDITOR</varname> in the shell config files will override <varname>services.emacs.defaultEditor</varname>. To make sure <varname>EDITOR</varname> refers to the Emacs wrapper script, remove any existing <varname>EDITOR</varname> assignment from <filename>.profile</filename>, <filename>.bashrc</filename>, <filename>.zshenv</filename> or any other shell config file. + Any setting of <varname>EDITOR</varname> in the shell config files will + override <varname>services.emacs.defaultEditor</varname>. To make sure + <varname>EDITOR</varname> refers to the Emacs wrapper script, remove any + existing <varname>EDITOR</varname> assignment from + <filename>.profile</filename>, <filename>.bashrc</filename>, + <filename>.zshenv</filename> or any other shell config file. </para> <para> - If you have formed certain bad habits when editing files, these can be corrected with a shell alias to the wrapper script: + If you have formed certain bad habits when editing files, these can be + corrected with a shell alias to the wrapper script: <programlisting>alias vi=$EDITOR</programlisting> </para> </section> @@ -360,7 +454,10 @@ emacsclient --create-frame --tty # opens a new frame on the current terminal <title>Per-User Enabling of the Service</title> <para> - In general, <command>systemd</command> user services are globally enabled by symlinks in <filename>/etc/systemd/user</filename>. In the case where Emacs daemon is not wanted for all users, it is possible to install the service but not globally enable it: + In general, <command>systemd</command> user services are globally enabled + by symlinks in <filename>/etc/systemd/user</filename>. In the case where + Emacs daemon is not wanted for all users, it is possible to install the + service but not globally enable it: <programlisting> <xref linkend="opt-services.emacs.enable"/> = false; <xref linkend="opt-services.emacs.install"/> = true; @@ -368,9 +465,11 @@ emacsclient --create-frame --tty # opens a new frame on the current terminal </para> <para> - To enable the <command>systemd</command> user service for just the currently logged in user, run: + To enable the <command>systemd</command> user service for just the + currently logged in user, run: <programlisting>systemctl --user enable emacs</programlisting> - This will add the symlink <filename>~/.config/systemd/user/emacs.service</filename>. + This will add the symlink + <filename>~/.config/systemd/user/emacs.service</filename>. </para> </section> </section> @@ -378,7 +477,8 @@ emacsclient --create-frame --tty # opens a new frame on the current terminal <title>Configuring Emacs</title> <para> - The Emacs init file should be changed to load the extension packages at startup: + The Emacs init file should be changed to load the extension packages at + startup: <example xml:id="module-services-emacs-package-initialisation"> <title>Package initialization in <filename>.emacs</filename></title> <programlisting><![CDATA[ @@ -394,7 +494,10 @@ emacsclient --create-frame --tty # opens a new frame on the current terminal </para> <para> - After the declarative emacs package configuration has been tested, previously downloaded packages can be cleaned up by removing <filename>~/.emacs.d/elpa</filename> (do make a backup first, in case you forgot a package). + After the declarative emacs package configuration has been tested, + previously downloaded packages can be cleaned up by removing + <filename>~/.emacs.d/elpa</filename> (do make a backup first, in case you + forgot a package). </para> <!-- @@ -406,7 +509,9 @@ emacsclient --create-frame --tty # opens a new frame on the current terminal <title>A Major Mode for Nix Expressions</title> <para> - Of interest may be <varname>melpaPackages.nix-mode</varname>, which provides syntax highlighting for the Nix language. This is particularly convenient if you regularly edit Nix files. + Of interest may be <varname>melpaPackages.nix-mode</varname>, which + provides syntax highlighting for the Nix language. This is particularly + convenient if you regularly edit Nix files. </para> </section> @@ -414,7 +519,9 @@ emacsclient --create-frame --tty # opens a new frame on the current terminal <title>Accessing man pages</title> <para> - You can use <function>woman</function> to get completion of all available man pages. For example, type <literal>M-x woman <RET> nixos-rebuild <RET>.</literal> + You can use <function>woman</function> to get completion of all available + man pages. For example, type <literal>M-x woman <RET> nixos-rebuild + <RET>.</literal> </para> </section> @@ -422,17 +529,29 @@ emacsclient --create-frame --tty # opens a new frame on the current terminal <title>Editing DocBook 5 XML Documents</title> <para> - Emacs includes <link - xlink:href="https://www.gnu.org/software/emacs/manual/html_node/nxml-mode/Introduction.html">nXML</link>, a major-mode for validating and editing XML documents. When editing DocBook 5.0 documents, such as <link linkend="book-nixos-manual">this one</link>, nXML needs to be configured with the relevant schema, which is not included. + Emacs includes + <link + xlink:href="https://www.gnu.org/software/emacs/manual/html_node/nxml-mode/Introduction.html">nXML</link>, + a major-mode for validating and editing XML documents. When editing DocBook + 5.0 documents, such as <link linkend="book-nixos-manual">this one</link>, + nXML needs to be configured with the relevant schema, which is not + included. </para> <para> - To install the DocBook 5.0 schemas, either add <varname>pkgs.docbook5</varname> to <xref linkend="opt-environment.systemPackages"/> (<link - linkend="sec-declarative-package-mgmt">NixOS</link>), or run <literal>nix-env -f '<nixpkgs>' -iA docbook5</literal> (<link linkend="sec-ad-hoc-packages">Nix</link>). + To install the DocBook 5.0 schemas, either add + <varname>pkgs.docbook5</varname> to + <xref linkend="opt-environment.systemPackages"/> + (<link + linkend="sec-declarative-package-mgmt">NixOS</link>), or run + <literal>nix-env -f '<nixpkgs>' -iA docbook5</literal> + (<link linkend="sec-ad-hoc-packages">Nix</link>). </para> <para> - Then customize the variable <varname>rng-schema-locating-files</varname> to include <filename>~/.emacs.d/schemas.xml</filename> and put the following text into that file: + Then customize the variable <varname>rng-schema-locating-files</varname> to + include <filename>~/.emacs.d/schemas.xml</filename> and put the following + text into that file: <example xml:id="ex-emacs-docbook-xml"> <title>nXML Schema Configuration (<filename>~/.emacs.d/schemas.xml</filename>)</title> <programlisting language="xml"><![CDATA[ diff --git a/nixos/modules/services/hardware/trezord.xml b/nixos/modules/services/hardware/trezord.xml index 4af6e1ad7cc..972d409d9d0 100644 --- a/nixos/modules/services/hardware/trezord.xml +++ b/nixos/modules/services/hardware/trezord.xml @@ -5,10 +5,16 @@ xml:id="trezor"> <title>Trezor</title> <para> - Trezor is an open-source cryptocurrency hardware wallet and security token allowing secure storage of private keys. + Trezor is an open-source cryptocurrency hardware wallet and security token + allowing secure storage of private keys. </para> <para> - It offers advanced features such U2F two-factor authorization, SSH login through <link xlink:href="https://wiki.trezor.io/Apps:SSH_agent">Trezor SSH agent</link>, <link xlink:href="https://wiki.trezor.io/GPG">GPG</link> and a <link xlink:href="https://wiki.trezor.io/Trezor_Password_Manager">password manager</link>. For more information, guides and documentation, see <link xlink:href="https://wiki.trezor.io"/>. + It offers advanced features such U2F two-factor authorization, SSH login + through + <link xlink:href="https://wiki.trezor.io/Apps:SSH_agent">Trezor SSH agent</link>, + <link xlink:href="https://wiki.trezor.io/GPG">GPG</link> and a + <link xlink:href="https://wiki.trezor.io/Trezor_Password_Manager">password manager</link>. + For more information, guides and documentation, see <link xlink:href="https://wiki.trezor.io"/>. </para> <para> To enable Trezor support, add the following to your <filename>configuration.nix</filename>: diff --git a/nixos/modules/services/misc/gitlab.xml b/nixos/modules/services/misc/gitlab.xml index a59f8919a47..b6171a9a194 100644 --- a/nixos/modules/services/misc/gitlab.xml +++ b/nixos/modules/services/misc/gitlab.xml @@ -11,11 +11,14 @@ <title>Prerequisites</title> <para> - The gitlab service exposes only an Unix socket at <literal>/run/gitlab/gitlab-workhorse.socket</literal>. You need to configure a webserver to proxy HTTP requests to the socket. + The gitlab service exposes only an Unix socket at + <literal>/run/gitlab/gitlab-workhorse.socket</literal>. You need to + configure a webserver to proxy HTTP requests to the socket. </para> <para> - For instance, the following configuration could be used to use nginx as frontend proxy: + For instance, the following configuration could be used to use nginx as + frontend proxy: <programlisting> <link linkend="opt-services.nginx.enable">services.nginx</link> = { <link linkend="opt-services.nginx.enable">enable</link> = true; @@ -36,11 +39,14 @@ <title>Configuring</title> <para> - Gitlab depends on both PostgreSQL and Redis and will automatically enable both services. In the case of PostgreSQL, a database and a role will be created. + Gitlab depends on both PostgreSQL and Redis and will automatically enable + both services. In the case of PostgreSQL, a database and a role will be + created. </para> <para> - The default state dir is <literal>/var/gitlab/state</literal>. This is where all data like the repositories and uploads will be stored. + The default state dir is <literal>/var/gitlab/state</literal>. This is where + all data like the repositories and uploads will be stored. </para> <para> @@ -79,19 +85,31 @@ services.gitlab = { </para> <para> - If you're setting up a new Gitlab instance, generate new secrets. You for instance use <literal>tr -dc A-Za-z0-9 < /dev/urandom | head -c 128 > /var/keys/gitlab/db</literal> to generate a new db secret. Make sure the files can be read by, and only by, the user specified by <link - linkend="opt-services.gitlab.user">services.gitlab.user</link>. Gitlab encrypts sensitive data stored in the database. If you're restoring an existing Gitlab instance, you must specify the secrets secret from <literal>config/secrets.yml</literal> located in your Gitlab state folder. + If you're setting up a new Gitlab instance, generate new + secrets. You for instance use <literal>tr -dc A-Za-z0-9 < + /dev/urandom | head -c 128 > /var/keys/gitlab/db</literal> to + generate a new db secret. Make sure the files can be read by, and + only by, the user specified by <link + linkend="opt-services.gitlab.user">services.gitlab.user</link>. Gitlab + encrypts sensitive data stored in the database. If you're restoring + an existing Gitlab instance, you must specify the secrets secret + from <literal>config/secrets.yml</literal> located in your Gitlab + state folder. </para> <para> - Refer to <xref linkend="ch-options" /> for all available configuration options for the <link linkend="opt-services.gitlab.enable">services.gitlab</link> module. + Refer to <xref linkend="ch-options" /> for all available configuration + options for the + <link linkend="opt-services.gitlab.enable">services.gitlab</link> module. </para> </section> <section xml:id="module-services-gitlab-maintenance"> <title>Maintenance</title> <para> - You can run Gitlab's rake tasks with <literal>gitlab-rake</literal> which will be available on the system when gitlab is enabled. You will have to run the command as the user that you configured to run gitlab with. + You can run Gitlab's rake tasks with <literal>gitlab-rake</literal> which + will be available on the system when gitlab is enabled. You will have to run + the command as the user that you configured to run gitlab with. </para> <para> diff --git a/nixos/modules/services/misc/taskserver/doc.xml b/nixos/modules/services/misc/taskserver/doc.xml index 902ed14940e..5656bb85b37 100644 --- a/nixos/modules/services/misc/taskserver/doc.xml +++ b/nixos/modules/services/misc/taskserver/doc.xml @@ -4,58 +4,87 @@ xml:id="module-taskserver"> <title>Taskserver</title> <para> - Taskserver is the server component of <link xlink:href="https://taskwarrior.org/">Taskwarrior</link>, a free and open source todo list application. + Taskserver is the server component of + <link xlink:href="https://taskwarrior.org/">Taskwarrior</link>, a free and + open source todo list application. </para> <para> - <emphasis>Upstream documentation:</emphasis> <link xlink:href="https://taskwarrior.org/docs/#taskd"/> + <emphasis>Upstream documentation:</emphasis> + <link xlink:href="https://taskwarrior.org/docs/#taskd"/> </para> <section xml:id="module-services-taskserver-configuration"> <title>Configuration</title> <para> - Taskserver does all of its authentication via TLS using client certificates, so you either need to roll your own CA or purchase a certificate from a known CA, which allows creation of client certificates. These certificates are usually advertised as <quote>server certificates</quote>. + Taskserver does all of its authentication via TLS using client certificates, + so you either need to roll your own CA or purchase a certificate from a + known CA, which allows creation of client certificates. These certificates + are usually advertised as <quote>server certificates</quote>. </para> <para> - So in order to make it easier to handle your own CA, there is a helper tool called <command>nixos-taskserver</command> which manages the custom CA along with Taskserver organisations, users and groups. + So in order to make it easier to handle your own CA, there is a helper tool + called <command>nixos-taskserver</command> which manages the custom CA along + with Taskserver organisations, users and groups. </para> <para> - While the client certificates in Taskserver only authenticate whether a user is allowed to connect, every user has its own UUID which identifies it as an entity. + While the client certificates in Taskserver only authenticate whether a user + is allowed to connect, every user has its own UUID which identifies it as an + entity. </para> <para> - With <command>nixos-taskserver</command> the client certificate is created along with the UUID of the user, so it handles all of the credentials needed in order to setup the Taskwarrior client to work with a Taskserver. + With <command>nixos-taskserver</command> the client certificate is created + along with the UUID of the user, so it handles all of the credentials needed + in order to setup the Taskwarrior client to work with a Taskserver. </para> </section> <section xml:id="module-services-taskserver-nixos-taskserver-tool"> <title>The nixos-taskserver tool</title> <para> - Because Taskserver by default only provides scripts to setup users imperatively, the <command>nixos-taskserver</command> tool is used for addition and deletion of organisations along with users and groups defined by <xref linkend="opt-services.taskserver.organisations"/> and as well for imperative set up. + Because Taskserver by default only provides scripts to setup users + imperatively, the <command>nixos-taskserver</command> tool is used for + addition and deletion of organisations along with users and groups defined + by <xref linkend="opt-services.taskserver.organisations"/> and as well for + imperative set up. </para> <para> - The tool is designed to not interfere if the command is used to manually set up some organisations, users or groups. + The tool is designed to not interfere if the command is used to manually set + up some organisations, users or groups. </para> <para> - For example if you add a new organisation using <command>nixos-taskserver org add foo</command>, the organisation is not modified and deleted no matter what you define in <option>services.taskserver.organisations</option>, even if you're adding the same organisation in that option. + For example if you add a new organisation using <command>nixos-taskserver + org add foo</command>, the organisation is not modified and deleted no + matter what you define in + <option>services.taskserver.organisations</option>, even if you're adding + the same organisation in that option. </para> <para> - The tool is modelled to imitate the official <command>taskd</command> command, documentation for each subcommand can be shown by using the <option>--help</option> switch. + The tool is modelled to imitate the official <command>taskd</command> + command, documentation for each subcommand can be shown by using the + <option>--help</option> switch. </para> </section> <section xml:id="module-services-taskserver-declarative-ca-management"> <title>Declarative/automatic CA management</title> <para> - Everything is done according to what you specify in the module options, however in order to set up a Taskwarrior client for synchronisation with a Taskserver instance, you have to transfer the keys and certificates to the client machine. + Everything is done according to what you specify in the module options, + however in order to set up a Taskwarrior client for synchronisation with a + Taskserver instance, you have to transfer the keys and certificates to the + client machine. </para> <para> - This is done using <command>nixos-taskserver user export $orgname $username</command> which is printing a shell script fragment to stdout which can either be used verbatim or adjusted to import the user on the client machine. + This is done using <command>nixos-taskserver user export $orgname + $username</command> which is printing a shell script fragment to stdout + which can either be used verbatim or adjusted to import the user on the + client machine. </para> <para> @@ -68,30 +97,39 @@ <link linkend="opt-services.taskserver.organisations._name_.users">services.taskserver.organisations.my-company.users</link> = [ "alice" ]; } </screen> - This creates an organisation called <literal>my-company</literal> with the user <literal>alice</literal>. + This creates an organisation called <literal>my-company</literal> with the + user <literal>alice</literal>. </para> <para> - Now in order to import the <literal>alice</literal> user to another machine <literal>alicebox</literal>, all we need to do is something like this: + Now in order to import the <literal>alice</literal> user to another machine + <literal>alicebox</literal>, all we need to do is something like this: <screen> <prompt>$ </prompt>ssh server nixos-taskserver user export my-company alice | sh </screen> - Of course, if no SSH daemon is available on the server you can also copy & paste it directly into a shell. + Of course, if no SSH daemon is available on the server you can also copy + & paste it directly into a shell. </para> <para> - After this step the user should be set up and you can start synchronising your tasks for the first time with <command>task sync init</command> on <literal>alicebox</literal>. + After this step the user should be set up and you can start synchronising + your tasks for the first time with <command>task sync init</command> on + <literal>alicebox</literal>. </para> <para> - Subsequent synchronisation requests merely require the command <command>task sync</command> after that stage. + Subsequent synchronisation requests merely require the command <command>task + sync</command> after that stage. </para> </section> <section xml:id="module-services-taskserver-manual-ca-management"> <title>Manual CA management</title> <para> - If you set any options within <link linkend="opt-services.taskserver.pki.manual.ca.cert">service.taskserver.pki.manual</link>.*, <command>nixos-taskserver</command> won't issue certificates, but you can still use it for adding or removing user accounts. + If you set any options within + <link linkend="opt-services.taskserver.pki.manual.ca.cert">service.taskserver.pki.manual</link>.*, + <command>nixos-taskserver</command> won't issue certificates, but you can + still use it for adding or removing user accounts. </para> </section> </chapter> diff --git a/nixos/modules/services/misc/weechat.xml b/nixos/modules/services/misc/weechat.xml index 34bfffe15d8..7255edfb9da 100644 --- a/nixos/modules/services/misc/weechat.xml +++ b/nixos/modules/services/misc/weechat.xml @@ -5,13 +5,18 @@ xml:id="module-services-weechat"> <title>WeeChat</title> <para> - <link xlink:href="https://weechat.org/">WeeChat</link> is a fast and extensible IRC client. + <link xlink:href="https://weechat.org/">WeeChat</link> is a fast and + extensible IRC client. </para> <section xml:id="module-services-weechat-basic-usage"> <title>Basic Usage</title> <para> - By default, the module creates a <literal><link xlink:href="https://www.freedesktop.org/wiki/Software/systemd/">systemd</link></literal> unit which runs the chat client in a detached <literal><link xlink:href="https://www.gnu.org/software/screen/">screen</link></literal> session. + By default, the module creates a + <literal><link xlink:href="https://www.freedesktop.org/wiki/Software/systemd/">systemd</link></literal> + unit which runs the chat client in a detached + <literal><link xlink:href="https://www.gnu.org/software/screen/">screen</link></literal> + session. </para> <para> @@ -26,14 +31,19 @@ </para> <para> - The service is managed by a dedicated user named <literal>weechat</literal> in the state directory <literal>/var/lib/weechat</literal>. + The service is managed by a dedicated user named <literal>weechat</literal> + in the state directory <literal>/var/lib/weechat</literal>. </para> </section> <section xml:id="module-services-weechat-reattach"> <title>Re-attaching to WeeChat</title> <para> - WeeChat runs in a screen session owned by a dedicated user. To explicitly allow your another user to attach to this session, the <literal>screenrc</literal> needs to be tweaked by adding <link xlink:href="https://www.gnu.org/software/screen/manual/html_node/Multiuser.html#Multiuser">multiuser</link> support: + WeeChat runs in a screen session owned by a dedicated user. To explicitly + allow your another user to attach to this session, the + <literal>screenrc</literal> needs to be tweaked by adding + <link xlink:href="https://www.gnu.org/software/screen/manual/html_node/Multiuser.html#Multiuser">multiuser</link> + support: <programlisting> { <link linkend="opt-programs.screen.screenrc">programs.screen.screenrc</link> = '' @@ -49,7 +59,8 @@ screen -x weechat/weechat-screen </para> <para> - <emphasis>The session name can be changed using <link linkend="opt-services.weechat.sessionName">services.weechat.sessionName.</link></emphasis> + <emphasis>The session name can be changed using + <link linkend="opt-services.weechat.sessionName">services.weechat.sessionName.</link></emphasis> </para> </section> </chapter> diff --git a/nixos/modules/services/monitoring/prometheus/exporters.xml b/nixos/modules/services/monitoring/prometheus/exporters.xml index 814e7365584..c2d4b05996a 100644 --- a/nixos/modules/services/monitoring/prometheus/exporters.xml +++ b/nixos/modules/services/monitoring/prometheus/exporters.xml @@ -5,13 +5,17 @@ xml:id="module-services-prometheus-exporters"> <title>Prometheus exporters</title> <para> - Prometheus exporters provide metrics for the <link xlink:href="https://prometheus.io">prometheus monitoring system</link>. + Prometheus exporters provide metrics for the + <link xlink:href="https://prometheus.io">prometheus monitoring system</link>. </para> <section xml:id="module-services-prometheus-exporters-configuration"> <title>Configuration</title> <para> - One of the most common exporters is the <link xlink:href="https://github.com/prometheus/node_exporter">node exporter</link>, it provides hardware and OS metrics from the host it's running on. The exporter could be configured as follows: + One of the most common exporters is the + <link xlink:href="https://github.com/prometheus/node_exporter">node + exporter</link>, it provides hardware and OS metrics from the host it's + running on. The exporter could be configured as follows: <programlisting> services.prometheus.exporters.node = { enable = true; @@ -26,20 +30,34 @@ firewallFilter = "-i br0 -p tcp -m tcp --dport 9100"; }; </programlisting> - It should now serve all metrics from the collectors that are explicitly enabled and the ones that are <link xlink:href="https://github.com/prometheus/node_exporter#enabled-by-default">enabled by default</link>, via http under <literal>/metrics</literal>. In this example the firewall should just allow incoming connections to the exporter's port on the bridge interface <literal>br0</literal> (this would have to be configured seperately of course). For more information about configuration see <literal>man configuration.nix</literal> or search through the <link xlink:href="https://nixos.org/nixos/options.html#prometheus.exporters">available options</link>. + It should now serve all metrics from the collectors that are explicitly + enabled and the ones that are + <link xlink:href="https://github.com/prometheus/node_exporter#enabled-by-default">enabled + by default</link>, via http under <literal>/metrics</literal>. In this + example the firewall should just allow incoming connections to the + exporter's port on the bridge interface <literal>br0</literal> (this would + have to be configured seperately of course). For more information about + configuration see <literal>man configuration.nix</literal> or search through + the + <link xlink:href="https://nixos.org/nixos/options.html#prometheus.exporters">available + options</link>. </para> </section> <section xml:id="module-services-prometheus-exporters-new-exporter"> <title>Adding a new exporter</title> <para> - To add a new exporter, it has to be packaged first (see <literal>nixpkgs/pkgs/servers/monitoring/prometheus/</literal> for examples), then a module can be added. The postfix exporter is used in this example: + To add a new exporter, it has to be packaged first (see + <literal>nixpkgs/pkgs/servers/monitoring/prometheus/</literal> for + examples), then a module can be added. The postfix exporter is used in this + example: </para> <itemizedlist> <listitem> <para> - Some default options for all exporters are provided by <literal>nixpkgs/nixos/modules/services/monitoring/prometheus/exporters.nix</literal>: + Some default options for all exporters are provided by + <literal>nixpkgs/nixos/modules/services/monitoring/prometheus/exporters.nix</literal>: </para> </listitem> <listitem override='none'> @@ -88,7 +106,11 @@ </listitem> <listitem> <para> - As there is already a package available, the module can now be added. This is accomplished by adding a new file to the <literal>nixos/modules/services/monitoring/prometheus/exporters/</literal> directory, which will be called postfix.nix and contains all exporter specific options and configuration: + As there is already a package available, the module can now be added. This + is accomplished by adding a new file to the + <literal>nixos/modules/services/monitoring/prometheus/exporters/</literal> + directory, which will be called postfix.nix and contains all exporter + specific options and configuration: <programlisting> # nixpgs/nixos/modules/services/prometheus/exporters/postfix.nix { config, lib, pkgs, options }: @@ -155,16 +177,21 @@ in </listitem> <listitem> <para> - This should already be enough for the postfix exporter. Additionally one could now add assertions and conditional default values. This can be done in the 'meta-module' that combines all exporter definitions and generates the submodules: <literal>nixpkgs/nixos/modules/services/prometheus/exporters.nix</literal> + This should already be enough for the postfix exporter. Additionally one + could now add assertions and conditional default values. This can be done + in the 'meta-module' that combines all exporter definitions and generates + the submodules: + <literal>nixpkgs/nixos/modules/services/prometheus/exporters.nix</literal> </para> </listitem> </itemizedlist> </section> <section xml:id="module-services-prometheus-exporters-update-exporter-module"> <title>Updating an exporter module</title> - - <para> - Should an exporter option change at some point, it is possible to add information about the change to the exporter definition similar to <literal>nixpkgs/nixos/modules/rename.nix</literal>: + <para> + Should an exporter option change at some point, it is possible to add + information about the change to the exporter definition similar to + <literal>nixpkgs/nixos/modules/rename.nix</literal>: <programlisting> { config, lib, pkgs, options }: @@ -195,6 +222,6 @@ in ]; } </programlisting> - </para> - </section> + </para> + </section> </chapter> diff --git a/nixos/modules/services/networking/dnscrypt-proxy.xml b/nixos/modules/services/networking/dnscrypt-proxy.xml index 04e2654d3cc..afc7880392a 100644 --- a/nixos/modules/services/networking/dnscrypt-proxy.xml +++ b/nixos/modules/services/networking/dnscrypt-proxy.xml @@ -5,7 +5,11 @@ xml:id="sec-dnscrypt-proxy"> <title>DNSCrypt client proxy</title> <para> - The DNSCrypt client proxy relays DNS queries to a DNSCrypt enabled upstream resolver. The traffic between the client and the upstream resolver is encrypted and authenticated, mitigating the risk of MITM attacks, DNS poisoning attacks, and third-party snooping (assuming the upstream is trustworthy). + The DNSCrypt client proxy relays DNS queries to a DNSCrypt enabled upstream + resolver. The traffic between the client and the upstream resolver is + encrypted and authenticated, mitigating the risk of MITM attacks, DNS + poisoning attacks, and third-party snooping (assuming the upstream is + trustworthy). </para> <sect1 xml:id="sec-dnscrypt-proxy-configuration"> <title>Basic configuration</title> @@ -18,14 +22,18 @@ </para> <para> - Enabling the client proxy does not alter the system nameserver; to relay local queries, prepend <literal>127.0.0.1</literal> to <option>networking.nameservers</option>. + Enabling the client proxy does not alter the system nameserver; to relay + local queries, prepend <literal>127.0.0.1</literal> to + <option>networking.nameservers</option>. </para> </sect1> <sect1 xml:id="sec-dnscrypt-proxy-forwarder"> <title>As a forwarder for another DNS client</title> <para> - To run the DNSCrypt proxy client as a forwarder for another DNS client, change the default proxy listening port to a non-standard value and point the other client to it: + To run the DNSCrypt proxy client as a forwarder for another DNS client, + change the default proxy listening port to a non-standard value and point + the other client to it: <programlisting> <xref linkend="opt-services.dnscrypt-proxy.localPort"/> = 43; </programlisting> diff --git a/nixos/modules/services/web-apps/matomo-doc.xml b/nixos/modules/services/web-apps/matomo-doc.xml index 2ab476f892c..8485492c51c 100644 --- a/nixos/modules/services/web-apps/matomo-doc.xml +++ b/nixos/modules/services/web-apps/matomo-doc.xml @@ -5,16 +5,21 @@ xml:id="module-services-matomo"> <title>Matomo</title> <para> - Matomo is a real-time web analytics application. This module configures php-fpm as backend for Matomo, optionally configuring an nginx vhost as well. + Matomo is a real-time web analytics application. This module configures + php-fpm as backend for Matomo, optionally configuring an nginx vhost as well. </para> <para> - An automatic setup is not suported by Matomo, so you need to configure Matomo itself in the browser-based Matomo setup. + An automatic setup is not suported by Matomo, so you need to configure Matomo + itself in the browser-based Matomo setup. </para> <section xml:id="module-services-matomo-database-setup"> <title>Database Setup</title> <para> - You also need to configure a MariaDB or MySQL database and -user for Matomo yourself, and enter those credentials in your browser. You can use passwordless database authentication via the UNIX_SOCKET authentication plugin with the following SQL commands: + You also need to configure a MariaDB or MySQL database and -user for Matomo + yourself, and enter those credentials in your browser. You can use + passwordless database authentication via the UNIX_SOCKET authentication + plugin with the following SQL commands: <programlisting> # For MariaDB INSTALL PLUGIN unix_socket SONAME 'auth_socket'; @@ -28,29 +33,51 @@ CREATE DATABASE matomo; CREATE USER 'matomo'@'localhost' IDENTIFIED WITH auth_socket; GRANT ALL PRIVILEGES ON matomo.* TO 'matomo'@'localhost'; </programlisting> - Then fill in <literal>matomo</literal> as database user and database name, and leave the password field blank. This authentication works by allowing only the <literal>matomo</literal> unix user to authenticate as the <literal>matomo</literal> database user (without needing a password), but no other users. For more information on passwordless login, see <link xlink:href="https://mariadb.com/kb/en/mariadb/unix_socket-authentication-plugin/" />. + Then fill in <literal>matomo</literal> as database user and database name, + and leave the password field blank. This authentication works by allowing + only the <literal>matomo</literal> unix user to authenticate as the + <literal>matomo</literal> database user (without needing a password), but no + other users. For more information on passwordless login, see + <link xlink:href="https://mariadb.com/kb/en/mariadb/unix_socket-authentication-plugin/" />. </para> <para> - Of course, you can use password based authentication as well, e.g. when the database is not on the same host. + Of course, you can use password based authentication as well, e.g. when the + database is not on the same host. </para> </section> <section xml:id="module-services-matomo-archive-processing"> <title>Archive Processing</title> <para> - This module comes with the systemd service <literal>matomo-archive-processing.service</literal> and a timer that automatically triggers archive processing every hour. This means that you can safely <link xlink:href="https://matomo.org/docs/setup-auto-archiving/#disable-browser-triggers-for-matomo-archiving-and-limit-matomo-reports-to-updating-every-hour"> disable browser triggers for Matomo archiving </link> at <literal>Administration > System > General Settings</literal>. + This module comes with the systemd service + <literal>matomo-archive-processing.service</literal> and a timer that + automatically triggers archive processing every hour. This means that you + can safely + <link xlink:href="https://matomo.org/docs/setup-auto-archiving/#disable-browser-triggers-for-matomo-archiving-and-limit-matomo-reports-to-updating-every-hour"> + disable browser triggers for Matomo archiving </link> at + <literal>Administration > System > General Settings</literal>. </para> <para> - With automatic archive processing, you can now also enable to <link xlink:href="https://matomo.org/docs/privacy/#step-2-delete-old-visitors-logs"> delete old visitor logs </link> at <literal>Administration > System > Privacy</literal>, but make sure that you run <literal>systemctl start matomo-archive-processing.service</literal> at least once without errors if you have already collected data before, so that the reports get archived before the source data gets deleted. + With automatic archive processing, you can now also enable to + <link xlink:href="https://matomo.org/docs/privacy/#step-2-delete-old-visitors-logs"> + delete old visitor logs </link> at <literal>Administration > System > + Privacy</literal>, but make sure that you run <literal>systemctl start + matomo-archive-processing.service</literal> at least once without errors if + you have already collected data before, so that the reports get archived + before the source data gets deleted. </para> </section> <section xml:id="module-services-matomo-backups"> <title>Backup</title> <para> - You only need to take backups of your MySQL database and the <filename>/var/lib/matomo/config/config.ini.php</filename> file. Use a user in the <literal>matomo</literal> group or root to access the file. For more information, see <link xlink:href="https://matomo.org/faq/how-to-install/faq_138/" />. + You only need to take backups of your MySQL database and the + <filename>/var/lib/matomo/config/config.ini.php</filename> file. Use a user + in the <literal>matomo</literal> group or root to access the file. For more + information, see + <link xlink:href="https://matomo.org/faq/how-to-install/faq_138/" />. </para> </section> <section xml:id="module-services-matomo-issues"> @@ -59,12 +86,15 @@ GRANT ALL PRIVILEGES ON matomo.* TO 'matomo'@'localhost'; <itemizedlist> <listitem> <para> - Matomo's file integrity check will warn you. This is due to the patches necessary for NixOS, you can safely ignore this. + Matomo's file integrity check will warn you. This is due to the patches + necessary for NixOS, you can safely ignore this. </para> </listitem> <listitem> <para> - Matomo will warn you that the JavaScript tracker is not writable. This is because it's located in the read-only nix store. You can safely ignore this, unless you need a plugin that needs JavaScript tracker access. + Matomo will warn you that the JavaScript tracker is not writable. This is + because it's located in the read-only nix store. You can safely ignore + this, unless you need a plugin that needs JavaScript tracker access. </para> </listitem> </itemizedlist> @@ -73,7 +103,11 @@ GRANT ALL PRIVILEGES ON matomo.* TO 'matomo'@'localhost'; <title>Using other Web Servers than nginx</title> <para> - You can use other web servers by forwarding calls for <filename>index.php</filename> and <filename>piwik.php</filename> to the <literal>/run/phpfpm-matomo.sock</literal> fastcgi unix socket. You can use the nginx configuration in the module code as a reference to what else should be configured. + You can use other web servers by forwarding calls for + <filename>index.php</filename> and <filename>piwik.php</filename> to the + <literal>/run/phpfpm-matomo.sock</literal> fastcgi unix socket. You can use + the nginx configuration in the module code as a reference to what else + should be configured. </para> </section> </chapter> diff --git a/nixos/modules/services/web-apps/nextcloud.xml b/nixos/modules/services/web-apps/nextcloud.xml index 4345c2b9810..d66e0f0c299 100644 --- a/nixos/modules/services/web-apps/nextcloud.xml +++ b/nixos/modules/services/web-apps/nextcloud.xml @@ -5,13 +5,21 @@ xml:id="module-services-nextcloud"> <title>Nextcloud</title> <para> - <link xlink:href="https://nextcloud.com/">Nextcloud</link> is an open-source, self-hostable cloud platform. The server setup can be automated using <link linkend="opt-services.nextcloud.enable">services.nextcloud</link>. A desktop client is packaged at <literal>pkgs.nextcloud-client</literal>. + <link xlink:href="https://nextcloud.com/">Nextcloud</link> is an open-source, + self-hostable cloud platform. The server setup can be automated using + <link linkend="opt-services.nextcloud.enable">services.nextcloud</link>. A + desktop client is packaged at <literal>pkgs.nextcloud-client</literal>. </para> <section xml:id="module-services-nextcloud-basic-usage"> <title>Basic usage</title> <para> - Nextcloud is a PHP-based application which requires an HTTP server (<literal><link linkend="opt-services.nextcloud.enable">services.nextcloud</link></literal> optionally supports <literal><link linkend="opt-services.nginx.enable">services.nginx</link></literal>) and a database (it's recommended to use <literal><link linkend="opt-services.postgresql.enable">services.postgresql</link></literal>). + Nextcloud is a PHP-based application which requires an HTTP server + (<literal><link linkend="opt-services.nextcloud.enable">services.nextcloud</link></literal> + optionally supports + <literal><link linkend="opt-services.nginx.enable">services.nginx</link></literal>) + and a database (it's recommended to use + <literal><link linkend="opt-services.postgresql.enable">services.postgresql</link></literal>). </para> <para> @@ -53,38 +61,57 @@ </para> <para> - The options <literal>hostName</literal> and <literal>nginx.enable</literal> are used internally to configure an HTTP server using <literal><link xlink:href="https://php-fpm.org/">PHP-FPM</link></literal> and <literal>nginx</literal>. The <literal>config</literal> attribute set is used by the imperative installer and all values are written to an additional file to ensure that changes can be applied by changing the module's options. + The options <literal>hostName</literal> and <literal>nginx.enable</literal> + are used internally to configure an HTTP server using + <literal><link xlink:href="https://php-fpm.org/">PHP-FPM</link></literal> + and <literal>nginx</literal>. The <literal>config</literal> attribute set is + used by the imperative installer and all values are written to an additional file + to ensure that changes can be applied by changing the module's options. </para> <para> - In case the application serves multiple domains (those are checked with <literal><link xlink:href="http://php.net/manual/en/reserved.variables.server.php">$_SERVER['HTTP_HOST']</link></literal>) it's needed to add them to <literal><link linkend="opt-services.nextcloud.config.extraTrustedDomains">services.nextcloud.config.extraTrustedDomains</link></literal>. + In case the application serves multiple domains (those are checked with + <literal><link xlink:href="http://php.net/manual/en/reserved.variables.server.php">$_SERVER['HTTP_HOST']</link></literal>) + it's needed to add them to + <literal><link linkend="opt-services.nextcloud.config.extraTrustedDomains">services.nextcloud.config.extraTrustedDomains</link></literal>. </para> <para> - Auto updates for Nextcloud apps can be enabled using <literal><link linkend="opt-services.nextcloud.autoUpdateApps.enable">services.nextcloud.autoUpdateApps</link></literal>. - </para> + Auto updates for Nextcloud apps can be enabled using + <literal><link linkend="opt-services.nextcloud.autoUpdateApps.enable">services.nextcloud.autoUpdateApps</link></literal>. +</para> + </section> <section xml:id="module-services-nextcloud-pitfalls-during-upgrade"> <title>Pitfalls</title> <para> - Unfortunately Nextcloud appears to be very stateful when it comes to managing its own configuration. The config file lives in the home directory of the <literal>nextcloud</literal> user (by default <literal>/var/lib/nextcloud/config/config.php</literal>) and is also used to track several states of the application (e.g. whether installed or not). + Unfortunately Nextcloud appears to be very stateful when it comes to + managing its own configuration. The config file lives in the home directory + of the <literal>nextcloud</literal> user (by default + <literal>/var/lib/nextcloud/config/config.php</literal>) and is also used to + track several states of the application (e.g. whether installed or not). </para> <para> - All configuration parameters are also stored in <literal>/var/lib/nextcloud/config/override.config.php</literal> which is generated by the module and linked from the store to ensure that all values from <literal>config.php</literal> can be modified by the module. However <literal>config.php</literal> manages the application's state and shouldn't be touched manually because of that. + All configuration parameters are also stored in + <literal>/var/lib/nextcloud/config/override.config.php</literal> which is generated by + the module and linked from the store to ensure that all values from <literal>config.php</literal> + can be modified by the module. + However <literal>config.php</literal> manages the application's state and shouldn't be touched + manually because of that. </para> <warning> - <para> - Don't delete <literal>config.php</literal>! This file tracks the application's state and a deletion can cause unwanted side-effects! - </para> + <para>Don't delete <literal>config.php</literal>! This file + tracks the application's state and a deletion can cause unwanted + side-effects!</para> </warning> <warning> - <para> - Don't rerun <literal>nextcloud-occ maintenance:install</literal>! This command tries to install the application and can cause unwanted side-effects! - </para> + <para>Don't rerun <literal>nextcloud-occ + maintenance:install</literal>! This command tries to install the application + and can cause unwanted side-effects!</para> </warning> </section> </chapter> diff --git a/nixos/modules/services/x11/desktop-managers/xfce4-14.nix b/nixos/modules/services/x11/desktop-managers/xfce4-14.nix index 458d4a2f422..130e865a1fb 100644 --- a/nixos/modules/services/x11/desktop-managers/xfce4-14.nix +++ b/nixos/modules/services/x11/desktop-managers/xfce4-14.nix @@ -53,6 +53,7 @@ in glib # for gsettings gtk3.out # gtk-update-icon-cache + gnome3.gnome-themes-extra gnome3.adwaita-icon-theme hicolor-icon-theme tango-icon-theme @@ -69,16 +70,17 @@ in exo garcon - gtk-xfce-engine libxfce4ui xfconf mousepad + parole ristretto xfce4-appfinder xfce4-screenshooter xfce4-session xfce4-settings + xfce4-taskmanager xfce4-terminal # TODO: resync patch for plugins @@ -86,12 +88,16 @@ in thunar ] # TODO: NetworkManager doesn't belong here ++ optional config.networking.networkmanager.enable networkmanagerapplet - ++ optional config.hardware.pulseaudio.enable xfce4-pulseaudio-plugin ++ optional config.powerManagement.enable xfce4-power-manager - ++ optional cfg.enableXfwm xfwm4 - ++ optionals (!cfg.noDesktop) [ - xfce4-panel + ++ optionals config.hardware.pulseaudio.enable [ + pavucontrol + xfce4-pulseaudio-plugin + ] ++ optionals cfg.enableXfwm [ + xfwm4 + xfwm4-themes + ] ++ optionals (!cfg.noDesktop) [ xfce4-notifyd + xfce4-panel xfdesktop ]; diff --git a/nixos/modules/services/x11/desktop-managers/xterm.nix b/nixos/modules/services/x11/desktop-managers/xterm.nix index 1408df31295..f76db278a92 100644 --- a/nixos/modules/services/x11/desktop-managers/xterm.nix +++ b/nixos/modules/services/x11/desktop-managers/xterm.nix @@ -5,6 +5,7 @@ with lib; let cfg = config.services.xserver.desktopManager.xterm; + xSessionEnabled = config.services.xserver.enable; in @@ -13,7 +14,8 @@ in services.xserver.desktopManager.xterm.enable = mkOption { type = types.bool; - default = (versionOlder config.system.stateVersion "19.09"); + default = (versionOlder config.system.stateVersion "19.09") && xSessionEnabled; + defaultText = if versionOlder config.system.stateVersion "19.09" then "config.services.xserver.enable" else "false"; description = "Enable a xterm terminal as a desktop manager."; }; |