From 5aaeddee5f2da59e5664d5c215ff08cfb6a6f252 Mon Sep 17 00:00:00 2001 From: Bobby Rong Date: Wed, 8 Sep 2021 14:40:26 +0800 Subject: [PATCH 01/11] nixos: nixos/doc/manual/administration/containers.xml to CommonMark --- .../administration/containers.chapter.md | 28 +++++++++++++++ .../doc/manual/administration/containers.xml | 34 ------------------- nixos/doc/manual/administration/running.xml | 2 +- .../administration/containers.chapter.xml | 31 +++++++++++++++++ 4 files changed, 60 insertions(+), 35 deletions(-) create mode 100644 nixos/doc/manual/administration/containers.chapter.md delete mode 100644 nixos/doc/manual/administration/containers.xml create mode 100644 nixos/doc/manual/from_md/administration/containers.chapter.xml 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} + + + +``` 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 @@ - - Container Management - - 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. - - - - 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. - - - - - diff --git a/nixos/doc/manual/administration/running.xml b/nixos/doc/manual/administration/running.xml index 24fd864956ff..7d0d56726226 100644 --- a/nixos/doc/manual/administration/running.xml +++ b/nixos/doc/manual/administration/running.xml @@ -16,6 +16,6 @@ - + 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 @@ + + Container Management + + 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. + + + + 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. + + + + + From 3d711cfc5e1205672dd6808909773dba8c26fe34 Mon Sep 17 00:00:00 2001 From: Bobby Rong Date: Wed, 8 Sep 2021 14:42:23 +0800 Subject: [PATCH 02/11] nixos: nixos/doc/manual/administration/troubleshooting.xml to CommonMark --- nixos/doc/manual/administration/running.xml | 2 +- .../administration/troubleshooting.chapter.md | 12 ++++++++++++ .../manual/administration/troubleshooting.xml | 16 ---------------- .../administration/troubleshooting.chapter.xml | 12 ++++++++++++ 4 files changed, 25 insertions(+), 17 deletions(-) create mode 100644 nixos/doc/manual/administration/troubleshooting.chapter.md delete mode 100644 nixos/doc/manual/administration/troubleshooting.xml create mode 100644 nixos/doc/manual/from_md/administration/troubleshooting.chapter.xml diff --git a/nixos/doc/manual/administration/running.xml b/nixos/doc/manual/administration/running.xml index 7d0d56726226..d9fcc1aee263 100644 --- a/nixos/doc/manual/administration/running.xml +++ b/nixos/doc/manual/administration/running.xml @@ -17,5 +17,5 @@ - + 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} + + + + + +``` 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 @@ - - Troubleshooting - - This chapter describes solutions to common problems you might encounter when - you manage your NixOS system. - - - - - - - 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 @@ + + Troubleshooting + + This chapter describes solutions to common problems you might + encounter when you manage your NixOS system. + + + + + + + From 8ce611b9fb664b6860b55f003d0b42a1dd0ab8e9 Mon Sep 17 00:00:00 2001 From: Bobby Rong Date: Wed, 8 Sep 2021 15:47:05 +0800 Subject: [PATCH 03/11] nixos: nixos/doc/manual/configuration/declarative-packages.xml to CommonMark --- .../declarative-packages.section.md | 46 ++++++++++++++++ .../configuration/declarative-packages.xml | 54 ------------------- .../doc/manual/configuration/package-mgmt.xml | 2 +- .../declarative-packages.section.xml | 53 ++++++++++++++++++ 4 files changed, 100 insertions(+), 55 deletions(-) create mode 100644 nixos/doc/manual/configuration/declarative-packages.section.md delete mode 100644 nixos/doc/manual/configuration/declarative-packages.xml create mode 100644 nixos/doc/manual/from_md/configuration/declarative-packages.section.xml 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} + + +``` 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 @@ -
- Declarative Package Management - - - With declarative package management, you specify which packages you want on - your system by setting the option - . For instance, adding the - following line to configuration.nix enables the Mozilla - Thunderbird email application: - - = [ 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. - - - - - Some packages require additional global configuration such as D-Bus or systemd service registration so adding them to might not be sufficient. You are advised to check the list of options whether a NixOS module for the package does not exist. - - - - - You can get a list of the available packages as follows: - -$ 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 - and run - nixos-rebuild switch. - - - - - -
diff --git a/nixos/doc/manual/configuration/package-mgmt.xml b/nixos/doc/manual/configuration/package-mgmt.xml index 2f9395d26fa8..499926ea50b4 100644 --- a/nixos/doc/manual/configuration/package-mgmt.xml +++ b/nixos/doc/manual/configuration/package-mgmt.xml @@ -26,6 +26,6 @@ - + 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 @@ +
+ Declarative Package Management + + With declarative package management, you specify which packages you + want on your system by setting the option + . For instance, + adding the following line to configuration.nix + enables the Mozilla Thunderbird email application: + + +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. + + + + Some packages require additional global configuration such as + D-Bus or systemd service registration so adding them to + might not be + sufficient. You are advised to check the + list of options whether a NixOS + module for the package does not exist. + + + + You can get a list of the available packages as follows: + + +$ 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 + and run + nixos-rebuild switch. + + + +
From 45c1d8f4aa37029cb3704db2421e55a308f583c0 Mon Sep 17 00:00:00 2001 From: Bobby Rong Date: Wed, 8 Sep 2021 15:43:55 +0800 Subject: [PATCH 04/11] nixos: nixos/doc/manual/configuration/config-syntax.xml to CommonMark --- .../configuration/config-syntax.chapter.md | 19 ++++++++++++++ .../manual/configuration/config-syntax.xml | 25 ------------------- .../manual/configuration/configuration.xml | 2 +- .../configuration/config-syntax.chapter.xml | 21 ++++++++++++++++ 4 files changed, 41 insertions(+), 26 deletions(-) create mode 100644 nixos/doc/manual/configuration/config-syntax.chapter.md delete mode 100644 nixos/doc/manual/configuration/config-syntax.xml create mode 100644 nixos/doc/manual/from_md/configuration/config-syntax.chapter.xml 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} + + + + +``` 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 @@ - - 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, but here we give a short overview of the most important - constructs useful in NixOS configuration files. - - - - - - diff --git a/nixos/doc/manual/configuration/configuration.xml b/nixos/doc/manual/configuration/configuration.xml index 2461a5de73ad..cfda6e2df493 100644 --- a/nixos/doc/manual/configuration/configuration.xml +++ b/nixos/doc/manual/configuration/configuration.xml @@ -13,7 +13,7 @@ effect after you run nixos-rebuild. - + 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 @@ + + 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, but here we give a short overview of the most + important constructs useful in NixOS configuration files. + + + + + + From 12a9632ab09b131d82032896d2adc6bc9904ea77 Mon Sep 17 00:00:00 2001 From: Bobby Rong Date: Wed, 8 Sep 2021 15:41:57 +0800 Subject: [PATCH 05/11] nixos: nixos/doc/manual/devlopment/nixos-tests.xml to CommonMark --- nixos/doc/manual/development/development.xml | 2 +- .../manual/development/nixos-tests.chapter.md | 13 ++++++++++++ nixos/doc/manual/development/nixos-tests.xml | 20 ------------------- .../development/nixos-tests.chapter.xml | 14 +++++++++++++ 4 files changed, 28 insertions(+), 21 deletions(-) create mode 100644 nixos/doc/manual/development/nixos-tests.chapter.md delete mode 100644 nixos/doc/manual/development/nixos-tests.xml create mode 100644 nixos/doc/manual/from_md/development/nixos-tests.chapter.xml diff --git a/nixos/doc/manual/development/development.xml b/nixos/doc/manual/development/development.xml index 670a391e3801..3fc9c7596883 100644 --- a/nixos/doc/manual/development/development.xml +++ b/nixos/doc/manual/development/development.xml @@ -14,6 +14,6 @@ - + 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} + + + + +``` 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 @@ - - 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. - - - - - - 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 @@ + + 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. + + + + + + From 7d7d2a44556a43d8b65bde4ea95267cf6525c9f4 Mon Sep 17 00:00:00 2001 From: Bobby Rong Date: Wed, 8 Sep 2021 15:47:38 +0800 Subject: [PATCH 06/11] nixos: nixos/doc/manual/configuration/package-mgmt.xml to CommonMark --- .../manual/configuration/configuration.xml | 2 +- .../configuration/package-mgmt.chapter.md | 18 +++++++++++ .../doc/manual/configuration/package-mgmt.xml | 31 ------------------- .../configuration/package-mgmt.chapter.xml | 28 +++++++++++++++++ 4 files changed, 47 insertions(+), 32 deletions(-) create mode 100644 nixos/doc/manual/configuration/package-mgmt.chapter.md delete mode 100644 nixos/doc/manual/configuration/package-mgmt.xml create mode 100644 nixos/doc/manual/from_md/configuration/package-mgmt.chapter.xml diff --git a/nixos/doc/manual/configuration/configuration.xml b/nixos/doc/manual/configuration/configuration.xml index cfda6e2df493..a55dea96c757 100644 --- a/nixos/doc/manual/configuration/configuration.xml +++ b/nixos/doc/manual/configuration/configuration.xml @@ -14,7 +14,7 @@ - + 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} + + +``` diff --git a/nixos/doc/manual/configuration/package-mgmt.xml b/nixos/doc/manual/configuration/package-mgmt.xml deleted file mode 100644 index 499926ea50b4..000000000000 --- a/nixos/doc/manual/configuration/package-mgmt.xml +++ /dev/null @@ -1,31 +0,0 @@ - - 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. - - - - - - - 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 @@ + + 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. + + + + + + From 4c10e0ff9ddea45b344134228dd5874b9ae0bd06 Mon Sep 17 00:00:00 2001 From: Bobby Rong Date: Wed, 8 Sep 2021 15:05:50 +0800 Subject: [PATCH 07/11] nixos: nixos/doc/manual/configuration/file-systems.xml to CommonMark --- .../manual/configuration/configuration.xml | 2 +- .../configuration/file-systems.chapter.md | 42 ++++++++++++++ .../doc/manual/configuration/file-systems.xml | 58 ------------------- .../configuration/file-systems.chapter.xml | 55 ++++++++++++++++++ 4 files changed, 98 insertions(+), 59 deletions(-) create mode 100644 nixos/doc/manual/configuration/file-systems.chapter.md delete mode 100644 nixos/doc/manual/configuration/file-systems.xml create mode 100644 nixos/doc/manual/from_md/configuration/file-systems.chapter.xml diff --git a/nixos/doc/manual/configuration/configuration.xml b/nixos/doc/manual/configuration/configuration.xml index a55dea96c757..6f59262eae70 100644 --- a/nixos/doc/manual/configuration/configuration.xml +++ b/nixos/doc/manual/configuration/configuration.xml @@ -16,7 +16,7 @@ - + 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} + + +``` 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 @@ - - File Systems - - You can define file systems using the - 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: - -."/data" = - { device = "/dev/disk/by-label/data"; - fsType = "ext4"; - }; - - This will create an entry in /etc/fstab, which will - generate a corresponding - systemd.mount - unit via - systemd-fstab-generator. - The filesystem will be mounted automatically unless - "noauto" is present in 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 - , - 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 - (), - 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 to ensure that the kernel module is - available. - - - - 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" ];. - - - - - 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 @@ + + 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: + + +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 + unit via + systemd-fstab-generator. + The filesystem will be mounted automatically unless + "noauto" is present in + 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. + + + + 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" ];. + + + + + From 2e808c8144bc864d8b837cc59ffbf52dc360a1d4 Mon Sep 17 00:00:00 2001 From: Bobby Rong Date: Wed, 8 Sep 2021 15:33:31 +0800 Subject: [PATCH 08/11] nixos: nixos/doc/manual/configuration/networking.xml to CommonMark --- .../manual/configuration/configuration.xml | 2 +- .../configuration/networking.chapter.md | 16 +++++++++++++++ nixos/doc/manual/configuration/networking.xml | 20 ------------------- .../configuration/networking.chapter.xml | 15 ++++++++++++++ 4 files changed, 32 insertions(+), 21 deletions(-) create mode 100644 nixos/doc/manual/configuration/networking.chapter.md delete mode 100644 nixos/doc/manual/configuration/networking.xml create mode 100644 nixos/doc/manual/from_md/configuration/networking.chapter.xml diff --git a/nixos/doc/manual/configuration/configuration.xml b/nixos/doc/manual/configuration/configuration.xml index 6f59262eae70..58a2b8400597 100644 --- a/nixos/doc/manual/configuration/configuration.xml +++ b/nixos/doc/manual/configuration/configuration.xml @@ -21,7 +21,7 @@ - + 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} + + + + + + + + +``` + 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 @@ - - Networking - - This section describes how to configure networking components on your NixOS - machine. - - - - - - - - - - - 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 @@ + + Networking + + This section describes how to configure networking components on + your NixOS machine. + + + + + + + + + + From 785d40d4d872a13642eb7eba7a5bc57f6ba5cdc5 Mon Sep 17 00:00:00 2001 From: Bobby Rong Date: Wed, 8 Sep 2021 15:35:45 +0800 Subject: [PATCH 09/11] nixos: nixos/doc/manual/configuration/profiles.xml to CommonMark --- .../manual/configuration/configuration.xml | 2 +- .../manual/configuration/profiles.chapter.md | 34 ++++++++++++++++ nixos/doc/manual/configuration/profiles.xml | 39 ------------------- .../configuration/profiles.chapter.xml | 38 ++++++++++++++++++ 4 files changed, 73 insertions(+), 40 deletions(-) create mode 100644 nixos/doc/manual/configuration/profiles.chapter.md delete mode 100644 nixos/doc/manual/configuration/profiles.xml create mode 100644 nixos/doc/manual/from_md/configuration/profiles.chapter.xml diff --git a/nixos/doc/manual/configuration/configuration.xml b/nixos/doc/manual/configuration/configuration.xml index 58a2b8400597..b04316cfa48e 100644 --- a/nixos/doc/manual/configuration/configuration.xml +++ b/nixos/doc/manual/configuration/configuration.xml @@ -25,7 +25,7 @@ - + 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 ``. That +is to say, expected usage is to add them to the imports list of your +`/etc/configuration.nix` as such: + +```nix +imports = [ + +]; +``` + +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} + + + + + + + + + + + +``` 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 @@ - - 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: - - - 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. - - - - - - - - - - - - - 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 @@ + + 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: + + +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. + + + + + + + + + + + + + From b8efe91ce225c4413301089d52f47c07f384e38e Mon Sep 17 00:00:00 2001 From: Bobby Rong Date: Wed, 8 Sep 2021 17:54:42 +0800 Subject: [PATCH 10/11] nixos: nixos/doc/manual/development/writing-modules.xml to CommonMark --- nixos/doc/manual/development/development.xml | 2 +- .../development/writing-modules.chapter.md | 166 +++++++++++++++ .../manual/development/writing-modules.xml | 191 ----------------- .../development/writing-modules.chapter.xml | 196 ++++++++++++++++++ 4 files changed, 363 insertions(+), 192 deletions(-) create mode 100644 nixos/doc/manual/development/writing-modules.chapter.md delete mode 100644 nixos/doc/manual/development/writing-modules.xml create mode 100644 nixos/doc/manual/from_md/development/writing-modules.chapter.xml diff --git a/nixos/doc/manual/development/development.xml b/nixos/doc/manual/development/development.xml index 3fc9c7596883..0b2ad60a878b 100644 --- a/nixos/doc/manual/development/development.xml +++ b/nixos/doc/manual/development/development.xml @@ -10,7 +10,7 @@ - + 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} + + + + + + + + + +``` 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 @@ - - Writing NixOS 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 - 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 - declares the option that allows other - modules (e.g. - sshd.nix) - to define PAM services; and it defines the option - (declared by - etc.nix) - to cause files to be created in /etc/pam.d. - - - In , we saw the following structure - of NixOS modules: - -{ 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 . - - - Structure of NixOS Modules - -{ config, pkgs, ... }: - -{ - imports = - [ paths of other modules - ]; - - options = { - option declarations - }; - - config = { - option definitions - }; -} - - - The meaning of each part is as follows. - - - - This 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 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 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). - - - - - - 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): - (whether the database should be - updated) and (when the update - should be done). It implements its functionality by defining two options - declared by other modules: (the set of all - systemd services) and (the list of commands - to be executed periodically by systemd). - - - NixOS Module for the “locate” Service - -{ 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; - }; - }; -} - - - - - - - - - - - - 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 @@ + + Writing NixOS 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 + 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 + declares the option security.pam.services that + allows other modules (e.g. + sshd.nix) + to define PAM services; and it defines the option + environment.etc (declared by + etc.nix) + to cause files to be created in /etc/pam.d. + + + In , we saw the following + structure of NixOS modules: + + +{ 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. + + + + Example: Structure of NixOS + Modules + + +{ 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 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 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). + + + + Example: NixOS Module for the + locate Service + + +{ 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; + }; + }; +} + + + + + + + + + + + From 7fb52b1325a383b7bd83aa2552f6d9d57106d241 Mon Sep 17 00:00:00 2001 From: Bobby Rong Date: Wed, 8 Sep 2021 23:45:32 +0800 Subject: [PATCH 11/11] nixos: nixos/doc/manual/installation/installing.xml to CommonMark --- .../installation/installing.chapter.xml | 642 ++++++++++++++++++ .../doc/manual/installation/installation.xml | 2 +- .../manual/installation/installing.chapter.md | 479 +++++++++++++ nixos/doc/manual/installation/installing.xml | 616 ----------------- 4 files changed, 1122 insertions(+), 617 deletions(-) create mode 100644 nixos/doc/manual/from_md/installation/installing.chapter.xml create mode 100644 nixos/doc/manual/installation/installing.chapter.md delete mode 100644 nixos/doc/manual/installation/installing.xml 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 @@ + + Installing NixOS +
+ Booting the system + + 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 + ). + + + 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 + + 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: + + +> 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: + + +> 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 + + +<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 + + 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) + + Here's an example partition scheme for UEFI, using + /dev/sda as the device. + + + + You can safely ignore parted's + informational message about needing to update /etc/fstab. + + + + + + Create a GPT partition table. + + +# parted /dev/sda -- mklabel gpt + + + + + 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. + + +# parted /dev/sda -- mkpart primary 512MiB -8GiB + + + + + Next, add a swap partition. The size + required will vary according to needs, here a 8GiB one is + created. + + +# parted /dev/sda -- mkpart primary linux-swap -8GiB 100% + + + + The swap partition size rules are no different than for + other Linux distributions. + + + + + + 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. + + +# parted /dev/sda -- mkpart ESP fat32 1MiB 512MiB +# parted /dev/sda -- set 3 esp on + + + + + Once complete, you can follow with + . + +
+
+ Legacy Boot (MBR) + + Here's an example partition scheme for Legacy Boot, using + /dev/sda as the device. + + + + You can safely ignore parted's + informational message about needing to update /etc/fstab. + + + + + + Create a MBR partition table. + + +# parted /dev/sda -- mklabel msdos + + + + + Add the root partition. This will fill + the the disk except for the end part, where the swap will + live. + + +# parted /dev/sda -- mkpart primary 1MiB -8GiB + + + + + Finally, add a swap partition. The size + required will vary according to needs, here a 8GiB one is + created. + + +# parted /dev/sda -- mkpart primary linux-swap -8GiB 100% + + + + The swap partition size rules are no different than for + other Linux distributions. + + + + + + Once complete, you can follow with + . + +
+
+ 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: + + +# 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: + + +# 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: + + +# 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 + + + + Mount the target file system on which NixOS should be + installed on /mnt, e.g. + + +# mount /dev/disk/by-label/nixos /mnt + + + + + UEFI systems + + + Mount the boot file system on /mnt/boot, + e.g. + + +# mkdir -p /mnt/boot +# mount /dev/disk/by-label/boot /mnt/boot + + + + + 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. + + +# swapon /dev/sda2 + + + + + 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 + , while a list of + available configuration options appears in + . A minimal example is shown in + Example: NixOS Configuration. + + + The command nixos-generate-config can + generate an initial configuration file for you: + + +# nixos-generate-config --root /mnt + + + You should then edit + /mnt/etc/nixos/configuration.nix to suit + your needs: + + +# 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 + 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 + + 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 + and + boot.loader.systemd-boot + as well. + + + + + + If there are other operating systems running on the machine + before installing NixOS, the + 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 + . 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 at this point or after + installation. + + + + 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. + + + + + + Do the installation: + + +# 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. + + +setting root password... +New password: *** +Retype new password: *** + + + + For unattended installations, it is possible to use + nixos-install --no-root-passwd in order + to disable the password prompt entirely. + + + + + + If everything went well: + + +# reboot + + + + + 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), 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: + + +$ useradd -c 'Eelco Dolstra' -m eelco +$ passwd eelco + + + You may also want to install some software. This will be + covered in . + + + +
+
+ Installation summary + + To summarise, Example: + Commands for Installing NixOS on + /dev/sda shows a typical sequence of + commands for installing NixOS on an empty hard drive (here + /dev/sda). Example: + NixOS Configuration shows a corresponding configuration Nix + expression. + + + + Example: Example partition schemes for + NixOS on /dev/sda (MBR) + + +# parted /dev/sda -- mklabel msdos +# parted /dev/sda -- mkpart primary 1MiB -8GiB +# parted /dev/sda -- mkpart primary linux-swap -8GiB 100% + + + + Example: Example partition schemes for + NixOS on /dev/sda (UEFI) + + +# 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 + + + + Example: Commands for Installing NixOS on + /dev/sda + + + With a partitioned disk. + + +# 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 + + + + Example: NixOS Configuration + + +{ 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 + + + + + +
+ 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 @@ - + 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 '' -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} + + + + + +``` 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 @@ - - Installing NixOS -
- Booting the system - - - 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 ). - - - - 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 - - - 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: - -> 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: - -> 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 - -<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 - - - 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) - - - Here's an example partition scheme for UEFI, using - /dev/sda as the device. - - - You can safely ignore parted's informational message - about needing to update /etc/fstab. - - - - - - - - - Create a GPT partition table. -# parted /dev/sda -- mklabel gpt - - - - - 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. -# parted /dev/sda -- mkpart primary 512MiB -8GiB - - - - - Next, add a swap partition. The size required will - vary according to needs, here a 8GiB one is created. -# parted /dev/sda -- mkpart primary linux-swap -8GiB 100% - - - The swap partition size rules are no different than for other Linux - distributions. - - - - - - - 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. -# parted /dev/sda -- mkpart ESP fat32 1MiB 512MiB -# parted /dev/sda -- set 3 esp on - - - - - - - Once complete, you can follow with - . - -
- -
- Legacy Boot (MBR) - - - Here's an example partition scheme for Legacy Boot, using - /dev/sda as the device. - - - You can safely ignore parted's informational message - about needing to update /etc/fstab. - - - - - - - - - Create a MBR partition table. -# parted /dev/sda -- mklabel msdos - - - - - Add the root partition. This will fill the the disk - except for the end part, where the swap will live. -# parted /dev/sda -- mkpart primary 1MiB -8GiB - - - - - Finally, add a swap partition. The size required - will vary according to needs, here a 8GiB one is created. -# parted /dev/sda -- mkpart primary linux-swap -8GiB 100% - - - The swap partition size rules are no different than for other Linux - distributions. - - - - - - - - - Once complete, you can follow with - . - -
- -
- 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 , - since this makes the file system configuration independent from device - changes. For example: - -# mkfs.ext4 -L nixos /dev/sda1 - - - - - For creating swap partitions: mkswap. Again it’s - recommended to assign a label to the swap partition: . For example: - -# 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: - . For example: - -# 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 - - - - - Mount the target file system on which NixOS should be installed on - /mnt, e.g. - -# mount /dev/disk/by-label/nixos /mnt - - - - - - - - UEFI systems - - - - Mount the boot file system on /mnt/boot, e.g. - -# mkdir -p /mnt/boot -# mount /dev/disk/by-label/boot /mnt/boot - - - - - - - - - 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. - -# swapon /dev/sda2 - - - - - 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 , while a list - of available configuration options appears in - . A minimal example is shown in - . - - - The command nixos-generate-config can generate an - initial configuration file for you: - -# nixos-generate-config --root /mnt - You should then edit /mnt/etc/nixos/configuration.nix - to suit your needs: - -# 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 - 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 - 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 - - and - - as well. - - - - - - If there are other operating systems running on the machine before - installing NixOS, the - 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 . 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 , 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 at this point or after - installation. - - - - - Depending on your hardware configuration or type of file system, you may - need to set the 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 /mnt, fix - /mnt/etc/nixos/configuration.nix and rerun - nixos-install.) In most cases, - nixos-generate-config will figure out the required - modules. - - - - - - Do the installation: - -# 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. - -setting root password... -New password: *** -Retype new password: *** - - - For unattended installations, it is possible to use - nixos-install --no-root-passwd in order to disable - the password prompt entirely. - - - - - - - If everything went well: - -# reboot - - - - - 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 - ), 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: - -$ useradd -c 'Eelco Dolstra' -m eelco -$ passwd eelco - - - You may also want to install some software. This will be covered - in . - - - -
-
- Installation summary - - - To summarise, shows a typical - sequence of commands for installing NixOS on an empty hard drive (here - /dev/sda). shows a - corresponding configuration Nix expression. - - - - Example partition schemes for NixOS on <filename>/dev/sda</filename> (MBR) - -# parted /dev/sda -- mklabel msdos -# parted /dev/sda -- mkpart primary 1MiB -8GiB -# parted /dev/sda -- mkpart primary linux-swap -8GiB 100% - - - - Example partition schemes for NixOS on <filename>/dev/sda</filename> (UEFI) - -# 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 - - - - Commands for Installing NixOS on <filename>/dev/sda</filename> - - With a partitioned disk. - -# 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 - - - - - NixOS Configuration - -{ config, pkgs, ... }: { - imports = [ - # Include the results of the hardware scan. - ./hardware-configuration.nix - ]; - - = "/dev/sda"; # (for BIOS systems only) - = 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 - - - - - - - - - - -
-