diff options
Diffstat (limited to 'nixos')
48 files changed, 2071 insertions, 1179 deletions
diff --git a/nixos/doc/manual/administration/containers.chapter.md b/nixos/doc/manual/administration/containers.chapter.md new file mode 100644 index 000000000000..ea51f91f698f --- /dev/null +++ b/nixos/doc/manual/administration/containers.chapter.md @@ -0,0 +1,28 @@ +# Container Management {#ch-containers} + +NixOS allows you to easily run other NixOS instances as *containers*. +Containers are a light-weight approach to virtualisation that runs +software in the container at the same speed as in the host system. NixOS +containers share the Nix store of the host, making container creation +very efficient. + +::: {.warning} +Currently, NixOS containers are not perfectly isolated from the host +system. This means that a user with root access to the container can do +things that affect the host. So you should not give container root +access to untrusted users. +::: + +NixOS containers can be created in two ways: imperatively, using the +command `nixos-container`, and declaratively, by specifying them in your +`configuration.nix`. The declarative approach implies that containers +get upgraded along with your host system when you run `nixos-rebuild`, +which is often not what you want. By contrast, in the imperative +approach, containers are configured and updated independently from the +host system. + +```{=docbook} +<xi:include href="imperative-containers.section.xml" /> +<xi:include href="declarative-containers.section.xml" /> +<xi:include href="container-networking.section.xml" /> +``` diff --git a/nixos/doc/manual/administration/containers.xml b/nixos/doc/manual/administration/containers.xml deleted file mode 100644 index 8e0e300f367b..000000000000 --- a/nixos/doc/manual/administration/containers.xml +++ /dev/null @@ -1,34 +0,0 @@ -<chapter xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="ch-containers"> - <title>Container Management</title> - <para> - NixOS allows you to easily run other NixOS instances as - <emphasis>containers</emphasis>. Containers are a light-weight approach to - virtualisation that runs software in the container at the same speed as in - the host system. NixOS containers share the Nix store of the host, making - container creation very efficient. - </para> - <warning> - <para> - Currently, NixOS containers are not perfectly isolated from the host system. - This means that a user with root access to the container can do things that - affect the host. So you should not give container root access to untrusted - users. - </para> - </warning> - <para> - NixOS containers can be created in two ways: imperatively, using the command - <command>nixos-container</command>, and declaratively, by specifying them in - your <filename>configuration.nix</filename>. The declarative approach implies - that containers get upgraded along with your host system when you run - <command>nixos-rebuild</command>, which is often not what you want. By - contrast, in the imperative approach, containers are configured and updated - independently from the host system. - </para> - <xi:include href="../from_md/administration/imperative-containers.section.xml" /> - <xi:include href="../from_md/administration/declarative-containers.section.xml" /> - <xi:include href="../from_md/administration/container-networking.section.xml" /> -</chapter> diff --git a/nixos/doc/manual/administration/running.xml b/nixos/doc/manual/administration/running.xml index 24fd864956ff..d9fcc1aee263 100644 --- a/nixos/doc/manual/administration/running.xml +++ b/nixos/doc/manual/administration/running.xml @@ -16,6 +16,6 @@ <xi:include href="../from_md/administration/control-groups.chapter.xml" /> <xi:include href="../from_md/administration/logging.chapter.xml" /> <xi:include href="../from_md/administration/cleaning-store.chapter.xml" /> - <xi:include href="containers.xml" /> - <xi:include href="troubleshooting.xml" /> + <xi:include href="../from_md/administration/containers.chapter.xml" /> + <xi:include href="../from_md/administration/troubleshooting.chapter.xml" /> </part> diff --git a/nixos/doc/manual/administration/troubleshooting.chapter.md b/nixos/doc/manual/administration/troubleshooting.chapter.md new file mode 100644 index 000000000000..548456eaf6d6 --- /dev/null +++ b/nixos/doc/manual/administration/troubleshooting.chapter.md @@ -0,0 +1,12 @@ +# Troubleshooting {#ch-troubleshooting} + +This chapter describes solutions to common problems you might encounter +when you manage your NixOS system. + +```{=docbook} +<xi:include href="boot-problems.section.xml" /> +<xi:include href="maintenance-mode.section.xml" /> +<xi:include href="rollback.section.xml" /> +<xi:include href="store-corruption.section.xml" /> +<xi:include href="network-problems.section.xml" /> +``` diff --git a/nixos/doc/manual/administration/troubleshooting.xml b/nixos/doc/manual/administration/troubleshooting.xml deleted file mode 100644 index d447b537335b..000000000000 --- a/nixos/doc/manual/administration/troubleshooting.xml +++ /dev/null @@ -1,16 +0,0 @@ -<chapter xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="ch-troubleshooting"> - <title>Troubleshooting</title> - <para> - This chapter describes solutions to common problems you might encounter when - you manage your NixOS system. - </para> - <xi:include href="../from_md/administration/boot-problems.section.xml" /> - <xi:include href="../from_md/administration/maintenance-mode.section.xml" /> - <xi:include href="../from_md/administration/rollback.section.xml" /> - <xi:include href="../from_md/administration/store-corruption.section.xml" /> - <xi:include href="../from_md/administration/network-problems.section.xml" /> -</chapter> diff --git a/nixos/doc/manual/configuration/config-syntax.chapter.md b/nixos/doc/manual/configuration/config-syntax.chapter.md new file mode 100644 index 000000000000..56d093c0f6e8 --- /dev/null +++ b/nixos/doc/manual/configuration/config-syntax.chapter.md @@ -0,0 +1,19 @@ +# Configuration Syntax {#sec-configuration-syntax} + +The NixOS configuration file `/etc/nixos/configuration.nix` is actually +a *Nix expression*, which is the Nix package manager's purely functional +language for describing how to build packages and configurations. This +means you have all the expressive power of that language at your +disposal, including the ability to abstract over common patterns, which +is very useful when managing complex systems. The syntax and semantics +of the Nix language are fully described in the [Nix +manual](https://nixos.org/nix/manual/#chap-writing-nix-expressions), but +here we give a short overview of the most important constructs useful in +NixOS configuration files. + +```{=docbook} +<xi:include href="config-file.section.xml" /> +<xi:include href="abstractions.section.xml" /> +<xi:include href="modularity.section.xml" /> +<xi:include href="summary.section.xml" /> +``` diff --git a/nixos/doc/manual/configuration/config-syntax.xml b/nixos/doc/manual/configuration/config-syntax.xml deleted file mode 100644 index d1351ff934e5..000000000000 --- a/nixos/doc/manual/configuration/config-syntax.xml +++ /dev/null @@ -1,25 +0,0 @@ -<chapter xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="sec-configuration-syntax"> - <title>Configuration Syntax</title> - <para> - The NixOS configuration file - <filename>/etc/nixos/configuration.nix</filename> is actually a <emphasis>Nix - expression</emphasis>, which is the Nix package manager’s purely functional - language for describing how to build packages and configurations. This means - you have all the expressive power of that language at your disposal, - including the ability to abstract over common patterns, which is very useful - when managing complex systems. The syntax and semantics of the Nix language - are fully described in the - <link -xlink:href="https://nixos.org/nix/manual/#chap-writing-nix-expressions">Nix - manual</link>, but here we give a short overview of the most important - constructs useful in NixOS configuration files. - </para> - <xi:include href="../from_md/configuration/config-file.section.xml" /> - <xi:include href="../from_md/configuration/abstractions.section.xml" /> - <xi:include href="../from_md/configuration/modularity.section.xml" /> - <xi:include href="../from_md/configuration/summary.section.xml" /> -</chapter> diff --git a/nixos/doc/manual/configuration/configuration.xml b/nixos/doc/manual/configuration/configuration.xml index 2461a5de73ad..b04316cfa48e 100644 --- a/nixos/doc/manual/configuration/configuration.xml +++ b/nixos/doc/manual/configuration/configuration.xml @@ -13,19 +13,19 @@ effect after you run <command>nixos-rebuild</command>. </para> </partintro> - <xi:include href="config-syntax.xml" /> - <xi:include href="package-mgmt.xml" /> + <xi:include href="../from_md/configuration/config-syntax.chapter.xml" /> + <xi:include href="../from_md/configuration/package-mgmt.chapter.xml" /> <xi:include href="../from_md/configuration/user-mgmt.chapter.xml" /> - <xi:include href="file-systems.xml" /> + <xi:include href="../from_md/configuration/file-systems.chapter.xml" /> <xi:include href="../from_md/configuration/x-windows.chapter.xml" /> <xi:include href="../from_md/configuration/wayland.chapter.xml" /> <xi:include href="../from_md/configuration/gpu-accel.chapter.xml" /> <xi:include href="../from_md/configuration/xfce.chapter.xml" /> - <xi:include href="networking.xml" /> + <xi:include href="../from_md/configuration/networking.chapter.xml" /> <xi:include href="../from_md/configuration/linux-kernel.chapter.xml" /> <xi:include href="../from_md/configuration/subversion.chapter.xml" /> <xi:include href="../generated/modules.xml" xpointer="xpointer(//section[@id='modules']/*)" /> - <xi:include href="profiles.xml" /> + <xi:include href="../from_md/configuration/profiles.chapter.xml" /> <xi:include href="../from_md/configuration/kubernetes.chapter.xml" /> <!-- Apache; libvirtd virtualisation --> </part> diff --git a/nixos/doc/manual/configuration/declarative-packages.section.md b/nixos/doc/manual/configuration/declarative-packages.section.md new file mode 100644 index 000000000000..337cdf8472e4 --- /dev/null +++ b/nixos/doc/manual/configuration/declarative-packages.section.md @@ -0,0 +1,46 @@ +# Declarative Package Management {#sec-declarative-package-mgmt} + +With declarative package management, you specify which packages you want +on your system by setting the option +[](#opt-environment.systemPackages). For instance, adding the +following line to `configuration.nix` enables the Mozilla Thunderbird +email application: + +```nix +environment.systemPackages = [ pkgs.thunderbird ]; +``` + +The effect of this specification is that the Thunderbird package from +Nixpkgs will be built or downloaded as part of the system when you run +`nixos-rebuild switch`. + +::: {.note} +Some packages require additional global configuration such as D-Bus or +systemd service registration so adding them to +[](#opt-environment.systemPackages) might not be sufficient. You are +advised to check the [list of options](#ch-options) whether a NixOS +module for the package does not exist. +::: + +You can get a list of the available packages as follows: + +```ShellSession +$ nix-env -qaP '*' --description +nixos.firefox firefox-23.0 Mozilla Firefox - the browser, reloaded +... +``` + +The first column in the output is the *attribute name*, such as +`nixos.thunderbird`. + +Note: the `nixos` prefix tells us that we want to get the package from +the `nixos` channel and works only in CLI tools. In declarative +configuration use `pkgs` prefix (variable). + +To "uninstall" a package, simply remove it from +[](#opt-environment.systemPackages) and run `nixos-rebuild switch`. + +```{=docbook} +<xi:include href="customizing-packages.section.xml" /> +<xi:include href="adding-custom-packages.section.xml" /> +``` diff --git a/nixos/doc/manual/configuration/declarative-packages.xml b/nixos/doc/manual/configuration/declarative-packages.xml deleted file mode 100644 index 8d321929f3f0..000000000000 --- a/nixos/doc/manual/configuration/declarative-packages.xml +++ /dev/null @@ -1,54 +0,0 @@ -<section xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="sec-declarative-package-mgmt"> - <title>Declarative Package Management</title> - - <para> - With declarative package management, you specify which packages you want on - your system by setting the option - <xref linkend="opt-environment.systemPackages"/>. For instance, adding the - following line to <filename>configuration.nix</filename> enables the Mozilla - Thunderbird email application: -<programlisting> -<xref linkend="opt-environment.systemPackages"/> = [ pkgs.thunderbird ]; -</programlisting> - The effect of this specification is that the Thunderbird package from Nixpkgs - will be built or downloaded as part of the system when you run - <command>nixos-rebuild switch</command>. - </para> - - <note> - <para> - Some packages require additional global configuration such as D-Bus or systemd service registration so adding them to <xref linkend="opt-environment.systemPackages"/> might not be sufficient. You are advised to check the <link xlink:href="#ch-options">list of options</link> whether a NixOS module for the package does not exist. - </para> - </note> - - <para> - You can get a list of the available packages as follows: -<screen> -<prompt>$ </prompt>nix-env -qaP '*' --description -nixos.firefox firefox-23.0 Mozilla Firefox - the browser, reloaded -<replaceable>...</replaceable> -</screen> - The first column in the output is the <emphasis>attribute name</emphasis>, - such as <literal>nixos.thunderbird</literal>. - </para> - <para> - Note: the <literal>nixos</literal> prefix tells us that we want to get the - package from the <literal>nixos</literal> channel and works only in CLI tools. - - In declarative configuration use <literal>pkgs</literal> prefix (variable). - </para> - - <para> - To “uninstall” a package, simply remove it from - <xref linkend="opt-environment.systemPackages"/> and run - <command>nixos-rebuild switch</command>. - </para> - - <xi:include href="../from_md/configuration/customizing-packages.section.xml" /> - - <xi:include href="../from_md/configuration/adding-custom-packages.section.xml" /> -</section> diff --git a/nixos/doc/manual/configuration/file-systems.chapter.md b/nixos/doc/manual/configuration/file-systems.chapter.md new file mode 100644 index 000000000000..901e2e4f181b --- /dev/null +++ b/nixos/doc/manual/configuration/file-systems.chapter.md @@ -0,0 +1,42 @@ +# File Systems {#ch-file-systems} + +You can define file systems using the `fileSystems` configuration +option. For instance, the following definition causes NixOS to mount the +Ext4 file system on device `/dev/disk/by-label/data` onto the mount +point `/data`: + +```nix +fileSystems."/data" = + { device = "/dev/disk/by-label/data"; + fsType = "ext4"; + }; +``` + +This will create an entry in `/etc/fstab`, which will generate a +corresponding [systemd.mount](https://www.freedesktop.org/software/systemd/man/systemd.mount.html) +unit via [systemd-fstab-generator](https://www.freedesktop.org/software/systemd/man/systemd-fstab-generator.html). +The filesystem will be mounted automatically unless `"noauto"` is +present in [options](#opt-fileSystems._name_.options). `"noauto"` +filesystems can be mounted explicitly using `systemctl` e.g. +`systemctl start data.mount`. Mount points are created automatically if they don't +already exist. For `device`, it's best to use the topology-independent +device aliases in `/dev/disk/by-label` and `/dev/disk/by-uuid`, as these +don't change if the topology changes (e.g. if a disk is moved to another +IDE controller). + +You can usually omit the file system type (`fsType`), since `mount` can +usually detect the type and load the necessary kernel module +automatically. However, if the file system is needed at early boot (in +the initial ramdisk) and is not `ext2`, `ext3` or `ext4`, then it's best +to specify `fsType` to ensure that the kernel module is available. + +::: {.note} +System startup will fail if any of the filesystems fails to mount, +dropping you to the emergency shell. You can make a mount asynchronous +and non-critical by adding `options = [ "nofail" ];`. +::: + +```{=docbook} +<xi:include href="luks-file-systems.section.xml" /> +<xi:include href="sshfs-file-systems.section.xml" /> +``` diff --git a/nixos/doc/manual/configuration/file-systems.xml b/nixos/doc/manual/configuration/file-systems.xml deleted file mode 100644 index 908b5d6c4681..000000000000 --- a/nixos/doc/manual/configuration/file-systems.xml +++ /dev/null @@ -1,58 +0,0 @@ -<chapter xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="ch-file-systems"> - <title>File Systems</title> - <para> - You can define file systems using the <option>fileSystems</option> - configuration option. For instance, the following definition causes NixOS to - mount the Ext4 file system on device - <filename>/dev/disk/by-label/data</filename> onto the mount point - <filename>/data</filename>: -<programlisting> -<xref linkend="opt-fileSystems"/>."/data" = - { device = "/dev/disk/by-label/data"; - fsType = "ext4"; - }; -</programlisting> - This will create an entry in <filename>/etc/fstab</filename>, which will - generate a corresponding - <link xlink:href="https://www.freedesktop.org/software/systemd/man/systemd.mount.html">systemd.mount</link> - unit via - <link xlink:href="https://www.freedesktop.org/software/systemd/man/systemd-fstab-generator.html">systemd-fstab-generator</link>. - The filesystem will be mounted automatically unless - <literal>"noauto"</literal> is present in <link - linkend="opt-fileSystems._name_.options">options</link>. - <literal>"noauto"</literal> filesystems can be mounted explicitly using - <command>systemctl</command> e.g. <command>systemctl start - data.mount</command>. - Mount points are created automatically if they don’t already exist. For - <option><link linkend="opt-fileSystems._name_.device">device</link></option>, - it’s best to use the topology-independent device aliases in - <filename>/dev/disk/by-label</filename> and - <filename>/dev/disk/by-uuid</filename>, as these don’t change if the - topology changes (e.g. if a disk is moved to another IDE controller). - </para> - <para> - You can usually omit the file system type - (<option><link linkend="opt-fileSystems._name_.fsType">fsType</link></option>), - since <command>mount</command> can usually detect the type and load the - necessary kernel module automatically. However, if the file system is needed - at early boot (in the initial ramdisk) and is not <literal>ext2</literal>, - <literal>ext3</literal> or <literal>ext4</literal>, then it’s best to - specify <option>fsType</option> to ensure that the kernel module is - available. - </para> - <note> - <para> - System startup will fail if any of the filesystems fails to mount, dropping - you to the emergency shell. You can make a mount asynchronous and - non-critical by adding - <literal><link linkend="opt-fileSystems._name_.options">options</link> = [ - "nofail" ];</literal>. - </para> - </note> - <xi:include href="../from_md/configuration/luks-file-systems.section.xml" /> - <xi:include href="../from_md/configuration/sshfs-file-systems.section.xml" /> -</chapter> diff --git a/nixos/doc/manual/configuration/networking.chapter.md b/nixos/doc/manual/configuration/networking.chapter.md new file mode 100644 index 000000000000..529dc0610bda --- /dev/null +++ b/nixos/doc/manual/configuration/networking.chapter.md @@ -0,0 +1,16 @@ +# Networking {#sec-networking} + +This section describes how to configure networking components +on your NixOS machine. + +```{=docbook} +<xi:include href="network-manager.section.xml" /> +<xi:include href="ssh.section.xml" /> +<xi:include href="ipv4-config.section.xml" /> +<xi:include href="ipv6-config.section.xml" /> +<xi:include href="firewall.section.xml" /> +<xi:include href="wireless.section.xml" /> +<xi:include href="ad-hoc-network-config.section.xml" /> +<xi:include href="renaming-interfaces.section.xml" /> +``` +<!-- TODO: OpenVPN, NAT --> diff --git a/nixos/doc/manual/configuration/networking.xml b/nixos/doc/manual/configuration/networking.xml deleted file mode 100644 index 5dd0278569b9..000000000000 --- a/nixos/doc/manual/configuration/networking.xml +++ /dev/null @@ -1,20 +0,0 @@ -<chapter xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="sec-networking"> - <title>Networking</title> - <para> - This section describes how to configure networking components on your NixOS - machine. - </para> - <xi:include href="../from_md/configuration/network-manager.section.xml" /> - <xi:include href="../from_md/configuration/ssh.section.xml" /> - <xi:include href="../from_md/configuration/ipv4-config.section.xml" /> - <xi:include href="../from_md/configuration/ipv6-config.section.xml" /> - <xi:include href="../from_md/configuration/firewall.section.xml" /> - <xi:include href="../from_md/configuration/wireless.section.xml" /> - <xi:include href="../from_md/configuration/ad-hoc-network-config.section.xml" /> - <xi:include href="../from_md/configuration/renaming-interfaces.section.xml" /> -<!-- TODO: OpenVPN, NAT --> -</chapter> diff --git a/nixos/doc/manual/configuration/package-mgmt.chapter.md b/nixos/doc/manual/configuration/package-mgmt.chapter.md new file mode 100644 index 000000000000..a6c414be59a9 --- /dev/null +++ b/nixos/doc/manual/configuration/package-mgmt.chapter.md @@ -0,0 +1,18 @@ +# Package Management {#sec-package-management} + +This section describes how to add additional packages to your system. +NixOS has two distinct styles of package management: + +- *Declarative*, where you declare what packages you want in your + `configuration.nix`. Every time you run `nixos-rebuild`, NixOS will + ensure that you get a consistent set of binaries corresponding to + your specification. + +- *Ad hoc*, where you install, upgrade and uninstall packages via the + `nix-env` command. This style allows mixing packages from different + Nixpkgs versions. It's the only choice for non-root users. + +```{=docbook} +<xi:include href="declarative-packages.section.xml" /> +<xi:include href="ad-hoc-packages.section.xml" /> +``` diff --git a/nixos/doc/manual/configuration/package-mgmt.xml b/nixos/doc/manual/configuration/package-mgmt.xml deleted file mode 100644 index 2f9395d26fa8..000000000000 --- a/nixos/doc/manual/configuration/package-mgmt.xml +++ /dev/null @@ -1,31 +0,0 @@ -<chapter xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="sec-package-management"> - <title>Package Management</title> - <para> - This section describes how to add additional packages to your system. NixOS - has two distinct styles of package management: - <itemizedlist> - <listitem> - <para> - <emphasis>Declarative</emphasis>, where you declare what packages you want - in your <filename>configuration.nix</filename>. Every time you run - <command>nixos-rebuild</command>, NixOS will ensure that you get a - consistent set of binaries corresponding to your specification. - </para> - </listitem> - <listitem> - <para> - <emphasis>Ad hoc</emphasis>, where you install, upgrade and uninstall - packages via the <command>nix-env</command> command. This style allows - mixing packages from different Nixpkgs versions. It’s the only choice - for non-root users. - </para> - </listitem> - </itemizedlist> - </para> - <xi:include href="declarative-packages.xml" /> - <xi:include href="../from_md/configuration/ad-hoc-packages.section.xml" /> -</chapter> diff --git a/nixos/doc/manual/configuration/profiles.chapter.md b/nixos/doc/manual/configuration/profiles.chapter.md new file mode 100644 index 000000000000..b4ae1b7d3faa --- /dev/null +++ b/nixos/doc/manual/configuration/profiles.chapter.md @@ -0,0 +1,34 @@ +# Profiles {#ch-profiles} + +In some cases, it may be desirable to take advantage of commonly-used, +predefined configurations provided by nixpkgs, but different from those +that come as default. This is a role fulfilled by NixOS\'s Profiles, +which come as files living in `<nixpkgs/nixos/modules/profiles>`. That +is to say, expected usage is to add them to the imports list of your +`/etc/configuration.nix` as such: + +```nix +imports = [ + <nixpkgs/nixos/modules/profiles/profile-name.nix> +]; +``` + +Even if some of these profiles seem only useful in the context of +install media, many are actually intended to be used in real installs. + +What follows is a brief explanation on the purpose and use-case for each +profile. Detailing each option configured by each one is out of scope. + +```{=docbook} +<xi:include href="profiles/all-hardware.section.xml" /> +<xi:include href="profiles/base.section.xml" /> +<xi:include href="profiles/clone-config.section.xml" /> +<xi:include href="profiles/demo.section.xml" /> +<xi:include href="profiles/docker-container.section.xml" /> +<xi:include href="profiles/graphical.section.xml" /> +<xi:include href="profiles/hardened.section.xml" /> +<xi:include href="profiles/headless.section.xml" /> +<xi:include href="profiles/installation-device.section.xml" /> +<xi:include href="profiles/minimal.section.xml" /> +<xi:include href="profiles/qemu-guest.section.xml" /> +``` diff --git a/nixos/doc/manual/configuration/profiles.xml b/nixos/doc/manual/configuration/profiles.xml deleted file mode 100644 index 6994c7e31705..000000000000 --- a/nixos/doc/manual/configuration/profiles.xml +++ /dev/null @@ -1,39 +0,0 @@ -<chapter xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="ch-profiles"> - <title>Profiles</title> - <para> - In some cases, it may be desirable to take advantage of commonly-used, - predefined configurations provided by nixpkgs, but different from those that - come as default. This is a role fulfilled by NixOS's Profiles, which come as - files living in <filename><nixpkgs/nixos/modules/profiles></filename>. - That is to say, expected usage is to add them to the imports list of your - <filename>/etc/configuration.nix</filename> as such: - </para> -<programlisting> - imports = [ - <nixpkgs/nixos/modules/profiles/profile-name.nix> - ]; -</programlisting> - <para> - Even if some of these profiles seem only useful in the context of install - media, many are actually intended to be used in real installs. - </para> - <para> - What follows is a brief explanation on the purpose and use-case for each - profile. Detailing each option configured by each one is out of scope. - </para> - <xi:include href="../from_md/configuration/profiles/all-hardware.section.xml" /> - <xi:include href="../from_md/configuration/profiles/base.section.xml" /> - <xi:include href="../from_md/configuration/profiles/clone-config.section.xml" /> - <xi:include href="../from_md/configuration/profiles/demo.section.xml" /> - <xi:include href="../from_md/configuration/profiles/docker-container.section.xml" /> - <xi:include href="../from_md/configuration/profiles/graphical.section.xml" /> - <xi:include href="../from_md/configuration/profiles/hardened.section.xml" /> - <xi:include href="../from_md/configuration/profiles/headless.section.xml" /> - <xi:include href="../from_md/configuration/profiles/installation-device.section.xml" /> - <xi:include href="../from_md/configuration/profiles/minimal.section.xml" /> - <xi:include href="../from_md/configuration/profiles/qemu-guest.section.xml" /> -</chapter> diff --git a/nixos/doc/manual/development/development.xml b/nixos/doc/manual/development/development.xml index 670a391e3801..0b2ad60a878b 100644 --- a/nixos/doc/manual/development/development.xml +++ b/nixos/doc/manual/development/development.xml @@ -10,10 +10,10 @@ </para> </partintro> <xi:include href="../from_md/development/sources.chapter.xml" /> - <xi:include href="writing-modules.xml" /> + <xi:include href="../from_md/development/writing-modules.chapter.xml" /> <xi:include href="../from_md/development/building-parts.chapter.xml" /> <xi:include href="../from_md/development/writing-documentation.chapter.xml" /> <xi:include href="../from_md/development/building-nixos.chapter.xml" /> - <xi:include href="nixos-tests.xml" /> + <xi:include href="../from_md/development/nixos-tests.chapter.xml" /> <xi:include href="../from_md/development/testing-installer.chapter.xml" /> </part> diff --git a/nixos/doc/manual/development/nixos-tests.chapter.md b/nixos/doc/manual/development/nixos-tests.chapter.md new file mode 100644 index 000000000000..2a4fdddeaa66 --- /dev/null +++ b/nixos/doc/manual/development/nixos-tests.chapter.md @@ -0,0 +1,13 @@ +# NixOS Tests {#sec-nixos-tests} + +When you add some feature to NixOS, you should write a test for it. +NixOS tests are kept in the directory `nixos/tests`, and are executed +(using Nix) by a testing framework that automatically starts one or more +virtual machines containing the NixOS system(s) required for the test. + +```{=docbook} +<xi:include href="writing-nixos-tests.section.xml" /> +<xi:include href="running-nixos-tests.section.xml" /> +<xi:include href="running-nixos-tests-interactively.section.xml" /> +<xi:include href="linking-nixos-tests-to-packages.section.xml" /> +``` diff --git a/nixos/doc/manual/development/nixos-tests.xml b/nixos/doc/manual/development/nixos-tests.xml deleted file mode 100644 index 67dc09fc715f..000000000000 --- a/nixos/doc/manual/development/nixos-tests.xml +++ /dev/null @@ -1,20 +0,0 @@ -<chapter xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="sec-nixos-tests"> - <title>NixOS Tests</title> - <para> - When you add some feature to NixOS, you should write a test for it. NixOS - tests are kept in the directory - <filename -xlink:href="https://github.com/NixOS/nixpkgs/tree/master/nixos/tests">nixos/tests</filename>, - and are executed (using Nix) by a testing framework that automatically starts - one or more virtual machines containing the NixOS system(s) required for the - test. - </para> - <xi:include href="../from_md/development/writing-nixos-tests.section.xml" /> - <xi:include href="../from_md/development/running-nixos-tests.section.xml" /> - <xi:include href="../from_md/development/running-nixos-tests-interactively.section.xml" /> - <xi:include href="../from_md/development/linking-nixos-tests-to-packages.section.xml" /> -</chapter> diff --git a/nixos/doc/manual/development/writing-modules.chapter.md b/nixos/doc/manual/development/writing-modules.chapter.md new file mode 100644 index 000000000000..2e3c6b34f1f5 --- /dev/null +++ b/nixos/doc/manual/development/writing-modules.chapter.md @@ -0,0 +1,166 @@ +# Writing NixOS Modules {#sec-writing-modules} + +NixOS has a modular system for declarative configuration. This system +combines multiple *modules* to produce the full system configuration. +One of the modules that constitute the configuration is +`/etc/nixos/configuration.nix`. Most of the others live in the +[`nixos/modules`](https://github.com/NixOS/nixpkgs/tree/master/nixos/modules) +subdirectory of the Nixpkgs tree. + +Each NixOS module is a file that handles one logical aspect of the +configuration, such as a specific kind of hardware, a service, or +network settings. A module configuration does not have to handle +everything from scratch; it can use the functionality provided by other +modules for its implementation. Thus a module can *declare* options that +can be used by other modules, and conversely can *define* options +provided by other modules in its own implementation. For example, the +module +[`pam.nix`](https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/security/pam.nix) +declares the option `security.pam.services` that allows other modules (e.g. +[`sshd.nix`](https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/services/networking/ssh/sshd.nix)) +to define PAM services; and it defines the option `environment.etc` (declared by +[`etc.nix`](https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/system/etc/etc.nix)) +to cause files to be created in `/etc/pam.d`. + +In [](#sec-configuration-syntax), we saw the following structure of +NixOS modules: + +```nix +{ config, pkgs, ... }: + +{ option definitions +} +``` + +This is actually an *abbreviated* form of module that only defines +options, but does not declare any. The structure of full NixOS modules +is shown in [Example: Structure of NixOS Modules](#ex-module-syntax). + +::: {#ex-module-syntax .example} +::: {.title} +**Example: Structure of NixOS Modules** +::: +```nix +{ config, pkgs, ... }: + +{ + imports = + [ paths of other modules + ]; + + options = { + option declarations + }; + + config = { + option definitions + }; +} +``` +::: + +The meaning of each part is as follows. + +- The first line makes the current Nix expression a function. The variable + `pkgs` contains Nixpkgs (by default, it takes the `nixpkgs` entry of + `NIX_PATH`, see the [Nix manual](https://nixos.org/manual/nix/stable/#sec-common-env) + for further details), while `config` contains the full system + configuration. This line can be omitted if there is no reference to + `pkgs` and `config` inside the module. + +- This `imports` list enumerates the paths to other NixOS modules that + should be included in the evaluation of the system configuration. A + default set of modules is defined in the file `modules/module-list.nix`. + These don\'t need to be added in the import list. + +- The attribute `options` is a nested set of *option declarations* + (described below). + +- The attribute `config` is a nested set of *option definitions* (also + described below). + +[Example: NixOS Module for the "locate" Service](#locate-example) +shows a module that handles the regular update of the "locate" database, +an index of all files in the file system. This module declares two +options that can be defined by other modules (typically the user's +`configuration.nix`): `services.locate.enable` (whether the database should +be updated) and `services.locate.interval` (when the update should be done). +It implements its functionality by defining two options declared by other +modules: `systemd.services` (the set of all systemd services) and +`systemd.timers` (the list of commands to be executed periodically by +`systemd`). + +::: {#locate-example .example} +::: {.title} +**Example: NixOS Module for the "locate" Service** +::: +```nix +{ config, lib, pkgs, ... }: + +with lib; + +let + cfg = config.services.locate; +in { + options.services.locate = { + enable = mkOption { + type = types.bool; + default = false; + description = '' + If enabled, NixOS will periodically update the database of + files used by the locate command. + ''; + }; + + interval = mkOption { + type = types.str; + default = "02:15"; + example = "hourly"; + description = '' + Update the locate database at this interval. Updates by + default at 2:15 AM every day. + + The format is described in + systemd.time(7). + ''; + }; + + # Other options omitted for documentation + }; + + config = { + systemd.services.update-locatedb = + { description = "Update Locate Database"; + path = [ pkgs.su ]; + script = + '' + mkdir -m 0755 -p $(dirname ${toString cfg.output}) + exec updatedb \ + --localuser=${cfg.localuser} \ + ${optionalString (!cfg.includeStore) "--prunepaths='/nix/store'"} \ + --output=${toString cfg.output} ${concatStringsSep " " cfg.extraFlags} + ''; + }; + + systemd.timers.update-locatedb = mkIf cfg.enable + { description = "Update timer for locate database"; + partOf = [ "update-locatedb.service" ]; + wantedBy = [ "timers.target" ]; + timerConfig.OnCalendar = cfg.interval; + }; + }; +} +``` +::: + +```{=docbook} +<xi:include href="option-declarations.section.xml" /> +<xi:include href="option-types.section.xml" /> +<xi:include href="option-def.section.xml" /> +<xi:include href="assertions.section.xml" /> +<xi:include href="meta-attributes.section.xml" /> +<xi:include href="importing-modules.section.xml" /> +<xi:include href="replace-modules.section.xml" /> +<xi:include href="freeform-modules.section.xml" /> +<xi:include href="settings-options.section.xml" /> +``` diff --git a/nixos/doc/manual/development/writing-modules.xml b/nixos/doc/manual/development/writing-modules.xml deleted file mode 100644 index 167976247091..000000000000 --- a/nixos/doc/manual/development/writing-modules.xml +++ /dev/null @@ -1,191 +0,0 @@ -<chapter xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="sec-writing-modules"> - <title>Writing NixOS Modules</title> - <para> - NixOS has a modular system for declarative configuration. This system - combines multiple <emphasis>modules</emphasis> to produce the full system - configuration. One of the modules that constitute the configuration is - <filename>/etc/nixos/configuration.nix</filename>. Most of the others live in - the - <link -xlink:href="https://github.com/NixOS/nixpkgs/tree/master/nixos/modules"><filename>nixos/modules</filename></link> - subdirectory of the Nixpkgs tree. - </para> - <para> - Each NixOS module is a file that handles one logical aspect of the - configuration, such as a specific kind of hardware, a service, or network - settings. A module configuration does not have to handle everything from - scratch; it can use the functionality provided by other modules for its - implementation. Thus a module can <emphasis>declare</emphasis> options that - can be used by other modules, and conversely can <emphasis>define</emphasis> - options provided by other modules in its own implementation. For example, the - module - <link -xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/security/pam.nix"><filename>pam.nix</filename></link> - declares the option <option>security.pam.services</option> that allows other - modules (e.g. - <link -xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/services/networking/ssh/sshd.nix"><filename>sshd.nix</filename></link>) - to define PAM services; and it defines the option - <option>environment.etc</option> (declared by - <link -xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/system/etc/etc.nix"><filename>etc.nix</filename></link>) - to cause files to be created in <filename>/etc/pam.d</filename>. - </para> - <para xml:id="para-module-syn"> - In <xref -linkend="sec-configuration-syntax"/>, we saw the following structure - of NixOS modules: -<programlisting> -{ config, pkgs, ... }: - -{ <replaceable>option definitions</replaceable> -} -</programlisting> - This is actually an <emphasis>abbreviated</emphasis> form of module that only - defines options, but does not declare any. The structure of full NixOS - modules is shown in <xref linkend='ex-module-syntax' />. - </para> - <example xml:id='ex-module-syntax'> - <title>Structure of NixOS Modules</title> -<programlisting> -{ config, pkgs, ... }: <co xml:id='module-syntax-1' /> - -{ - imports = - [ <replaceable>paths of other modules</replaceable> <co xml:id='module-syntax-2' /> - ]; - - options = { - <replaceable>option declarations</replaceable> <co xml:id='module-syntax-3' /> - }; - - config = { - <replaceable>option definitions</replaceable> <co xml:id='module-syntax-4' /> - }; -}</programlisting> - </example> - <para> - The meaning of each part is as follows. - <calloutlist> - <callout arearefs='module-syntax-1'> - <para> - This line makes the current Nix expression a function. The variable - <varname>pkgs</varname> contains Nixpkgs (by default, it takes the - <varname>nixpkgs</varname> entry of <envar>NIX_PATH</envar>, see the <link - xlink:href="https://nixos.org/manual/nix/stable/#sec-common-env">Nix - manual</link> for further details), while <varname>config</varname> - contains the full system configuration. This line can be omitted if there - is no reference to <varname>pkgs</varname> and <varname>config</varname> - inside the module. - </para> - </callout> - <callout arearefs='module-syntax-2'> - <para> - This list enumerates the paths to other NixOS modules that should be - included in the evaluation of the system configuration. A default set of - modules is defined in the file - <filename>modules/module-list.nix</filename>. These don't need to be added - in the import list. - </para> - </callout> - <callout arearefs='module-syntax-3'> - <para> - The attribute <varname>options</varname> is a nested set of - <emphasis>option declarations</emphasis> (described below). - </para> - </callout> - <callout arearefs='module-syntax-4'> - <para> - The attribute <varname>config</varname> is a nested set of - <emphasis>option definitions</emphasis> (also described below). - </para> - </callout> - </calloutlist> - </para> - <para> - <xref linkend='locate-example' /> shows a module that handles the regular - update of the “locate” database, an index of all files in the file - system. This module declares two options that can be defined by other modules - (typically the user’s <filename>configuration.nix</filename>): - <option>services.locate.enable</option> (whether the database should be - updated) and <option>services.locate.interval</option> (when the update - should be done). It implements its functionality by defining two options - declared by other modules: <option>systemd.services</option> (the set of all - systemd services) and <option>systemd.timers</option> (the list of commands - to be executed periodically by <command>systemd</command>). - </para> - <example xml:id='locate-example'> - <title>NixOS Module for the “locate” Service</title> -<programlisting> -{ config, lib, pkgs, ... }: - -with lib; - -let - cfg = config.services.locate; -in { - options.services.locate = { - enable = mkOption { - type = types.bool; - default = false; - description = '' - If enabled, NixOS will periodically update the database of - files used by the <command>locate</command> command. - ''; - }; - - interval = mkOption { - type = types.str; - default = "02:15"; - example = "hourly"; - description = '' - Update the locate database at this interval. Updates by - default at 2:15 AM every day. - - The format is described in - <citerefentry><refentrytitle>systemd.time</refentrytitle> - <manvolnum>7</manvolnum></citerefentry>. - ''; - }; - - # Other options omitted for documentation - }; - - config = { - systemd.services.update-locatedb = - { description = "Update Locate Database"; - path = [ pkgs.su ]; - script = - '' - mkdir -m 0755 -p $(dirname ${toString cfg.output}) - exec updatedb \ - --localuser=${cfg.localuser} \ - ${optionalString (!cfg.includeStore) "--prunepaths='/nix/store'"} \ - --output=${toString cfg.output} ${concatStringsSep " " cfg.extraFlags} - ''; - }; - - systemd.timers.update-locatedb = mkIf cfg.enable - { description = "Update timer for locate database"; - partOf = [ "update-locatedb.service" ]; - wantedBy = [ "timers.target" ]; - timerConfig.OnCalendar = cfg.interval; - }; - }; -} -</programlisting> - </example> - <xi:include href="../from_md/development/option-declarations.section.xml" /> - <xi:include href="../from_md/development/option-types.section.xml" /> - <xi:include href="../from_md/development/option-def.section.xml" /> - <xi:include href="../from_md/development/assertions.section.xml" /> - <xi:include href="../from_md/development/meta-attributes.section.xml" /> - <xi:include href="../from_md/development/importing-modules.section.xml" /> - <xi:include href="../from_md/development/replace-modules.section.xml" /> - <xi:include href="../from_md/development/freeform-modules.section.xml" /> - <xi:include href="../from_md/development/settings-options.section.xml" /> -</chapter> diff --git a/nixos/doc/manual/from_md/administration/containers.chapter.xml b/nixos/doc/manual/from_md/administration/containers.chapter.xml new file mode 100644 index 000000000000..afbd5b35aaa5 --- /dev/null +++ b/nixos/doc/manual/from_md/administration/containers.chapter.xml @@ -0,0 +1,31 @@ +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" xml:id="ch-containers"> + <title>Container Management</title> + <para> + NixOS allows you to easily run other NixOS instances as + <emphasis>containers</emphasis>. Containers are a light-weight + approach to virtualisation that runs software in the container at + the same speed as in the host system. NixOS containers share the Nix + store of the host, making container creation very efficient. + </para> + <warning> + <para> + Currently, NixOS containers are not perfectly isolated from the + host system. This means that a user with root access to the + container can do things that affect the host. So you should not + give container root access to untrusted users. + </para> + </warning> + <para> + NixOS containers can be created in two ways: imperatively, using the + command <literal>nixos-container</literal>, and declaratively, by + specifying them in your <literal>configuration.nix</literal>. The + declarative approach implies that containers get upgraded along with + your host system when you run <literal>nixos-rebuild</literal>, + which is often not what you want. By contrast, in the imperative + approach, containers are configured and updated independently from + the host system. + </para> + <xi:include href="imperative-containers.section.xml" /> + <xi:include href="declarative-containers.section.xml" /> + <xi:include href="container-networking.section.xml" /> +</chapter> diff --git a/nixos/doc/manual/from_md/administration/troubleshooting.chapter.xml b/nixos/doc/manual/from_md/administration/troubleshooting.chapter.xml new file mode 100644 index 000000000000..8bbb8a1fe729 --- /dev/null +++ b/nixos/doc/manual/from_md/administration/troubleshooting.chapter.xml @@ -0,0 +1,12 @@ +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" xml:id="ch-troubleshooting"> + <title>Troubleshooting</title> + <para> + This chapter describes solutions to common problems you might + encounter when you manage your NixOS system. + </para> + <xi:include href="boot-problems.section.xml" /> + <xi:include href="maintenance-mode.section.xml" /> + <xi:include href="rollback.section.xml" /> + <xi:include href="store-corruption.section.xml" /> + <xi:include href="network-problems.section.xml" /> +</chapter> diff --git a/nixos/doc/manual/from_md/configuration/config-syntax.chapter.xml b/nixos/doc/manual/from_md/configuration/config-syntax.chapter.xml new file mode 100644 index 000000000000..01446e53e38f --- /dev/null +++ b/nixos/doc/manual/from_md/configuration/config-syntax.chapter.xml @@ -0,0 +1,21 @@ +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" xml:id="sec-configuration-syntax"> + <title>Configuration Syntax</title> + <para> + The NixOS configuration file + <literal>/etc/nixos/configuration.nix</literal> is actually a + <emphasis>Nix expression</emphasis>, which is the Nix package + manager’s purely functional language for describing how to build + packages and configurations. This means you have all the expressive + power of that language at your disposal, including the ability to + abstract over common patterns, which is very useful when managing + complex systems. The syntax and semantics of the Nix language are + fully described in the + <link xlink:href="https://nixos.org/nix/manual/#chap-writing-nix-expressions">Nix + manual</link>, but here we give a short overview of the most + important constructs useful in NixOS configuration files. + </para> + <xi:include href="config-file.section.xml" /> + <xi:include href="abstractions.section.xml" /> + <xi:include href="modularity.section.xml" /> + <xi:include href="summary.section.xml" /> +</chapter> diff --git a/nixos/doc/manual/from_md/configuration/declarative-packages.section.xml b/nixos/doc/manual/from_md/configuration/declarative-packages.section.xml new file mode 100644 index 000000000000..da31f18d9233 --- /dev/null +++ b/nixos/doc/manual/from_md/configuration/declarative-packages.section.xml @@ -0,0 +1,53 @@ +<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" xml:id="sec-declarative-package-mgmt"> + <title>Declarative Package Management</title> + <para> + With declarative package management, you specify which packages you + want on your system by setting the option + <xref linkend="opt-environment.systemPackages" />. For instance, + adding the following line to <literal>configuration.nix</literal> + enables the Mozilla Thunderbird email application: + </para> + <programlisting language="bash"> +environment.systemPackages = [ pkgs.thunderbird ]; +</programlisting> + <para> + The effect of this specification is that the Thunderbird package + from Nixpkgs will be built or downloaded as part of the system when + you run <literal>nixos-rebuild switch</literal>. + </para> + <note> + <para> + Some packages require additional global configuration such as + D-Bus or systemd service registration so adding them to + <xref linkend="opt-environment.systemPackages" /> might not be + sufficient. You are advised to check the + <link linkend="ch-options">list of options</link> whether a NixOS + module for the package does not exist. + </para> + </note> + <para> + You can get a list of the available packages as follows: + </para> + <programlisting> +$ nix-env -qaP '*' --description +nixos.firefox firefox-23.0 Mozilla Firefox - the browser, reloaded +... +</programlisting> + <para> + The first column in the output is the <emphasis>attribute + name</emphasis>, such as <literal>nixos.thunderbird</literal>. + </para> + <para> + Note: the <literal>nixos</literal> prefix tells us that we want to + get the package from the <literal>nixos</literal> channel and works + only in CLI tools. In declarative configuration use + <literal>pkgs</literal> prefix (variable). + </para> + <para> + To <quote>uninstall</quote> a package, simply remove it from + <xref linkend="opt-environment.systemPackages" /> and run + <literal>nixos-rebuild switch</literal>. + </para> + <xi:include href="customizing-packages.section.xml" /> + <xi:include href="adding-custom-packages.section.xml" /> +</section> diff --git a/nixos/doc/manual/from_md/configuration/file-systems.chapter.xml b/nixos/doc/manual/from_md/configuration/file-systems.chapter.xml new file mode 100644 index 000000000000..71441d8b4a5b --- /dev/null +++ b/nixos/doc/manual/from_md/configuration/file-systems.chapter.xml @@ -0,0 +1,55 @@ +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" xml:id="ch-file-systems"> + <title>File Systems</title> + <para> + You can define file systems using the <literal>fileSystems</literal> + configuration option. For instance, the following definition causes + NixOS to mount the Ext4 file system on device + <literal>/dev/disk/by-label/data</literal> onto the mount point + <literal>/data</literal>: + </para> + <programlisting language="bash"> +fileSystems."/data" = + { device = "/dev/disk/by-label/data"; + fsType = "ext4"; + }; +</programlisting> + <para> + This will create an entry in <literal>/etc/fstab</literal>, which + will generate a corresponding + <link xlink:href="https://www.freedesktop.org/software/systemd/man/systemd.mount.html">systemd.mount</link> + unit via + <link xlink:href="https://www.freedesktop.org/software/systemd/man/systemd-fstab-generator.html">systemd-fstab-generator</link>. + The filesystem will be mounted automatically unless + <literal>"noauto"</literal> is present in + <link linkend="opt-fileSystems._name_.options">options</link>. + <literal>"noauto"</literal> filesystems can be mounted + explicitly using <literal>systemctl</literal> e.g. + <literal>systemctl start data.mount</literal>. Mount points are + created automatically if they don’t already exist. For + <literal>device</literal>, it’s best to use the topology-independent + device aliases in <literal>/dev/disk/by-label</literal> and + <literal>/dev/disk/by-uuid</literal>, as these don’t change if the + topology changes (e.g. if a disk is moved to another IDE + controller). + </para> + <para> + You can usually omit the file system type + (<literal>fsType</literal>), since <literal>mount</literal> can + usually detect the type and load the necessary kernel module + automatically. However, if the file system is needed at early boot + (in the initial ramdisk) and is not <literal>ext2</literal>, + <literal>ext3</literal> or <literal>ext4</literal>, then it’s best + to specify <literal>fsType</literal> to ensure that the kernel + module is available. + </para> + <note> + <para> + System startup will fail if any of the filesystems fails to mount, + dropping you to the emergency shell. You can make a mount + asynchronous and non-critical by adding + <literal>options = [ "nofail" ];</literal>. + </para> + </note> + <xi:include href="luks-file-systems.section.xml" /> + <xi:include href="sshfs-file-systems.section.xml" /> +</chapter> diff --git a/nixos/doc/manual/from_md/configuration/networking.chapter.xml b/nixos/doc/manual/from_md/configuration/networking.chapter.xml new file mode 100644 index 000000000000..2ed86ea3b589 --- /dev/null +++ b/nixos/doc/manual/from_md/configuration/networking.chapter.xml @@ -0,0 +1,15 @@ +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" xml:id="sec-networking"> + <title>Networking</title> + <para> + This section describes how to configure networking components on + your NixOS machine. + </para> + <xi:include href="network-manager.section.xml" /> + <xi:include href="ssh.section.xml" /> + <xi:include href="ipv4-config.section.xml" /> + <xi:include href="ipv6-config.section.xml" /> + <xi:include href="firewall.section.xml" /> + <xi:include href="wireless.section.xml" /> + <xi:include href="ad-hoc-network-config.section.xml" /> + <xi:include href="renaming-interfaces.section.xml" /> +</chapter> diff --git a/nixos/doc/manual/from_md/configuration/package-mgmt.chapter.xml b/nixos/doc/manual/from_md/configuration/package-mgmt.chapter.xml new file mode 100644 index 000000000000..d3727edbe08d --- /dev/null +++ b/nixos/doc/manual/from_md/configuration/package-mgmt.chapter.xml @@ -0,0 +1,28 @@ +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" xml:id="sec-package-management"> + <title>Package Management</title> + <para> + This section describes how to add additional packages to your + system. NixOS has two distinct styles of package management: + </para> + <itemizedlist> + <listitem> + <para> + <emphasis>Declarative</emphasis>, where you declare what + packages you want in your <literal>configuration.nix</literal>. + Every time you run <literal>nixos-rebuild</literal>, NixOS will + ensure that you get a consistent set of binaries corresponding + to your specification. + </para> + </listitem> + <listitem> + <para> + <emphasis>Ad hoc</emphasis>, where you install, upgrade and + uninstall packages via the <literal>nix-env</literal> command. + This style allows mixing packages from different Nixpkgs + versions. It’s the only choice for non-root users. + </para> + </listitem> + </itemizedlist> + <xi:include href="declarative-packages.section.xml" /> + <xi:include href="ad-hoc-packages.section.xml" /> +</chapter> diff --git a/nixos/doc/manual/from_md/configuration/profiles.chapter.xml b/nixos/doc/manual/from_md/configuration/profiles.chapter.xml new file mode 100644 index 000000000000..6f5fc130c6a0 --- /dev/null +++ b/nixos/doc/manual/from_md/configuration/profiles.chapter.xml @@ -0,0 +1,38 @@ +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" xml:id="ch-profiles"> + <title>Profiles</title> + <para> + In some cases, it may be desirable to take advantage of + commonly-used, predefined configurations provided by nixpkgs, but + different from those that come as default. This is a role fulfilled + by NixOS's Profiles, which come as files living in + <literal><nixpkgs/nixos/modules/profiles></literal>. That is + to say, expected usage is to add them to the imports list of your + <literal>/etc/configuration.nix</literal> as such: + </para> + <programlisting language="bash"> +imports = [ + <nixpkgs/nixos/modules/profiles/profile-name.nix> +]; +</programlisting> + <para> + Even if some of these profiles seem only useful in the context of + install media, many are actually intended to be used in real + installs. + </para> + <para> + What follows is a brief explanation on the purpose and use-case for + each profile. Detailing each option configured by each one is out of + scope. + </para> + <xi:include href="profiles/all-hardware.section.xml" /> + <xi:include href="profiles/base.section.xml" /> + <xi:include href="profiles/clone-config.section.xml" /> + <xi:include href="profiles/demo.section.xml" /> + <xi:include href="profiles/docker-container.section.xml" /> + <xi:include href="profiles/graphical.section.xml" /> + <xi:include href="profiles/hardened.section.xml" /> + <xi:include href="profiles/headless.section.xml" /> + <xi:include href="profiles/installation-device.section.xml" /> + <xi:include href="profiles/minimal.section.xml" /> + <xi:include href="profiles/qemu-guest.section.xml" /> +</chapter> diff --git a/nixos/doc/manual/from_md/development/nixos-tests.chapter.xml b/nixos/doc/manual/from_md/development/nixos-tests.chapter.xml new file mode 100644 index 000000000000..b9ff2269676c --- /dev/null +++ b/nixos/doc/manual/from_md/development/nixos-tests.chapter.xml @@ -0,0 +1,14 @@ +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" xml:id="sec-nixos-tests"> + <title>NixOS Tests</title> + <para> + When you add some feature to NixOS, you should write a test for it. + NixOS tests are kept in the directory + <literal>nixos/tests</literal>, and are executed (using Nix) by a + testing framework that automatically starts one or more virtual + machines containing the NixOS system(s) required for the test. + </para> + <xi:include href="writing-nixos-tests.section.xml" /> + <xi:include href="running-nixos-tests.section.xml" /> + <xi:include href="running-nixos-tests-interactively.section.xml" /> + <xi:include href="linking-nixos-tests-to-packages.section.xml" /> +</chapter> diff --git a/nixos/doc/manual/from_md/development/writing-modules.chapter.xml b/nixos/doc/manual/from_md/development/writing-modules.chapter.xml new file mode 100644 index 000000000000..e33c24f4f12c --- /dev/null +++ b/nixos/doc/manual/from_md/development/writing-modules.chapter.xml @@ -0,0 +1,196 @@ +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" xml:id="sec-writing-modules"> + <title>Writing NixOS Modules</title> + <para> + NixOS has a modular system for declarative configuration. This + system combines multiple <emphasis>modules</emphasis> to produce the + full system configuration. One of the modules that constitute the + configuration is <literal>/etc/nixos/configuration.nix</literal>. + Most of the others live in the + <link xlink:href="https://github.com/NixOS/nixpkgs/tree/master/nixos/modules"><literal>nixos/modules</literal></link> + subdirectory of the Nixpkgs tree. + </para> + <para> + Each NixOS module is a file that handles one logical aspect of the + configuration, such as a specific kind of hardware, a service, or + network settings. A module configuration does not have to handle + everything from scratch; it can use the functionality provided by + other modules for its implementation. Thus a module can + <emphasis>declare</emphasis> options that can be used by other + modules, and conversely can <emphasis>define</emphasis> options + provided by other modules in its own implementation. For example, + the module + <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/security/pam.nix"><literal>pam.nix</literal></link> + declares the option <literal>security.pam.services</literal> that + allows other modules (e.g. + <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/services/networking/ssh/sshd.nix"><literal>sshd.nix</literal></link>) + to define PAM services; and it defines the option + <literal>environment.etc</literal> (declared by + <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/system/etc/etc.nix"><literal>etc.nix</literal></link>) + to cause files to be created in <literal>/etc/pam.d</literal>. + </para> + <para> + In <xref linkend="sec-configuration-syntax" />, we saw the following + structure of NixOS modules: + </para> + <programlisting language="bash"> +{ config, pkgs, ... }: + +{ option definitions +} +</programlisting> + <para> + This is actually an <emphasis>abbreviated</emphasis> form of module + that only defines options, but does not declare any. The structure + of full NixOS modules is shown in + <link linkend="ex-module-syntax">Example: Structure of NixOS + Modules</link>. + </para> + <anchor xml:id="ex-module-syntax" /> + <para> + <emphasis role="strong">Example: Structure of NixOS + Modules</emphasis> + </para> + <programlisting language="bash"> +{ config, pkgs, ... }: + +{ + imports = + [ paths of other modules + ]; + + options = { + option declarations + }; + + config = { + option definitions + }; +} +</programlisting> + <para> + The meaning of each part is as follows. + </para> + <itemizedlist> + <listitem> + <para> + The first line makes the current Nix expression a function. The + variable <literal>pkgs</literal> contains Nixpkgs (by default, + it takes the <literal>nixpkgs</literal> entry of + <literal>NIX_PATH</literal>, see the + <link xlink:href="https://nixos.org/manual/nix/stable/#sec-common-env">Nix + manual</link> for further details), while + <literal>config</literal> contains the full system + configuration. This line can be omitted if there is no reference + to <literal>pkgs</literal> and <literal>config</literal> inside + the module. + </para> + </listitem> + <listitem> + <para> + This <literal>imports</literal> list enumerates the paths to + other NixOS modules that should be included in the evaluation of + the system configuration. A default set of modules is defined in + the file <literal>modules/module-list.nix</literal>. These don't + need to be added in the import list. + </para> + </listitem> + <listitem> + <para> + The attribute <literal>options</literal> is a nested set of + <emphasis>option declarations</emphasis> (described below). + </para> + </listitem> + <listitem> + <para> + The attribute <literal>config</literal> is a nested set of + <emphasis>option definitions</emphasis> (also described below). + </para> + </listitem> + </itemizedlist> + <para> + <link linkend="locate-example">Example: NixOS Module for the + <quote>locate</quote> Service</link> shows a module that handles the + regular update of the <quote>locate</quote> database, an index of + all files in the file system. This module declares two options that + can be defined by other modules (typically the user’s + <literal>configuration.nix</literal>): + <literal>services.locate.enable</literal> (whether the database + should be updated) and <literal>services.locate.interval</literal> + (when the update should be done). It implements its functionality by + defining two options declared by other modules: + <literal>systemd.services</literal> (the set of all systemd + services) and <literal>systemd.timers</literal> (the list of + commands to be executed periodically by <literal>systemd</literal>). + </para> + <anchor xml:id="locate-example" /> + <para> + <emphasis role="strong">Example: NixOS Module for the + <quote>locate</quote> Service</emphasis> + </para> + <programlisting language="bash"> +{ config, lib, pkgs, ... }: + +with lib; + +let + cfg = config.services.locate; +in { + options.services.locate = { + enable = mkOption { + type = types.bool; + default = false; + description = '' + If enabled, NixOS will periodically update the database of + files used by the locate command. + ''; + }; + + interval = mkOption { + type = types.str; + default = "02:15"; + example = "hourly"; + description = '' + Update the locate database at this interval. Updates by + default at 2:15 AM every day. + + The format is described in + systemd.time(7). + ''; + }; + + # Other options omitted for documentation + }; + + config = { + systemd.services.update-locatedb = + { description = "Update Locate Database"; + path = [ pkgs.su ]; + script = + '' + mkdir -m 0755 -p $(dirname ${toString cfg.output}) + exec updatedb \ + --localuser=${cfg.localuser} \ + ${optionalString (!cfg.includeStore) "--prunepaths='/nix/store'"} \ + --output=${toString cfg.output} ${concatStringsSep " " cfg.extraFlags} + ''; + }; + + systemd.timers.update-locatedb = mkIf cfg.enable + { description = "Update timer for locate database"; + partOf = [ "update-locatedb.service" ]; + wantedBy = [ "timers.target" ]; + timerConfig.OnCalendar = cfg.interval; + }; + }; +} +</programlisting> + <xi:include href="option-declarations.section.xml" /> + <xi:include href="option-types.section.xml" /> + <xi:include href="option-def.section.xml" /> + <xi:include href="assertions.section.xml" /> + <xi:include href="meta-attributes.section.xml" /> + <xi:include href="importing-modules.section.xml" /> + <xi:include href="replace-modules.section.xml" /> + <xi:include href="freeform-modules.section.xml" /> + <xi:include href="settings-options.section.xml" /> +</chapter> diff --git a/nixos/doc/manual/from_md/installation/installing.chapter.xml b/nixos/doc/manual/from_md/installation/installing.chapter.xml new file mode 100644 index 000000000000..91ab71682977 --- /dev/null +++ b/nixos/doc/manual/from_md/installation/installing.chapter.xml @@ -0,0 +1,642 @@ +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" xml:id="sec-installation"> + <title>Installing NixOS</title> + <section xml:id="sec-installation-booting"> + <title>Booting the system</title> + <para> + NixOS can be installed on BIOS or UEFI systems. The procedure for + a UEFI installation is by and large the same as a BIOS + installation. The differences are mentioned in the steps that + follow. + </para> + <para> + The installation media can be burned to a CD, or now more + commonly, <quote>burned</quote> to a USB drive (see + <xref linkend="sec-booting-from-usb" />). + </para> + <para> + The installation media contains a basic NixOS installation. When + it’s finished booting, it should have detected most of your + hardware. + </para> + <para> + The NixOS manual is available by running + <literal>nixos-help</literal>. + </para> + <para> + You are logged-in automatically as <literal>nixos</literal>. The + <literal>nixos</literal> user account has an empty password so you + can use <literal>sudo</literal> without a password. + </para> + <para> + If you downloaded the graphical ISO image, you can run + <literal>systemctl start display-manager</literal> to start the + desktop environment. If you want to continue on the terminal, you + can use <literal>loadkeys</literal> to switch to your preferred + keyboard layout. (We even provide neo2 via + <literal>loadkeys de neo</literal>!) + </para> + <para> + If the text is too small to be legible, try + <literal>setfont ter-v32n</literal> to increase the font size. + </para> + <para> + To install over a serial port connect with + <literal>115200n8</literal> (e.g. + <literal>picocom -b 115200 /dev/ttyUSB0</literal>). When the + bootloader lists boot entries, select the serial console boot + entry. + </para> + <section xml:id="sec-installation-booting-networking"> + <title>Networking in the installer</title> + <para> + The boot process should have brought up networking (check + <literal>ip a</literal>). Networking is necessary for the + installer, since it will download lots of stuff (such as source + tarballs or Nixpkgs channel binaries). It’s best if you have a + DHCP server on your network. Otherwise configure networking + manually using <literal>ifconfig</literal>. + </para> + <para> + On the graphical installer, you can configure the network, wifi + included, through NetworkManager. Using the + <literal>nmtui</literal> program, you can do so even in a + non-graphical session. If you prefer to configure the network + manually, disable NetworkManager with + <literal>systemctl stop NetworkManager</literal>. + </para> + <para> + On the minimal installer, NetworkManager is not available, so + configuration must be perfomed manually. To configure the wifi, + first start wpa_supplicant with + <literal>sudo systemctl start wpa_supplicant</literal>, then run + <literal>wpa_cli</literal>. For most home networks, you need to + type in the following commands: + </para> + <programlisting> +> add_network +0 +> set_network 0 ssid "myhomenetwork" +OK +> set_network 0 psk "mypassword" +OK +> set_network 0 key_mgmt WPA-PSK +OK +> enable_network 0 +OK +</programlisting> + <para> + For enterprise networks, for example + <emphasis>eduroam</emphasis>, instead do: + </para> + <programlisting> +> add_network +0 +> set_network 0 ssid "eduroam" +OK +> set_network 0 identity "myname@example.com" +OK +> set_network 0 password "mypassword" +OK +> set_network 0 key_mgmt WPA-EAP +OK +> enable_network 0 +OK +</programlisting> + <para> + When successfully connected, you should see a line such as this + one + </para> + <programlisting> +<3>CTRL-EVENT-CONNECTED - Connection to 32:85:ab:ef:24:5c completed [id=0 id_str=] +</programlisting> + <para> + you can now leave <literal>wpa_cli</literal> by typing + <literal>quit</literal>. + </para> + <para> + If you would like to continue the installation from a different + machine you can use activated SSH daemon. You need to copy your + ssh key to either + <literal>/home/nixos/.ssh/authorized_keys</literal> or + <literal>/root/.ssh/authorized_keys</literal> (Tip: For + installers with a modifiable filesystem such as the sd-card + installer image a key can be manually placed by mounting the + image on a different machine). Alternatively you must set a + password for either <literal>root</literal> or + <literal>nixos</literal> with <literal>passwd</literal> to be + able to login. + </para> + </section> + </section> + <section xml:id="sec-installation-partitioning"> + <title>Partitioning and formatting</title> + <para> + The NixOS installer doesn’t do any partitioning or formatting, so + you need to do that yourself. + </para> + <para> + The NixOS installer ships with multiple partitioning tools. The + examples below use <literal>parted</literal>, but also provides + <literal>fdisk</literal>, <literal>gdisk</literal>, + <literal>cfdisk</literal>, and <literal>cgdisk</literal>. + </para> + <para> + The recommended partition scheme differs depending if the computer + uses <emphasis>Legacy Boot</emphasis> or + <emphasis>UEFI</emphasis>. + </para> + <section xml:id="sec-installation-partitioning-UEFI"> + <title>UEFI (GPT)</title> + <para> + Here's an example partition scheme for UEFI, using + <literal>/dev/sda</literal> as the device. + </para> + <note> + <para> + You can safely ignore <literal>parted</literal>'s + informational message about needing to update /etc/fstab. + </para> + </note> + <orderedlist numeration="arabic"> + <listitem> + <para> + Create a <emphasis>GPT</emphasis> partition table. + </para> + <programlisting> +# parted /dev/sda -- mklabel gpt +</programlisting> + </listitem> + <listitem> + <para> + Add the <emphasis>root</emphasis> partition. This will fill + the disk except for the end part, where the swap will live, + and the space left in front (512MiB) which will be used by + the boot partition. + </para> + <programlisting> +# parted /dev/sda -- mkpart primary 512MiB -8GiB +</programlisting> + </listitem> + <listitem> + <para> + Next, add a <emphasis>swap</emphasis> partition. The size + required will vary according to needs, here a 8GiB one is + created. + </para> + <programlisting> +# parted /dev/sda -- mkpart primary linux-swap -8GiB 100% +</programlisting> + <note> + <para> + The swap partition size rules are no different than for + other Linux distributions. + </para> + </note> + </listitem> + <listitem> + <para> + Finally, the <emphasis>boot</emphasis> partition. NixOS by + default uses the ESP (EFI system partition) as its + <emphasis>/boot</emphasis> partition. It uses the initially + reserved 512MiB at the start of the disk. + </para> + <programlisting> +# parted /dev/sda -- mkpart ESP fat32 1MiB 512MiB +# parted /dev/sda -- set 3 esp on +</programlisting> + </listitem> + </orderedlist> + <para> + Once complete, you can follow with + <xref linkend="sec-installation-partitioning-formatting" />. + </para> + </section> + <section xml:id="sec-installation-partitioning-MBR"> + <title>Legacy Boot (MBR)</title> + <para> + Here's an example partition scheme for Legacy Boot, using + <literal>/dev/sda</literal> as the device. + </para> + <note> + <para> + You can safely ignore <literal>parted</literal>'s + informational message about needing to update /etc/fstab. + </para> + </note> + <orderedlist numeration="arabic"> + <listitem> + <para> + Create a <emphasis>MBR</emphasis> partition table. + </para> + <programlisting> +# parted /dev/sda -- mklabel msdos +</programlisting> + </listitem> + <listitem> + <para> + Add the <emphasis>root</emphasis> partition. This will fill + the the disk except for the end part, where the swap will + live. + </para> + <programlisting> +# parted /dev/sda -- mkpart primary 1MiB -8GiB +</programlisting> + </listitem> + <listitem> + <para> + Finally, add a <emphasis>swap</emphasis> partition. The size + required will vary according to needs, here a 8GiB one is + created. + </para> + <programlisting> +# parted /dev/sda -- mkpart primary linux-swap -8GiB 100% +</programlisting> + <note> + <para> + The swap partition size rules are no different than for + other Linux distributions. + </para> + </note> + </listitem> + </orderedlist> + <para> + Once complete, you can follow with + <xref linkend="sec-installation-partitioning-formatting" />. + </para> + </section> + <section xml:id="sec-installation-partitioning-formatting"> + <title>Formatting</title> + <para> + Use the following commands: + </para> + <itemizedlist> + <listitem> + <para> + For initialising Ext4 partitions: + <literal>mkfs.ext4</literal>. It is recommended that you + assign a unique symbolic label to the file system using the + option <literal>-L label</literal>, since this makes the + file system configuration independent from device changes. + For example: + </para> + <programlisting> +# mkfs.ext4 -L nixos /dev/sda1 +</programlisting> + </listitem> + <listitem> + <para> + For creating swap partitions: <literal>mkswap</literal>. + Again it’s recommended to assign a label to the swap + partition: <literal>-L label</literal>. For example: + </para> + <programlisting> +# mkswap -L swap /dev/sda2 +</programlisting> + </listitem> + <listitem> + <para> + <emphasis role="strong">UEFI systems</emphasis> + </para> + <para> + For creating boot partitions: <literal>mkfs.fat</literal>. + Again it’s recommended to assign a label to the boot + partition: <literal>-n label</literal>. For example: + </para> + <programlisting> +# mkfs.fat -F 32 -n boot /dev/sda3 +</programlisting> + </listitem> + <listitem> + <para> + For creating LVM volumes, the LVM commands, e.g., + <literal>pvcreate</literal>, <literal>vgcreate</literal>, + and <literal>lvcreate</literal>. + </para> + </listitem> + <listitem> + <para> + For creating software RAID devices, use + <literal>mdadm</literal>. + </para> + </listitem> + </itemizedlist> + </section> + </section> + <section xml:id="sec-installation-installing"> + <title>Installing</title> + <orderedlist numeration="arabic"> + <listitem> + <para> + Mount the target file system on which NixOS should be + installed on <literal>/mnt</literal>, e.g. + </para> + <programlisting> +# mount /dev/disk/by-label/nixos /mnt +</programlisting> + </listitem> + <listitem> + <para> + <emphasis role="strong">UEFI systems</emphasis> + </para> + <para> + Mount the boot file system on <literal>/mnt/boot</literal>, + e.g. + </para> + <programlisting> +# mkdir -p /mnt/boot +# mount /dev/disk/by-label/boot /mnt/boot +</programlisting> + </listitem> + <listitem> + <para> + If your machine has a limited amount of memory, you may want + to activate swap devices now + (<literal>swapon device</literal>). The installer (or rather, + the build actions that it may spawn) may need quite a bit of + RAM, depending on your configuration. + </para> + <programlisting> +# swapon /dev/sda2 +</programlisting> + </listitem> + <listitem> + <para> + You now need to create a file + <literal>/mnt/etc/nixos/configuration.nix</literal> that + specifies the intended configuration of the system. This is + because NixOS has a <emphasis>declarative</emphasis> + configuration model: you create or edit a description of the + desired configuration of your system, and then NixOS takes + care of making it happen. The syntax of the NixOS + configuration file is described in + <xref linkend="sec-configuration-syntax" />, while a list of + available configuration options appears in + <xref linkend="ch-options" />. A minimal example is shown in + <link linkend="ex-config">Example: NixOS Configuration</link>. + </para> + <para> + The command <literal>nixos-generate-config</literal> can + generate an initial configuration file for you: + </para> + <programlisting> +# nixos-generate-config --root /mnt +</programlisting> + <para> + You should then edit + <literal>/mnt/etc/nixos/configuration.nix</literal> to suit + your needs: + </para> + <programlisting> +# nano /mnt/etc/nixos/configuration.nix +</programlisting> + <para> + If you’re using the graphical ISO image, other editors may be + available (such as <literal>vim</literal>). If you have + network access, you can also install other editors – for + instance, you can install Emacs by running + <literal>nix-env -f '<nixpkgs>' -iA emacs</literal>. + </para> + <variablelist> + <varlistentry> + <term> + BIOS systems + </term> + <listitem> + <para> + You <emphasis>must</emphasis> set the option + <xref linkend="opt-boot.loader.grub.device" /> to + specify on which disk the GRUB boot loader is to be + installed. Without it, NixOS cannot boot. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + UEFI systems + </term> + <listitem> + <para> + You <emphasis>must</emphasis> set the option + <xref linkend="opt-boot.loader.systemd-boot.enable" /> + to <literal>true</literal>. + <literal>nixos-generate-config</literal> should do this + automatically for new configurations when booted in UEFI + mode. + </para> + <para> + You may want to look at the options starting with + <link linkend="opt-boot.loader.efi.canTouchEfiVariables"><literal>boot.loader.efi</literal></link> + and + <link linkend="opt-boot.loader.systemd-boot.enable"><literal>boot.loader.systemd-boot</literal></link> + as well. + </para> + </listitem> + </varlistentry> + </variablelist> + <para> + If there are other operating systems running on the machine + before installing NixOS, the + <xref linkend="opt-boot.loader.grub.useOSProber" /> option can + be set to <literal>true</literal> to automatically add them to + the grub menu. + </para> + <para> + If you need to configure networking for your machine the + configuration options are described in + <xref linkend="sec-networking" />. In particular, while wifi + is supported on the installation image, it is not enabled by + default in the configuration generated by + <literal>nixos-generate-config</literal>. + </para> + <para> + Another critical option is <literal>fileSystems</literal>, + specifying the file systems that need to be mounted by NixOS. + However, you typically don’t need to set it yourself, because + <literal>nixos-generate-config</literal> sets it automatically + in + <literal>/mnt/etc/nixos/hardware-configuration.nix</literal> + from your currently mounted file systems. (The configuration + file <literal>hardware-configuration.nix</literal> is included + from <literal>configuration.nix</literal> and will be + overwritten by future invocations of + <literal>nixos-generate-config</literal>; thus, you generally + should not modify it.) Additionally, you may want to look at + <link xlink:href="https://github.com/NixOS/nixos-hardware">Hardware + configuration for known-hardware</link> at this point or after + installation. + </para> + <note> + <para> + Depending on your hardware configuration or type of file + system, you may need to set the option + <literal>boot.initrd.kernelModules</literal> to include the + kernel modules that are necessary for mounting the root file + system, otherwise the installed system will not be able to + boot. (If this happens, boot from the installation media + again, mount the target file system on + <literal>/mnt</literal>, fix + <literal>/mnt/etc/nixos/configuration.nix</literal> and + rerun <literal>nixos-install</literal>.) In most cases, + <literal>nixos-generate-config</literal> will figure out the + required modules. + </para> + </note> + </listitem> + <listitem> + <para> + Do the installation: + </para> + <programlisting> +# nixos-install +</programlisting> + <para> + This will install your system based on the configuration you + provided. If anything fails due to a configuration problem or + any other issue (such as a network outage while downloading + binaries from the NixOS binary cache), you can re-run + <literal>nixos-install</literal> after fixing your + <literal>configuration.nix</literal>. + </para> + <para> + As the last step, <literal>nixos-install</literal> will ask + you to set the password for the <literal>root</literal> user, + e.g. + </para> + <programlisting> +setting root password... +New password: *** +Retype new password: *** +</programlisting> + <note> + <para> + For unattended installations, it is possible to use + <literal>nixos-install --no-root-passwd</literal> in order + to disable the password prompt entirely. + </para> + </note> + </listitem> + <listitem> + <para> + If everything went well: + </para> + <programlisting> +# reboot +</programlisting> + </listitem> + <listitem> + <para> + You should now be able to boot into the installed NixOS. The + GRUB boot menu shows a list of <emphasis>available + configurations</emphasis> (initially just one). Every time you + change the NixOS configuration (see + <link linkend="sec-changing-config">Changing + Configuration</link>), a new item is added to the menu. This + allows you to easily roll back to a previous configuration if + something goes wrong. + </para> + <para> + You should log in and change the <literal>root</literal> + password with <literal>passwd</literal>. + </para> + <para> + You’ll probably want to create some user accounts as well, + which can be done with <literal>useradd</literal>: + </para> + <programlisting> +$ useradd -c 'Eelco Dolstra' -m eelco +$ passwd eelco +</programlisting> + <para> + You may also want to install some software. This will be + covered in <xref linkend="sec-package-management" />. + </para> + </listitem> + </orderedlist> + </section> + <section xml:id="sec-installation-summary"> + <title>Installation summary</title> + <para> + To summarise, <link linkend="ex-install-sequence">Example: + Commands for Installing NixOS on + <literal>/dev/sda</literal></link> shows a typical sequence of + commands for installing NixOS on an empty hard drive (here + <literal>/dev/sda</literal>). <link linkend="ex-config">Example: + NixOS Configuration</link> shows a corresponding configuration Nix + expression. + </para> + <anchor xml:id="ex-partition-scheme-MBR" /> + <para> + <emphasis role="strong">Example: Example partition schemes for + NixOS on <literal>/dev/sda</literal> (MBR)</emphasis> + </para> + <programlisting> +# parted /dev/sda -- mklabel msdos +# parted /dev/sda -- mkpart primary 1MiB -8GiB +# parted /dev/sda -- mkpart primary linux-swap -8GiB 100% +</programlisting> + <anchor xml:id="ex-partition-scheme-UEFI" /> + <para> + <emphasis role="strong">Example: Example partition schemes for + NixOS on <literal>/dev/sda</literal> (UEFI)</emphasis> + </para> + <programlisting> +# parted /dev/sda -- mklabel gpt +# parted /dev/sda -- mkpart primary 512MiB -8GiB +# parted /dev/sda -- mkpart primary linux-swap -8GiB 100% +# parted /dev/sda -- mkpart ESP fat32 1MiB 512MiB +# parted /dev/sda -- set 3 esp on +</programlisting> + <anchor xml:id="ex-install-sequence" /> + <para> + <emphasis role="strong">Example: Commands for Installing NixOS on + <literal>/dev/sda</literal></emphasis> + </para> + <para> + With a partitioned disk. + </para> + <programlisting> +# mkfs.ext4 -L nixos /dev/sda1 +# mkswap -L swap /dev/sda2 +# swapon /dev/sda2 +# mkfs.fat -F 32 -n boot /dev/sda3 # (for UEFI systems only) +# mount /dev/disk/by-label/nixos /mnt +# mkdir -p /mnt/boot # (for UEFI systems only) +# mount /dev/disk/by-label/boot /mnt/boot # (for UEFI systems only) +# nixos-generate-config --root /mnt +# nano /mnt/etc/nixos/configuration.nix +# nixos-install +# reboot +</programlisting> + <anchor xml:id="ex-config" /> + <para> + <emphasis role="strong">Example: NixOS Configuration</emphasis> + </para> + <programlisting> +{ config, pkgs, ... }: { + imports = [ + # Include the results of the hardware scan. + ./hardware-configuration.nix + ]; + + boot.loader.grub.device = "/dev/sda"; # (for BIOS systems only) + boot.loader.systemd-boot.enable = true; # (for UEFI systems only) + + # Note: setting fileSystems is generally not + # necessary, since nixos-generate-config figures them out + # automatically in hardware-configuration.nix. + #fileSystems."/".device = "/dev/disk/by-label/nixos"; + + # Enable the OpenSSH server. + services.sshd.enable = true; +} +</programlisting> + </section> + <section xml:id="sec-installation-additional-notes"> + <title>Additional installation notes</title> + <xi:include href="installing-usb.section.xml" /> + <xi:include href="installing-pxe.section.xml" /> + <xi:include href="installing-virtualbox-guest.section.xml" /> + <xi:include href="installing-from-other-distro.section.xml" /> + <xi:include href="installing-behind-a-proxy.section.xml" /> + </section> +</chapter> diff --git a/nixos/doc/manual/from_md/release-notes/rl-2111.section.xml b/nixos/doc/manual/from_md/release-notes/rl-2111.section.xml index 5554927b8b2a..b18e29191470 100644 --- a/nixos/doc/manual/from_md/release-notes/rl-2111.section.xml +++ b/nixos/doc/manual/from_md/release-notes/rl-2111.section.xml @@ -232,6 +232,13 @@ <link linkend="opt-services.nats.enable">services.nats</link>. </para> </listitem> + <listitem> + <para> + <link xlink:href="https://git-scm.com">git</link>, a + distributed version control system. Available as + <link xlink:href="options.html#opt-programs.git.enable">programs.git</link>. + </para> + </listitem> </itemizedlist> </section> <section xml:id="sec-release-21.11-incompatibilities"> @@ -1143,6 +1150,13 @@ Superuser created successfully. other and share data. </para> </listitem> + <listitem> + <para> + <literal>lua</literal> and <literal>luajit</literal> + interpreters have been patched to avoid looking into /usr/lib + directories, thus increasing the purity of the build. + </para> + </listitem> </itemizedlist> </section> </section> diff --git a/nixos/doc/manual/installation/installation.xml b/nixos/doc/manual/installation/installation.xml index cc18a9c6e9ff..1d443bbd0ee1 100644 --- a/nixos/doc/manual/installation/installation.xml +++ b/nixos/doc/manual/installation/installation.xml @@ -11,7 +11,7 @@ </para> </partintro> <xi:include href="../from_md/installation/obtaining.chapter.xml" /> - <xi:include href="installing.xml" /> + <xi:include href="../from_md/installation/installing.chapter.xml" /> <xi:include href="../from_md/installation/changing-config.chapter.xml" /> <xi:include href="../from_md/installation/upgrading.chapter.xml" /> </part> diff --git a/nixos/doc/manual/installation/installing.chapter.md b/nixos/doc/manual/installation/installing.chapter.md new file mode 100644 index 000000000000..a0823b51e9cb --- /dev/null +++ b/nixos/doc/manual/installation/installing.chapter.md @@ -0,0 +1,479 @@ +# Installing NixOS {#sec-installation} + +## Booting the system {#sec-installation-booting} + +NixOS can be installed on BIOS or UEFI systems. The procedure for a UEFI +installation is by and large the same as a BIOS installation. The +differences are mentioned in the steps that follow. + +The installation media can be burned to a CD, or now more commonly, +"burned" to a USB drive (see [](#sec-booting-from-usb)). + +The installation media contains a basic NixOS installation. When it's +finished booting, it should have detected most of your hardware. + +The NixOS manual is available by running `nixos-help`. + +You are logged-in automatically as `nixos`. The `nixos` user account has +an empty password so you can use `sudo` without a password. + +If you downloaded the graphical ISO image, you can run `systemctl +start display-manager` to start the desktop environment. If you want +to continue on the terminal, you can use `loadkeys` to switch to your +preferred keyboard layout. (We even provide neo2 via `loadkeys de +neo`!) + +If the text is too small to be legible, try `setfont ter-v32n` to +increase the font size. + +To install over a serial port connect with `115200n8` (e.g. +`picocom -b 115200 /dev/ttyUSB0`). When the bootloader lists boot +entries, select the serial console boot entry. + +### Networking in the installer {#sec-installation-booting-networking} + +The boot process should have brought up networking (check `ip +a`). Networking is necessary for the installer, since it will +download lots of stuff (such as source tarballs or Nixpkgs channel +binaries). It's best if you have a DHCP server on your network. +Otherwise configure networking manually using `ifconfig`. + +On the graphical installer, you can configure the network, wifi +included, through NetworkManager. Using the `nmtui` program, you can do +so even in a non-graphical session. If you prefer to configure the +network manually, disable NetworkManager with +`systemctl stop NetworkManager`. + +On the minimal installer, NetworkManager is not available, so +configuration must be perfomed manually. To configure the wifi, first +start wpa_supplicant with `sudo systemctl start wpa_supplicant`, then +run `wpa_cli`. For most home networks, you need to type in the following +commands: + +```plain +> add_network +0 +> set_network 0 ssid "myhomenetwork" +OK +> set_network 0 psk "mypassword" +OK +> set_network 0 key_mgmt WPA-PSK +OK +> enable_network 0 +OK +``` + +For enterprise networks, for example *eduroam*, instead do: + +```plain +> add_network +0 +> set_network 0 ssid "eduroam" +OK +> set_network 0 identity "myname@example.com" +OK +> set_network 0 password "mypassword" +OK +> set_network 0 key_mgmt WPA-EAP +OK +> enable_network 0 +OK +``` + +When successfully connected, you should see a line such as this one + +```plain +<3>CTRL-EVENT-CONNECTED - Connection to 32:85:ab:ef:24:5c completed [id=0 id_str=] +``` + +you can now leave `wpa_cli` by typing `quit`. + +If you would like to continue the installation from a different machine +you can use activated SSH daemon. You need to copy your ssh key to +either `/home/nixos/.ssh/authorized_keys` or +`/root/.ssh/authorized_keys` (Tip: For installers with a modifiable +filesystem such as the sd-card installer image a key can be manually +placed by mounting the image on a different machine). Alternatively you +must set a password for either `root` or `nixos` with `passwd` to be +able to login. + +## Partitioning and formatting {#sec-installation-partitioning} + +The NixOS installer doesn't do any partitioning or formatting, so you +need to do that yourself. + +The NixOS installer ships with multiple partitioning tools. The examples +below use `parted`, but also provides `fdisk`, `gdisk`, `cfdisk`, and +`cgdisk`. + +The recommended partition scheme differs depending if the computer uses +*Legacy Boot* or *UEFI*. + +### UEFI (GPT) {#sec-installation-partitioning-UEFI} + +Here\'s an example partition scheme for UEFI, using `/dev/sda` as the +device. + +::: {.note} +You can safely ignore `parted`\'s informational message about needing to +update /etc/fstab. +::: + +1. Create a *GPT* partition table. + + ```ShellSession + # parted /dev/sda -- mklabel gpt + ``` + +2. Add the *root* partition. This will fill the disk except for the end + part, where the swap will live, and the space left in front (512MiB) + which will be used by the boot partition. + + ```ShellSession + # parted /dev/sda -- mkpart primary 512MiB -8GiB + ``` + +3. Next, add a *swap* partition. The size required will vary according + to needs, here a 8GiB one is created. + + ```ShellSession + # parted /dev/sda -- mkpart primary linux-swap -8GiB 100% + ``` + + ::: {.note} + The swap partition size rules are no different than for other Linux + distributions. + ::: + +4. Finally, the *boot* partition. NixOS by default uses the ESP (EFI + system partition) as its */boot* partition. It uses the initially + reserved 512MiB at the start of the disk. + + ```ShellSession + # parted /dev/sda -- mkpart ESP fat32 1MiB 512MiB + # parted /dev/sda -- set 3 esp on + ``` + +Once complete, you can follow with +[](#sec-installation-partitioning-formatting). + +### Legacy Boot (MBR) {#sec-installation-partitioning-MBR} + +Here\'s an example partition scheme for Legacy Boot, using `/dev/sda` as +the device. + +::: {.note} +You can safely ignore `parted`\'s informational message about needing to +update /etc/fstab. +::: + +1. Create a *MBR* partition table. + + ```ShellSession + # parted /dev/sda -- mklabel msdos + ``` + +2. Add the *root* partition. This will fill the the disk except for the + end part, where the swap will live. + + ```ShellSession + # parted /dev/sda -- mkpart primary 1MiB -8GiB + ``` + +3. Finally, add a *swap* partition. The size required will vary + according to needs, here a 8GiB one is created. + + ```ShellSession + # parted /dev/sda -- mkpart primary linux-swap -8GiB 100% + ``` + + ::: {.note} + The swap partition size rules are no different than for other Linux + distributions. + ::: + +Once complete, you can follow with +[](#sec-installation-partitioning-formatting). + +### Formatting {#sec-installation-partitioning-formatting} + +Use the following commands: + +- For initialising Ext4 partitions: `mkfs.ext4`. It is recommended + that you assign a unique symbolic label to the file system using the + option `-L label`, since this makes the file system configuration + independent from device changes. For example: + + ```ShellSession + # mkfs.ext4 -L nixos /dev/sda1 + ``` + +- For creating swap partitions: `mkswap`. Again it's recommended to + assign a label to the swap partition: `-L label`. For example: + + ```ShellSession + # mkswap -L swap /dev/sda2 + ``` + +- **UEFI systems** + + For creating boot partitions: `mkfs.fat`. Again it's recommended + to assign a label to the boot partition: `-n label`. For + example: + + ```ShellSession + # mkfs.fat -F 32 -n boot /dev/sda3 + ``` + +- For creating LVM volumes, the LVM commands, e.g., `pvcreate`, + `vgcreate`, and `lvcreate`. + +- For creating software RAID devices, use `mdadm`. + +## Installing {#sec-installation-installing} + +1. Mount the target file system on which NixOS should be installed on + `/mnt`, e.g. + + ```ShellSession + # mount /dev/disk/by-label/nixos /mnt + ``` + +2. **UEFI systems** + + Mount the boot file system on `/mnt/boot`, e.g. + + ```ShellSession + # mkdir -p /mnt/boot + # mount /dev/disk/by-label/boot /mnt/boot + ``` + +3. If your machine has a limited amount of memory, you may want to + activate swap devices now (`swapon device`). + The installer (or rather, the build actions that it + may spawn) may need quite a bit of RAM, depending on your + configuration. + + ```ShellSession + # swapon /dev/sda2 + ``` + +4. You now need to create a file `/mnt/etc/nixos/configuration.nix` + that specifies the intended configuration of the system. This is + because NixOS has a *declarative* configuration model: you create or + edit a description of the desired configuration of your system, and + then NixOS takes care of making it happen. The syntax of the NixOS + configuration file is described in [](#sec-configuration-syntax), + while a list of available configuration options appears in + [](#ch-options). A minimal example is shown in + [Example: NixOS Configuration](#ex-config). + + The command `nixos-generate-config` can generate an initial + configuration file for you: + + ```ShellSession + # nixos-generate-config --root /mnt + ``` + + You should then edit `/mnt/etc/nixos/configuration.nix` to suit your + needs: + + ```ShellSession + # nano /mnt/etc/nixos/configuration.nix + ``` + + If you're using the graphical ISO image, other editors may be + available (such as `vim`). If you have network access, you can also + install other editors -- for instance, you can install Emacs by + running `nix-env -f '<nixpkgs>' -iA emacs`. + + BIOS systems + + : You *must* set the option [](#opt-boot.loader.grub.device) to + specify on which disk the GRUB boot loader is to be installed. + Without it, NixOS cannot boot. + + UEFI systems + + : You *must* set the option [](#opt-boot.loader.systemd-boot.enable) + to `true`. `nixos-generate-config` should do this automatically + for new configurations when booted in UEFI mode. + + You may want to look at the options starting with + [`boot.loader.efi`](#opt-boot.loader.efi.canTouchEfiVariables) and + [`boot.loader.systemd-boot`](#opt-boot.loader.systemd-boot.enable) + as well. + + If there are other operating systems running on the machine before + installing NixOS, the [](#opt-boot.loader.grub.useOSProber) + option can be set to `true` to automatically add them to the grub + menu. + + If you need to configure networking for your machine the + configuration options are described in [](#sec-networking). In + particular, while wifi is supported on the installation image, it is + not enabled by default in the configuration generated by + `nixos-generate-config`. + + Another critical option is `fileSystems`, specifying the file + systems that need to be mounted by NixOS. However, you typically + don't need to set it yourself, because `nixos-generate-config` sets + it automatically in `/mnt/etc/nixos/hardware-configuration.nix` from + your currently mounted file systems. (The configuration file + `hardware-configuration.nix` is included from `configuration.nix` + and will be overwritten by future invocations of + `nixos-generate-config`; thus, you generally should not modify it.) + Additionally, you may want to look at [Hardware configuration for + known-hardware](https://github.com/NixOS/nixos-hardware) at this + point or after installation. + + ::: {.note} + Depending on your hardware configuration or type of file system, you + may need to set the option `boot.initrd.kernelModules` to include + the kernel modules that are necessary for mounting the root file + system, otherwise the installed system will not be able to boot. (If + this happens, boot from the installation media again, mount the + target file system on `/mnt`, fix `/mnt/etc/nixos/configuration.nix` + and rerun `nixos-install`.) In most cases, `nixos-generate-config` + will figure out the required modules. + ::: + +5. Do the installation: + + ```ShellSession + # nixos-install + ``` + + This will install your system based on the configuration you + provided. If anything fails due to a configuration problem or any + other issue (such as a network outage while downloading binaries + from the NixOS binary cache), you can re-run `nixos-install` after + fixing your `configuration.nix`. + + As the last step, `nixos-install` will ask you to set the password + for the `root` user, e.g. + + ```plain + setting root password... + New password: *** + Retype new password: *** + ``` + + ::: {.note} + For unattended installations, it is possible to use + `nixos-install --no-root-passwd` in order to disable the password + prompt entirely. + ::: + +6. If everything went well: + + ```ShellSession + # reboot + ``` + +7. You should now be able to boot into the installed NixOS. The GRUB + boot menu shows a list of *available configurations* (initially just + one). Every time you change the NixOS configuration (see [Changing + Configuration](#sec-changing-config)), a new item is added to the + menu. This allows you to easily roll back to a previous + configuration if something goes wrong. + + You should log in and change the `root` password with `passwd`. + + You'll probably want to create some user accounts as well, which can + be done with `useradd`: + + ```ShellSession + $ useradd -c 'Eelco Dolstra' -m eelco + $ passwd eelco + ``` + + You may also want to install some software. This will be covered in + [](#sec-package-management). + +## Installation summary {#sec-installation-summary} + +To summarise, [Example: Commands for Installing NixOS on `/dev/sda`](#ex-install-sequence) +shows a typical sequence of commands for installing NixOS on an empty hard +drive (here `/dev/sda`). [Example: NixOS Configuration](#ex-config) shows a +corresponding configuration Nix expression. + +::: {#ex-partition-scheme-MBR .example} +::: {.title} +**Example: Example partition schemes for NixOS on `/dev/sda` (MBR)** +::: +```ShellSession +# parted /dev/sda -- mklabel msdos +# parted /dev/sda -- mkpart primary 1MiB -8GiB +# parted /dev/sda -- mkpart primary linux-swap -8GiB 100% +``` +::: + +::: {#ex-partition-scheme-UEFI .example} +::: {.title} +**Example: Example partition schemes for NixOS on `/dev/sda` (UEFI)** +::: +```ShellSession +# parted /dev/sda -- mklabel gpt +# parted /dev/sda -- mkpart primary 512MiB -8GiB +# parted /dev/sda -- mkpart primary linux-swap -8GiB 100% +# parted /dev/sda -- mkpart ESP fat32 1MiB 512MiB +# parted /dev/sda -- set 3 esp on +``` +::: + +::: {#ex-install-sequence .example} +::: {.title} +**Example: Commands for Installing NixOS on `/dev/sda`** +::: +With a partitioned disk. + +```ShellSession +# mkfs.ext4 -L nixos /dev/sda1 +# mkswap -L swap /dev/sda2 +# swapon /dev/sda2 +# mkfs.fat -F 32 -n boot /dev/sda3 # (for UEFI systems only) +# mount /dev/disk/by-label/nixos /mnt +# mkdir -p /mnt/boot # (for UEFI systems only) +# mount /dev/disk/by-label/boot /mnt/boot # (for UEFI systems only) +# nixos-generate-config --root /mnt +# nano /mnt/etc/nixos/configuration.nix +# nixos-install +# reboot +``` +::: + +::: {#ex-config .example} +::: {.title} +**Example: NixOS Configuration** +::: +```ShellSession +{ config, pkgs, ... }: { + imports = [ + # Include the results of the hardware scan. + ./hardware-configuration.nix + ]; + + boot.loader.grub.device = "/dev/sda"; # (for BIOS systems only) + boot.loader.systemd-boot.enable = true; # (for UEFI systems only) + + # Note: setting fileSystems is generally not + # necessary, since nixos-generate-config figures them out + # automatically in hardware-configuration.nix. + #fileSystems."/".device = "/dev/disk/by-label/nixos"; + + # Enable the OpenSSH server. + services.sshd.enable = true; +} +``` +::: + +## Additional installation notes {#sec-installation-additional-notes} + +```{=docbook} +<xi:include href="installing-usb.section.xml" /> +<xi:include href="installing-pxe.section.xml" /> +<xi:include href="installing-virtualbox-guest.section.xml" /> +<xi:include href="installing-from-other-distro.section.xml" /> +<xi:include href="installing-behind-a-proxy.section.xml" /> +``` diff --git a/nixos/doc/manual/installation/installing.xml b/nixos/doc/manual/installation/installing.xml deleted file mode 100644 index 6eb097f243ab..000000000000 --- a/nixos/doc/manual/installation/installing.xml +++ /dev/null @@ -1,616 +0,0 @@ -<chapter xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="sec-installation"> - <title>Installing NixOS</title> - <section xml:id="sec-installation-booting"> - <title>Booting the system</title> - - <para> - NixOS can be installed on BIOS or UEFI systems. The procedure for a UEFI - installation is by and large the same as a BIOS installation. The - differences are mentioned in the steps that follow. - </para> - - <para> - The installation media can be burned to a CD, or now more commonly, "burned" - to a USB drive (see <xref linkend="sec-booting-from-usb"/>). - </para> - - <para> - The installation media contains a basic NixOS installation. When it’s - finished booting, it should have detected most of your hardware. - </para> - - <para> - The NixOS manual is available by running <command>nixos-help</command>. - </para> - - <para> - You are logged-in automatically as <literal>nixos</literal>. - The <literal>nixos</literal> user account has an empty password so you - can use <command>sudo</command> without a password. - </para> - - <para> - If you downloaded the graphical ISO image, you can run <command>systemctl - start display-manager</command> to start the desktop environment. If you want to continue on the - terminal, you can use <command>loadkeys</command> to switch to your - preferred keyboard layout. (We even provide neo2 via <command>loadkeys de - neo</command>!) - </para> - - <para> - If the text is too small to be legible, try <command>setfont ter-v32n</command> - to increase the font size. - </para> - - <para> - To install over a serial port connect with <literal>115200n8</literal> - (e.g. <command>picocom -b 115200 /dev/ttyUSB0</command>). When the - bootloader lists boot entries, select the serial console boot entry. - </para> - - <section xml:id="sec-installation-booting-networking"> - <title>Networking in the installer</title> - - <para> - The boot process should have brought up networking (check <command>ip - a</command>). Networking is necessary for the installer, since it will - download lots of stuff (such as source tarballs or Nixpkgs channel - binaries). It’s best if you have a DHCP server on your network. Otherwise - configure networking manually using <command>ifconfig</command>. - </para> - - <para> - On the graphical installer, you can configure the network, wifi included, - through NetworkManager. Using the <command>nmtui</command> program, you - can do so even in a non-graphical session. If you prefer to configure the - network manually, disable NetworkManager with - <command>systemctl stop NetworkManager</command>. - </para> - - <para> - On the minimal installer, NetworkManager is not available, so configuration - must be perfomed manually. To configure the wifi, first start wpa_supplicant - with <command>sudo systemctl start wpa_supplicant</command>, then run - <command>wpa_cli</command>. For most home networks, you need to type - in the following commands: - <programlisting> -<prompt>> </prompt>add_network -0 -<prompt>> </prompt>set_network 0 ssid "myhomenetwork" -OK -<prompt>> </prompt>set_network 0 psk "mypassword" -OK -<prompt>> </prompt>set_network 0 key_mgmt WPA-PSK -OK -<prompt>> </prompt>enable_network 0 -OK - </programlisting> - For enterprise networks, for example <emphasis>eduroam</emphasis>, instead do: - <programlisting> -<prompt>> </prompt>add_network -0 -<prompt>> </prompt>set_network 0 ssid "eduroam" -OK -<prompt>> </prompt>set_network 0 identity "myname@example.com" -OK -<prompt>> </prompt>set_network 0 password "mypassword" -OK -<prompt>> </prompt>set_network 0 key_mgmt WPA-EAP -OK -<prompt>> </prompt>enable_network 0 -OK - </programlisting> - When successfully connected, you should see a line such as this one - <programlisting> -<3>CTRL-EVENT-CONNECTED - Connection to 32:85:ab:ef:24:5c completed [id=0 id_str=] - </programlisting> - you can now leave <command>wpa_cli</command> by typing <command>quit</command>. - </para> - - <para> - If you would like to continue the installation from a different machine you - can use activated SSH daemon. You need to copy your ssh key to either - <literal>/home/nixos/.ssh/authorized_keys</literal> or - <literal>/root/.ssh/authorized_keys</literal> (Tip: For installers with a - modifiable filesystem such as the sd-card installer image a key can be manually - placed by mounting the image on a different machine). Alternatively you must set - a password for either <literal>root</literal> or <literal>nixos</literal> with - <command>passwd</command> to be able to login. - </para> - </section> - </section> - <section xml:id="sec-installation-partitioning"> - <title>Partitioning and formatting</title> - - <para> - The NixOS installer doesn’t do any partitioning or formatting, so you need - to do that yourself. - </para> - - <para> - The NixOS installer ships with multiple partitioning tools. The examples - below use <command>parted</command>, but also provides - <command>fdisk</command>, <command>gdisk</command>, - <command>cfdisk</command>, and <command>cgdisk</command>. - </para> - - <para> - The recommended partition scheme differs depending if the computer uses - <emphasis>Legacy Boot</emphasis> or <emphasis>UEFI</emphasis>. - </para> - - <section xml:id="sec-installation-partitioning-UEFI"> - <title>UEFI (GPT)</title> - - <para> - Here's an example partition scheme for UEFI, using - <filename>/dev/sda</filename> as the device. - <note> - <para> - You can safely ignore <command>parted</command>'s informational message - about needing to update /etc/fstab. - </para> - </note> - </para> - - <para> - <orderedlist> - <listitem> - <para> - Create a <emphasis>GPT</emphasis> partition table. -<screen language="commands"><prompt># </prompt>parted /dev/sda -- mklabel gpt</screen> - </para> - </listitem> - <listitem> - <para> - Add the <emphasis>root</emphasis> partition. This will fill the disk - except for the end part, where the swap will live, and the space left in - front (512MiB) which will be used by the boot partition. -<screen language="commands"><prompt># </prompt>parted /dev/sda -- mkpart primary 512MiB -8GiB</screen> - </para> - </listitem> - <listitem> - <para> - Next, add a <emphasis>swap</emphasis> partition. The size required will - vary according to needs, here a 8GiB one is created. -<screen language="commands"><prompt># </prompt>parted /dev/sda -- mkpart primary linux-swap -8GiB 100%</screen> - <note> - <para> - The swap partition size rules are no different than for other Linux - distributions. - </para> - </note> - </para> - </listitem> - <listitem> - <para> - Finally, the <emphasis>boot</emphasis> partition. NixOS by default uses - the ESP (EFI system partition) as its <emphasis>/boot</emphasis> - partition. It uses the initially reserved 512MiB at the start of the - disk. -<screen language="commands"><prompt># </prompt>parted /dev/sda -- mkpart ESP fat32 1MiB 512MiB -<prompt># </prompt>parted /dev/sda -- set 3 esp on</screen> - </para> - </listitem> - </orderedlist> - </para> - - <para> - Once complete, you can follow with - <xref linkend="sec-installation-partitioning-formatting"/>. - </para> - </section> - - <section xml:id="sec-installation-partitioning-MBR"> - <title>Legacy Boot (MBR)</title> - - <para> - Here's an example partition scheme for Legacy Boot, using - <filename>/dev/sda</filename> as the device. - <note> - <para> - You can safely ignore <command>parted</command>'s informational message - about needing to update /etc/fstab. - </para> - </note> - </para> - - <para> - <orderedlist> - <listitem> - <para> - Create a <emphasis>MBR</emphasis> partition table. -<screen language="commands"><prompt># </prompt>parted /dev/sda -- mklabel msdos</screen> - </para> - </listitem> - <listitem> - <para> - Add the <emphasis>root</emphasis> partition. This will fill the the disk - except for the end part, where the swap will live. -<screen language="commands"><prompt># </prompt>parted /dev/sda -- mkpart primary 1MiB -8GiB</screen> - </para> - </listitem> - <listitem> - <para> - Finally, add a <emphasis>swap</emphasis> partition. The size required - will vary according to needs, here a 8GiB one is created. -<screen language="commands"><prompt># </prompt>parted /dev/sda -- mkpart primary linux-swap -8GiB 100%</screen> - <note> - <para> - The swap partition size rules are no different than for other Linux - distributions. - </para> - </note> - </para> - </listitem> - </orderedlist> - </para> - - <para> - Once complete, you can follow with - <xref linkend="sec-installation-partitioning-formatting"/>. - </para> - </section> - - <section xml:id="sec-installation-partitioning-formatting"> - <title>Formatting</title> - - <para> - Use the following commands: - <itemizedlist> - <listitem> - <para> - For initialising Ext4 partitions: <command>mkfs.ext4</command>. It is - recommended that you assign a unique symbolic label to the file system - using the option <option>-L <replaceable>label</replaceable></option>, - since this makes the file system configuration independent from device - changes. For example: -<screen> -<prompt># </prompt>mkfs.ext4 -L nixos /dev/sda1</screen> - </para> - </listitem> - <listitem> - <para> - For creating swap partitions: <command>mkswap</command>. Again it’s - recommended to assign a label to the swap partition: <option>-L - <replaceable>label</replaceable></option>. For example: -<screen> -<prompt># </prompt>mkswap -L swap /dev/sda2</screen> - </para> - </listitem> - <listitem> - <variablelist> - <varlistentry> - <term> - UEFI systems - </term> - <listitem> - <para> - For creating boot partitions: <command>mkfs.fat</command>. Again - it’s recommended to assign a label to the boot partition: - <option>-n <replaceable>label</replaceable></option>. For example: -<screen> -<prompt># </prompt>mkfs.fat -F 32 -n boot /dev/sda3</screen> - </para> - </listitem> - </varlistentry> - </variablelist> - </listitem> - <listitem> - <para> - For creating LVM volumes, the LVM commands, e.g., - <command>pvcreate</command>, <command>vgcreate</command>, and - <command>lvcreate</command>. - </para> - </listitem> - <listitem> - <para> - For creating software RAID devices, use <command>mdadm</command>. - </para> - </listitem> - </itemizedlist> - </para> - </section> - </section> - <section xml:id="sec-installation-installing"> - <title>Installing</title> - - <orderedlist> - <listitem> - <para> - Mount the target file system on which NixOS should be installed on - <filename>/mnt</filename>, e.g. -<screen> -<prompt># </prompt>mount /dev/disk/by-label/nixos /mnt -</screen> - </para> - </listitem> - <listitem> - <variablelist> - <varlistentry> - <term> - UEFI systems - </term> - <listitem> - <para> - Mount the boot file system on <filename>/mnt/boot</filename>, e.g. -<screen> -<prompt># </prompt>mkdir -p /mnt/boot -<prompt># </prompt>mount /dev/disk/by-label/boot /mnt/boot -</screen> - </para> - </listitem> - </varlistentry> - </variablelist> - </listitem> - <listitem> - <para> - If your machine has a limited amount of memory, you may want to activate - swap devices now (<command>swapon - <replaceable>device</replaceable></command>). The installer (or rather, - the build actions that it may spawn) may need quite a bit of RAM, - depending on your configuration. -<screen> -<prompt># </prompt>swapon /dev/sda2</screen> - </para> - </listitem> - <listitem> - <para> - You now need to create a file - <filename>/mnt/etc/nixos/configuration.nix</filename> that specifies the - intended configuration of the system. This is because NixOS has a - <emphasis>declarative</emphasis> configuration model: you create or edit a - description of the desired configuration of your system, and then NixOS - takes care of making it happen. The syntax of the NixOS configuration file - is described in <xref linkend="sec-configuration-syntax"/>, while a list - of available configuration options appears in - <xref - linkend="ch-options"/>. A minimal example is shown in - <xref - linkend="ex-config"/>. - </para> - <para> - The command <command>nixos-generate-config</command> can generate an - initial configuration file for you: -<screen> -<prompt># </prompt>nixos-generate-config --root /mnt</screen> - You should then edit <filename>/mnt/etc/nixos/configuration.nix</filename> - to suit your needs: -<screen> -<prompt># </prompt>nano /mnt/etc/nixos/configuration.nix -</screen> - If you’re using the graphical ISO image, other editors may be available - (such as <command>vim</command>). If you have network access, you can also - install other editors — for instance, you can install Emacs by running - <literal>nix-env -f '<nixpkgs>' -iA emacs</literal>. - </para> - <variablelist> - <varlistentry> - <term> - BIOS systems - </term> - <listitem> - <para> - You <emphasis>must</emphasis> set the option - <xref linkend="opt-boot.loader.grub.device"/> to specify on which disk - the GRUB boot loader is to be installed. Without it, NixOS cannot boot. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - UEFI systems - </term> - <listitem> - <para> - You <emphasis>must</emphasis> set the option - <xref linkend="opt-boot.loader.systemd-boot.enable"/> to - <literal>true</literal>. <command>nixos-generate-config</command> - should do this automatically for new configurations when booted in UEFI - mode. - </para> - <para> - You may want to look at the options starting with - <option><link linkend="opt-boot.loader.efi.canTouchEfiVariables">boot.loader.efi</link></option> - and - <option><link linkend="opt-boot.loader.systemd-boot.enable">boot.loader.systemd-boot</link></option> - as well. - </para> - </listitem> - </varlistentry> - </variablelist> - <para> - If there are other operating systems running on the machine before - installing NixOS, the <xref linkend="opt-boot.loader.grub.useOSProber"/> - option can be set to <literal>true</literal> to automatically add them to - the grub menu. - </para> - <para> - If you need to configure networking for your machine the configuration - options are described in <xref linkend="sec-networking"/>. In particular, - while wifi is supported on the installation image, it is not enabled by - default in the configuration generated by - <command>nixos-generate-config</command>. - </para> - <para> - Another critical option is <option>fileSystems</option>, specifying the - file systems that need to be mounted by NixOS. However, you typically - don’t need to set it yourself, because - <command>nixos-generate-config</command> sets it automatically in - <filename>/mnt/etc/nixos/hardware-configuration.nix</filename> from your - currently mounted file systems. (The configuration file - <filename>hardware-configuration.nix</filename> is included from - <filename>configuration.nix</filename> and will be overwritten by future - invocations of <command>nixos-generate-config</command>; thus, you - generally should not modify it.) Additionally, you may want to look at - <link xlink:href="https://github.com/NixOS/nixos-hardware">Hardware - configuration for known-hardware</link> at this point or after - installation. - - </para> - <note> - <para> - Depending on your hardware configuration or type of file system, you may - need to set the option <option>boot.initrd.kernelModules</option> to - include the kernel modules that are necessary for mounting the root file - system, otherwise the installed system will not be able to boot. (If this - happens, boot from the installation media again, mount the target file - system on <filename>/mnt</filename>, fix - <filename>/mnt/etc/nixos/configuration.nix</filename> and rerun - <filename>nixos-install</filename>.) In most cases, - <command>nixos-generate-config</command> will figure out the required - modules. - </para> - </note> - </listitem> - <listitem> - <para> - Do the installation: -<screen> -<prompt># </prompt>nixos-install</screen> - This will install your system based on the configuration you provided. - If anything fails due to a configuration problem or any other issue - (such as a network outage while downloading binaries from the NixOS - binary cache), you can re-run <command>nixos-install</command> after - fixing your <filename>configuration.nix</filename>. - </para> - <para> - As the last step, <command>nixos-install</command> will ask you to set the - password for the <literal>root</literal> user, e.g. -<screen> -setting root password... -New password: *** -Retype new password: ***</screen> - <note> - <para> - For unattended installations, it is possible to use - <command>nixos-install --no-root-passwd</command> in order to disable - the password prompt entirely. - </para> - </note> - </para> - </listitem> - <listitem> - <para> - If everything went well: -<screen> -<prompt># </prompt>reboot</screen> - </para> - </listitem> - <listitem> - <para> - You should now be able to boot into the installed NixOS. The GRUB boot - menu shows a list of <emphasis>available configurations</emphasis> - (initially just one). Every time you change the NixOS configuration (see - <link - linkend="sec-changing-config">Changing Configuration</link> - ), a new item is added to the menu. This allows you to easily roll back to - a previous configuration if something goes wrong. - </para> - <para> - You should log in and change the <literal>root</literal> password with - <command>passwd</command>. - </para> - <para> - You’ll probably want to create some user accounts as well, which can be - done with <command>useradd</command>: -<screen> -<prompt>$ </prompt>useradd -c 'Eelco Dolstra' -m eelco -<prompt>$ </prompt>passwd eelco</screen> - </para> - <para> - You may also want to install some software. This will be covered - in <xref linkend="sec-package-management" />. - </para> - </listitem> - </orderedlist> - </section> - <section xml:id="sec-installation-summary"> - <title>Installation summary</title> - - <para> - To summarise, <xref linkend="ex-install-sequence" /> shows a typical - sequence of commands for installing NixOS on an empty hard drive (here - <filename>/dev/sda</filename>). <xref linkend="ex-config" -/> shows a - corresponding configuration Nix expression. - </para> - - <example xml:id="ex-partition-scheme-MBR"> - <title>Example partition schemes for NixOS on <filename>/dev/sda</filename> (MBR)</title> -<screen language="commands"> -<prompt># </prompt>parted /dev/sda -- mklabel msdos -<prompt># </prompt>parted /dev/sda -- mkpart primary 1MiB -8GiB -<prompt># </prompt>parted /dev/sda -- mkpart primary linux-swap -8GiB 100%</screen> - </example> - - <example xml:id="ex-partition-scheme-UEFI"> - <title>Example partition schemes for NixOS on <filename>/dev/sda</filename> (UEFI)</title> -<screen language="commands"> -<prompt># </prompt>parted /dev/sda -- mklabel gpt -<prompt># </prompt>parted /dev/sda -- mkpart primary 512MiB -8GiB -<prompt># </prompt>parted /dev/sda -- mkpart primary linux-swap -8GiB 100% -<prompt># </prompt>parted /dev/sda -- mkpart ESP fat32 1MiB 512MiB -<prompt># </prompt>parted /dev/sda -- set 3 esp on</screen> - </example> - - <example xml:id="ex-install-sequence"> - <title>Commands for Installing NixOS on <filename>/dev/sda</filename></title> - <para> - With a partitioned disk. -<screen language="commands"> -<prompt># </prompt>mkfs.ext4 -L nixos /dev/sda1 -<prompt># </prompt>mkswap -L swap /dev/sda2 -<prompt># </prompt>swapon /dev/sda2 -<prompt># </prompt>mkfs.fat -F 32 -n boot /dev/sda3 # <lineannotation>(for UEFI systems only)</lineannotation> -<prompt># </prompt>mount /dev/disk/by-label/nixos /mnt -<prompt># </prompt>mkdir -p /mnt/boot # <lineannotation>(for UEFI systems only)</lineannotation> -<prompt># </prompt>mount /dev/disk/by-label/boot /mnt/boot # <lineannotation>(for UEFI systems only)</lineannotation> -<prompt># </prompt>nixos-generate-config --root /mnt -<prompt># </prompt>nano /mnt/etc/nixos/configuration.nix -<prompt># </prompt>nixos-install -<prompt># </prompt>reboot</screen> - </para> - </example> - - <example xml:id='ex-config'> - <title>NixOS Configuration</title> -<programlisting> -{ config, pkgs, ... }: { - imports = [ - # Include the results of the hardware scan. - ./hardware-configuration.nix - ]; - - <xref linkend="opt-boot.loader.grub.device"/> = "/dev/sda"; # <lineannotation>(for BIOS systems only)</lineannotation> - <xref linkend="opt-boot.loader.systemd-boot.enable"/> = true; # <lineannotation>(for UEFI systems only)</lineannotation> - - # Note: setting fileSystems is generally not - # necessary, since nixos-generate-config figures them out - # automatically in hardware-configuration.nix. - #<link linkend="opt-fileSystems._name_.device">fileSystems."/".device</link> = "/dev/disk/by-label/nixos"; - - # Enable the OpenSSH server. - services.sshd.enable = true; -} -</programlisting> - </example> - </section> - <section xml:id="sec-installation-additional-notes"> - <title>Additional installation notes</title> - - <xi:include href="../from_md/installation/installing-usb.section.xml" /> - - <xi:include href="../from_md/installation/installing-pxe.section.xml" /> - - <xi:include href="../from_md/installation/installing-virtualbox-guest.section.xml" /> - - <xi:include href="../from_md/installation/installing-from-other-distro.section.xml" /> - - <xi:include href="../from_md/installation/installing-behind-a-proxy.section.xml" /> - </section> -</chapter> diff --git a/nixos/doc/manual/release-notes/rl-2111.section.md b/nixos/doc/manual/release-notes/rl-2111.section.md index 00844d529b77..3dc15449c772 100644 --- a/nixos/doc/manual/release-notes/rl-2111.section.md +++ b/nixos/doc/manual/release-notes/rl-2111.section.md @@ -71,6 +71,8 @@ subsonic-compatible api. Available as [navidrome](#opt-services.navidrome.enable - [nats](https://nats.io/), a high performance cloud and edge messaging system. Available as [services.nats](#opt-services.nats.enable). +- [git](https://git-scm.com), a distributed version control system. Available as [programs.git](options.html#opt-programs.git.enable). + ## Backward Incompatibilities {#sec-release-21.11-incompatibilities} @@ -326,3 +328,6 @@ To be able to access the web UI this port needs to be opened in the firewall. - `rofi` has been updated from '1.6.1' to '1.7.0', one important thing is the removal of the old xresources based configuration setup. Read more [in rofi's changelog](https://github.com/davatorium/rofi/blob/cb12e6fc058f4a0f4f/Changelog#L1). - ipfs now defaults to not listening on you local network. This setting was change as server providers won't accept port scanning on their private network. If you have several ipfs instances running on a network you own, feel free to change the setting `ipfs.localDiscovery = true;`. localDiscovery enables different instances to discover each other and share data. + +- `lua` and `luajit` interpreters have been patched to avoid looking into /usr/lib + directories, thus increasing the purity of the build. diff --git a/nixos/modules/module-list.nix b/nixos/modules/module-list.nix index 1998a309035b..76cc4411baba 100644 --- a/nixos/modules/module-list.nix +++ b/nixos/modules/module-list.nix @@ -145,6 +145,7 @@ ./programs/fuse.nix ./programs/gamemode.nix ./programs/geary.nix + ./programs/git.nix ./programs/gnome-disks.nix ./programs/gnome-documents.nix ./programs/gnome-terminal.nix @@ -873,7 +874,6 @@ ./services/networking/wasabibackend.nix ./services/networking/websockify.nix ./services/networking/wg-quick.nix - ./services/networking/wicd.nix ./services/networking/wireguard.nix ./services/networking/wpa_supplicant.nix ./services/networking/xandikos.nix diff --git a/nixos/modules/programs/git.nix b/nixos/modules/programs/git.nix new file mode 100644 index 000000000000..4e06b576f896 --- /dev/null +++ b/nixos/modules/programs/git.nix @@ -0,0 +1,45 @@ +{ config, lib, pkgs, ... }: + +with lib; + +let + cfg = config.programs.git; +in + +{ + options = { + programs.git = { + enable = mkEnableOption "git"; + + package = mkOption { + type = types.package; + default = pkgs.git; + defaultText = "pkgs.git"; + example = literalExample "pkgs.gitFull"; + description = "The git package to use"; + }; + + config = mkOption { + type = types.attrs; + default = { }; + example = { + init.defaultBranch = "main"; + url."https://github.com/".insteadOf = [ "gh:" "github:" ]; + }; + description = '' + Configuration to write to /etc/gitconfig. See the CONFIGURATION FILE + section of git-config(1) for more information. + ''; + }; + }; + }; + + config = mkIf cfg.enable { + environment.systemPackages = [ cfg.package ]; + environment.etc.gitconfig = mkIf (cfg.config != {}) { + text = generators.toGitINI cfg.config; + }; + }; + + meta.maintainers = with maintainers; [ figsoda ]; +} diff --git a/nixos/modules/rename.nix b/nixos/modules/rename.nix index 233e3ee848be..4db6efb75d82 100644 --- a/nixos/modules/rename.nix +++ b/nixos/modules/rename.nix @@ -27,6 +27,7 @@ with lib; (mkRemovedOptionModule [ "services" "mesos" ] "The corresponding package was removed from nixpkgs.") (mkRemovedOptionModule [ "services" "winstone" ] "The corresponding package was removed from nixpkgs.") (mkRemovedOptionModule [ "networking" "vpnc" ] "Use environment.etc.\"vpnc/service.conf\" instead.") + (mkRemovedOptionModule [ "networking" "wicd" ] "The corresponding package was removed from nixpkgs.") (mkRemovedOptionModule [ "environment" "blcr" "enable" ] "The BLCR module has been removed") (mkRemovedOptionModule [ "services" "beegfsEnable" ] "The BeeGFS module has been removed") (mkRemovedOptionModule [ "services" "beegfs" ] "The BeeGFS module has been removed") diff --git a/nixos/modules/services/amqp/rabbitmq.nix b/nixos/modules/services/amqp/rabbitmq.nix index 8fdfda9a66d8..dabd80312d9d 100644 --- a/nixos/modules/services/amqp/rabbitmq.nix +++ b/nixos/modules/services/amqp/rabbitmq.nix @@ -135,25 +135,14 @@ in description = "The list of directories containing external plugins"; }; - managementPlugin = mkOption { - description = "The options to run the management plugin"; - type = types.submodule { - options = { - enable = mkOption { - default = false; - type = types.bool; - description = '' - Whether to enable the management plugin - ''; - }; - port = mkOption { - default = 15672; - type = types.port; - description = '' - On which port to run the management plugin - ''; - }; - }; + managementPlugin = { + enable = mkEnableOption "the management plugin"; + port = mkOption { + default = 15672; + type = types.port; + description = '' + On which port to run the management plugin + ''; }; }; }; diff --git a/nixos/modules/services/cluster/kubernetes/kubelet.nix b/nixos/modules/services/cluster/kubernetes/kubelet.nix index 08f5cdfdf334..51b2b5f6eb0d 100644 --- a/nixos/modules/services/cluster/kubernetes/kubelet.nix +++ b/nixos/modules/services/cluster/kubernetes/kubelet.nix @@ -343,7 +343,7 @@ in }; # Allways include cni plugins - services.kubernetes.kubelet.cni.packages = [pkgs.cni-plugins]; + services.kubernetes.kubelet.cni.packages = [pkgs.cni-plugins pkgs.cni-plugin-flannel]; boot.kernelModules = ["br_netfilter" "overlay"]; diff --git a/nixos/modules/services/logging/promtail.nix b/nixos/modules/services/logging/promtail.nix index 34211687dc1d..95c83796ece6 100644 --- a/nixos/modules/services/logging/promtail.nix +++ b/nixos/modules/services/logging/promtail.nix @@ -7,6 +7,9 @@ let ''; allowSystemdJournal = cfg.configuration ? scrape_configs && lib.any (v: v ? journal) cfg.configuration.scrape_configs; + + allowPositionsFile = !lib.hasPrefix "/var/cache/promtail" positionsFile; + positionsFile = cfg.configuration.positions.filename; in { options.services.promtail = with types; { enable = mkEnableOption "the Promtail ingresser"; @@ -53,6 +56,7 @@ in { RestrictSUIDSGID = true; PrivateMounts = true; CacheDirectory = "promtail"; + ReadWritePaths = lib.optional allowPositionsFile (builtins.dirOf positionsFile); User = "promtail"; Group = "promtail"; diff --git a/nixos/modules/services/networking/wicd.nix b/nixos/modules/services/networking/wicd.nix deleted file mode 100644 index aa10a50f876a..000000000000 --- a/nixos/modules/services/networking/wicd.nix +++ /dev/null @@ -1,40 +0,0 @@ -{ config, lib, pkgs, ... }: - -with lib; - -{ - - ###### interface - - options = { - - networking.wicd.enable = mkOption { - type = types.bool; - default = false; - description = '' - Whether to start <command>wicd</command>. Wired and - wireless network configurations can then be managed by - wicd-client. - ''; - }; - }; - - - ###### implementation - - config = mkIf config.networking.wicd.enable { - - environment.systemPackages = [pkgs.wicd]; - - systemd.services.wicd = { - after = [ "network-pre.target" ]; - before = [ "network.target" ]; - wants = [ "network.target" ]; - wantedBy = [ "multi-user.target" ]; - script = "${pkgs.wicd}/sbin/wicd -f"; - }; - - services.dbus.enable = true; - services.dbus.packages = [pkgs.wicd]; - }; -} diff --git a/nixos/modules/services/security/privacyidea.nix b/nixos/modules/services/security/privacyidea.nix index 63271848e943..5f894d0fa691 100644 --- a/nixos/modules/services/security/privacyidea.nix +++ b/nixos/modules/services/security/privacyidea.nix @@ -228,7 +228,7 @@ in path = with pkgs; [ openssl ]; environment.PRIVACYIDEA_CONFIGFILE = "${cfg.stateDir}/privacyidea.cfg"; preStart = let - pi-manage = "${pkgs.sudo}/bin/sudo -u privacyidea -HE ${penv}/bin/pi-manage"; + pi-manage = "${config.security.sudo.package}/bin/sudo -u privacyidea -HE ${penv}/bin/pi-manage"; pgsu = config.services.postgresql.superUser; psql = config.services.postgresql.package; in '' @@ -239,8 +239,8 @@ in -i "${piCfgFile}" chown ${cfg.user}:${cfg.group} ${cfg.stateDir}/privacyidea.cfg if ! test -e "${cfg.stateDir}/db-created"; then - ${pkgs.sudo}/bin/sudo -u ${pgsu} ${psql}/bin/createuser --no-superuser --no-createdb --no-createrole ${cfg.user} - ${pkgs.sudo}/bin/sudo -u ${pgsu} ${psql}/bin/createdb --owner ${cfg.user} privacyidea + ${config.security.sudo.package}/bin/sudo -u ${pgsu} ${psql}/bin/createuser --no-superuser --no-createdb --no-createrole ${cfg.user} + ${config.security.sudo.package}/bin/sudo -u ${pgsu} ${psql}/bin/createdb --owner ${cfg.user} privacyidea ${pi-manage} create_enckey ${pi-manage} create_audit_keys ${pi-manage} createdb diff --git a/nixos/tests/handbrake.nix b/nixos/tests/handbrake.nix index 226dc8b2aa8a..c92fb5db7d6c 100644 --- a/nixos/tests/handbrake.nix +++ b/nixos/tests/handbrake.nix @@ -9,7 +9,7 @@ in { name = "handbrake"; meta = { - maintainers = with pkgs.lib.maintainers; [ danieldk ]; + maintainers = with pkgs.lib.maintainers; [ ]; }; machine = { pkgs, ... }: { |