Revert "nixos/doc: re-format"

This reverts commit ea6e8775bd. The new
format is not an improvement.
openssl
Eelco Dolstra 3 years ago
parent db3d31b903
commit b0ccd6dd16
No known key found for this signature in database
GPG Key ID: 8170B4726D7198DE
  1. 32
      nixos/doc/manual/administration/boot-problems.xml
  2. 32
      nixos/doc/manual/administration/cleaning-store.xml
  3. 26
      nixos/doc/manual/administration/container-networking.xml
  4. 19
      nixos/doc/manual/administration/containers.xml
  5. 33
      nixos/doc/manual/administration/control-groups.xml
  6. 31
      nixos/doc/manual/administration/declarative-containers.xml
  7. 57
      nixos/doc/manual/administration/imperative-containers.xml
  8. 19
      nixos/doc/manual/administration/logging.xml
  9. 4
      nixos/doc/manual/administration/maintenance-mode.xml
  10. 13
      nixos/doc/manual/administration/network-problems.xml
  11. 11
      nixos/doc/manual/administration/rebooting.xml
  12. 15
      nixos/doc/manual/administration/rollback.xml
  13. 3
      nixos/doc/manual/administration/running.xml
  14. 26
      nixos/doc/manual/administration/service-mgmt.xml
  15. 17
      nixos/doc/manual/administration/store-corruption.xml
  16. 3
      nixos/doc/manual/administration/troubleshooting.xml
  17. 15
      nixos/doc/manual/administration/user-sessions.xml
  18. 48
      nixos/doc/manual/configuration/abstractions.xml
  19. 5
      nixos/doc/manual/configuration/ad-hoc-network-config.xml
  20. 26
      nixos/doc/manual/configuration/ad-hoc-packages.xml
  21. 23
      nixos/doc/manual/configuration/adding-custom-packages.xml
  22. 71
      nixos/doc/manual/configuration/config-file.xml
  23. 14
      nixos/doc/manual/configuration/config-syntax.xml
  24. 6
      nixos/doc/manual/configuration/configuration.xml
  25. 54
      nixos/doc/manual/configuration/customizing-packages.xml
  26. 23
      nixos/doc/manual/configuration/declarative-packages.xml
  27. 28
      nixos/doc/manual/configuration/file-systems.xml
  28. 15
      nixos/doc/manual/configuration/firewall.xml
  29. 15
      nixos/doc/manual/configuration/ipv4-config.xml
  30. 13
      nixos/doc/manual/configuration/ipv6-config.xml
  31. 74
      nixos/doc/manual/configuration/kubernetes.xml
  32. 59
      nixos/doc/manual/configuration/linux-kernel.xml
  33. 12
      nixos/doc/manual/configuration/luks-file-systems.xml
  34. 73
      nixos/doc/manual/configuration/matrix.xml
  35. 63
      nixos/doc/manual/configuration/modularity.xml
  36. 22
      nixos/doc/manual/configuration/network-manager.xml
  37. 3
      nixos/doc/manual/configuration/networking.xml
  38. 13
      nixos/doc/manual/configuration/package-mgmt.xml
  39. 13
      nixos/doc/manual/configuration/profiles.xml
  40. 10
      nixos/doc/manual/configuration/profiles/all-hardware.xml
  41. 6
      nixos/doc/manual/configuration/profiles/base.xml
  42. 10
      nixos/doc/manual/configuration/profiles/clone-config.xml
  43. 6
      nixos/doc/manual/configuration/profiles/demo.xml
  44. 7
      nixos/doc/manual/configuration/profiles/docker-container.xml
  45. 11
      nixos/doc/manual/configuration/profiles/graphical.xml
  46. 14
      nixos/doc/manual/configuration/profiles/hardened.xml
  47. 6
      nixos/doc/manual/configuration/profiles/headless.xml
  48. 25
      nixos/doc/manual/configuration/profiles/installation-device.xml
  49. 8
      nixos/doc/manual/configuration/profiles/minimal.xml
  50. 7
      nixos/doc/manual/configuration/profiles/qemu-guest.xml
  51. 7
      nixos/doc/manual/configuration/ssh.xml
  52. 8
      nixos/doc/manual/configuration/summary.xml
  53. 53
      nixos/doc/manual/configuration/user-mgmt.xml
  54. 18
      nixos/doc/manual/configuration/wireless.xml
  55. 151
      nixos/doc/manual/configuration/x-windows.xml
  56. 21
      nixos/doc/manual/configuration/xfce.xml
  57. 18
      nixos/doc/manual/development/assertions.xml
  58. 11
      nixos/doc/manual/development/building-nixos.xml
  59. 31
      nixos/doc/manual/development/building-parts.xml
  60. 7
      nixos/doc/manual/development/importing-modules.xml
  61. 19
      nixos/doc/manual/development/meta-attributes.xml
  62. 9
      nixos/doc/manual/development/nixos-tests.xml
  63. 80
      nixos/doc/manual/development/option-declarations.xml
  64. 34
      nixos/doc/manual/development/option-def.xml
  65. 208
      nixos/doc/manual/development/option-types.xml
  66. 126
      nixos/doc/manual/development/releases.xml
  67. 22
      nixos/doc/manual/development/replace-modules.xml
  68. 14
      nixos/doc/manual/development/running-nixos-tests-interactively.xml
  69. 13
      nixos/doc/manual/development/running-nixos-tests.xml
  70. 48
      nixos/doc/manual/development/sources.xml
  71. 6
      nixos/doc/manual/development/testing-installer.xml
  72. 74
      nixos/doc/manual/development/writing-documentation.xml
  73. 69
      nixos/doc/manual/development/writing-modules.xml
  74. 113
      nixos/doc/manual/development/writing-nixos-tests.xml
  75. 53
      nixos/doc/manual/installation/changing-config.xml
  76. 3
      nixos/doc/manual/installation/installation.xml
  77. 15
      nixos/doc/manual/installation/installing-behind-a-proxy.xml
  78. 152
      nixos/doc/manual/installation/installing-from-other-distro.xml
  79. 25
      nixos/doc/manual/installation/installing-pxe.xml
  80. 15
      nixos/doc/manual/installation/installing-usb.xml
  81. 29
      nixos/doc/manual/installation/installing-virtualbox-guest.xml
  82. 230
      nixos/doc/manual/installation/installing.xml
  83. 38
      nixos/doc/manual/installation/obtaining.xml
  84. 82
      nixos/doc/manual/installation/upgrading.xml
  85. 5
      nixos/doc/manual/man-configuration.xml
  86. 41
      nixos/doc/manual/man-nixos-build-vms.xml
  87. 22
      nixos/doc/manual/man-nixos-enter.xml
  88. 64
      nixos/doc/manual/man-nixos-generate-config.xml
  89. 95
      nixos/doc/manual/man-nixos-install.xml
  90. 27
      nixos/doc/manual/man-nixos-option.xml
  91. 309
      nixos/doc/manual/man-nixos-rebuild.xml
  92. 23
      nixos/doc/manual/man-nixos-version.xml
  93. 21
      nixos/doc/manual/manual.xml
  94. 3
      nixos/doc/manual/release-notes/release-notes.xml
  95. 83
      nixos/doc/manual/release-notes/rl-1404.xml
  96. 81
      nixos/doc/manual/release-notes/rl-1412.xml
  97. 208
      nixos/doc/manual/release-notes/rl-1509.xml
  98. 205
      nixos/doc/manual/release-notes/rl-1603.xml
  99. 161
      nixos/doc/manual/release-notes/rl-1609.xml
  100. 193
      nixos/doc/manual/release-notes/rl-1703.xml
  101. Some files were not shown because too many files have changed in this diff Show More

@ -6,7 +6,12 @@
<title>Boot Problems</title>
<para>
If NixOS fails to boot, there are a number of kernel command line parameters that may help you to identify or fix the issue. You can add these parameters in the GRUB boot menu by pressing “e” to modify the selected boot entry and editing the line starting with <literal>linux</literal>. The following are some useful kernel command line parameters that are recognised by the NixOS boot scripts or by systemd:
If NixOS fails to boot, there are a number of kernel command line parameters
that may help you to identify or fix the issue. You can add these parameters
in the GRUB boot menu by pressing “e” to modify the selected boot entry
and editing the line starting with <literal>linux</literal>. The following
are some useful kernel command line parameters that are recognised by the
NixOS boot scripts or by systemd:
<variablelist>
<varlistentry>
<term>
@ -14,7 +19,9 @@
</term>
<listitem>
<para>
Start a root shell if something goes wrong in stage 1 of the boot process (the initial ramdisk). This is disabled by default because there is no authentication for the root shell.
Start a root shell if something goes wrong in stage 1 of the boot process
(the initial ramdisk). This is disabled by default because there is no
authentication for the root shell.
</para>
</listitem>
</varlistentry>
@ -24,7 +31,10 @@
</term>
<listitem>
<para>
Start an interactive shell in stage 1 before anything useful has been done. That is, no modules have been loaded and no file systems have been mounted, except for <filename>/proc</filename> and <filename>/sys</filename>.
Start an interactive shell in stage 1 before anything useful has been
done. That is, no modules have been loaded and no file systems have been
mounted, except for <filename>/proc</filename> and
<filename>/sys</filename>.
</para>
</listitem>
</varlistentry>
@ -44,7 +54,11 @@
</term>
<listitem>
<para>
Boot into rescue mode (a.k.a. single user mode). This will cause systemd to start nothing but the unit <literal>rescue.target</literal>, which runs <command>sulogin</command> to prompt for the root password and start a root login shell. Exiting the shell causes the system to continue with the normal boot process.
Boot into rescue mode (a.k.a. single user mode). This will cause systemd
to start nothing but the unit <literal>rescue.target</literal>, which
runs <command>sulogin</command> to prompt for the root password and start
a root login shell. Exiting the shell causes the system to continue with
the normal boot process.
</para>
</listitem>
</varlistentry>
@ -54,7 +68,8 @@
</term>
<listitem>
<para>
Make systemd very verbose and send log messages to the console instead of the journal.
Make systemd very verbose and send log messages to the console instead of
the journal.
</para>
</listitem>
</varlistentry>
@ -65,6 +80,11 @@
</para>
<para>
If no login prompts or X11 login screens appear (e.g. due to hanging dependencies), you can press Alt+ArrowUp. If you’re lucky, this will start rescue mode (described above). (Also note that since most units have a 90-second timeout before systemd gives up on them, the <command>agetty</command> login prompts should appear eventually unless something is very wrong.)
If no login prompts or X11 login screens appear (e.g. due to hanging
dependencies), you can press Alt+ArrowUp. If you’re lucky, this will start
rescue mode (described above). (Also note that since most units have a
90-second timeout before systemd gives up on them, the
<command>agetty</command> login prompts should appear eventually unless
something is very wrong.)
</para>
</section>

@ -5,22 +5,31 @@
xml:id="sec-nix-gc">
<title>Cleaning the Nix Store</title>
<para>
Nix has a purely functional model, meaning that packages are never upgraded in place. Instead new versions of packages end up in a different location in the Nix store (<filename>/nix/store</filename>). You should periodically run Nix’s <emphasis>garbage collector</emphasis> to remove old, unreferenced packages. This is easy:
Nix has a purely functional model, meaning that packages are never upgraded
in place. Instead new versions of packages end up in a different location in
the Nix store (<filename>/nix/store</filename>). You should periodically run
Nix’s <emphasis>garbage collector</emphasis> to remove old, unreferenced
packages. This is easy:
<screen>
<prompt>$ </prompt>nix-collect-garbage
</screen>
Alternatively, you can use a systemd unit that does the same in the background:
Alternatively, you can use a systemd unit that does the same in the
background:
<screen>
<prompt># </prompt>systemctl start nix-gc.service
</screen>
You can tell NixOS in <filename>configuration.nix</filename> to run this unit automatically at certain points in time, for instance, every night at 03:15:
You can tell NixOS in <filename>configuration.nix</filename> to run this unit
automatically at certain points in time, for instance, every night at 03:15:
<programlisting>
<xref linkend="opt-nix.gc.automatic"/> = true;
<xref linkend="opt-nix.gc.dates"/> = "03:15";
</programlisting>
</para>
<para>
The commands above do not remove garbage collector roots, such as old system configurations. Thus they do not remove the ability to roll back to previous configurations. The following command deletes old roots, removing the ability to roll back to them:
The commands above do not remove garbage collector roots, such as old system
configurations. Thus they do not remove the ability to roll back to previous
configurations. The following command deletes old roots, removing the ability
to roll back to them:
<screen>
<prompt>$ </prompt>nix-collect-garbage -d
</screen>
@ -28,20 +37,27 @@
<screen>
<prompt>$ </prompt>nix-env -p /nix/var/nix/profiles/per-user/eelco/profile --delete-generations old
</screen>
Note that NixOS system configurations are stored in the profile <filename>/nix/var/nix/profiles/system</filename>.
Note that NixOS system configurations are stored in the profile
<filename>/nix/var/nix/profiles/system</filename>.
</para>
<para>
Another way to reclaim disk space (often as much as 40% of the size of the Nix store) is to run Nix’s store optimiser, which seeks out identical files in the store and replaces them with hard links to a single copy.
Another way to reclaim disk space (often as much as 40% of the size of the
Nix store) is to run Nix’s store optimiser, which seeks out identical files
in the store and replaces them with hard links to a single copy.
<screen>
<prompt>$ </prompt>nix-store --optimise
</screen>
Since this command needs to read the entire Nix store, it can take quite a while to finish.
Since this command needs to read the entire Nix store, it can take quite a
while to finish.
</para>
<section xml:id="sect-nixos-gc-boot-entries">
<title>NixOS Boot Entries</title>
<para>
If your <filename>/boot</filename> partition runs out of space, after clearing old profiles you must rebuild your system with <literal>nixos-rebuild</literal> to update the <filename>/boot</filename> partition and clear space.
If your <filename>/boot</filename> partition runs out of space, after
clearing old profiles you must rebuild your system with
<literal>nixos-rebuild</literal> to update the <filename>/boot</filename>
partition and clear space.
</para>
</section>
</chapter>

@ -6,7 +6,10 @@
<title>Container Networking</title>
<para>
When you create a container using <literal>nixos-container create</literal>, it gets it own private IPv4 address in the range <literal>10.233.0.0/16</literal>. You can get the container’s IPv4 address as follows:
When you create a container using <literal>nixos-container create</literal>,
it gets it own private IPv4 address in the range
<literal>10.233.0.0/16</literal>. You can get the container’s IPv4 address
as follows:
<screen>
<prompt># </prompt>nixos-container show-ip foo
10.233.4.2
@ -17,21 +20,34 @@
</para>
<para>
Networking is implemented using a pair of virtual Ethernet devices. The network interface in the container is called <literal>eth0</literal>, while the matching interface in the host is called <literal>ve-<replaceable>container-name</replaceable></literal> (e.g., <literal>ve-foo</literal>). The container has its own network namespace and the <literal>CAP_NET_ADMIN</literal> capability, so it can perform arbitrary network configuration such as setting up firewall rules, without affecting or having access to the host’s network.
Networking is implemented using a pair of virtual Ethernet devices. The
network interface in the container is called <literal>eth0</literal>, while
the matching interface in the host is called
<literal>ve-<replaceable>container-name</replaceable></literal> (e.g.,
<literal>ve-foo</literal>). The container has its own network namespace and
the <literal>CAP_NET_ADMIN</literal> capability, so it can perform arbitrary
network configuration such as setting up firewall rules, without affecting or
having access to the host’s network.
</para>
<para>
By default, containers cannot talk to the outside network. If you want that, you should set up Network Address Translation (NAT) rules on the host to rewrite container traffic to use your external IP address. This can be accomplished using the following configuration on the host:
By default, containers cannot talk to the outside network. If you want that,
you should set up Network Address Translation (NAT) rules on the host to
rewrite container traffic to use your external IP address. This can be
accomplished using the following configuration on the host:
<programlisting>
<xref linkend="opt-networking.nat.enable"/> = true;
<xref linkend="opt-networking.nat.internalInterfaces"/> = ["ve-+"];
<xref linkend="opt-networking.nat.externalInterface"/> = "eth0";
</programlisting>
where <literal>eth0</literal> should be replaced with the desired external interface. Note that <literal>ve-+</literal> is a wildcard that matches all container interfaces.
where <literal>eth0</literal> should be replaced with the desired external
interface. Note that <literal>ve-+</literal> is a wildcard that matches all
container interfaces.
</para>
<para>
If you are using Network Manager, you need to explicitly prevent it from managing container interfaces:
If you are using Network Manager, you need to explicitly prevent it from
managing container interfaces:
<programlisting>
networking.networkmanager.unmanaged = [ "interface-name:ve-*" ];
</programlisting>

@ -5,15 +5,28 @@
xml:id="ch-containers">
<title>Container Management</title>
<para>
NixOS allows you to easily run other NixOS instances as <emphasis>containers</emphasis>. Containers are a light-weight approach to virtualisation that runs software in the container at the same speed as in the host system. NixOS containers share the Nix store of the host, making container creation very efficient.
NixOS allows you to easily run other NixOS instances as
<emphasis>containers</emphasis>. Containers are a light-weight approach to
virtualisation that runs software in the container at the same speed as in
the host system. NixOS containers share the Nix store of the host, making
container creation very efficient.
</para>
<warning>
<para>
Currently, NixOS containers are not perfectly isolated from the host system. This means that a user with root access to the container can do things that affect the host. So you should not give container root access to untrusted users.
Currently, NixOS containers are not perfectly isolated from the host system.
This means that a user with root access to the container can do things that
affect the host. So you should not give container root access to untrusted
users.
</para>
</warning>
<para>
NixOS containers can be created in two ways: imperatively, using the command <command>nixos-container</command>, and declaratively, by specifying them in your <filename>configuration.nix</filename>. The declarative approach implies that containers get upgraded along with your host system when you run <command>nixos-rebuild</command>, which is often not what you want. By contrast, in the imperative approach, containers are configured and updated independently from the host system.
NixOS containers can be created in two ways: imperatively, using the command
<command>nixos-container</command>, and declaratively, by specifying them in
your <filename>configuration.nix</filename>. The declarative approach implies
that containers get upgraded along with your host system when you run
<command>nixos-rebuild</command>, which is often not what you want. By
contrast, in the imperative approach, containers are configured and updated
independently from the host system.
</para>
<xi:include href="imperative-containers.xml" />
<xi:include href="declarative-containers.xml" />

@ -5,10 +5,16 @@
xml:id="sec-cgroups">
<title>Control Groups</title>
<para>
To keep track of the processes in a running system, systemd uses <emphasis>control groups</emphasis> (cgroups). A control group is a set of processes used to allocate resources such as CPU, memory or I/O bandwidth. There can be multiple control group hierarchies, allowing each kind of resource to be managed independently.
To keep track of the processes in a running system, systemd uses
<emphasis>control groups</emphasis> (cgroups). A control group is a set of
processes used to allocate resources such as CPU, memory or I/O bandwidth.
There can be multiple control group hierarchies, allowing each kind of
resource to be managed independently.
</para>
<para>
The command <command>systemd-cgls</command> lists all control groups in the <literal>systemd</literal> hierarchy, which is what systemd uses to keep track of the processes belonging to each service or user session:
The command <command>systemd-cgls</command> lists all control groups in the
<literal>systemd</literal> hierarchy, which is what systemd uses to keep
track of the processes belonging to each service or user session:
<screen>
<prompt>$ </prompt>systemd-cgls
├─user
@ -26,19 +32,34 @@
│ └─2376 dhcpcd --config /nix/store/f8dif8dsi2yaa70n03xir8r653776ka6-dhcpcd.conf
└─ <replaceable>...</replaceable>
</screen>
Similarly, <command>systemd-cgls cpu</command> shows the cgroups in the CPU hierarchy, which allows per-cgroup CPU scheduling priorities. By default, every systemd service gets its own CPU cgroup, while all user sessions are in the top-level CPU cgroup. This ensures, for instance, that a thousand run-away processes in the <literal>httpd.service</literal> cgroup cannot starve the CPU for one process in the <literal>postgresql.service</literal> cgroup. (By contrast, it they were in the same cgroup, then the PostgreSQL process would get 1/1001 of the cgroup’s CPU time.) You can limit a service’s CPU share in <filename>configuration.nix</filename>:
Similarly, <command>systemd-cgls cpu</command> shows the cgroups in the CPU
hierarchy, which allows per-cgroup CPU scheduling priorities. By default,
every systemd service gets its own CPU cgroup, while all user sessions are in
the top-level CPU cgroup. This ensures, for instance, that a thousand
run-away processes in the <literal>httpd.service</literal> cgroup cannot
starve the CPU for one process in the <literal>postgresql.service</literal>
cgroup. (By contrast, it they were in the same cgroup, then the PostgreSQL
process would get 1/1001 of the cgroup’s CPU time.) You can limit a
service’s CPU share in <filename>configuration.nix</filename>:
<programlisting>
<link linkend="opt-systemd.services._name_.serviceConfig">systemd.services.httpd.serviceConfig</link>.CPUShares = 512;
</programlisting>
By default, every cgroup has 1024 CPU shares, so this will halve the CPU allocation of the <literal>httpd.service</literal> cgroup.
By default, every cgroup has 1024 CPU shares, so this will halve the CPU
allocation of the <literal>httpd.service</literal> cgroup.
</para>
<para>
There also is a <literal>memory</literal> hierarchy that controls memory allocation limits; by default, all processes are in the top-level cgroup, so any service or session can exhaust all available memory. Per-cgroup memory limits can be specified in <filename>configuration.nix</filename>; for instance, to limit <literal>httpd.service</literal> to 512 MiB of RAM (excluding swap):
There also is a <literal>memory</literal> hierarchy that controls memory
allocation limits; by default, all processes are in the top-level cgroup, so
any service or session can exhaust all available memory. Per-cgroup memory
limits can be specified in <filename>configuration.nix</filename>; for
instance, to limit <literal>httpd.service</literal> to 512 MiB of RAM
(excluding swap):
<programlisting>
<link linkend="opt-systemd.services._name_.serviceConfig">systemd.services.httpd.serviceConfig</link>.MemoryLimit = "512M";
</programlisting>
</para>
<para>
The command <command>systemd-cgtop</command> shows a continuously updated list of all cgroups with their CPU and memory usage.
The command <command>systemd-cgtop</command> shows a continuously updated
list of all cgroups with their CPU and memory usage.
</para>
</chapter>

@ -6,7 +6,10 @@
<title>Declarative Container Specification</title>
<para>
You can also specify containers and their configuration in the host’s <filename>configuration.nix</filename>. For example, the following specifies that there shall be a container named <literal>database</literal> running PostgreSQL:
You can also specify containers and their configuration in the host’s
<filename>configuration.nix</filename>. For example, the following specifies
that there shall be a container named <literal>database</literal> running
PostgreSQL:
<programlisting>
containers.database =
{ config =
@ -16,11 +19,18 @@ containers.database =
};
};
</programlisting>
If you run <literal>nixos-rebuild switch</literal>, the container will be built. If the container was already running, it will be updated in place, without rebooting. The container can be configured to start automatically by setting <literal>containers.database.autoStart = true</literal> in its configuration.
If you run <literal>nixos-rebuild switch</literal>, the container will be
built. If the container was already running, it will be updated in place,
without rebooting. The container can be configured to start automatically by
setting <literal>containers.database.autoStart = true</literal> in its
configuration.
</para>
<para>
By default, declarative containers share the network namespace of the host, meaning that they can listen on (privileged) ports. However, they cannot change the network configuration. You can give a container its own network as follows:
By default, declarative containers share the network namespace of the host,
meaning that they can listen on (privileged) ports. However, they cannot
change the network configuration. You can give a container its own network as
follows:
<programlisting>
containers.database = {
<link linkend="opt-containers._name_.privateNetwork">privateNetwork</link> = true;
@ -28,14 +38,23 @@ containers.database = {
<link linkend="opt-containers._name_.localAddress">localAddress</link> = "192.168.100.11";
};
</programlisting>
This gives the container a private virtual Ethernet interface with IP address <literal>192.168.100.11</literal>, which is hooked up to a virtual Ethernet interface on the host with IP address <literal>192.168.100.10</literal>. (See the next section for details on container networking.)
This gives the container a private virtual Ethernet interface with IP address
<literal>192.168.100.11</literal>, which is hooked up to a virtual Ethernet
interface on the host with IP address <literal>192.168.100.10</literal>. (See
the next section for details on container networking.)
</para>
<para>
To disable the container, just remove it from <filename>configuration.nix</filename> and run <literal>nixos-rebuild switch</literal>. Note that this will not delete the root directory of the container in <literal>/var/lib/containers</literal>. Containers can be destroyed using the imperative method: <literal>nixos-container destroy foo</literal>.
To disable the container, just remove it from
<filename>configuration.nix</filename> and run <literal>nixos-rebuild
switch</literal>. Note that this will not delete the root directory of the
container in <literal>/var/lib/containers</literal>. Containers can be
destroyed using the imperative method: <literal>nixos-container destroy
foo</literal>.
</para>
<para>
Declarative containers can be started and stopped using the corresponding systemd service, e.g. <literal>systemctl start container@database</literal>.
Declarative containers can be started and stopped using the corresponding
systemd service, e.g. <literal>systemctl start container@database</literal>.
</para>
</section>

@ -6,7 +6,9 @@
<title>Imperative Container Management</title>
<para>
We’ll cover imperative container management using <command>nixos-container</command> first. Be aware that container management is currently only possible as <literal>root</literal>.
We’ll cover imperative container management using
<command>nixos-container</command> first. Be aware that container management
is currently only possible as <literal>root</literal>.
</para>
<para>
@ -14,14 +16,23 @@
<screen>
# nixos-container create foo
</screen>
This creates the container’s root directory in <filename>/var/lib/containers/foo</filename> and a small configuration file in <filename>/etc/containers/foo.conf</filename>. It also builds the container’s initial system configuration and stores it in <filename>/nix/var/nix/profiles/per-container/foo/system</filename>. You can modify the initial configuration of the container on the command line. For instance, to create a container that has <command>sshd</command> running, with the given public key for <literal>root</literal>:
This creates the container’s root directory in
<filename>/var/lib/containers/foo</filename> and a small configuration file
in <filename>/etc/containers/foo.conf</filename>. It also builds the
container’s initial system configuration and stores it in
<filename>/nix/var/nix/profiles/per-container/foo/system</filename>. You can
modify the initial configuration of the container on the command line. For
instance, to create a container that has <command>sshd</command> running,
with the given public key for <literal>root</literal>:
<screen>
# nixos-container create foo --config '
<xref linkend="opt-services.openssh.enable"/> = true;
<link linkend="opt-users.users._name__.openssh.authorizedKeys.keys">users.users.root.openssh.authorizedKeys.keys</link> = ["ssh-dss AAAAB3N…"];
'
</screen>
By default the next free address in the <literal>10.233.0.0/16</literal> subnet will be chosen as container IP. This behavior can be altered by setting <literal>--host-address</literal> and <literal>--local-address</literal>:
By default the next free address in the <literal>10.233.0.0/16</literal> subnet will be chosen
as container IP. This behavior can be altered by setting <literal>--host-address</literal> and
<literal>--local-address</literal>:
<screen>
# nixos-container create test --config-file test-container.nix \
--local-address 10.235.1.2 --host-address 10.235.1.1
@ -33,25 +44,35 @@
<screen>
# nixos-container start foo
</screen>
This command will return as soon as the container has booted and has reached <literal>multi-user.target</literal>. On the host, the container runs within a systemd unit called <literal>container@<replaceable>container-name</replaceable>.service</literal>. Thus, if something went wrong, you can get status info using <command>systemctl</command>:
This command will return as soon as the container has booted and has reached
<literal>multi-user.target</literal>. On the host, the container runs within
a systemd unit called
<literal>container@<replaceable>container-name</replaceable>.service</literal>.
Thus, if something went wrong, you can get status info using
<command>systemctl</command>:
<screen>
# systemctl status container@foo
</screen>
</para>
<para>
If the container has started successfully, you can log in as root using the <command>root-login</command> operation:
If the container has started successfully, you can log in as root using the
<command>root-login</command> operation:
<screen>
# nixos-container root-login foo
[root@foo:~]#
</screen>
Note that only root on the host can do this (since there is no authentication). You can also get a regular login prompt using the <command>login</command> operation, which is available to all users on the host:
Note that only root on the host can do this (since there is no
authentication). You can also get a regular login prompt using the
<command>login</command> operation, which is available to all users on the
host:
<screen>
# nixos-container login foo
foo login: alice
Password: ***
</screen>
With <command>nixos-container run</command>, you can execute arbitrary commands in the container:
With <command>nixos-container run</command>, you can execute arbitrary
commands in the container:
<screen>
# nixos-container run foo -- uname -a
Linux foo 3.4.82 #1-NixOS SMP Thu Mar 20 14:44:05 UTC 2014 x86_64 GNU/Linux
@ -59,11 +80,15 @@ Linux foo 3.4.82 #1-NixOS SMP Thu Mar 20 14:44:05 UTC 2014 x86_64 GNU/Linux
</para>
<para>
There are several ways to change the configuration of the container. First, on the host, you can edit <literal>/var/lib/container/<replaceable>name</replaceable>/etc/nixos/configuration.nix</literal>, and run
There are several ways to change the configuration of the container. First,
on the host, you can edit
<literal>/var/lib/container/<replaceable>name</replaceable>/etc/nixos/configuration.nix</literal>,
and run
<screen>
# nixos-container update foo
</screen>
This will build and activate the new configuration. You can also specify a new configuration on the command line:
This will build and activate the new configuration. You can also specify a
new configuration on the command line:
<screen>
# nixos-container update foo --config '
<xref linkend="opt-services.httpd.enable"/> = true;
@ -74,15 +99,23 @@ Linux foo 3.4.82 #1-NixOS SMP Thu Mar 20 14:44:05 UTC 2014 x86_64 GNU/Linux
# curl http://$(nixos-container show-ip foo)/
&lt;!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">…
</screen>
However, note that this will overwrite the container’s <filename>/etc/nixos/configuration.nix</filename>.
However, note that this will overwrite the container’s
<filename>/etc/nixos/configuration.nix</filename>.
</para>
<para>
Alternatively, you can change the configuration from within the container itself by running <command>nixos-rebuild switch</command> inside the container. Note that the container by default does not have a copy of the NixOS channel, so you should run <command>nix-channel --update</command> first.
Alternatively, you can change the configuration from within the container
itself by running <command>nixos-rebuild switch</command> inside the
container. Note that the container by default does not have a copy of the
NixOS channel, so you should run <command>nix-channel --update</command>
first.
</para>
<para>
Containers can be stopped and started using <literal>nixos-container stop</literal> and <literal>nixos-container start</literal>, respectively, or by using <command>systemctl</command> on the container’s service unit. To destroy a container, including its file system, do
Containers can be stopped and started using <literal>nixos-container
stop</literal> and <literal>nixos-container start</literal>, respectively, or
by using <command>systemctl</command> on the container’s service unit. To
destroy a container, including its file system, do
<screen>
# nixos-container destroy foo
</screen>

@ -5,11 +5,18 @@
xml:id="sec-logging">
<title>Logging</title>
<para>
System-wide logging is provided by systemd’s <emphasis>journal</emphasis>, which subsumes traditional logging daemons such as syslogd and klogd. Log entries are kept in binary files in <filename>/var/log/journal/</filename>. The command <literal>journalctl</literal> allows you to see the contents of the journal. For example,
System-wide logging is provided by systemd’s <emphasis>journal</emphasis>,
which subsumes traditional logging daemons such as syslogd and klogd. Log
entries are kept in binary files in <filename>/var/log/journal/</filename>.
The command <literal>journalctl</literal> allows you to see the contents of
the journal. For example,
<screen>
<prompt>$ </prompt>journalctl -b
</screen>
shows all journal entries since the last reboot. (The output of <command>journalctl</command> is piped into <command>less</command> by default.) You can use various options and match operators to restrict output to messages of interest. For instance, to get all messages from PostgreSQL:
shows all journal entries since the last reboot. (The output of
<command>journalctl</command> is piped into <command>less</command> by
default.) You can use various options and match operators to restrict output
to messages of interest. For instance, to get all messages from PostgreSQL:
<screen>
<prompt>$ </prompt>journalctl -u postgresql.service
-- Logs begin at Mon, 2013-01-07 13:28:01 CET, end at Tue, 2013-01-08 01:09:57 CET. --
@ -19,7 +26,8 @@ Jan 07 15:44:14 hagbard postgres[2681]: [2-1] LOG: database system is shut down
Jan 07 15:45:10 hagbard postgres[2532]: [1-1] LOG: database system was shut down at 2013-01-07 15:44:14 CET
Jan 07 15:45:13 hagbard postgres[2500]: [1-1] LOG: database system is ready to accept connections
</screen>
Or to get all messages since the last reboot that have at least a “critical” severity level:
Or to get all messages since the last reboot that have at least a
“critical” severity level:
<screen>
<prompt>$ </prompt>journalctl -b -p crit
Dec 17 21:08:06 mandark sudo[3673]: pam_unix(sudo:auth): auth could not identify password for [alice]
@ -27,6 +35,9 @@ Dec 29 01:30:22 mandark kernel[6131]: [1053513.909444] CPU6: Core temperature ab
</screen>
</para>
<para>
The system journal is readable by root and by users in the <literal>wheel</literal> and <literal>systemd-journal</literal> groups. All users have a private journal that can be read using <command>journalctl</command>.
The system journal is readable by root and by users in the
<literal>wheel</literal> and <literal>systemd-journal</literal> groups. All
users have a private journal that can be read using
<command>journalctl</command>.
</para>
</chapter>

@ -9,6 +9,8 @@
You can enter rescue mode by running:
<screen>
# systemctl rescue</screen>
This will eventually give you a single-user root shell. Systemd will stop (almost) all system services. To get out of maintenance mode, just exit from the rescue shell.
This will eventually give you a single-user root shell. Systemd will stop
(almost) all system services. To get out of maintenance mode, just exit from
the rescue shell.
</para>
</section>

@ -6,11 +6,20 @@
<title>Network Problems</title>
<para>
Nix uses a so-called <emphasis>binary cache</emphasis> to optimise building a package from source into downloading it as a pre-built binary. That is, whenever a command like <command>nixos-rebuild</command> needs a path in the Nix store, Nix will try to download that path from the Internet rather than build it from source. The default binary cache is <uri>https://cache.nixos.org/</uri>. If this cache is unreachable, Nix operations may take a long time due to HTTP connection timeouts. You can disable the use of the binary cache by adding <option>--option use-binary-caches false</option>, e.g.
Nix uses a so-called <emphasis>binary cache</emphasis> to optimise building a
package from source into downloading it as a pre-built binary. That is,
whenever a command like <command>nixos-rebuild</command> needs a path in the
Nix store, Nix will try to download that path from the Internet rather than
build it from source. The default binary cache is
<uri>https://cache.nixos.org/</uri>. If this cache is unreachable, Nix
operations may take a long time due to HTTP connection timeouts. You can
disable the use of the binary cache by adding <option>--option
use-binary-caches false</option>, e.g.
<screen>
# nixos-rebuild switch --option use-binary-caches false
</screen>
If you have an alternative binary cache at your disposal, you can use it instead:
If you have an alternative binary cache at your disposal, you can use it
instead:
<screen>
# nixos-rebuild switch --option binary-caches http://my-cache.example.org/
</screen>

@ -16,15 +16,20 @@
<screen>
# reboot
</screen>
which is equivalent to <command>systemctl reboot</command>. Alternatively, you can quickly reboot the system using <literal>kexec</literal>, which bypasses the BIOS by directly loading the new kernel into memory:
which is equivalent to <command>systemctl reboot</command>. Alternatively,
you can quickly reboot the system using <literal>kexec</literal>, which
bypasses the BIOS by directly loading the new kernel into memory:
<screen>
# systemctl kexec
</screen>
</para>
<para>
The machine can be suspended to RAM (if supported) using <command>systemctl suspend</command>, and suspended to disk using <command>systemctl hibernate</command>.
The machine can be suspended to RAM (if supported) using <command>systemctl
suspend</command>, and suspended to disk using <command>systemctl
hibernate</command>.
</para>
<para>
These commands can be run by any user who is logged in locally, i.e. on a virtual console or in X11; otherwise, the user is asked for authentication.
These commands can be run by any user who is logged in locally, i.e. on a
virtual console or in X11; otherwise, the user is asked for authentication.
</para>
</chapter>

@ -6,11 +6,19 @@
<title>Rolling Back Configuration Changes</title>
<para>
After running <command>nixos-rebuild</command> to switch to a new configuration, you may find that the new configuration doesn’t work very well. In that case, there are several ways to return to a previous configuration.
After running <command>nixos-rebuild</command> to switch to a new
configuration, you may find that the new configuration doesn’t work very
well. In that case, there are several ways to return to a previous
configuration.
</para>
<para>
First, the GRUB boot manager allows you to boot into any previous configuration that hasn’t been garbage-collected. These configurations can be found under the GRUB submenu “NixOS - All configurations”. This is especially useful if the new configuration fails to boot. After the system has booted, you can make the selected configuration the default for subsequent boots:
First, the GRUB boot manager allows you to boot into any previous
configuration that hasn’t been garbage-collected. These configurations can
be found under the GRUB submenu “NixOS - All configurations”. This is
especially useful if the new configuration fails to boot. After the system
has booted, you can make the selected configuration the default for
subsequent boots:
<screen>
# /run/current-system/bin/switch-to-configuration boot</screen>
</para>
@ -22,7 +30,8 @@
This is equivalent to running:
<screen>
# /nix/var/nix/profiles/system-<replaceable>N</replaceable>-link/bin/switch-to-configuration switch</screen>
where <replaceable>N</replaceable> is the number of the NixOS system configuration. To get a list of the available configurations, do:
where <replaceable>N</replaceable> is the number of the NixOS system
configuration. To get a list of the available configurations, do:
<screen>
<prompt>$ </prompt>ls -l /nix/var/nix/profiles/system-*-link
<replaceable>...</replaceable>

@ -6,7 +6,8 @@
<title>Administration</title>
<partintro xml:id="ch-running-intro">
<para>
This chapter describes various aspects of managing a running NixOS system, such as how to use the <command>systemd</command> service manager.
This chapter describes various aspects of managing a running NixOS system,
such as how to use the <command>systemd</command> service manager.
</para>
</partintro>
<xi:include href="service-mgmt.xml" />

@ -5,10 +5,21 @@
xml:id="sec-systemctl">
<title>Service Management</title>
<para>
In NixOS, all system services are started and monitored using the systemd program. Systemd is the “init” process of the system (i.e. PID 1), the parent of all other processes. It manages a set of so-called “units”, which can be things like system services (programs), but also mount points, swap files, devices, targets (groups of units) and more. Units can have complex dependencies; for instance, one unit can require that another unit must be successfully started before the first unit can be started. When the system boots, it starts a unit named <literal>default.target</literal>; the dependencies of this unit cause all system services to be started, file systems to be mounted, swap files to be activated, and so on.
In NixOS, all system services are started and monitored using the systemd
program. Systemd is the “init” process of the system (i.e. PID 1), the
parent of all other processes. It manages a set of so-called “units”,
which can be things like system services (programs), but also mount points,
swap files, devices, targets (groups of units) and more. Units can have
complex dependencies; for instance, one unit can require that another unit
must be successfully started before the first unit can be started. When the
system boots, it starts a unit named <literal>default.target</literal>; the
dependencies of this unit cause all system services to be started, file
systems to be mounted, swap files to be activated, and so on.
</para>
<para>
The command <command>systemctl</command> is the main way to interact with <command>systemd</command>. Without any arguments, it shows the status of active units:
The command <command>systemctl</command> is the main way to interact with
<command>systemd</command>. Without any arguments, it shows the status of
active units:
<screen>
<prompt>$ </prompt>systemctl
-.mount loaded active mounted /
@ -19,7 +30,8 @@ graphical.target loaded active active Graphical Interface
</screen>
</para>
<para>
You can ask for detailed status information about a unit, for instance, the PostgreSQL database service:
You can ask for detailed status information about a unit, for instance, the
PostgreSQL database service:
<screen>
<prompt>$ </prompt>systemctl status postgresql.service
postgresql.service - PostgreSQL Server
@ -39,7 +51,9 @@ Jan 07 15:55:57 hagbard postgres[2390]: [1-1] LOG: database system is ready to
Jan 07 15:55:57 hagbard postgres[2420]: [1-1] LOG: autovacuum launcher started
Jan 07 15:55:57 hagbard systemd[1]: Started PostgreSQL Server.
</screen>
Note that this shows the status of the unit (active and running), all the processes belonging to the service, as well as the most recent log messages from the service.
Note that this shows the status of the unit (active and running), all the
processes belonging to the service, as well as the most recent log messages
from the service.
</para>
<para>
Units can be stopped, started or restarted:
@ -48,7 +62,9 @@ Jan 07 15:55:57 hagbard systemd[1]: Started PostgreSQL Server.
# systemctl start postgresql.service
# systemctl restart postgresql.service
</screen>
These operations are synchronous: they wait until the service has finished starting or stopping (or has failed). Starting a unit will cause the dependencies of that unit to be started as well (if necessary).
These operations are synchronous: they wait until the service has finished
starting or stopping (or has failed). Starting a unit will cause the
dependencies of that unit to be started as well (if necessary).
</para>
<!-- - cgroups: each service and user session is a cgroup

@ -6,15 +6,23 @@
<title>Nix Store Corruption</title>
<para>
After a system crash, it’s possible for files in the Nix store to become corrupted. (For instance, the Ext4 file system has the tendency to replace un-synced files with zero bytes.) NixOS tries hard to prevent this from happening: it performs a <command>sync</command> before switching to a new configuration, and Nix’s database is fully transactional. If corruption still occurs, you may be able to fix it automatically.
After a system crash, it’s possible for files in the Nix store to become
corrupted. (For instance, the Ext4 file system has the tendency to replace
un-synced files with zero bytes.) NixOS tries hard to prevent this from
happening: it performs a <command>sync</command> before switching to a new
configuration, and Nix’s database is fully transactional. If corruption
still occurs, you may be able to fix it automatically.
</para>
<para>
If the corruption is in a path in the closure of the NixOS system configuration, you can fix it by doing
If the corruption is in a path in the closure of the NixOS system
configuration, you can fix it by doing
<screen>
<prompt># </prompt>nixos-rebuild switch --repair
</screen>
This will cause Nix to check every path in the closure, and if its cryptographic hash differs from the hash recorded in Nix’s database, the path is rebuilt or redownloaded.
This will cause Nix to check every path in the closure, and if its
cryptographic hash differs from the hash recorded in Nix’s database, the
path is rebuilt or redownloaded.
</para>
<para>
@ -22,6 +30,7 @@
<screen>
<prompt># </prompt>nix-store --verify --check-contents --repair
</screen>
Any corrupt paths will be redownloaded if they’re available in a binary cache; otherwise, they cannot be repaired.
Any corrupt paths will be redownloaded if they’re available in a binary
cache; otherwise, they cannot be repaired.
</para>
</section>

@ -5,7 +5,8 @@
xml:id="ch-troubleshooting">
<title>Troubleshooting</title>
<para>
This chapter describes solutions to common problems you might encounter when you manage your NixOS system.
This chapter describes solutions to common problems you might encounter when
you manage your NixOS system.
</para>
<xi:include href="boot-problems.xml" />
<xi:include href="maintenance-mode.xml" />

@ -5,7 +5,10 @@
xml:id="sec-user-sessions">
<title>User Sessions</title>
<para>
Systemd keeps track of all users who are logged into the system (e.g. on a virtual console or remotely via SSH). The command <command>loginctl</command> allows querying and manipulating user sessions. For instance, to list all user sessions:
Systemd keeps track of all users who are logged into the system (e.g. on a
virtual console or remotely via SSH). The command <command>loginctl</command>
allows querying and manipulating user sessions. For instance, to list all
user sessions:
<screen>
<prompt>$ </prompt>loginctl
SESSION UID USER SEAT
@ -13,7 +16,10 @@
c3 0 root seat0
c4 500 alice
</screen>
This shows that two users are logged in locally, while another is logged in remotely. (“Seats” are essentially the combinations of displays and input devices attached to the system; usually, there is only one seat.) To get information about a session:
This shows that two users are logged in locally, while another is logged in
remotely. (“Seats” are essentially the combinations of displays and input
devices attached to the system; usually, there is only one seat.) To get
information about a session:
<screen>
<prompt>$ </prompt>loginctl session-status c3
c3 - root (0)
@ -28,7 +34,10 @@ c3 - root (0)
├─10339 -bash
└─10355 w3m nixos.org
</screen>
This shows that the user is logged in on virtual console 3. It also lists the processes belonging to this session. Since systemd keeps track of this, you can terminate a session in a way that ensures that all the session’s processes are gone:
This shows that the user is logged in on virtual console 3. It also lists the
processes belonging to this session. Since systemd keeps track of this, you
can terminate a session in a way that ensures that all the session’s
processes are gone:
<screen>
# loginctl terminate-session c3
</screen>

@ -6,7 +6,8 @@
<title>Abstractions</title>
<para>
If you find yourself repeating yourself over and over, it’s time to abstract. Take, for instance, this Apache HTTP Server configuration:
If you find yourself repeating yourself over and over, it’s time to
abstract. Take, for instance, this Apache HTTP Server configuration:
<programlisting>
{
<xref linkend="opt-services.httpd.virtualHosts"/> =
@ -26,7 +27,9 @@
];
}
</programlisting>
It defines two virtual hosts with nearly identical configuration; the only difference is that the second one has SSL enabled. To prevent this duplication, we can use a <literal>let</literal>:
It defines two virtual hosts with nearly identical configuration; the only
difference is that the second one has SSL enabled. To prevent this
duplication, we can use a <literal>let</literal>:
<programlisting>
let
exampleOrgCommon =
@ -47,11 +50,16 @@ in
];
}
</programlisting>
The <literal>let exampleOrgCommon = <replaceable>...</replaceable></literal> defines a variable named <literal>exampleOrgCommon</literal>. The <literal>//</literal> operator merges two attribute sets, so the configuration of the second virtual host is the set <literal>exampleOrgCommon</literal> extended with the SSL options.
The <literal>let exampleOrgCommon = <replaceable>...</replaceable></literal>
defines a variable named <literal>exampleOrgCommon</literal>. The
<literal>//</literal> operator merges two attribute sets, so the
configuration of the second virtual host is the set
<literal>exampleOrgCommon</literal> extended with the SSL options.
</para>
<para>
You can write a <literal>let</literal> wherever an expression is allowed. Thus, you also could have written:
You can write a <literal>let</literal> wherever an expression is allowed.
Thus, you also could have written:
<programlisting>
{
<xref linkend="opt-services.httpd.virtualHosts"/> =
@ -61,11 +69,16 @@ in
];
}
</programlisting>
but not <literal>{ let exampleOrgCommon = <replaceable>...</replaceable>; in <replaceable>...</replaceable>; }</literal> since attributes (as opposed to attribute values) are not expressions.
but not <literal>{ let exampleOrgCommon = <replaceable>...</replaceable>; in
<replaceable>...</replaceable>; }</literal> since attributes (as opposed to
attribute values) are not expressions.
</para>
<para>
<emphasis>Functions</emphasis> provide another method of abstraction. For instance, suppose that we want to generate lots of different virtual hosts, all with identical configuration except for the host name. This can be done as follows:
<emphasis>Functions</emphasis> provide another method of abstraction. For
instance, suppose that we want to generate lots of different virtual hosts,
all with identical configuration except for the host name. This can be done
as follows:
<programlisting>
{
<xref linkend="opt-services.httpd.virtualHosts"/> =
@ -83,11 +96,15 @@ in
];
}
</programlisting>
Here, <varname>makeVirtualHost</varname> is a function that takes a single argument <literal>name</literal> and returns the configuration for a virtual host. That function is then called for several names to produce the list of virtual host configurations.
Here, <varname>makeVirtualHost</varname> is a function that takes a single
argument <literal>name</literal> and returns the configuration for a virtual
host. That function is then called for several names to produce the list of
virtual host configurations.
</para>
<para>
We can further improve on this by using the function <varname>map</varname>, which applies another function to every element in a list:
We can further improve on this by using the function <varname>map</varname>,
which applies another function to every element in a list:
<programlisting>
{
<xref linkend="opt-services.httpd.virtualHosts"/> =
@ -97,11 +114,15 @@ in
[ "example.org" "example.com" "example.gov" "example.nl" ];
}
</programlisting>
(The function <literal>map</literal> is called a <emphasis>higher-order function</emphasis> because it takes another function as an argument.)
(The function <literal>map</literal> is called a <emphasis>higher-order
function</emphasis> because it takes another function as an argument.)
</para>
<para>
What if you need more than one argument, for instance, if we want to use a different <literal>documentRoot</literal> for each virtual host? Then we can make <varname>makeVirtualHost</varname> a function that takes a <emphasis>set</emphasis> as its argument, like this:
What if you need more than one argument, for instance, if we want to use a
different <literal>documentRoot</literal> for each virtual host? Then we can
make <varname>makeVirtualHost</varname> a function that takes a
<emphasis>set</emphasis> as its argument, like this:
<programlisting>
{
<xref linkend="opt-services.httpd.virtualHosts"/> =
@ -119,7 +140,9 @@ in
];
}
</programlisting>
But in this case (where every root is a subdirectory of <filename>/sites</filename> named after the virtual host), it would have been shorter to define <varname>makeVirtualHost</varname> as
But in this case (where every root is a subdirectory of
<filename>/sites</filename> named after the virtual host), it would have been
shorter to define <varname>makeVirtualHost</varname> as
<programlisting>
makeVirtualHost = name:
{ hostName = name;
@ -127,6 +150,7 @@ makeVirtualHost = name:
adminAddr = "alice@example.org";
};
</programlisting>
Here, the construct <literal>${<replaceable>...</replaceable>}</literal> allows the result of an expression to be spliced into a string.
Here, the construct <literal>${<replaceable>...</replaceable>}</literal>
allows the result of an expression to be spliced into a string.
</para>
</section>

@ -6,7 +6,10 @@
<title>Ad-Hoc Configuration</title>
<para>
You can use <xref linkend="opt-networking.localCommands"/> to specify shell commands to be run at the end of <literal>network-setup.service</literal>. This is useful for doing network configuration not covered by the existing NixOS modules. For instance, to statically configure an IPv6 address:
You can use <xref linkend="opt-networking.localCommands"/> to specify shell
commands to be run at the end of <literal>network-setup.service</literal>.
This is useful for doing network configuration not covered by the existing
NixOS modules. For instance, to statically configure an IPv6 address:
<programlisting>
<xref linkend="opt-networking.localCommands"/> =
''

@ -6,18 +6,33 @@
<title>Ad-Hoc Package Management</title>
<para>
With the command <command>nix-env</command>, you can install and uninstall packages from the command line. For instance, to install Mozilla Thunderbird:
With the command <command>nix-env</command>, you can install and uninstall
packages from the command line. For instance, to install Mozilla Thunderbird:
<screen>
<prompt>$ </prompt>nix-env -iA nixos.thunderbird</screen>
If you invoke this as root, the package is installed in the Nix profile <filename>/nix/var/nix/profiles/default</filename> and visible to all users of the system; otherwise, the package ends up in <filename>/nix/var/nix/profiles/per-user/<replaceable>username</replaceable>/profile</filename> and is not visible to other users. The <option>-A</option> flag specifies the package by its attribute name; without it, the package is installed by matching against its package name (e.g. <literal>thunderbird</literal>). The latter is slower because it requires matching against all available Nix packages, and is ambiguous if there are multiple matching packages.
If you invoke this as root, the package is installed in the Nix profile
<filename>/nix/var/nix/profiles/default</filename> and visible to all users
of the system; otherwise, the package ends up in
<filename>/nix/var/nix/profiles/per-user/<replaceable>username</replaceable>/profile</filename>
and is not visible to other users. The <option>-A</option> flag specifies the
package by its attribute name; without it, the package is installed by
matching against its package name (e.g. <literal>thunderbird</literal>). The
latter is slower because it requires matching against all available Nix
packages, and is ambiguous if there are multiple matching packages.
</para>
<para>
Packages come from the NixOS channel. You typically upgrade a package by updating to the latest version of the NixOS channel:
Packages come from the NixOS channel. You typically upgrade a package by
updating to the latest version of the NixOS channel:
<screen>
<prompt>$ </prompt>nix-channel --update nixos
</screen>
and then running <literal>nix-env -i</literal> again. Other packages in the profile are <emphasis>not</emphasis> affected; this is the crucial difference with the declarative style of package management, where running <command>nixos-rebuild switch</command> causes all packages to be updated to their current versions in the NixOS channel. You can however upgrade all packages for which there is a newer version by doing:
and then running <literal>nix-env -i</literal> again. Other packages in the
profile are <emphasis>not</emphasis> affected; this is the crucial difference
with the declarative style of package management, where running
<command>nixos-rebuild switch</command> causes all packages to be updated to
their current versions in the NixOS channel. You can however upgrade all
packages for which there is a newer version by doing:
<screen>
<prompt>$ </prompt>nix-env -u '*'
</screen>
@ -38,7 +53,8 @@
</para>
<para>
<command>nix-env</command> has many more flags. For details, see the <citerefentry>
<command>nix-env</command> has many more flags. For details, see the
<citerefentry>
<refentrytitle>nix-env</refentrytitle>
<manvolnum>1</manvolnum></citerefentry> manpage or the Nix manual.
</para>

@ -6,23 +6,33 @@
<title>Adding Custom Packages</title>
<para>
It’s possible that a package you need is not available in NixOS. In that case, you can do two things. First, you can clone the Nixpkgs repository, add the package to your clone, and (optionally) submit a patch or pull request to have it accepted into the main Nixpkgs repository. This is described in detail in the <link
xlink:href="http://nixos.org/nixpkgs/manual">Nixpkgs manual</link>. In short, you clone Nixpkgs:
It’s possible that a package you need is not available in NixOS. In that
case, you can do two things. First, you can clone the Nixpkgs repository, add
the package to your clone, and (optionally) submit a patch or pull request to
have it accepted into the main Nixpkgs repository. This is described in
detail in the <link
xlink:href="http://nixos.org/nixpkgs/manual">Nixpkgs
manual</link>. In short, you clone Nixpkgs:
<screen>
<prompt>$ </prompt>git clone https://github.com/NixOS/nixpkgs
<prompt>$ </prompt>cd nixpkgs
</screen>
Then you write and test the package as described in the Nixpkgs manual. Finally, you add it to <literal>environment.systemPackages</literal>, e.g.
Then you write and test the package as described in the Nixpkgs manual.
Finally, you add it to <literal>environment.systemPackages</literal>, e.g.
<programlisting>
<xref linkend="opt-environment.systemPackages"/> = [ pkgs.my-package ];
</programlisting>
and you run <command>nixos-rebuild</command>, specifying your own Nixpkgs tree:
and you run <command>nixos-rebuild</command>, specifying your own Nixpkgs
tree:
<screen>
# nixos-rebuild switch -I nixpkgs=/path/to/my/nixpkgs</screen>
</para>
<para>
The second possibility is to add the package outside of the Nixpkgs tree. For instance, here is how you specify a build of the <link xlink:href="https://www.gnu.org/software/hello/">GNU Hello</link> package directly in <filename>configuration.nix</filename>:
The second possibility is to add the package outside of the Nixpkgs tree. For
instance, here is how you specify a build of the
<link xlink:href="https://www.gnu.org/software/hello/">GNU Hello</link>
package directly in <filename>configuration.nix</filename>:
<programlisting>
<xref linkend="opt-environment.systemPackages"/> =
let
@ -36,7 +46,8 @@ xlink:href="http://nixos.org/nixpkgs/manual">Nixpkgs manual</link>. In short, yo
in
[ my-hello ];
</programlisting>
Of course, you can also move the definition of <literal>my-hello</literal> into a separate Nix expression, e.g.
Of course, you can also move the definition of <literal>my-hello</literal>
into a separate Nix expression, e.g.
<programlisting>
<xref linkend="opt-environment.systemPackages"/> = [ (import ./my-hello.nix) ];
</programlisting>

@ -13,7 +13,15 @@
{ <replaceable>option definitions</replaceable>
}
</programlisting>
The first line (<literal>{ config, pkgs, ... }:</literal>) denotes that this is actually a function that takes at least the two arguments <varname>config</varname> and <varname>pkgs</varname>. (These are explained later.) The function returns a <emphasis>set</emphasis> of option definitions (<literal>{ <replaceable>...</replaceable> }</literal>). These definitions have the form <literal><replaceable>name</replaceable> = <replaceable>value</replaceable></literal>, where <replaceable>name</replaceable> is the name of an option and <replaceable>value</replaceable> is its value. For example,
The first line (<literal>{ config, pkgs, ... }:</literal>) denotes that this
is actually a function that takes at least the two arguments
<varname>config</varname> and <varname>pkgs</varname>. (These are explained
later.) The function returns a <emphasis>set</emphasis> of option definitions
(<literal>{ <replaceable>...</replaceable> }</literal>). These definitions
have the form <literal><replaceable>name</replaceable> =
<replaceable>value</replaceable></literal>, where
<replaceable>name</replaceable> is the name of an option and
<replaceable>value</replaceable> is its value. For example,
<programlisting>
{ config, pkgs, ... }:
@ -22,11 +30,19 @@
<xref linkend="opt-services.httpd.documentRoot"/> = "/webroot";
}
</programlisting>
defines a configuration with three option definitions that together enable the Apache HTTP Server with <filename>/webroot</filename> as the document root.
defines a configuration with three option definitions that together enable
the Apache HTTP Server with <filename>/webroot</filename> as the document
root.
</para>
<para>
Sets can be nested, and in fact dots in option names are shorthand for defining a set containing another set. For instance, <xref linkend="opt-services.httpd.enable"/> defines a set named <varname>services</varname> that contains a set named <varname>httpd</varname>, which in turn contains an option definition named <varname>enable</varname> with value <literal>true</literal>. This means that the example above can also be written as:
Sets can be nested, and in fact dots in option names are shorthand for
defining a set containing another set. For instance,
<xref linkend="opt-services.httpd.enable"/> defines a set named
<varname>services</varname> that contains a set named
<varname>httpd</varname>, which in turn contains an option definition named
<varname>enable</varname> with value <literal>true</literal>. This means that
the example above can also be written as:
<programlisting>
{ config, pkgs, ... }:
@ -39,15 +55,22 @@
};
}
</programlisting>
which may be more convenient if you have lots of option definitions that share the same prefix (such as <literal>services.httpd</literal>).
which may be more convenient if you have lots of option definitions that
share the same prefix (such as <literal>services.httpd</literal>).
</para>
<para>
NixOS checks your option definitions for correctness. For instance, if you try to define an option that doesn’t exist (that is, doesn’t have a corresponding <emphasis>option declaration</emphasis>), <command>nixos-rebuild</command> will give an error like:
NixOS checks your option definitions for correctness. For instance, if you
try to define an option that doesn’t exist (that is, doesn’t have a
corresponding <emphasis>option declaration</emphasis>),
<command>nixos-rebuild</command> will give an error like:
<screen>
The option `services.httpd.enable' defined in `/etc/nixos/configuration.nix' does not exist.
</screen>
Likewise, values in option definitions must have a correct type. For instance, <option>services.httpd.enable</option> must be a Boolean (<literal>true</literal> or <literal>false</literal>). Trying to give it a value of another type, such as a string, will cause an error:
Likewise, values in option definitions must have a correct type. For
instance, <option>services.httpd.enable</option> must be a Boolean
(<literal>true</literal> or <literal>false</literal>). Trying to give it a
value of another type, such as a string, will cause an error:
<screen>
The option value `services.httpd.enable' in `/etc/nixos/configuration.nix' is not a boolean.
</screen>
@ -66,10 +89,12 @@ The option value `services.httpd.enable' in `/etc/nixos/configuration.nix' is no
<programlisting>
<xref linkend="opt-networking.hostName"/> = "dexter";
</programlisting>
Special characters can be escaped by prefixing them with a backslash (e.g. <literal>\"</literal>).
Special characters can be escaped by prefixing them with a backslash
(e.g. <literal>\"</literal>).
</para>
<para>
Multi-line strings can be enclosed in <emphasis>double single quotes</emphasis>, e.g.
Multi-line strings can be enclosed in <emphasis>double single
quotes</emphasis>, e.g.
<programlisting>
<xref linkend="opt-networking.extraHosts"/> =
''
@ -77,7 +102,13 @@ The option value `services.httpd.enable' in `/etc/nixos/configuration.nix' is no
10.0.0.1 server
'';
</programlisting>
The main difference is that it strips from each line a number of spaces equal to the minimal indentation of the string as a whole (disregarding the indentation of empty lines), and that characters like <literal>"</literal> and <literal>\</literal> are not special (making it more convenient for including things like shell code). See more info about this in the Nix manual <link
The main difference is that it strips from each line a number of spaces
equal to the minimal indentation of the string as a whole (disregarding
the indentation of empty lines), and that characters like
<literal>"</literal> and <literal>\</literal> are not special (making it
more convenient for including things like shell code). See more info
about this in the Nix manual
<link
xlink:href="https://nixos.org/nix/manual/#ssec-values">here</link>.
</para>
</listitem>
@ -106,7 +137,12 @@ The option value `services.httpd.enable' in `/etc/nixos/configuration.nix' is no
<programlisting>
<xref linkend="opt-boot.kernel.sysctl"/>."net.ipv4.tcp_keepalive_time" = 60;
</programlisting>
(Note that here the attribute name <literal>net.ipv4.tcp_keepalive_time</literal> is enclosed in quotes to prevent it from being interpreted as a set named <literal>net</literal> containing a set named <literal>ipv4</literal>, and so on. This is because it’s not a NixOS option but the literal name of a Linux kernel setting.)
(Note that here the attribute name
<literal>net.ipv4.tcp_keepalive_time</literal> is enclosed in quotes to
prevent it from being interpreted as a set named <literal>net</literal>
containing a set named <literal>ipv4</literal>, and so on. This is
because it’s not a NixOS option but the literal name of a Linux kernel
setting.)
</para>
</listitem>
</varlistentry>
@ -116,7 +152,8 @@ The option value `services.httpd.enable' in `/etc/nixos/configuration.nix' is no
</term>
<listitem>
<para>
Sets were introduced above. They are name/value pairs enclosed in braces, as in the option definition
Sets were introduced above. They are name/value pairs enclosed in braces,
as in the option definition
<programlisting>
<xref linkend="opt-fileSystems"/>."/boot" =
{ device = "/dev/sda1";
@ -133,7 +170,8 @@ The option value `services.httpd.enable' in `/etc/nixos/configuration.nix' is no
</term>
<listitem>
<para>
The important thing to note about lists is that list elements are separated by whitespace, like this:
The important thing to note about lists is that list elements are
separated by whitespace, like this:
<programlisting>
<xref linkend="opt-boot.kernelModules"/> = [ "fuse" "kvm-intel" "coretemp" ];
</programlisting>
@ -150,7 +188,9 @@ swapDevices = [ { device = "/dev/disk/by-label/swap"; } ];
</term>
<listitem>
<para>
Usually, the packages you need are already part of the Nix Packages collection, which is a set that can be accessed through the function argument <varname>pkgs</varname>. Typical uses:
Usually, the packages you need are already part of the Nix Packages
collection, which is a set that can be accessed through the function
argument <varname>pkgs</varname>. Typical uses:
<programlisting>
<xref linkend="opt-environment.systemPackages"/> =
[ pkgs.thunderbird
@ -159,7 +199,10 @@ swapDevices = [ { device = "/dev/disk/by-label/swap"; } ];
<xref linkend="opt-services.postgresql.package"/> = pkgs.postgresql_10;
</programlisting>
The latter option definition changes the default PostgreSQL package used by NixOS’s PostgreSQL service to 10.x. For more information on packages, including how to add new ones, see <xref linkend="sec-custom-packages"/>.
The latter option definition changes the default PostgreSQL package used
by NixOS’s PostgreSQL service to 10.x. For more information on
packages, including how to add new ones, see
<xref linkend="sec-custom-packages"/>.
</para>
</listitem>
</varlistentry>

@ -5,8 +5,18 @@
xml:id="sec-configuration-syntax">
<title>Configuration Syntax</title>
<para>
The NixOS configuration file <filename>/etc/nixos/configuration.nix</filename> is actually a <emphasis>Nix expression</emphasis>, which is the Nix package manager’s purely functional language for describing how to build packages and configurations. This means you have all the expressive power of that language at your disposal, including the ability to abstract over common patterns, which is very useful when managing complex systems. The syntax and semantics of the Nix language are fully described in the <link
xlink:href="http://nixos.org/nix/manual/#chap-writing-nix-expressions">Nix manual</link>, but here we give a short overview of the most important constructs useful in NixOS configuration files.
The NixOS configuration file
<filename>/etc/nixos/configuration.nix</filename> is actually a <emphasis>Nix
expression</emphasis>, which is the Nix package manager’s purely functional
language for describing how to build packages and configurations. This means
you have all the expressive power of that language at your disposal,
including the ability to abstract over common patterns, which is very useful
when managing complex systems. The syntax and semantics of the Nix language
are fully described in the
<link
xlink:href="http://nixos.org/nix/manual/#chap-writing-nix-expressions">Nix
manual</link>, but here we give a short overview of the most important
constructs useful in NixOS configuration files.
</para>
<xi:include href="config-file.xml" />
<xi:include href="abstractions.xml" />

@ -6,7 +6,11 @@
<title>Configuration</title>
<partintro xml:id="ch-configuration-intro">
<para>
This chapter describes how to configure various aspects of a NixOS machine through the configuration file <filename>/etc/nixos/configuration.nix</filename>. As described in <xref linkend="sec-changing-config" />, changes to this file only take effect after you run <command>nixos-rebuild</command>.
This chapter describes how to configure various aspects of a NixOS machine
through the configuration file
<filename>/etc/nixos/configuration.nix</filename>. As described in
<xref linkend="sec-changing-config" />, changes to this file only take
effect after you run <command>nixos-rebuild</command>.
</para>
</partintro>
<xi:include href="config-syntax.xml" />

@ -6,25 +6,47 @@
<title>Customising Packages</title>
<para>
Some packages in Nixpkgs have options to enable or disable optional functionality or change other aspects of the package. For instance, the Firefox wrapper package (which provides Firefox with a set of plugins such as the Adobe Flash player) has an option to enable the Google Talk plugin. It can be set in <filename>configuration.nix</filename> as follows: <filename> nixpkgs.config.firefox.enableGoogleTalkPlugin = true; </filename>
Some packages in Nixpkgs have options to enable or disable optional
functionality or change other aspects of the package. For instance, the
Firefox wrapper package (which provides Firefox with a set of plugins such as
the Adobe Flash player) has an option to enable the Google Talk plugin. It
can be set in <filename>configuration.nix</filename> as follows: <filename>
nixpkgs.config.firefox.enableGoogleTalkPlugin = true; </filename>
</para>
<warning>
<para>
Unfortunately, Nixpkgs currently lacks a way to query available configuration options.
Unfortunately, Nixpkgs currently lacks a way to query available
configuration options.
</para>
</warning>
<para>
Apart from high-level options, it’s possible to tweak a package in almost arbitrary ways, such as changing or disabling dependencies of a package. For instance, the Emacs package in Nixpkgs by default has a dependency on GTK 2. If you want to build it against GTK 3, you can specify that as follows:
Apart from high-level options, it’s possible to tweak a package in almost
arbitrary ways, such as changing or disabling dependencies of a package. For
instance, the Emacs package in Nixpkgs by default has a dependency on GTK 2.
If you want to build it against GTK 3, you can specify that as follows:
<programlisting>
<xref linkend="opt-environment.systemPackages"/> = [ (pkgs.emacs.override { gtk = pkgs.gtk3; }) ];
</programlisting>
The function <varname>override</varname> performs the call to the Nix function that produces Emacs, with the original arguments amended by the set of arguments specified by you. So here the function argument <varname>gtk</varname> gets the value <literal>pkgs.gtk3</literal>, causing Emacs to depend on GTK 3. (The parentheses are necessary because in Nix, function application binds more weakly than list construction, so without them, <xref linkend="opt-environment.systemPackages"/> would be a list with two elements.)
The function <varname>override</varname> performs the call to the Nix
function that produces Emacs, with the original arguments amended by the set
of arguments specified by you. So here the function argument
<varname>gtk</varname> gets the value <literal>pkgs.gtk3</literal>, causing
Emacs to depend on GTK 3. (The parentheses are necessary because in Nix,
function application binds more weakly than list construction, so without
them, <xref linkend="opt-environment.systemPackages"/> would be a list with
two elements.)
</para>
<para>
Even greater customisation is possible using the function <varname>overrideAttrs</varname>. While the <varname>override</varname> mechanism above overrides the arguments of a package function, <varname>overrideAttrs</varname> allows changing the <emphasis>attributes</emphasis> passed to <literal>mkDerivation</literal>. This permits changing any aspect of the package, such as the source code. For instance, if you want to override the source code of Emacs, you can say:
Even greater customisation is possible using the function
<varname>overrideAttrs</varname>. While the <varname>override</varname>
mechanism above overrides the arguments of a package function,
<varname>overrideAttrs</varname> allows changing the
<emphasis>attributes</emphasis> passed to <literal>mkDerivation</literal>.
This permits changing any aspect of the package, such as the source code. For
instance, if you want to override the source code of Emacs, you can say:
<programlisting>
<xref linkend="opt-environment.systemPackages"/> = [
(pkgs.emacs.overrideAttrs (oldAttrs: {