diff options
Diffstat (limited to 'nixos/doc')
101 files changed, 12392 insertions, 5018 deletions
diff --git a/nixos/doc/manual/.gitignore b/nixos/doc/manual/.gitignore new file mode 100644 index 000000000000..879282624217 --- /dev/null +++ b/nixos/doc/manual/.gitignore @@ -0,0 +1,2 @@ +generated +manual-combined.xml diff --git a/nixos/doc/manual/Makefile b/nixos/doc/manual/Makefile new file mode 100644 index 000000000000..5cbbf140869a --- /dev/null +++ b/nixos/doc/manual/Makefile @@ -0,0 +1,29 @@ +.PHONY: all +all: manual-combined.xml format + +.PHONY: debug +debug: generated manual-combined.xml + +manual-combined.xml: generated *.xml + rm -f ./manual-combined.xml + nix-shell --packages xmloscopy \ + --run "xmloscopy --docbook5 ./manual.xml ./manual-combined.xml" + +.PHONY: format +format: + find . -iname '*.xml' -type f -print0 | xargs -0 -I{} -n1 \ + xmlformat --config-file "../xmlformat.conf" -i {} + +.PHONY: fix-misc-xml +fix-misc-xml: + find . -iname '*.xml' -type f \ + -exec ../varlistentry-fixer.rb {} ';' + +.PHONY: clean +clean: + rm -f manual-combined.xml generated + +generated: ./options-to-docbook.xsl + nix-build ../../release.nix \ + --attr manualGeneratedSources.x86_64-linux \ + --out-link ./generated diff --git a/nixos/doc/manual/administration/boot-problems.xml b/nixos/doc/manual/administration/boot-problems.xml index be6ff3aac0fe..de3d8ac21aeb 100644 --- a/nixos/doc/manual/administration/boot-problems.xml +++ b/nixos/doc/manual/administration/boot-problems.xml @@ -3,63 +3,88 @@ xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="sec-boot-problems"> + <title>Boot Problems</title> -<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: + <variablelist> + <varlistentry> + <term> + <literal>boot.shell_on_fail</literal> + </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. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <literal>boot.debug1</literal> + </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>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <literal>boot.trace</literal> + </term> + <listitem> + <para> + Print every shell command executed by the stage 1 and 2 boot scripts. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <literal>single</literal> + </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. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <literal>systemd.log_level=debug systemd.log_target=console</literal> + </term> + <listitem> + <para> + Make systemd very verbose and send log messages to the console instead of + the journal. + </para> + </listitem> + </varlistentry> + </variablelist> + For more parameters recognised by systemd, see <citerefentry> + <refentrytitle>systemd</refentrytitle> + <manvolnum>1</manvolnum></citerefentry>. + </para> -<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: - -<variablelist> - - <varlistentry><term><literal>boot.shell_on_fail</literal></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.</para></listitem> - </varlistentry> - - <varlistentry><term><literal>boot.debug1</literal></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>.</para></listitem> - </varlistentry> - - <varlistentry><term><literal>boot.trace</literal></term> - <listitem><para>Print every shell command executed by the stage 1 - and 2 boot scripts.</para></listitem> - </varlistentry> - - <varlistentry><term><literal>single</literal></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.</para></listitem> - </varlistentry> - - <varlistentry><term><literal>systemd.log_level=debug systemd.log_target=console</literal></term> - <listitem><para>Make systemd very verbose and send log messages to - the console instead of the journal.</para></listitem> - </varlistentry> - -</variablelist> - -For more parameters recognised by systemd, see -<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</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.)</para> - -</section> \ No newline at end of file + <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.) + </para> +</section> diff --git a/nixos/doc/manual/administration/cleaning-store.xml b/nixos/doc/manual/administration/cleaning-store.xml index 41dc65795b68..ee201982a40b 100644 --- a/nixos/doc/manual/administration/cleaning-store.xml +++ b/nixos/doc/manual/administration/cleaning-store.xml @@ -3,60 +3,51 @@ xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" 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: - + <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: <screen> $ 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> -$ systemctl start nix-gc.service +# 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> -nix.gc.automatic = true; -nix.gc.dates = "03:15"; +<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: + </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: <screen> $ nix-collect-garbage -d </screen> -You can also do this for specific profiles, e.g. + You can also do this for specific profiles, e.g. <screen> $ 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>.</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. + 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. <screen> $ nix-store --optimise </screen> -Since this command needs to read the entire Nix store, it can take -quite a while to finish.</para> - -</chapter> \ No newline at end of file + Since this command needs to read the entire Nix store, it can take quite a + while to finish. + </para> +</chapter> diff --git a/nixos/doc/manual/administration/container-networking.xml b/nixos/doc/manual/administration/container-networking.xml index adea3e69840d..4b977d1d82eb 100644 --- a/nixos/doc/manual/administration/container-networking.xml +++ b/nixos/doc/manual/administration/container-networking.xml @@ -3,48 +3,53 @@ xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="sec-container-networking"> + <title>Container Networking</title> - -<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: - + <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: <screen> -$ nixos-container show-ip foo +# nixos-container show-ip foo 10.233.4.2 $ ping -c1 10.233.4.2 64 bytes from 10.233.4.2: icmp_seq=1 ttl=64 time=0.106 ms </screen> - -</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.</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: - + </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. + </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: <programlisting> -networking.nat.enable = true; -networking.nat.internalInterfaces = ["ve-+"]; -networking.nat.externalInterface = "eth0"; +<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.</para> - -</section> \ No newline at end of file + 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: +<programlisting> +networking.networkmanager.unmanaged = [ "interface-name:ve-*" ]; +</programlisting> + </para> +</section> diff --git a/nixos/doc/manual/administration/containers.xml b/nixos/doc/manual/administration/containers.xml index 4cd2c8ae5563..0d3355e56a58 100644 --- a/nixos/doc/manual/administration/containers.xml +++ b/nixos/doc/manual/administration/containers.xml @@ -3,32 +3,32 @@ xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="ch-containers"> - -<title>Container Management</title> - -<para>NixOS allows you to easily run other NixOS instances as -<emphasis>containers</emphasis>. Containers are a light-weight -approach to virtualisation that runs software in the container at the -same speed as in the host system. NixOS containers share the Nix store -of the host, making container creation very efficient.</para> - -<warning><para>Currently, NixOS containers are not perfectly isolated -from the host system. This means that a user with root access to the -container can do things that affect the host. So you should not give -container root access to untrusted users.</para></warning> - -<para>NixOS containers can be created in two ways: imperatively, using -the command <command>nixos-container</command>, and declaratively, by -specifying them in your <filename>configuration.nix</filename>. The -declarative approach implies that containers get upgraded along with -your host system when you run <command>nixos-rebuild</command>, which -is often not what you want. By contrast, in the imperative approach, -containers are configured and updated independently from the host -system.</para> - -<xi:include href="imperative-containers.xml" /> -<xi:include href="declarative-containers.xml" /> -<xi:include href="container-networking.xml" /> - + <title>Container Management</title> + <para> + NixOS allows you to easily run other NixOS instances as + <emphasis>containers</emphasis>. Containers are a light-weight approach to + virtualisation that runs software in the container at the same speed as in + the host system. NixOS containers share the Nix store of the host, making + container creation very efficient. + </para> + <warning> + <para> + Currently, NixOS containers are not perfectly isolated from the host system. + This means that a user with root access to the container can do things that + affect the host. So you should not give container root access to untrusted + users. + </para> + </warning> + <para> + NixOS containers can be created in two ways: imperatively, using the command + <command>nixos-container</command>, and declaratively, by specifying them in + your <filename>configuration.nix</filename>. The declarative approach implies + that containers get upgraded along with your host system when you run + <command>nixos-rebuild</command>, which is often not what you want. By + contrast, in the imperative approach, containers are configured and updated + independently from the host system. + </para> + <xi:include href="imperative-containers.xml" /> + <xi:include href="declarative-containers.xml" /> + <xi:include href="container-networking.xml" /> </chapter> - diff --git a/nixos/doc/manual/administration/control-groups.xml b/nixos/doc/manual/administration/control-groups.xml index 0d7b8ae910a7..bb8b7f83d9e0 100644 --- a/nixos/doc/manual/administration/control-groups.xml +++ b/nixos/doc/manual/administration/control-groups.xml @@ -3,20 +3,18 @@ xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" 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.</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: - + <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. + </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: <screen> $ systemd-cgls ├─user @@ -34,40 +32,34 @@ $ systemd-cgls │ └─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> -systemd.services.httpd.serviceConfig.CPUShares = 512; +<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.</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): - + 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): <programlisting> -systemd.services.httpd.serviceConfig.MemoryLimit = "512M"; +<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.</para> - + </para> + <para> + The command <command>systemd-cgtop</command> shows a continuously updated + list of all cgroups with their CPU and memory usage. + </para> </chapter> diff --git a/nixos/doc/manual/administration/declarative-containers.xml b/nixos/doc/manual/administration/declarative-containers.xml index 228c45b0c1fe..2a98fb126231 100644 --- a/nixos/doc/manual/administration/declarative-containers.xml +++ b/nixos/doc/manual/administration/declarative-containers.xml @@ -3,54 +3,58 @@ xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="sec-declarative-containers"> + <title>Declarative Container Specification</title> -<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: - + <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: <programlisting> containers.database = { config = { config, pkgs, ... }: - { services.postgresql.enable = true; - services.postgresql.package = pkgs.postgresql92; + { <xref linkend="opt-services.postgresql.enable"/> = true; + <xref linkend="opt-services.postgresql.package"/> = pkgs.postgresql96; }; }; </programlisting> - -If you run <literal>nixos-rebuild switch</literal>, the container will -be built and started. If the container was already running, it will be -updated in place, without rebooting.</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: - + 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: <programlisting> -containers.database = - { privateNetwork = true; - hostAddress = "192.168.100.10"; - localAddress = "192.168.100.11"; - }; +containers.database = { + <link linkend="opt-containers._name_.privateNetwork">privateNetwork</link> = true; + <link linkend="opt-containers._name_.hostAddress">hostAddress</link> = "192.168.100.10"; + <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.)</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>.</para> - -<para>Declarative containers can be started and stopped using the -corresponding systemd service, e.g. <literal>systemctl start -container@database</literal>.</para> - + 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>. + </para> + + <para> + Declarative containers can be started and stopped using the corresponding + systemd service, e.g. <literal>systemctl start container@database</literal>. + </para> </section> diff --git a/nixos/doc/manual/administration/imperative-containers.xml b/nixos/doc/manual/administration/imperative-containers.xml index 6131d4e04ea8..9cc7ca3e672a 100644 --- a/nixos/doc/manual/administration/imperative-containers.xml +++ b/nixos/doc/manual/administration/imperative-containers.xml @@ -3,122 +3,114 @@ xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="sec-imperative-containers"> + <title>Imperative Container Management</title> -<title>Imperative Container Management</title> - -<para>We’ll cover imperative container management using -<command>nixos-container</command> first. You create a container with -identifier <literal>foo</literal> as follows: + <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>. + </para> + <para> + You create a container with identifier <literal>foo</literal> as follows: <screen> -$ nixos-container create foo +# 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 'services.openssh.enable = true; \ - users.extraUsers.root.openssh.authorizedKeys.keys = ["ssh-dss AAAAB3N…"];' +# nixos-container create foo --config ' + <xref linkend="opt-services.openssh.enable"/> = true; + <link linkend="opt-users.users._name__.openssh.authorizedKeys.keys">users.extraUsers.root.openssh.authorizedKeys.keys</link> = ["ssh-dss AAAAB3N…"]; +' </screen> + </para> -</para> - -<para>Creating a container does not start it. To start the container, -run: - + <para> + Creating a container does not start it. To start the container, run: <screen> -$ nixos-container start foo +# 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 +# systemctl status container@foo </screen> + </para> -</para> - -<para>If the container has started succesfully, you can log in as -root using the <command>root-login</command> operation: - + <para> + 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 +# 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 +# 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 +# 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 </screen> + </para> -</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 - + <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 <screen> -$ nixos-container update foo +# 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 'services.httpd.enable = true; \ - services.httpd.adminAddr = "foo@example.org";' +# nixos-container update foo --config ' + <xref linkend="opt-services.httpd.enable"/> = true; + <xref linkend="opt-services.httpd.adminAddr"/> = "foo@example.org"; + <xref linkend="opt-networking.firewall.allowedTCPPorts"/> = [ 80 ]; +' -$ curl http://$(nixos-container show-ip foo)/ +# curl http://$(nixos-container show-ip foo)/ <!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>.</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.</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 - + 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. + </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 <screen> -$ nixos-container destroy foo +# nixos-container destroy foo </screen> - -</para> - -</section> \ No newline at end of file + </para> +</section> diff --git a/nixos/doc/manual/administration/logging.xml b/nixos/doc/manual/administration/logging.xml index 1d5df7770e29..a41936b373d6 100644 --- a/nixos/doc/manual/administration/logging.xml +++ b/nixos/doc/manual/administration/logging.xml @@ -3,26 +3,20 @@ xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" 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, - + <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, <screen> $ 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> $ 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. -- @@ -32,21 +26,18 @@ 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> $ journalctl -b -p crit Dec 17 21:08:06 mandark sudo[3673]: pam_unix(sudo:auth): auth could not identify password for [alice] Dec 29 01:30:22 mandark kernel[6131]: [1053513.909444] CPU6: Core temperature above threshold, cpu clock throttled (total events = 1) </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>.</para> - -</chapter> \ No newline at end of file + </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>. + </para> +</chapter> diff --git a/nixos/doc/manual/administration/maintenance-mode.xml b/nixos/doc/manual/administration/maintenance-mode.xml index 15c1f902da79..71e3f9ea665d 100644 --- a/nixos/doc/manual/administration/maintenance-mode.xml +++ b/nixos/doc/manual/administration/maintenance-mode.xml @@ -3,16 +3,14 @@ xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="sec-maintenance-mode"> + <title>Maintenance Mode</title> -<title>Maintenance Mode</title> - -<para>You can enter rescue mode by running: - + <para> + 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.</para> - -</section> \ No newline at end of file +# 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. + </para> +</section> diff --git a/nixos/doc/manual/administration/network-problems.xml b/nixos/doc/manual/administration/network-problems.xml index 3af9cc59742f..570f58358845 100644 --- a/nixos/doc/manual/administration/network-problems.xml +++ b/nixos/doc/manual/administration/network-problems.xml @@ -3,31 +3,25 @@ xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="sec-nix-network-issues"> + <title>Network Problems</title> -<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. - + <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. <screen> -$ nixos-rebuild switch --option use-binary-caches false +# 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/ +# nixos-rebuild switch --option binary-caches http://my-cache.example.org/ </screen> - -</para> - + </para> </section> diff --git a/nixos/doc/manual/administration/rebooting.xml b/nixos/doc/manual/administration/rebooting.xml index d1db7b141cf2..a5abd6f02588 100644 --- a/nixos/doc/manual/administration/rebooting.xml +++ b/nixos/doc/manual/administration/rebooting.xml @@ -3,42 +3,33 @@ xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="sec-rebooting"> - -<title>Rebooting and Shutting Down</title> - -<para>The system can be shut down (and automatically powered off) by -doing: - + <title>Rebooting and Shutting Down</title> + <para> + The system can be shut down (and automatically powered off) by doing: <screen> -$ shutdown +# shutdown </screen> - -This is equivalent to running <command>systemctl -poweroff</command>.</para> - -<para>To reboot the system, run - + This is equivalent to running <command>systemctl poweroff</command>. + </para> + <para> + To reboot the system, run <screen> -$ reboot +# 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 +# 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>.</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.</para> - -</chapter> \ No newline at end of file + </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>. + </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. + </para> +</chapter> diff --git a/nixos/doc/manual/administration/rollback.xml b/nixos/doc/manual/administration/rollback.xml index 23a3ece7c070..07c6acaa469c 100644 --- a/nixos/doc/manual/administration/rollback.xml +++ b/nixos/doc/manual/administration/rollback.xml @@ -3,46 +3,39 @@ xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="sec-rollback"> - -<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.</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: - + <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. + </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: <screen> -$ /run/current-system/bin/switch-to-configuration boot</screen> - -</para> - -<para>Second, you can switch to the previous configuration in a running -system: +# /run/current-system/bin/switch-to-configuration boot</screen> + </para> + <para> + Second, you can switch to the previous configuration in a running system: <screen> -$ nixos-rebuild switch --rollback</screen> - -This is equivalent to running: - +# nixos-rebuild switch --rollback</screen> + 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: - +# /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: <screen> $ ls -l /nix/var/nix/profiles/system-*-link <replaceable>...</replaceable> lrwxrwxrwx 1 root root 78 Aug 12 13:54 /nix/var/nix/profiles/system-268-link -> /nix/store/202b...-nixos-13.07pre4932_5a676e4-4be1055 </screen> - -</para> - -</section> \ No newline at end of file + </para> +</section> diff --git a/nixos/doc/manual/administration/running.xml b/nixos/doc/manual/administration/running.xml index 9091511ed527..786dd5e2390d 100644 --- a/nixos/doc/manual/administration/running.xml +++ b/nixos/doc/manual/administration/running.xml @@ -3,22 +3,19 @@ xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="ch-running"> - -<title>Administration</title> - -<partintro> -<para>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" /> -<xi:include href="rebooting.xml" /> -<xi:include href="user-sessions.xml" /> -<xi:include href="control-groups.xml" /> -<xi:include href="logging.xml" /> -<xi:include href="cleaning-store.xml" /> -<xi:include href="containers.xml" /> -<xi:include href="troubleshooting.xml" /> - + <title>Administration</title> + <partintro> + <para> + 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" /> + <xi:include href="rebooting.xml" /> + <xi:include href="user-sessions.xml" /> + <xi:include href="control-groups.xml" /> + <xi:include href="logging.xml" /> + <xi:include href="cleaning-store.xml" /> + <xi:include href="containers.xml" /> + <xi:include href="troubleshooting.xml" /> </part> diff --git a/nixos/doc/manual/administration/service-mgmt.xml b/nixos/doc/manual/administration/service-mgmt.xml index c0940a42f307..0c2085c81559 100644 --- a/nixos/doc/manual/administration/service-mgmt.xml +++ b/nixos/doc/manual/administration/service-mgmt.xml @@ -3,26 +3,23 @@ xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" 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.</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: - + <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. + </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: <screen> $ systemctl -.mount loaded active mounted / @@ -31,12 +28,10 @@ sshd.service loaded active running SSH Daemon graphical.target loaded active active Graphical Interface <replaceable>...</replaceable> </screen> - -</para> - -<para>You can ask for detailed status information about a unit, for -instance, the PostgreSQL database service: - + </para> + <para> + You can ask for detailed status information about a unit, for instance, the + PostgreSQL database service: <screen> $ systemctl status postgresql.service postgresql.service - PostgreSQL Server @@ -56,28 +51,22 @@ 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. - -</para> - -<para>Units can be stopped, started or restarted: - + 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: <screen> -$ systemctl stop postgresql.service -$ systemctl start postgresql.service -$ systemctl restart postgresql.service +# systemctl stop postgresql.service +# 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).</para> - + 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 - cgroup resource management --> - </chapter> diff --git a/nixos/doc/manual/administration/store-corruption.xml b/nixos/doc/manual/administration/store-corruption.xml index 0160cb45358b..a4ca3b651e20 100644 --- a/nixos/doc/manual/administration/store-corruption.xml +++ b/nixos/doc/manual/administration/store-corruption.xml @@ -3,35 +3,34 @@ xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="sec-nix-store-corruption"> - -<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.</para> - -<para>If the corruption is in a path in the closure of the NixOS -system configuration, you can fix it by doing - + <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. + </para> + + <para> + If the corruption is in a path in the closure of the NixOS system + configuration, you can fix it by doing <screen> -$ nixos-rebuild switch --repair +# 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. + </para> -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>You can also scan the entire Nix store for corrupt paths: - + <para> + You can also scan the entire Nix store for corrupt paths: <screen> -$ nix-store --verify --check-contents --repair +# 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.</para> - -</section> \ No newline at end of file + Any corrupt paths will be redownloaded if they’re available in a binary + cache; otherwise, they cannot be repaired. + </para> +</section> diff --git a/nixos/doc/manual/administration/troubleshooting.xml b/nixos/doc/manual/administration/troubleshooting.xml index 351fb1883310..6496e7bde387 100644 --- a/nixos/doc/manual/administration/troubleshooting.xml +++ b/nixos/doc/manual/administration/troubleshooting.xml @@ -3,16 +3,14 @@ xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="ch-troubleshooting"> - -<title>Troubleshooting</title> - -<para>This chapter describes solutions to common problems you might -encounter when you manage your NixOS system.</para> - -<xi:include href="boot-problems.xml" /> -<xi:include href="maintenance-mode.xml" /> -<xi:include href="rollback.xml" /> -<xi:include href="store-corruption.xml" /> -<xi:include href="network-problems.xml" /> - + <title>Troubleshooting</title> + <para> + This chapter describes solutions to common problems you might encounter when + you manage your NixOS system. + </para> + <xi:include href="boot-problems.xml" /> + <xi:include href="maintenance-mode.xml" /> + <xi:include href="rollback.xml" /> + <xi:include href="store-corruption.xml" /> + <xi:include href="network-problems.xml" /> </chapter> diff --git a/nixos/doc/manual/administration/user-sessions.xml b/nixos/doc/manual/administration/user-sessions.xml index 05e2c1a9b29f..1d95cfb22b69 100644 --- a/nixos/doc/manual/administration/user-sessions.xml +++ b/nixos/doc/manual/administration/user-sessions.xml @@ -3,14 +3,12 @@ xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" 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: - + <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: <screen> $ loginctl SESSION UID USER SEAT @@ -18,12 +16,10 @@ $ loginctl 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> $ loginctl session-status c3 c3 - root (0) @@ -38,16 +34,12 @@ 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 +# loginctl terminate-session c3 </screen> - -</para> - -</chapter> \ No newline at end of file + </para> +</chapter> diff --git a/nixos/doc/manual/configuration/abstractions.xml b/nixos/doc/manual/configuration/abstractions.xml index cbd54bca62f9..5bf0635cc1aa 100644 --- a/nixos/doc/manual/configuration/abstractions.xml +++ b/nixos/doc/manual/configuration/abstractions.xml @@ -3,15 +3,14 @@ xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="sec-module-abstractions"> + <title>Abstractions</title> -<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: - + <para> + If you find yourself repeating yourself over and over, it’s time to + abstract. Take, for instance, this Apache HTTP Server configuration: <programlisting> { - services.httpd.virtualHosts = + <xref linkend="opt-services.httpd.virtualHosts"/> = [ { hostName = "example.org"; documentRoot = "/webroot"; adminAddr = "alice@example.org"; @@ -28,11 +27,9 @@ to abstract. Take, for instance, this Apache HTTP Server configuration: ]; } </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 = @@ -43,7 +40,7 @@ let }; in { - services.httpd.virtualHosts = + <xref linkend="opt-services.httpd.virtualHosts"/> = [ exampleOrgCommon (exampleOrgCommon // { enableSSL = true; @@ -53,40 +50,38 @@ 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.</para> - -<para>You can write a <literal>let</literal> wherever an expression is -allowed. Thus, you also could have written: - + 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: <programlisting> { - services.httpd.virtualHosts = + <xref linkend="opt-services.httpd.virtualHosts"/> = let exampleOrgCommon = <replaceable>...</replaceable>; in [ exampleOrgCommon (exampleOrgCommon // { <replaceable>...</replaceable> }) ]; } </programlisting> - -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: - + 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: <programlisting> { - services.httpd.virtualHosts = + <xref linkend="opt-services.httpd.virtualHosts"/> = let makeVirtualHost = name: { hostName = name; @@ -101,38 +96,36 @@ the host name. This can be done as follows: ]; } </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.</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: - + 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: <programlisting> { - services.httpd.virtualHosts = + <xref linkend="opt-services.httpd.virtualHosts"/> = let makeVirtualHost = <replaceable>...</replaceable>; in map makeVirtualHost [ "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.)</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: - + (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: <programlisting> { - services.httpd.virtualHosts = + <xref linkend="opt-services.httpd.virtualHosts"/> = let makeVirtualHost = { name, root }: { hostName = name; @@ -147,10 +140,9 @@ function that takes a <emphasis>set</emphasis> as its argument, like this: ]; } </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; @@ -158,9 +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.</para> - + Here, the construct <literal>${<replaceable>...</replaceable>}</literal> + allows the result of an expression to be spliced into a string. + </para> </section> diff --git a/nixos/doc/manual/configuration/ad-hoc-network-config.xml b/nixos/doc/manual/configuration/ad-hoc-network-config.xml index 26a572ba1fb5..00e595c7cb7f 100644 --- a/nixos/doc/manual/configuration/ad-hoc-network-config.xml +++ b/nixos/doc/manual/configuration/ad-hoc-network-config.xml @@ -3,22 +3,18 @@ xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="ad-hoc-network-config"> + <title>Ad-Hoc Configuration</title> -<title>Ad-Hoc Configuration</title> - -<para>You can use <option>networking.localCommands</option> 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: - + <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: <programlisting> -networking.localCommands = +<xref linkend="opt-networking.localCommands"/> = '' ip -6 addr add 2001:610:685:1::1/64 dev eth0 ''; </programlisting> - -</para> - + </para> </section> diff --git a/nixos/doc/manual/configuration/ad-hoc-packages.xml b/nixos/doc/manual/configuration/ad-hoc-packages.xml index a147291c4f3d..19159d8db5b6 100644 --- a/nixos/doc/manual/configuration/ad-hoc-packages.xml +++ b/nixos/doc/manual/configuration/ad-hoc-packages.xml @@ -3,61 +3,59 @@ xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="sec-ad-hoc-packages"> + <title>Ad-Hoc Package Management</title> -<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: - + <para> + With the command <command>nix-env</command>, you can install and uninstall + packages from the command line. For instance, to install Mozilla Thunderbird: <screen> $ 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.</para> - -<para>Packages come from the NixOS channel. You typically upgrade a -package by updating to the latest version of the NixOS channel: + 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: <screen> $ 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> $ nix-env -u '*' </screen> -</para> + </para> -<para>A package can be uninstalled using the <option>-e</option> -flag: + <para> + A package can be uninstalled using the <option>-e</option> flag: <screen> $ nix-env -e thunderbird </screen> -</para> + </para> -<para>Finally, you can roll back an undesirable -<command>nix-env</command> action: + <para> + Finally, you can roll back an undesirable <command>nix-env</command> action: <screen> $ nix-env --rollback </screen> -</para> - -<para><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> - + </para> + + <para> + <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> </section> diff --git a/nixos/doc/manual/configuration/adding-custom-packages.xml b/nixos/doc/manual/configuration/adding-custom-packages.xml index c1789fcbc041..b59287a622e6 100644 --- a/nixos/doc/manual/configuration/adding-custom-packages.xml +++ b/nixos/doc/manual/configuration/adding-custom-packages.xml @@ -3,45 +3,38 @@ xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="sec-custom-packages"> + <title>Adding Custom Packages</title> -<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: - + <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: <screen> $ git clone git://github.com/NixOS/nixpkgs.git $ 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> -environment.systemPackages = [ pkgs.my-package ]; +<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="http://www.gnu.org/software/hello/">GNU Hello</link> -package directly in <filename>configuration.nix</filename>: +# 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="http://www.gnu.org/software/hello/">GNU Hello</link> + package directly in <filename>configuration.nix</filename>: <programlisting> -environment.systemPackages = +<xref linkend="opt-environment.systemPackages"/> = let my-hello = with pkgs; stdenv.mkDerivation rec { name = "hello-2.8"; @@ -53,13 +46,12 @@ environment.systemPackages = 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> -environment.systemPackages = [ (import ./my-hello.nix) ]; +<xref linkend="opt-environment.systemPackages"/> = [ (import ./my-hello.nix) ]; </programlisting> -where <filename>my-hello.nix</filename> contains: + where <filename>my-hello.nix</filename> contains: <programlisting> with import <nixpkgs> {}; # bring all of Nixpkgs into scope @@ -71,14 +63,11 @@ stdenv.mkDerivation rec { }; } </programlisting> - -This allows testing the package easily: + This allows testing the package easily: <screen> $ nix-build my-hello.nix $ ./result/bin/hello Hello, world! </screen> - -</para> - + </para> </section> diff --git a/nixos/doc/manual/configuration/config-file.xml b/nixos/doc/manual/configuration/config-file.xml index b613c7f06cc8..8a1a39c98c10 100644 --- a/nixos/doc/manual/configuration/config-file.xml +++ b/nixos/doc/manual/configuration/config-file.xml @@ -3,49 +3,46 @@ xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="sec-configuration-file"> + <title>NixOS Configuration File</title> -<title>NixOS Configuration File</title> - -<para>The NixOS configuration file generally looks like this: - + <para> + The NixOS configuration file generally looks like this: <programlisting> { config, pkgs, ... }: { <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, ... }: -{ services.httpd.enable = true; - services.httpd.adminAddr = "alice@example.org"; - services.httpd.documentRoot = "/webroot"; +{ <xref linkend="opt-services.httpd.enable"/> = true; + <xref linkend="opt-services.httpd.adminAddr"/> = "alice@example.org"; + <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.</para> - -<para>Sets can be nested, and in fact dots in option names are -shorthand for defining a set containing another set. For instance, -<option>services.httpd.enable</option> 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: - + 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: <programlisting> { config, pkgs, ... }: @@ -58,156 +55,156 @@ This means that the example above can also be written as: }; } </programlisting> - -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: + 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: <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> - -</para> - -<para>Options have various types of values. The most important are: - -<variablelist> - <varlistentry> - <term>Strings</term> + </para> + + <para> + Options have various types of values. The most important are: + <variablelist> + <varlistentry> + <term> + Strings + </term> <listitem> - <para>Strings are enclosed in double quotes, e.g. - + <para> + Strings are enclosed in double quotes, e.g. <programlisting> -networking.hostName = "dexter"; +<xref linkend="opt-networking.hostName"/> = "dexter"; </programlisting> - - 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. - + 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. <programlisting> -networking.extraHosts = +<xref linkend="opt-networking.extraHosts"/> = '' 127.0.0.2 other-localhost 10.0.0.1 server ''; </programlisting> - - The main difference is that preceding whitespace is - automatically stripped from each line, and that characters like - <literal>"</literal> and <literal>\</literal> are not special - (making it more convenient for including things like shell - code).</para> + 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> - </varlistentry> - - <varlistentry> - <term>Booleans</term> + </varlistentry> + <varlistentry> + <term> + Booleans + </term> <listitem> - <para>These can be <literal>true</literal> or - <literal>false</literal>, e.g. - + <para> + These can be <literal>true</literal> or <literal>false</literal>, e.g. <programlisting> -networking.firewall.enable = true; -networking.firewall.allowPing = false; +<xref linkend="opt-networking.firewall.enable"/> = true; +<xref linkend="opt-networking.firewall.allowPing"/> = false; </programlisting> - </para> + </para> </listitem> - </varlistentry> - - <varlistentry> - <term>Integers</term> + </varlistentry> + <varlistentry> + <term> + Integers + </term> <listitem> - <para>For example, - + <para> + For example, <programlisting> -boot.kernel.sysctl."net.ipv4.tcp_keepalive_time" = 60; +<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.)</para> + <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> - - <varlistentry> - <term>Sets</term> + </varlistentry> + <varlistentry> + <term> + Sets + </term> <listitem> - <para>Sets were introduced above. They are name/value pairs - enclosed in braces, as in the option definition - + <para> + Sets were introduced above. They are name/value pairs enclosed in braces, + as in the option definition <programlisting> -fileSystems."/boot" = +<xref linkend="opt-fileSystems"/>."/boot" = { device = "/dev/sda1"; fsType = "ext4"; - options = "rw,data=ordered,relatime"; + options = [ "rw" "data=ordered" "relatime" ]; }; </programlisting> - </para> + </para> </listitem> - </varlistentry> - - <varlistentry> - <term>Lists</term> + </varlistentry> + <varlistentry> + <term> + Lists + </term> <listitem> - <para>The important thing to note about lists is that list - elements are separated by whitespace, like this: - + <para> + The important thing to note about lists is that list elements are + separated by whitespace, like this: <programlisting> -boot.kernelModules = [ "fuse" "kvm-intel" "coretemp" ]; +<xref linkend="opt-boot.kernelModules"/> = [ "fuse" "kvm-intel" "coretemp" ]; </programlisting> - List elements can be any other type, e.g. sets: - <programlisting> swapDevices = [ { device = "/dev/disk/by-label/swap"; } ]; </programlisting> - </para> + </para> </listitem> - </varlistentry> - - <varlistentry> - <term>Packages</term> + </varlistentry> + <varlistentry> + <term> + Packages + </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: - + <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: <programlisting> -environment.systemPackages = +<xref linkend="opt-environment.systemPackages"/> = [ pkgs.thunderbird pkgs.emacs ]; -postgresql.package = pkgs.postgresql90; +<xref linkend="opt-services.postgresql.package"/> = pkgs.postgresql90; </programlisting> - - The latter option definition changes the default PostgreSQL - package used by NixOS’s PostgreSQL service to 9.0. For more - information on packages, including how to add new ones, see - <xref linkend="sec-custom-packages"/>.</para> + The latter option definition changes the default PostgreSQL package used + by NixOS’s PostgreSQL service to 9.0. For more information on packages, + including how to add new ones, see <xref linkend="sec-custom-packages"/>. + </para> </listitem> - </varlistentry> - -</variablelist> - -</para> - + </varlistentry> + </variablelist> + </para> </section> diff --git a/nixos/doc/manual/configuration/config-syntax.xml b/nixos/doc/manual/configuration/config-syntax.xml index 87847f8451ec..5ef498cf9ae3 100644 --- a/nixos/doc/manual/configuration/config-syntax.xml +++ b/nixos/doc/manual/configuration/config-syntax.xml @@ -3,25 +3,23 @@ xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="sec-configuration-syntax"> - -<title>Configuration Syntax</title> - -<para>The NixOS configuration file -<filename>/etc/nixos/configuration.nix</filename> is actually a -<emphasis>Nix expression</emphasis>, which is the Nix package -manager’s purely functional language for describing how to build -packages and configurations. This means you have all the expressive -power of that language at your disposal, including the ability to -abstract over common patterns, which is very useful when managing -complex systems. The syntax and semantics of the Nix language are -fully described in the <link + <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.</para> - -<xi:include href="config-file.xml" /> -<xi:include href="abstractions.xml" /> -<xi:include href="modularity.xml" /> -<xi:include href="summary.xml" /> - + 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" /> + <xi:include href="modularity.xml" /> + <xi:include href="summary.xml" /> </chapter> diff --git a/nixos/doc/manual/configuration/configuration.xml b/nixos/doc/manual/configuration/configuration.xml index 8fde0dc7e611..8d05dcd34b4d 100644 --- a/nixos/doc/manual/configuration/configuration.xml +++ b/nixos/doc/manual/configuration/configuration.xml @@ -3,30 +3,24 @@ xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="ch-configuration"> - -<title>Configuration</title> - -<partintro> - -<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>.</para> - -</partintro> - -<xi:include href="config-syntax.xml" /> -<xi:include href="package-mgmt.xml" /> -<xi:include href="user-mgmt.xml" /> -<xi:include href="file-systems.xml" /> -<xi:include href="x-windows.xml" /> -<xi:include href="networking.xml" /> -<xi:include href="linux-kernel.xml" /> - -<!-- FIXME: auto-include NixOS module docs --> -<xi:include href="postgresql.xml" /> - + <title>Configuration</title> + <partintro> + <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>. + </para> + </partintro> + <xi:include href="config-syntax.xml" /> + <xi:include href="package-mgmt.xml" /> + <xi:include href="user-mgmt.xml" /> + <xi:include href="file-systems.xml" /> + <xi:include href="x-windows.xml" /> + <xi:include href="xfce.xml" /> + <xi:include href="networking.xml" /> + <xi:include href="linux-kernel.xml" /> + <xi:include href="../generated/modules.xml" xpointer="xpointer(//section[@id='modules']/*)" /> <!-- Apache; libvirtd virtualisation --> - </part> diff --git a/nixos/doc/manual/configuration/customizing-packages.xml b/nixos/doc/manual/configuration/customizing-packages.xml index 6ee7a95dc6fa..03b5bb53197b 100644 --- a/nixos/doc/manual/configuration/customizing-packages.xml +++ b/nixos/doc/manual/configuration/customizing-packages.xml @@ -3,90 +3,84 @@ xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="sec-customising-packages"> + <title>Customising Packages</title> -<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> + </para> -<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> -</para> - -<warning><para>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: + <warning> + <para> + 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: <programlisting> -environment.systemPackages = [ (pkgs.emacs.override { gtk = pkgs.gtk3; }) ]; +<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.) + </para> -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, -<literal>environment.systemPackages</literal> would be a list with two -elements.)</para> - -<para>Even greater customisation is possible using the function -<varname>overrideDerivation</varname>. While the -<varname>override</varname> mechanism above overrides the arguments of -a package function, <varname>overrideDerivation</varname> allows -changing the <emphasis>result</emphasis> of the function. 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: - + <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: <programlisting> -environment.systemPackages = - [ (pkgs.lib.overrideDerivation pkgs.emacs (attrs: { - name = "emacs-25.0-pre"; - src = /path/to/my/emacs/tree; - })) - ]; +<xref linkend="opt-environment.systemPackages"/> = [ + (pkgs.emacs.overrideAttrs (oldAttrs: { + name = "emacs-25.0-pre"; + src = /path/to/my/emacs/tree; + })) +]; </programlisting> + Here, <varname>overrideAttrs</varname> takes the Nix derivation specified by + <varname>pkgs.emacs</varname> and produces a new derivation in which the + original’s <literal>name</literal> and <literal>src</literal> attribute + have been replaced by the given values by re-calling + <literal>stdenv.mkDerivation</literal>. The original attributes are + accessible via the function argument, which is conventionally named + <varname>oldAttrs</varname>. + </para> -Here, <varname>overrideDerivation</varname> takes the Nix derivation -specified by <varname>pkgs.emacs</varname> and produces a new -derivation in which the original’s <literal>name</literal> and -<literal>src</literal> attribute have been replaced by the given -values. The original attributes are accessible via -<varname>attrs</varname>.</para> - -<para>The overrides shown above are not global. They do not affect -the original package; other packages in Nixpkgs continue to depend on -the original rather than the customised package. This means that if -another package in your system depends on the original package, you -end up with two instances of the package. If you want to have -everything depend on your customised instance, you can apply a -<emphasis>global</emphasis> override as follows: - + <para> + The overrides shown above are not global. They do not affect the original + package; other packages in Nixpkgs continue to depend on the original rather + than the customised package. This means that if another package in your + system depends on the original package, you end up with two instances of the + package. If you want to have everything depend on your customised instance, + you can apply a <emphasis>global</emphasis> override as follows: <screen> nixpkgs.config.packageOverrides = pkgs: { emacs = pkgs.emacs.override { gtk = pkgs.gtk3; }; }; </screen> - -The effect of this definition is essentially equivalent to modifying -the <literal>emacs</literal> attribute in the Nixpkgs source tree. -Any package in Nixpkgs that depends on <literal>emacs</literal> will -be passed your customised instance. (However, the value -<literal>pkgs.emacs</literal> in -<varname>nixpkgs.config.packageOverrides</varname> refers to the -original rather than overridden instance, to prevent an infinite -recursion.)</para> - + The effect of this definition is essentially equivalent to modifying the + <literal>emacs</literal> attribute in the Nixpkgs source tree. Any package in + Nixpkgs that depends on <literal>emacs</literal> will be passed your + customised instance. (However, the value <literal>pkgs.emacs</literal> in + <varname>nixpkgs.config.packageOverrides</varname> refers to the original + rather than overridden instance, to prevent an infinite recursion.) + </para> </section> diff --git a/nixos/doc/manual/configuration/declarative-packages.xml b/nixos/doc/manual/configuration/declarative-packages.xml index dc2fa715097c..be9884fe9dce 100644 --- a/nixos/doc/manual/configuration/declarative-packages.xml +++ b/nixos/doc/manual/configuration/declarative-packages.xml @@ -3,41 +3,41 @@ xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="sec-declarative-package-mgmt"> - -<title>Declarative Package Management</title> - -<para>With declarative package management, you specify which packages -you want on your system by setting the option -<option>environment.systemPackages</option>. For instance, adding the -following line to <filename>configuration.nix</filename> enables the -Mozilla Thunderbird email application: - + <title>Declarative Package Management</title> + + <para> + With declarative package management, you specify which packages you want on + your system by setting the option + <xref linkend="opt-environment.systemPackages"/>. For instance, adding the + following line to <filename>configuration.nix</filename> enables the Mozilla + Thunderbird email application: <programlisting> -environment.systemPackages = [ pkgs.thunderbird ]; +<xref linkend="opt-environment.systemPackages"/> = [ pkgs.thunderbird ]; </programlisting> + The effect of this specification is that the Thunderbird package from Nixpkgs + will be built or downloaded as part of the system when you run + <command>nixos-rebuild switch</command>. + </para> -The effect of this specification is that the Thunderbird package from -Nixpkgs will be built or downloaded as part of the system when you run -<command>nixos-rebuild switch</command>.</para> - -<para>You can get a list of the available packages as follows: + <para> + You can get a list of the available packages as follows: <screen> $ nix-env -qaP '*' --description nixos.firefox firefox-23.0 Mozilla Firefox - the browser, reloaded <replaceable>...</replaceable> </screen> + The first column in the output is the <emphasis>attribute name</emphasis>, + such as <literal>nixos.thunderbird</literal>. (The <literal>nixos</literal> + prefix allows distinguishing between different channels that you might have.) + </para> -The first column in the output is the <emphasis>attribute -name</emphasis>, such as -<literal>nixos.thunderbird</literal>. (The -<literal>nixos</literal> prefix allows distinguishing between -different channels that you might have.)</para> - -<para>To “uninstall” a package, simply remove it from -<option>environment.systemPackages</option> and run -<command>nixos-rebuild switch</command>.</para> + <para> + To “uninstall” a package, simply remove it from + <xref linkend="opt-environment.systemPackages"/> and run + <command>nixos-rebuild switch</command>. + </para> -<xi:include href="customizing-packages.xml" /> -<xi:include href="adding-custom-packages.xml" /> + <xi:include href="customizing-packages.xml" /> + <xi:include href="adding-custom-packages.xml" /> </section> diff --git a/nixos/doc/manual/configuration/file-systems.xml b/nixos/doc/manual/configuration/file-systems.xml index d1b324af3f12..e4c03de71b72 100644 --- a/nixos/doc/manual/configuration/file-systems.xml +++ b/nixos/doc/manual/configuration/file-systems.xml @@ -3,38 +3,44 @@ xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="ch-file-systems"> - -<title>File Systems</title> - -<para>You can define file systems using the -<option>fileSystems</option> configuration option. For instance, the -following definition causes NixOS to mount the Ext4 file system on -device <filename>/dev/disk/by-label/data</filename> onto the mount -point <filename>/data</filename>: - + <title>File Systems</title> + <para> + You can define file systems using the <option>fileSystems</option> + configuration option. For instance, the following definition causes NixOS to + mount the Ext4 file system on device + <filename>/dev/disk/by-label/data</filename> onto the mount point + <filename>/data</filename>: <programlisting> -fileSystems."/data" = +<xref linkend="opt-fileSystems"/>."/data" = { device = "/dev/disk/by-label/data"; fsType = "ext4"; }; </programlisting> - -Mount points are created automatically if they don’t already exist. -For <option>device</option>, it’s best to use the topology-independent -device aliases in <filename>/dev/disk/by-label</filename> and -<filename>/dev/disk/by-uuid</filename>, as these don’t change if the -topology changes (e.g. if a disk is moved to another IDE -controller).</para> - -<para>You can usually omit the file system type -(<option>fsType</option>), since <command>mount</command> can usually -detect the type and load the necessary kernel module automatically. -However, if the file system is needed at early boot (in the initial -ramdisk) and is not <literal>ext2</literal>, <literal>ext3</literal> -or <literal>ext4</literal>, then it’s best to specify -<option>fsType</option> to ensure that the kernel module is -available.</para> - -<xi:include href="luks-file-systems.xml" /> - + Mount points are created automatically if they don’t already exist. For + <option><link linkend="opt-fileSystems._name__.device">device</link></option>, + it’s best to use the topology-independent device aliases in + <filename>/dev/disk/by-label</filename> and + <filename>/dev/disk/by-uuid</filename>, as these don’t change if the + topology changes (e.g. if a disk is moved to another IDE controller). + </para> + <para> + You can usually omit the file system type + (<option><link linkend="opt-fileSystems._name__.fsType">fsType</link></option>), + since <command>mount</command> can usually detect the type and load the + necessary kernel module automatically. However, if the file system is needed + at early boot (in the initial ramdisk) and is not <literal>ext2</literal>, + <literal>ext3</literal> or <literal>ext4</literal>, then it’s best to + specify <option>fsType</option> to ensure that the kernel module is + available. + </para> + <note> + <para> + System startup will fail if any of the filesystems fails to mount, dropping + you to the emergency shell. You can make a mount asynchronous and + non-critical by adding + <literal><link linkend="opt-fileSystems._name__.options">options</link> = [ + "nofail" ];</literal>. + </para> + </note> + <xi:include href="luks-file-systems.xml" /> </chapter> diff --git a/nixos/doc/manual/configuration/firewall.xml b/nixos/doc/manual/configuration/firewall.xml index 87406c28c2f7..b66adcedce6e 100644 --- a/nixos/doc/manual/configuration/firewall.xml +++ b/nixos/doc/manual/configuration/firewall.xml @@ -3,36 +3,44 @@ xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="sec-firewall"> + <title>Firewall</title> -<title>Firewall</title> - -<para>NixOS has a simple stateful firewall that blocks incoming -connections and other unexpected packets. The firewall applies to -both IPv4 and IPv6 traffic. It is enabled by default. It can be -disabled as follows: - + <para> + NixOS has a simple stateful firewall that blocks incoming connections and + other unexpected packets. The firewall applies to both IPv4 and IPv6 traffic. + It is enabled by default. It can be disabled as follows: <programlisting> -networking.firewall.enable = false; +<xref linkend="opt-networking.firewall.enable"/> = false; </programlisting> - -If the firewall is enabled, you can open specific TCP ports to the -outside world: - + If the firewall is enabled, you can open specific TCP ports to the outside + world: <programlisting> -networking.firewall.allowedTCPPorts = [ 80 443 ]; +<xref linkend="opt-networking.firewall.allowedTCPPorts"/> = [ 80 443 ]; </programlisting> - -Note that TCP port 22 (ssh) is opened automatically if the SSH daemon -is enabled (<option>services.openssh.enable = true</option>). UDP -ports can be opened through -<option>networking.firewall.allowedUDPPorts</option>. Also of -interest is - + Note that TCP port 22 (ssh) is opened automatically if the SSH daemon is + enabled (<option><xref linkend="opt-services.openssh.enable"/> = + true</option>). UDP ports can be opened through + <xref linkend="opt-networking.firewall.allowedUDPPorts"/>. + </para> + + <para> + To open ranges of TCP ports: <programlisting> -networking.firewall.allowPing = true; +<xref linkend="opt-networking.firewall.allowedTCPPortRanges"/> = [ + { from = 4000; to = 4007; } + { from = 8000; to = 8010; } +]; </programlisting> + Similarly, UDP port ranges can be opened through + <xref linkend="opt-networking.firewall.allowedUDPPortRanges"/>. + </para> -to allow the machine to respond to ping requests. (ICMPv6 pings are -always allowed.)</para> - + <para> + Also of interest is +<programlisting> +<xref linkend="opt-networking.firewall.allowPing"/> = true; +</programlisting> + to allow the machine to respond to ping requests. (ICMPv6 pings are always + allowed.) + </para> </section> diff --git a/nixos/doc/manual/configuration/ipv4-config.xml b/nixos/doc/manual/configuration/ipv4-config.xml index 053501b1736d..71ddf41491ba 100644 --- a/nixos/doc/manual/configuration/ipv4-config.xml +++ b/nixos/doc/manual/configuration/ipv4-config.xml @@ -3,42 +3,41 @@ xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="sec-ipv4"> + <title>IPv4 Configuration</title> -<title>IPv4 Configuration</title> - -<para>By default, NixOS uses DHCP (specifically, -<command>dhcpcd</command>) to automatically configure network -interfaces. However, you can configure an interface manually as -follows: - + <para> + By default, NixOS uses DHCP (specifically, <command>dhcpcd</command>) to + automatically configure network interfaces. However, you can configure an + interface manually as follows: <programlisting> -networking.interfaces.eth0.ip4 = [ { address = "192.168.1.2"; prefixLength = 24; } ]; +<link linkend="opt-networking.interfaces._name__.ipv4.addresses">networking.interfaces.eth0.ipv4.addresses</link> = [ { + address = "192.168.1.2"; + prefixLength = 24; +} ]; </programlisting> - -Typically you’ll also want to set a default gateway and set of name -servers: - + Typically you’ll also want to set a default gateway and set of name + servers: <programlisting> -networking.defaultGateway = "192.168.1.1"; -networking.nameservers = [ "8.8.8.8" ]; +<xref linkend="opt-networking.defaultGateway"/> = "192.168.1.1"; +<xref linkend="opt-networking.nameservers"/> = [ "8.8.8.8" ]; </programlisting> - -</para> - -<note><para>Statically configured interfaces are set up by the systemd -service -<replaceable>interface-name</replaceable><literal>-cfg.service</literal>. -The default gateway and name server configuration is performed by -<literal>network-setup.service</literal>.</para></note> - -<para>The host name is set using <option>networking.hostName</option>: - + </para> + + <note> + <para> + Statically configured interfaces are set up by the systemd service + <replaceable>interface-name</replaceable><literal>-cfg.service</literal>. + The default gateway and name server configuration is performed by + <literal>network-setup.service</literal>. + </para> + </note> + + <para> + The host name is set using <xref linkend="opt-networking.hostName"/>: <programlisting> -networking.hostName = "cartman"; +<xref linkend="opt-networking.hostName"/> = "cartman"; </programlisting> - -The default host name is <literal>nixos</literal>. Set it to the -empty string (<literal>""</literal>) to allow the DHCP server to -provide the host name.</para> - + The default host name is <literal>nixos</literal>. Set it to the empty string + (<literal>""</literal>) to allow the DHCP server to provide the host name. + </para> </section> diff --git a/nixos/doc/manual/configuration/ipv6-config.xml b/nixos/doc/manual/configuration/ipv6-config.xml index 592bf20e545d..e9ab7cce4eb2 100644 --- a/nixos/doc/manual/configuration/ipv6-config.xml +++ b/nixos/doc/manual/configuration/ipv6-config.xml @@ -3,17 +3,48 @@ xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="sec-ipv6"> + <title>IPv6 Configuration</title> -<title>IPv6 Configuration</title> + <para> + IPv6 is enabled by default. Stateless address autoconfiguration is used to + automatically assign IPv6 addresses to all interfaces. You can disable IPv6 + support globally by setting: +<programlisting> +<xref linkend="opt-networking.enableIPv6"/> = false; +</programlisting> + </para> -<para>IPv6 is enabled by default. Stateless address autoconfiguration -is used to automatically assign IPv6 addresses to all interfaces. You -can disable IPv6 support globally by setting: + <para> + You can disable IPv6 on a single interface using a normal sysctl (in this + example, we use interface <varname>eth0</varname>): +<programlisting> +<xref linkend="opt-boot.kernel.sysctl"/>."net.ipv6.conf.eth0.disable_ipv6" = true; +</programlisting> + </para> + <para> + As with IPv4 networking interfaces are automatically configured via DHCPv6. + You can configure an interface manually: <programlisting> -networking.enableIPv6 = false; +<link linkend="opt-networking.interfaces._name__.ipv6.addresses">networking.interfaces.eth0.ipv6.addresses</link> = [ { + address = "fe00:aa:bb:cc::2"; + prefixLength = 64; +} ]; </programlisting> + </para> -</para> + <para> + For configuring a gateway, optionally with explicitly specified interface: +<programlisting> +<xref linkend="opt-networking.defaultGateway6"/> = { + address = "fe00::1"; + interface = "enp0s3"; +} +</programlisting> + </para> + <para> + See <xref linkend='sec-ipv4' /> for similar examples and additional + information. + </para> </section> diff --git a/nixos/doc/manual/configuration/linux-kernel.xml b/nixos/doc/manual/configuration/linux-kernel.xml index ffd7b354efe1..f4d697c42dbd 100644 --- a/nixos/doc/manual/configuration/linux-kernel.xml +++ b/nixos/doc/manual/configuration/linux-kernel.xml @@ -3,29 +3,29 @@ xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="sec-kernel-config"> - -<title>Linux Kernel</title> - -<para>You can override the Linux kernel and associated packages using -the option <option>boot.kernelPackages</option>. For instance, this -selects the Linux 3.10 kernel: + <title>Linux Kernel</title> + <para> + You can override the Linux kernel and associated packages using the option + <option>boot.kernelPackages</option>. For instance, this selects the Linux + 3.10 kernel: <programlisting> -boot.kernelPackages = pkgs.linuxPackages_3_10; +<xref linkend="opt-boot.kernelPackages"/> = pkgs.linuxPackages_3_10; </programlisting> -Note that this not only replaces the kernel, but also packages that -are specific to the kernel version, such as the NVIDIA video drivers. -This ensures that driver packages are consistent with the -kernel.</para> - -<para>The default Linux kernel configuration should be fine for most users. You can see the configuration of your current kernel with the following command: + Note that this not only replaces the kernel, but also packages that are + specific to the kernel version, such as the NVIDIA video drivers. This + ensures that driver packages are consistent with the kernel. + </para> + <para> + The default Linux kernel configuration should be fine for most users. You can + see the configuration of your current kernel with the following command: <programlisting> -cat /proc/config.gz | gunzip +zcat /proc/config.gz </programlisting> -If you want to change the kernel configuration, you can use the -<option>packageOverrides</option> feature (see <xref -linkend="sec-customising-packages" />). For instance, to enable -support for the kernel debugger KGDB: - + If you want to change the kernel configuration, you can use the + <option>packageOverrides</option> feature (see + <xref +linkend="sec-customising-packages" />). For instance, to enable support + for the kernel debugger KGDB: <programlisting> nixpkgs.config.packageOverrides = pkgs: { linux_3_4 = pkgs.linux_3_4.override { @@ -36,34 +36,103 @@ nixpkgs.config.packageOverrides = pkgs: }; }; </programlisting> - -<varname>extraConfig</varname> takes a list of Linux kernel -configuration options, one per line. The name of the option should -not include the prefix <literal>CONFIG_</literal>. The option value -is typically <literal>y</literal>, <literal>n</literal> or -<literal>m</literal> (to build something as a kernel module).</para> - -<para>Kernel modules for hardware devices are generally loaded -automatically by <command>udev</command>. You can force a module to -be loaded via <option>boot.kernelModules</option>, e.g. + <varname>extraConfig</varname> takes a list of Linux kernel configuration + options, one per line. The name of the option should not include the prefix + <literal>CONFIG_</literal>. The option value is typically + <literal>y</literal>, <literal>n</literal> or <literal>m</literal> (to build + something as a kernel module). + </para> + <para> + Kernel modules for hardware devices are generally loaded automatically by + <command>udev</command>. You can force a module to be loaded via + <xref linkend="opt-boot.kernelModules"/>, e.g. <programlisting> -boot.kernelModules = [ "fuse" "kvm-intel" "coretemp" ]; +<xref linkend="opt-boot.kernelModules"/> = [ "fuse" "kvm-intel" "coretemp" ]; </programlisting> -If the module is required early during the boot (e.g. to mount the -root file system), you can use -<option>boot.initrd.extraKernelModules</option>: + If the module is required early during the boot (e.g. to mount the root file + system), you can use <xref linkend="opt-boot.initrd.kernelModules"/>: <programlisting> -boot.initrd.extraKernelModules = [ "cifs" ]; +<xref linkend="opt-boot.initrd.kernelModules"/> = [ "cifs" ]; </programlisting> -This causes the specified modules and their dependencies to be added -to the initial ramdisk.</para> - -<para>Kernel runtime parameters can be set through -<option>boot.kernel.sysctl</option>, e.g. + This causes the specified modules and their dependencies to be added to the + initial ramdisk. + </para> + <para> + Kernel runtime parameters can be set through + <xref linkend="opt-boot.kernel.sysctl"/>, e.g. <programlisting> -boot.kernel.sysctl."net.ipv4.tcp_keepalive_time" = 120; +<xref linkend="opt-boot.kernel.sysctl"/>."net.ipv4.tcp_keepalive_time" = 120; </programlisting> -sets the kernel’s TCP keepalive time to 120 seconds. To see the -available parameters, run <command>sysctl -a</command>.</para> + sets the kernel’s TCP keepalive time to 120 seconds. To see the available + parameters, run <command>sysctl -a</command>. + </para> + <section> + <title>Customize your kernel</title> + + <para> + The first step before compiling the kernel is to generate an appropriate + <literal>.config</literal> configuration. Either you pass your own config via + the <literal>configfile</literal> setting of <literal>linuxManualConfig</literal>: + <screen><![CDATA[ + custom-kernel = super.linuxManualConfig { + inherit (super) stdenv hostPlatform; + inherit (linux_4_9) src; + version = "${linux_4_9.version}-custom"; + + configfile = /home/me/my_kernel_config; + allowImportFromDerivation = true; + }; + ]]></screen> + +You can edit the config with this snippet (by default <command>make menuconfig</command> won't work + out of the box on nixos): + <screen><![CDATA[ + nix-shell -E 'with import <nixpkgs> {}; kernelToOverride.overrideAttrs (o: {nativeBuildInputs=o.nativeBuildInputs ++ [ pkgconfig ncurses ];})' + ]]></screen> + + + or you can let nixpkgs generate the configuration. + Nixpkgs generates it via answering the interactive kernel utility <command>make config</command>. + The answers depend on parameters passed to <filename>pkgs/os-specific/linux/kernel/generic.nix</filename> + (which you can influence by overriding <literal>extraConfig, autoModules, modDirVersion, preferBuiltin, extraConfig</literal>). +<screen><![CDATA[ + + mptcp93.override ({ + name="mptcp-local"; + + ignoreConfigErrors = true; + autoModules = false; + kernelPreferBuiltin = true; + + enableParallelBuilding = true; + + extraConfig = '' + DEBUG_KERNEL y + FRAME_POINTER y + KGDB y + KGDB_SERIAL_CONSOLE y + DEBUG_INFO y + ''; + }); + ]]></screen> + </para> + </section> + <section> + <title>Developing kernel modules</title> + + <para> + When developing kernel modules it's often convenient to run edit-compile-run + loop as quickly as possible. See below snippet as an example of developing + <literal>mellanox</literal> drivers. + </para> +<screen><![CDATA[ +$ nix-build '<nixpkgs>' -A linuxPackages.kernel.dev +$ nix-shell '<nixpkgs>' -A linuxPackages.kernel +$ unpackPhase +$ cd linux-* +$ make -C $dev/lib/modules/*/build M=$(pwd)/drivers/net/ethernet/mellanox modules +# insmod ./drivers/net/ethernet/mellanox/mlx5/core/mlx5_core.ko +]]></screen> + </section> </chapter> diff --git a/nixos/doc/manual/configuration/luks-file-systems.xml b/nixos/doc/manual/configuration/luks-file-systems.xml index 45475dbcd446..8a2b107e0ee8 100644 --- a/nixos/doc/manual/configuration/luks-file-systems.xml +++ b/nixos/doc/manual/configuration/luks-file-systems.xml @@ -3,40 +3,38 @@ xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="sec-luks-file-systems"> + <title>LUKS-Encrypted File Systems</title> -<title>LUKS-Encrypted File Systems</title> - -<para>NixOS supports file systems that are encrypted using -<emphasis>LUKS</emphasis> (Linux Unified Key Setup). For example, -here is how you create an encrypted Ext4 file system on the device -<filename>/dev/sda2</filename>: - + <para> + NixOS supports file systems that are encrypted using + <emphasis>LUKS</emphasis> (Linux Unified Key Setup). For example, here is how + you create an encrypted Ext4 file system on the device + <filename>/dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d</filename>: <screen> -$ cryptsetup luksFormat /dev/sda2 +# cryptsetup luksFormat /dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d WARNING! ======== -This will overwrite data on /dev/sda2 irrevocably. +This will overwrite data on /dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d irrevocably. Are you sure? (Type uppercase yes): YES Enter LUKS passphrase: *** Verify passphrase: *** -$ cryptsetup luksOpen /dev/sda2 crypted -Enter passphrase for /dev/sda2: *** +# cryptsetup luksOpen /dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d crypted +Enter passphrase for /dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d: *** -$ mkfs.ext4 /dev/mapper/crypted +# mkfs.ext4 /dev/mapper/crypted </screen> - -To ensure that this file system is automatically mounted at boot time -as <filename>/</filename>, add the following to -<filename>configuration.nix</filename>: - + To ensure that this file system is automatically mounted at boot time as + <filename>/</filename>, add the following to + <filename>configuration.nix</filename>: <programlisting> -boot.initrd.luks.devices = [ { device = "/dev/sda2"; name = "crypted"; } ]; -fileSystems."/".device = "/dev/mapper/crypted"; +<link linkend="opt-boot.initrd.luks.devices._name__.device">boot.initrd.luks.devices.crypted.device</link> = "/dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d"; +<xref linkend="opt-fileSystems"/>."/".device = "/dev/mapper/crypted"; </programlisting> - -</para> - + Should grub be used as bootloader, and <filename>/boot</filename> is located + on an encrypted partition, it is necessary to add the following grub option: +<programlisting><xref linkend="opt-boot.loader.grub.enableCryptodisk"/> = true;</programlisting> + </para> </section> diff --git a/nixos/doc/manual/configuration/modularity.xml b/nixos/doc/manual/configuration/modularity.xml index d95091bd1628..3ff96f719ec5 100644 --- a/nixos/doc/manual/configuration/modularity.xml +++ b/nixos/doc/manual/configuration/modularity.xml @@ -3,102 +3,95 @@ xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="sec-modularity"> - -<title>Modularity</title> - -<para>The NixOS configuration mechanism is modular. If your -<filename>configuration.nix</filename> becomes too big, you can split -it into multiple files. Likewise, if you have multiple NixOS -configurations (e.g. for different computers) with some commonality, -you can move the common configuration into a shared file.</para> - -<para>Modules have exactly the same syntax as -<filename>configuration.nix</filename>. In fact, -<filename>configuration.nix</filename> is itself a module. You can -use other modules by including them from -<filename>configuration.nix</filename>, e.g.: - + <title>Modularity</title> + + <para> + The NixOS configuration mechanism is modular. If your + <filename>configuration.nix</filename> becomes too big, you can split it into + multiple files. Likewise, if you have multiple NixOS configurations (e.g. for + different computers) with some commonality, you can move the common + configuration into a shared file. + </para> + + <para> + Modules have exactly the same syntax as + <filename>configuration.nix</filename>. In fact, + <filename>configuration.nix</filename> is itself a module. You can use other + modules by including them from <filename>configuration.nix</filename>, e.g.: <programlisting> { config, pkgs, ... }: { imports = [ ./vpn.nix ./kde.nix ]; - services.httpd.enable = true; - environment.systemPackages = [ pkgs.emacs ]; + <xref linkend="opt-services.httpd.enable"/> = true; + <xref linkend="opt-environment.systemPackages"/> = [ pkgs.emacs ]; <replaceable>...</replaceable> } </programlisting> - -Here, we include two modules from the same directory, -<filename>vpn.nix</filename> and <filename>kde.nix</filename>. The -latter might look like this: - + Here, we include two modules from the same directory, + <filename>vpn.nix</filename> and <filename>kde.nix</filename>. The latter + might look like this: <programlisting> { config, pkgs, ... }: -{ services.xserver.enable = true; - services.xserver.displayManager.kdm.enable = true; - services.xserver.desktopManager.kde4.enable = true; - environment.systemPackages = [ pkgs.kde4.kscreensaver ]; +{ <xref linkend="opt-services.xserver.enable"/> = true; + <xref linkend="opt-services.xserver.displayManager.sddm.enable"/> = true; + <xref linkend="opt-services.xserver.desktopManager.plasma5.enable"/> = true; } </programlisting> - -Note that both <filename>configuration.nix</filename> and -<filename>kde.nix</filename> define the option -<option>environment.systemPackages</option>. When multiple modules -define an option, NixOS will try to <emphasis>merge</emphasis> the -definitions. In the case of -<option>environment.systemPackages</option>, that’s easy: the lists of -packages can simply be concatenated. The value in -<filename>configuration.nix</filename> is merged last, so for -list-type options, it will appear at the end of the merged list. If -you want it to appear first, you can use <varname>mkBefore</varname>: - + Note that both <filename>configuration.nix</filename> and + <filename>kde.nix</filename> define the option + <xref linkend="opt-environment.systemPackages"/>. When multiple modules + define an option, NixOS will try to <emphasis>merge</emphasis> the + definitions. In the case of <xref linkend="opt-environment.systemPackages"/>, + that’s easy: the lists of packages can simply be concatenated. The value in + <filename>configuration.nix</filename> is merged last, so for list-type + options, it will appear at the end of the merged list. If you want it to + appear first, you can use <varname>mkBefore</varname>: <programlisting> -boot.kernelModules = mkBefore [ "kvm-intel" ]; +<xref linkend="opt-boot.kernelModules"/> = mkBefore [ "kvm-intel" ]; </programlisting> - -This causes the <literal>kvm-intel</literal> kernel module to be -loaded before any other kernel modules.</para> - -<para>For other types of options, a merge may not be possible. For -instance, if two modules define -<option>services.httpd.adminAddr</option>, -<command>nixos-rebuild</command> will give an error: - + This causes the <literal>kvm-intel</literal> kernel module to be loaded + before any other kernel modules. + </para> + + <para> + For other types of options, a merge may not be possible. For instance, if two + modules define <xref linkend="opt-services.httpd.adminAddr"/>, + <command>nixos-rebuild</command> will give an error: <screen> The unique option `services.httpd.adminAddr' is defined multiple times, in `/etc/nixos/httpd.nix' and `/etc/nixos/configuration.nix'. </screen> - -When that happens, it’s possible to force one definition take -precedence over the others: - + When that happens, it’s possible to force one definition take precedence + over the others: <programlisting> -services.httpd.adminAddr = pkgs.lib.mkForce "bob@example.org"; +<xref linkend="opt-services.httpd.adminAddr"/> = pkgs.lib.mkForce "bob@example.org"; </programlisting> - -</para> - -<para>When using multiple modules, you may need to access -configuration values defined in other modules. This is what the -<varname>config</varname> function argument is for: it contains the -complete, merged system configuration. That is, -<varname>config</varname> is the result of combining the -configurations returned by every module<footnote><para>If you’re -wondering how it’s possible that the (indirect) -<emphasis>result</emphasis> of a function is passed as an -<emphasis>input</emphasis> to that same function: that’s because Nix -is a “lazy” language — it only computes values when they are needed. -This works as long as no individual configuration value depends on -itself.</para></footnote>. For example, here is a module that adds -some packages to <option>environment.systemPackages</option> only if -<option>services.xserver.enable</option> is set to -<literal>true</literal> somewhere else: - + </para> + + <para> + When using multiple modules, you may need to access configuration values + defined in other modules. This is what the <varname>config</varname> function + argument is for: it contains the complete, merged system configuration. That + is, <varname>config</varname> is the result of combining the configurations + returned by every module + <footnote> + <para> + If you’re wondering how it’s possible that the (indirect) + <emphasis>result</emphasis> of a function is passed as an + <emphasis>input</emphasis> to that same function: that’s because Nix is a + “lazy” language — it only computes values when they are needed. This + works as long as no individual configuration value depends on itself. + </para> + </footnote> + . For example, here is a module that adds some packages to + <xref linkend="opt-environment.systemPackages"/> only if + <xref linkend="opt-services.xserver.enable"/> is set to + <literal>true</literal> somewhere else: <programlisting> { config, pkgs, ... }: -{ environment.systemPackages = - if config.services.xserver.enable then +{ <xref linkend="opt-environment.systemPackages"/> = + if config.<xref linkend="opt-services.xserver.enable"/> then [ pkgs.firefox pkgs.thunderbird ] @@ -106,38 +99,32 @@ some packages to <option>environment.systemPackages</option> only if [ ]; } </programlisting> + </para> -</para> - -<para>With multiple modules, it may not be obvious what the final -value of a configuration option is. The command -<option>nixos-option</option> allows you to find out: - + <para> + With multiple modules, it may not be obvious what the final value of a + configuration option is. The command <option>nixos-option</option> allows you + to find out: <screen> -$ nixos-option services.xserver.enable +$ nixos-option <xref linkend="opt-services.xserver.enable"/> true -$ nixos-option boot.kernelModules +$ nixos-option <xref linkend="opt-boot.kernelModules"/> [ "tun" "ipv6" "loop" <replaceable>...</replaceable> ] </screen> - -Interactive exploration of the configuration is possible using -<command + Interactive exploration of the configuration is possible using + <command xlink:href="https://github.com/edolstra/nix-repl">nix-repl</command>, -a read-eval-print loop for Nix expressions. It’s not installed by -default; run <literal>nix-env -i nix-repl</literal> to get it. A -typical use: - + a read-eval-print loop for Nix expressions. It’s not installed by default; + run <literal>nix-env -i nix-repl</literal> to get it. A typical use: <screen> -$ nix-repl '<nixos>' +$ nix-repl '<nixpkgs/nixos>' -nix-repl> config.networking.hostName +nix-repl> config.<xref linkend="opt-networking.hostName"/> "mandark" -nix-repl> map (x: x.hostName) config.services.httpd.virtualHosts +nix-repl> map (x: x.hostName) config.<xref linkend="opt-services.httpd.virtualHosts"/> [ "example.org" "example.gov" ] </screen> - -</para> - + </para> </section> diff --git a/nixos/doc/manual/configuration/network-manager.xml b/nixos/doc/manual/configuration/network-manager.xml index b7e47b8729f3..e217a99148b9 100644 --- a/nixos/doc/manual/configuration/network-manager.xml +++ b/nixos/doc/manual/configuration/network-manager.xml @@ -3,25 +3,42 @@ xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="sec-networkmanager"> + <title>NetworkManager</title> -<title>NetworkManager</title> - -<para>To facilitate network configuration, some desktop environments -use NetworkManager. You can enable NetworkManager by setting: - + <para> + To facilitate network configuration, some desktop environments use + NetworkManager. You can enable NetworkManager by setting: <programlisting> -networking.networkmanager.enable = true; +<xref linkend="opt-networking.networkmanager.enable"/> = true; </programlisting> + some desktop managers (e.g., GNOME) enable NetworkManager automatically for + you. + </para> -some desktop managers (e.g., GNOME) enable NetworkManager -automatically for you.</para> - -<para>All users that should have permission to change network settings -must belong to the <code>networkmanager</code> group.</para> + <para> + All users that should have permission to change network settings must belong + to the <code>networkmanager</code> group: +<programlisting> +<link linkend="opt-users.users._name__.extraGroups">users.extraUsers.youruser.extraGroups</link> = [ "networkmanager" ]; +</programlisting> + </para> -<note><para><code>networking.networkmanager</code> and -<code>networking.wireless</code> can not be enabled at the same time: -you can still connect to the wireless networks using -NetworkManager.</para></note> + <para> + NetworkManager is controlled using either <command>nmcli</command> or + <command>nmtui</command> (curses-based terminal user interface). See their + manual pages for details on their usage. Some desktop environments (GNOME, + KDE) have their own configuration tools for NetworkManager. On XFCE, there is + no configuration tool for NetworkManager by default: by adding + <code>networkmanagerapplet</code> to the list of system packages, the + graphical applet will be installed and will launch automatically when XFCE is + starting (and will show in the status tray). + </para> + <note> + <para> + <code>networking.networkmanager</code> and <code>networking.wireless</code> + (WPA Supplicant) cannot be enabled at the same time: you can still connect + to the wireless networks using NetworkManager. + </para> + </note> </section> diff --git a/nixos/doc/manual/configuration/networking.xml b/nixos/doc/manual/configuration/networking.xml index 5f08bc1f1275..02cf811e0bd3 100644 --- a/nixos/doc/manual/configuration/networking.xml +++ b/nixos/doc/manual/configuration/networking.xml @@ -3,20 +3,17 @@ xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="sec-networking"> - -<title>Networking</title> - -<para>This section describes how to configure networking components on -your NixOS machine.</para> - -<xi:include href="network-manager.xml" /> -<xi:include href="ssh.xml" /> -<xi:include href="ipv4-config.xml" /> -<xi:include href="ipv6-config.xml" /> -<xi:include href="firewall.xml" /> -<xi:include href="wireless.xml" /> -<xi:include href="ad-hoc-network-config.xml" /> - + <title>Networking</title> + <para> + This section describes how to configure networking components on your NixOS + machine. + </para> + <xi:include href="network-manager.xml" /> + <xi:include href="ssh.xml" /> + <xi:include href="ipv4-config.xml" /> + <xi:include href="ipv6-config.xml" /> + <xi:include href="firewall.xml" /> + <xi:include href="wireless.xml" /> + <xi:include href="ad-hoc-network-config.xml" /> <!-- TODO: OpenVPN, NAT --> - </chapter> diff --git a/nixos/doc/manual/configuration/package-mgmt.xml b/nixos/doc/manual/configuration/package-mgmt.xml index 73c1722da02c..e8ac5d0681a9 100644 --- a/nixos/doc/manual/configuration/package-mgmt.xml +++ b/nixos/doc/manual/configuration/package-mgmt.xml @@ -3,32 +3,29 @@ xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="sec-package-management"> - -<title>Package Management</title> - -<para>This section describes how to add additional packages to your -system. NixOS has two distinct styles of package management: - -<itemizedlist> - - <listitem><para><emphasis>Declarative</emphasis>, where you declare - what packages you want in your - <filename>configuration.nix</filename>. Every time you run - <command>nixos-rebuild</command>, NixOS will ensure that you get a - consistent set of binaries corresponding to your - specification.</para></listitem> - - <listitem><para><emphasis>Ad hoc</emphasis>, where you install, - upgrade and uninstall packages via the <command>nix-env</command> - command. This style allows mixing packages from different Nixpkgs - versions. It’s the only choice for non-root - users.</para></listitem> - -</itemizedlist> - -</para> - -<xi:include href="declarative-packages.xml" /> -<xi:include href="ad-hoc-packages.xml" /> - + <title>Package Management</title> + <para> + This section describes how to add additional packages to your system. NixOS + has two distinct styles of package management: + <itemizedlist> + <listitem> + <para> + <emphasis>Declarative</emphasis>, where you declare what packages you want + in your <filename>configuration.nix</filename>. Every time you run + <command>nixos-rebuild</command>, NixOS will ensure that you get a + consistent set of binaries corresponding to your specification. + </para> + </listitem> + <listitem> + <para> + <emphasis>Ad hoc</emphasis>, where you install, upgrade and uninstall + packages via the <command>nix-env</command> command. This style allows + mixing packages from different Nixpkgs versions. It’s the only choice + for non-root users. + </para> + </listitem> + </itemizedlist> + </para> + <xi:include href="declarative-packages.xml" /> + <xi:include href="ad-hoc-packages.xml" /> </chapter> diff --git a/nixos/doc/manual/configuration/ssh.xml b/nixos/doc/manual/configuration/ssh.xml index 7c928baaf896..6e883e3fbbc1 100644 --- a/nixos/doc/manual/configuration/ssh.xml +++ b/nixos/doc/manual/configuration/ssh.xml @@ -3,30 +3,25 @@ xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="sec-ssh"> + <title>Secure Shell Access</title> -<title>Secure Shell Access</title> - -<para>Secure shell (SSH) access to your machine can be enabled by -setting: - + <para> + Secure shell (SSH) access to your machine can be enabled by setting: <programlisting> -services.openssh.enable = true; +<xref linkend="opt-services.openssh.enable"/> = true; </programlisting> - -By default, root logins using a password are disallowed. They can be -disabled entirely by setting -<literal>services.openssh.permitRootLogin</literal> to -<literal>"no"</literal>.</para> - -<para>You can declaratively specify authorised RSA/DSA public keys for -a user as follows: - + By default, root logins using a password are disallowed. They can be disabled + entirely by setting <xref linkend="opt-services.openssh.permitRootLogin"/> to + <literal>"no"</literal>. + </para> + + <para> + You can declaratively specify authorised RSA/DSA public keys for a user as + follows: <!-- FIXME: this might not work if the user is unmanaged. --> <programlisting> -users.extraUsers.alice.openssh.authorizedKeys.keys = +<link linkend="opt-users.users._name__.openssh.authorizedKeys.keys">users.extraUsers.alice.openssh.authorizedKeys.keys</link> = [ "ssh-dss AAAAB3NzaC1kc3MAAACBAPIkGWVEt4..." ]; </programlisting> - -</para> - + </para> </section> diff --git a/nixos/doc/manual/configuration/summary.xml b/nixos/doc/manual/configuration/summary.xml index 6ff0390c0ed3..ea980254a8fc 100644 --- a/nixos/doc/manual/configuration/summary.xml +++ b/nixos/doc/manual/configuration/summary.xml @@ -3,189 +3,225 @@ xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="sec-nix-syntax-summary"> + <title>Syntax Summary</title> -<title>Syntax Summary</title> - -<para>Below is a summary of the most important syntactic constructs in -the Nix expression language. It’s not complete. In particular, there -are many other built-in functions. See the <link + <para> + Below is a summary of the most important syntactic constructs in the Nix + expression language. It’s not complete. In particular, there are many other + built-in functions. See the + <link xlink:href="http://nixos.org/nix/manual/#chap-writing-nix-expressions">Nix -manual</link> for the rest.</para> + manual</link> for the rest. + </para> -<informaltable frame='none'> + <informaltable frame='none'> <tgroup cols='2'> - <colspec colname='c1' rowsep='1' colsep='1' /> - <colspec colname='c2' rowsep='1' /> - <thead> - <row> - <entry>Example</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - - <row> - <entry namest="c1" nameend="c2"><emphasis>Basic values</emphasis></entry> - </row> - <row> - <entry><literal>"Hello world"</literal></entry> - <entry>A string</entry> - </row> - <row> - <entry><literal>"${pkgs.bash}/bin/sh"</literal></entry> - <entry>A string containing an expression (expands to <literal>"/nix/store/<replaceable>hash</replaceable>-bash-<replaceable>version</replaceable>/bin/sh"</literal>)</entry> - </row> - <row> - <entry><literal>true</literal>, <literal>false</literal></entry> - <entry>Booleans</entry> - </row> - <row> - <entry><literal>123</literal></entry> - <entry>An integer</entry> - </row> - <row> - <entry><literal>./foo.png</literal></entry> - <entry>A path (relative to the containing Nix expression)</entry> - </row> - - <row> - <entry namest="c1" nameend="c2"><emphasis>Compound values</emphasis></entry> - </row> - <row> - <entry><literal>{ x = 1; y = 2; }</literal></entry> - <entry>An set with attributes names <literal>x</literal> and <literal>y</literal></entry> - </row> - <row> - <entry><literal>{ foo.bar = 1; }</literal></entry> - <entry>A nested set, equivalent to <literal>{ foo = { bar = 1; }; }</literal></entry> - </row> - <row> - <entry><literal>rec { x = "foo"; y = x + "bar"; }</literal></entry> - <entry>A recursive set, equivalent to <literal>{ x = "foo"; y = "foobar"; }</literal></entry> - </row> - <row> - <entry><literal>[ "foo" "bar" ]</literal></entry> - <entry>A list with two elements</entry> - </row> - - <row> - <entry namest="c1" nameend="c2"><emphasis>Operators</emphasis></entry> - </row> - <row> - <entry><literal>"foo" + "bar"</literal></entry> - <entry>String concatenation</entry> - </row> - <row> - <entry><literal>1 + 2</literal></entry> - <entry>Integer addition</entry> - </row> - <row> - <entry><literal>"foo" == "f" + "oo"</literal></entry> - <entry>Equality test (evaluates to <literal>true</literal>)</entry> - </row> - <row> - <entry><literal>"foo" != "bar"</literal></entry> - <entry>Inequality test (evaluates to <literal>true</literal>)</entry> - </row> - <row> - <entry><literal>!true</literal></entry> - <entry>Boolean negation</entry> - </row> - <row> - <entry><literal>{ x = 1; y = 2; }.x</literal></entry> - <entry>Attribute selection (evaluates to <literal>1</literal>)</entry> - </row> - <row> - <entry><literal>{ x = 1; y = 2; }.z or 3</literal></entry> - <entry>Attribute selection with default (evaluates to <literal>3</literal>)</entry> - </row> - <row> - <entry><literal>{ x = 1; y = 2; } // { z = 3; }</literal></entry> - <entry>Merge two sets (attributes in the right-hand set taking precedence)</entry> - </row> - - <row> - <entry namest="c1" nameend="c2"><emphasis>Control structures</emphasis></entry> - </row> - <row> - <entry><literal>if 1 + 1 == 2 then "yes!" else "no!"</literal></entry> - <entry>Conditional expression</entry> - </row> - <row> - <entry><literal>assert 1 + 1 == 2; "yes!"</literal></entry> - <entry>Assertion check (evaluates to <literal>"yes!"</literal>)</entry> - </row> - <row> - <entry><literal>let x = "foo"; y = "bar"; in x + y</literal></entry> - <entry>Variable definition</entry> - </row> - <row> - <entry><literal>with pkgs.lib; head [ 1 2 3 ]</literal></entry> - <entry>Add all attributes from the given set to the scope + <colspec colname='c1' rowsep='1' colsep='1' /> + <colspec colname='c2' rowsep='1' /> + <thead> + <row> + <entry>Example</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry namest="c1" nameend="c2"><emphasis>Basic values</emphasis> + </entry> + </row> + <row> + <entry><literal>"Hello world"</literal> + </entry> + <entry>A string</entry> + </row> + <row> + <entry><literal>"${pkgs.bash}/bin/sh"</literal> + </entry> + <entry>A string containing an expression (expands to <literal>"/nix/store/<replaceable>hash</replaceable>-bash-<replaceable>version</replaceable>/bin/sh"</literal>)</entry> + </row> + <row> + <entry><literal>true</literal>, <literal>false</literal> + </entry> + <entry>Booleans</entry> + </row> + <row> + <entry><literal>123</literal> + </entry> + <entry>An integer</entry> + </row> + <row> + <entry><literal>./foo.png</literal> + </entry> + <entry>A path (relative to the containing Nix expression)</entry> + </row> + <row> + <entry namest="c1" nameend="c2"><emphasis>Compound values</emphasis> + </entry> + </row> + <row> + <entry><literal>{ x = 1; y = 2; }</literal> + </entry> + <entry>A set with attributes named <literal>x</literal> and <literal>y</literal> + </entry> + </row> + <row> + <entry><literal>{ foo.bar = 1; }</literal> + </entry> + <entry>A nested set, equivalent to <literal>{ foo = { bar = 1; }; }</literal> + </entry> + </row> + <row> + <entry><literal>rec { x = "foo"; y = x + "bar"; }</literal> + </entry> + <entry>A recursive set, equivalent to <literal>{ x = "foo"; y = "foobar"; }</literal> + </entry> + </row> + <row> + <entry><literal>[ "foo" "bar" ]</literal> + </entry> + <entry>A list with two elements</entry> + </row> + <row> + <entry namest="c1" nameend="c2"><emphasis>Operators</emphasis> + </entry> + </row> + <row> + <entry><literal>"foo" + "bar"</literal> + </entry> + <entry>String concatenation</entry> + </row> + <row> + <entry><literal>1 + 2</literal> + </entry> + <entry>Integer addition</entry> + </row> + <row> + <entry><literal>"foo" == "f" + "oo"</literal> + </entry> + <entry>Equality test (evaluates to <literal>true</literal>)</entry> + </row> + <row> + <entry><literal>"foo" != "bar"</literal> + </entry> + <entry>Inequality test (evaluates to <literal>true</literal>)</entry> + </row> + <row> + <entry><literal>!true</literal> + </entry> + <entry>Boolean negation</entry> + </row> + <row> + <entry><literal>{ x = 1; y = 2; }.x</literal> + </entry> + <entry>Attribute selection (evaluates to <literal>1</literal>)</entry> + </row> + <row> + <entry><literal>{ x = 1; y = 2; }.z or 3</literal> + </entry> + <entry>Attribute selection with default (evaluates to <literal>3</literal>)</entry> + </row> + <row> + <entry><literal>{ x = 1; y = 2; } // { z = 3; }</literal> + </entry> + <entry>Merge two sets (attributes in the right-hand set taking precedence)</entry> + </row> + <row> + <entry namest="c1" nameend="c2"><emphasis>Control structures</emphasis> + </entry> + </row> + <row> + <entry><literal>if 1 + 1 == 2 then "yes!" else "no!"</literal> + </entry> + <entry>Conditional expression</entry> + </row> + <row> + <entry><literal>assert 1 + 1 == 2; "yes!"</literal> + </entry> + <entry>Assertion check (evaluates to <literal>"yes!"</literal>). See <xref + linkend="sec-assertions"/> for using assertions in modules</entry> + </row> + <row> + <entry><literal>let x = "foo"; y = "bar"; in x + y</literal> + </entry> + <entry>Variable definition</entry> + </row> + <row> + <entry><literal>with pkgs.lib; head [ 1 2 3 ]</literal> + </entry> + <entry>Add all attributes from the given set to the scope (evaluates to <literal>1</literal>)</entry> - </row> - - <row> - <entry namest="c1" nameend="c2"><emphasis>Functions (lambdas)</emphasis></entry> - </row> - <row> - <entry><literal>x: x + 1</literal></entry> - <entry>A function that expects an integer and returns it increased by 1</entry> - </row> - <row> - <entry><literal>(x: x + 1) 100</literal></entry> - <entry>A function call (evaluates to 101)</entry> - </row> - <row> - <entry><literal>let inc = x: x + 1; in inc (inc (inc 100))</literal></entry> - <entry>A function bound to a variable and subsequently called by name (evaluates to 103)</entry> - </row> - <row> - <entry><literal>{ x, y }: x + y</literal></entry> - <entry>A function that expects a set with required attributes + </row> + <row> + <entry namest="c1" nameend="c2"><emphasis>Functions (lambdas)</emphasis> + </entry> + </row> + <row> + <entry><literal>x: x + 1</literal> + </entry> + <entry>A function that expects an integer and returns it increased by 1</entry> + </row> + <row> + <entry><literal>(x: x + 1) 100</literal> + </entry> + <entry>A function call (evaluates to 101)</entry> + </row> + <row> + <entry><literal>let inc = x: x + 1; in inc (inc (inc 100))</literal> + </entry> + <entry>A function bound to a variable and subsequently called by name (evaluates to 103)</entry> + </row> + <row> + <entry><literal>{ x, y }: x + y</literal> + </entry> + <entry>A function that expects a set with required attributes <literal>x</literal> and <literal>y</literal> and concatenates them</entry> - </row> - <row> - <entry><literal>{ x, y ? "bar" }: x + y</literal></entry> - <entry>A function that expects a set with required attribute + </row> + <row> + <entry><literal>{ x, y ? "bar" }: x + y</literal> + </entry> + <entry>A function that expects a set with required attribute <literal>x</literal> and optional <literal>y</literal>, using <literal>"bar"</literal> as default value for - <literal>y</literal></entry> - </row> - <row> - <entry><literal>{ x, y, ... }: x + y</literal></entry> - <entry>A function that expects a set with required attributes + <literal>y</literal> + </entry> + </row> + <row> + <entry><literal>{ x, y, ... }: x + y</literal> + </entry> + <entry>A function that expects a set with required attributes <literal>x</literal> and <literal>y</literal> and ignores any other attributes</entry> - </row> - <row> - <entry><literal>{ x, y } @ args: x + y</literal></entry> - <entry>A function that expects a set with required attributes + </row> + <row> + <entry><literal>{ x, y } @ args: x + y</literal> + </entry> + <entry>A function that expects a set with required attributes <literal>x</literal> and <literal>y</literal>, and binds the - whole set to <literal>args</literal></entry> - </row> - - <row> - <entry namest="c1" nameend="c2"><emphasis>Built-in functions</emphasis></entry> - </row> - <row> - <entry><literal>import ./foo.nix</literal></entry> - <entry>Load and return Nix expression in given file</entry> - </row> - <row> - <entry><literal>map (x: x + x) [ 1 2 3 ]</literal></entry> - <entry>Apply a function to every element of a list (evaluates to <literal>[ 2 4 6 ]</literal>)</entry> - </row> - <!-- + whole set to <literal>args</literal> + </entry> + </row> + <row> + <entry namest="c1" nameend="c2"><emphasis>Built-in functions</emphasis> + </entry> + </row> + <row> + <entry><literal>import ./foo.nix</literal> + </entry> + <entry>Load and return Nix expression in given file</entry> + </row> + <row> + <entry><literal>map (x: x + x) [ 1 2 3 ]</literal> + </entry> + <entry>Apply a function to every element of a list (evaluates to <literal>[ 2 4 6 ]</literal>)</entry> + </row> +<!-- <row> <entry><literal>throw "Urgh"</literal></entry> <entry>Raise an error condition</entry> </row> --> - - </tbody> + </tbody> </tgroup> -</informaltable> - + </informaltable> </section> diff --git a/nixos/doc/manual/configuration/user-mgmt.xml b/nixos/doc/manual/configuration/user-mgmt.xml index 40362fbbb23f..66c1c6eb3a11 100644 --- a/nixos/doc/manual/configuration/user-mgmt.xml +++ b/nixos/doc/manual/configuration/user-mgmt.xml @@ -3,87 +3,86 @@ xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="sec-user-management"> - -<title>User Management</title> - -<para>NixOS supports both declarative and imperative styles of user -management. In the declarative style, users are specified in -<filename>configuration.nix</filename>. For instance, the following -states that a user account named <literal>alice</literal> shall exist: - + <title>User Management</title> + <para> + NixOS supports both declarative and imperative styles of user management. In + the declarative style, users are specified in + <filename>configuration.nix</filename>. For instance, the following states + that a user account named <literal>alice</literal> shall exist: <programlisting> -users.extraUsers.alice = - { isNormalUser = true; - home = "/home/alice"; - description = "Alice Foobar"; - extraGroups = [ "wheel" "networkmanager" ]; - openssh.authorizedKeys.keys = [ "ssh-dss AAAAB3Nza... alice@foobar" ]; - }; +<xref linkend="opt-users.users"/>.alice = { + <link linkend="opt-users.users._name__.isNormalUser">isNormalUser</link> = true; + <link linkend="opt-users.users._name__.home">home</link> = "/home/alice"; + <link linkend="opt-users.users._name__.description">description</link> = "Alice Foobar"; + <link linkend="opt-users.users._name__.extraGroups">extraGroups</link> = [ "wheel" "networkmanager" ]; + <link linkend="opt-users.users._name__.openssh.authorizedKeys.keys">openssh.authorizedKeys.keys</link> = [ "ssh-dss AAAAB3Nza... alice@foobar" ]; +}; </programlisting> - -Note that <literal>alice</literal> is a member of the -<literal>wheel</literal> and <literal>networkmanager</literal> groups, -which allows her to use <command>sudo</command> to execute commands as -<literal>root</literal> and to configure the network, respectively. -Also note the SSH public key that allows remote logins with the -corresponding private key. Users created in this way do not have a -password by default, so they cannot log in via mechanisms that require -a password. However, you can use the <command>passwd</command> program -to set a password, which is retained across invocations of -<command>nixos-rebuild</command>.</para> - -<para>If you set users.mutableUsers to false, then the contents of /etc/passwd -and /etc/group will be congruent to your NixOS configuration. For instance, -if you remove a user from users.extraUsers and run nixos-rebuild, the user -account will cease to exist. Also, imperative commands for managing users -and groups, such as useradd, are no longer available.</para> - -<para>A user ID (uid) is assigned automatically. You can also specify -a uid manually by adding - + Note that <literal>alice</literal> is a member of the + <literal>wheel</literal> and <literal>networkmanager</literal> groups, which + allows her to use <command>sudo</command> to execute commands as + <literal>root</literal> and to configure the network, respectively. Also note + the SSH public key that allows remote logins with the corresponding private + key. Users created in this way do not have a password by default, so they + cannot log in via mechanisms that require a password. However, you can use + the <command>passwd</command> program to set a password, which is retained + across invocations of <command>nixos-rebuild</command>. + </para> + <para> + If you set <xref linkend="opt-users.mutableUsers"/> to false, then the + contents of <literal>/etc/passwd</literal> and <literal>/etc/group</literal> + will be congruent to your NixOS configuration. For instance, if you remove a + user from <xref linkend="opt-users.users"/> and run nixos-rebuild, the user + account will cease to exist. Also, imperative commands for managing users and + groups, such as useradd, are no longer available. Passwords may still be + assigned by setting the user's + <link linkend="opt-users.users._name__.hashedPassword">hashedPassword</link> + option. A hashed password can be generated using <command>mkpasswd -m + sha-512</command> after installing the <literal>mkpasswd</literal> package. + </para> + <para> + A user ID (uid) is assigned automatically. You can also specify a uid + manually by adding <programlisting> uid = 1000; </programlisting> - -to the user specification.</para> - -<para>Groups can be specified similarly. The following states that a -group named <literal>students</literal> shall exist: - + to the user specification. + </para> + <para> + Groups can be specified similarly. The following states that a group named + <literal>students</literal> shall exist: <programlisting> -users.extraGroups.students.gid = 1000; +<xref linkend="opt-users.groups"/>.students.gid = 1000; </programlisting> - -As with users, the group ID (gid) is optional and will be assigned -automatically if it’s missing.</para> - -<para>In the imperative style, users and groups are managed by -commands such as <command>useradd</command>, -<command>groupmod</command> and so on. For instance, to create a user -account named <literal>alice</literal>: - + As with users, the group ID (gid) is optional and will be assigned + automatically if it’s missing. + </para> + <para> + In the imperative style, users and groups are managed by commands such as + <command>useradd</command>, <command>groupmod</command> and so on. For + instance, to create a user account named <literal>alice</literal>: <screen> -$ useradd -m alice</screen> - -The flag <option>-m</option> causes the creation of a home directory -for the new user, which is generally what you want. The user does not -have an initial password and therefore cannot log in. A password can -be set using the <command>passwd</command> utility: - +# useradd -m alice</screen> + To make all nix tools available to this new user use `su - USER` which opens + a login shell (==shell that loads the profile) for given user. This will + create the ~/.nix-defexpr symlink. So run: <screen> -$ passwd alice +# su - alice -c "true"</screen> + The flag <option>-m</option> causes the creation of a home directory for the + new user, which is generally what you want. The user does not have an initial + password and therefore cannot log in. A password can be set using the + <command>passwd</command> utility: +<screen> +# passwd alice Enter new UNIX password: *** Retype new UNIX password: *** </screen> - -A user can be deleted using <command>userdel</command>: - + A user can be deleted using <command>userdel</command>: <screen> -$ userdel -r alice</screen> - -The flag <option>-r</option> deletes the user’s home directory. -Accounts can be modified using <command>usermod</command>. Unix -groups can be managed using <command>groupadd</command>, -<command>groupmod</command> and <command>groupdel</command>.</para> - +# userdel -r alice</screen> + The flag <option>-r</option> deletes the user’s home directory. Accounts + can be modified using <command>usermod</command>. Unix groups can be managed + using <command>groupadd</command>, <command>groupmod</command> and + <command>groupdel</command>. + </para> </chapter> diff --git a/nixos/doc/manual/configuration/wireless.xml b/nixos/doc/manual/configuration/wireless.xml index 373a9168cc87..999447234ad1 100644 --- a/nixos/doc/manual/configuration/wireless.xml +++ b/nixos/doc/manual/configuration/wireless.xml @@ -3,39 +3,43 @@ xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="sec-wireless"> + <title>Wireless Networks</title> -<title>Wireless Networks</title> - -<para>For a desktop installation using NetworkManager (e.g., GNOME), -you just have to make sure the user is in the -<code>networkmanager</code> group and you can skip the rest of this -section on wireless networks.</para> - -<para> -NixOS will start wpa_supplicant for you if you enable this setting: + <para> + For a desktop installation using NetworkManager (e.g., GNOME), you just have + to make sure the user is in the <code>networkmanager</code> group and you can + skip the rest of this section on wireless networks. + </para> + <para> + NixOS will start wpa_supplicant for you if you enable this setting: <programlisting> -networking.wireless.enable = true; +<xref linkend="opt-networking.wireless.enable"/> = true; </programlisting> - -NixOS currently does not generate wpa_supplicant's -configuration file, <literal>/etc/wpa_supplicant.conf</literal>. You should edit this file -yourself to define wireless networks, WPA keys and so on (see -wpa_supplicant.conf(5)). -</para> - -<para> -If you are using WPA2 the <command>wpa_passphrase</command> tool might be useful -to generate the <literal>wpa_supplicant.conf</literal>. - + NixOS lets you specify networks for wpa_supplicant declaratively: +<programlisting> +<xref linkend="opt-networking.wireless.networks"/> = { + echelon = { + psk = "abcdefgh"; + }; + "free.wifi" = {}; +} +</programlisting> + Be aware that keys will be written to the nix store in plaintext! When no + networks are set, it will default to using a configuration file at + <literal>/etc/wpa_supplicant.conf</literal>. You should edit this file + yourself to define wireless networks, WPA keys and so on (see + wpa_supplicant.conf(5)). + </para> + + <para> + If you are using WPA2 the <command>wpa_passphrase</command> tool might be + useful to generate the <literal>wpa_supplicant.conf</literal>. <screen> -$ wpa_passphrase ESSID PSK > /etc/wpa_supplicant.conf</screen> - -After you have edited the <literal>wpa_supplicant.conf</literal>, -you need to restart the wpa_supplicant service. - +# wpa_passphrase ESSID PSK > /etc/wpa_supplicant.conf</screen> + After you have edited the <literal>wpa_supplicant.conf</literal>, you need to + restart the wpa_supplicant service. <screen> -$ systemctl restart wpa_supplicant.service</screen> -</para> - +# systemctl restart wpa_supplicant.service</screen> + </para> </section> diff --git a/nixos/doc/manual/configuration/x-windows.xml b/nixos/doc/manual/configuration/x-windows.xml index 7f43acab2c38..9a0969ad6355 100644 --- a/nixos/doc/manual/configuration/x-windows.xml +++ b/nixos/doc/manual/configuration/x-windows.xml @@ -3,117 +3,133 @@ xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="sec-x11"> - -<title>X Window System</title> - -<para>The X Window System (X11) provides the basis of NixOS’ graphical -user interface. It can be enabled as follows: + <title>X Window System</title> + <para> + The X Window System (X11) provides the basis of NixOS’ graphical user + interface. It can be enabled as follows: <programlisting> -services.xserver.enable = true; +<xref linkend="opt-services.xserver.enable"/> = true; </programlisting> -The X server will automatically detect and use the appropriate video -driver from a set of X.org drivers (such as <literal>vesa</literal> -and <literal>intel</literal>). You can also specify a driver -manually, e.g. + The X server will automatically detect and use the appropriate video driver + from a set of X.org drivers (such as <literal>vesa</literal> and + <literal>intel</literal>). You can also specify a driver manually, e.g. <programlisting> -services.xserver.videoDrivers = [ "r128" ]; +<xref linkend="opt-services.xserver.videoDrivers"/> = [ "r128" ]; </programlisting> -to enable X.org’s <literal>xf86-video-r128</literal> driver.</para> - -<para>You also need to enable at least one desktop or window manager. -Otherwise, you can only log into a plain undecorated -<command>xterm</command> window. Thus you should pick one or more of -the following lines: + to enable X.org’s <literal>xf86-video-r128</literal> driver. + </para> + <para> + You also need to enable at least one desktop or window manager. Otherwise, + you can only log into a plain undecorated <command>xterm</command> window. + Thus you should pick one or more of the following lines: <programlisting> -services.xserver.desktopManager.kde4.enable = true; -services.xserver.desktopManager.xfce.enable = true; -services.xserver.windowManager.xmonad.enable = true; -services.xserver.windowManager.twm.enable = true; -services.xserver.windowManager.icewm.enable = true; +<xref linkend="opt-services.xserver.desktopManager.plasma5.enable"/> = true; +<xref linkend="opt-services.xserver.desktopManager.xfce.enable"/> = true; +<xref linkend="opt-services.xserver.desktopManager.gnome3.enable"/> = true; +<xref linkend="opt-services.xserver.windowManager.xmonad.enable"/> = true; +<xref linkend="opt-services.xserver.windowManager.twm.enable"/> = true; +<xref linkend="opt-services.xserver.windowManager.icewm.enable"/> = true; +<xref linkend="opt-services.xserver.windowManager.i3.enable"/> = true; </programlisting> -</para> - -<para>NixOS’s default <emphasis>display manager</emphasis> (the -program that provides a graphical login prompt and manages the X -server) is SLiM. You can select KDE’s <command>kdm</command> instead: + </para> + <para> + NixOS’s default <emphasis>display manager</emphasis> (the program that + provides a graphical login prompt and manages the X server) is SLiM. You can + select an alternative one by picking one of the following lines: <programlisting> -services.xserver.displayManager.kdm.enable = true; +<xref linkend="opt-services.xserver.displayManager.sddm.enable"/> = true; +<xref linkend="opt-services.xserver.displayManager.lightdm.enable"/> = true; </programlisting> -</para> - -<para>The X server is started automatically at boot time. If you -don’t want this to happen, you can set: + </para> + <para> + You can set the keyboard layout (and optionally the layout variant): <programlisting> -services.xserver.autorun = false; +<xref linkend="opt-services.xserver.layout"/> = "de"; +<xref linkend="opt-services.xserver.xkbVariant"/> = "neo"; </programlisting> -The X server can then be started manually: + </para> + <para> + The X server is started automatically at boot time. If you don’t want this + to happen, you can set: +<programlisting> +<xref linkend="opt-services.xserver.autorun"/> = false; +</programlisting> + The X server can then be started manually: <screen> -$ systemctl start display-manager.service +# systemctl start display-manager.service </screen> -</para> - - -<simplesect><title>NVIDIA Graphics Cards</title> - -<para>NVIDIA provides a proprietary driver for its graphics cards that -has better 3D performance than the X.org drivers. It is not enabled -by default because it’s not free software. You can enable it as follows: + </para> + <simplesect> + <title>NVIDIA Graphics Cards</title> + <para> + NVIDIA provides a proprietary driver for its graphics cards that has better + 3D performance than the X.org drivers. It is not enabled by default because + it’s not free software. You can enable it as follows: <programlisting> -services.xserver.videoDrivers = [ "nvidia" ]; +<xref linkend="opt-services.xserver.videoDrivers"/> = [ "nvidia" ]; </programlisting> -Or if you have an older card, you may have to use one of the legacy drivers: + Or if you have an older card, you may have to use one of the legacy drivers: <programlisting> -services.xserver.videoDrivers = [ "nvidiaLegacy340" ]; -services.xserver.videoDrivers = [ "nvidiaLegacy304" ]; -services.xserver.videoDrivers = [ "nvidiaLegacy173" ]; +<xref linkend="opt-services.xserver.videoDrivers"/> = [ "nvidiaLegacy340" ]; +<xref linkend="opt-services.xserver.videoDrivers"/> = [ "nvidiaLegacy304" ]; +<xref linkend="opt-services.xserver.videoDrivers"/> = [ "nvidiaLegacy173" ]; </programlisting> -You may need to reboot after enabling this driver to prevent a clash -with other kernel modules.</para> - -<para>On 64-bit systems, if you want full acceleration for 32-bit -programs such as Wine, you should also set the following: + You may need to reboot after enabling this driver to prevent a clash with + other kernel modules. + </para> + <para> + On 64-bit systems, if you want full acceleration for 32-bit programs such as + Wine, you should also set the following: <programlisting> -hardware.opengl.driSupport32Bit = true; +<xref linkend="opt-hardware.opengl.driSupport32Bit"/> = true; </programlisting> -</para> - -</simplesect> - -<simplesect><title>AMD Graphics Cards</title> - -<para>AMD provides a proprietary driver for its graphics cards that -has better 3D performance than the X.org drivers. It is not enabled -by default because it’s not free software. You can enable it as follows: + </para> + </simplesect> + <simplesect> + <title>AMD Graphics Cards</title> + <para> + AMD provides a proprietary driver for its graphics cards that has better 3D + performance than the X.org drivers. It is not enabled by default because + it’s not free software. You can enable it as follows: <programlisting> -services.xserver.videoDrivers = [ "ati_unfree" ]; +<xref linkend="opt-services.xserver.videoDrivers"/> = [ "ati_unfree" ]; </programlisting> -You will need to reboot after enabling this driver to prevent a clash -with other kernel modules.</para> - -<para>On 64-bit systems, if you want full acceleration for 32-bit -programs such as Wine, you should also set the following: + You will need to reboot after enabling this driver to prevent a clash with + other kernel modules. + </para> + <para> + On 64-bit systems, if you want full acceleration for 32-bit programs such as + Wine, you should also set the following: <programlisting> -hardware.opengl.driSupport32Bit = true; +<xref linkend="opt-hardware.opengl.driSupport32Bit"/> = true; </programlisting> -</para> - -</simplesect> - -<simplesect><title>Touchpads</title> - -<para>Support for Synaptics touchpads (found in many laptops such as -the Dell Latitude series) can be enabled as follows: + </para> + </simplesect> + <simplesect> + <title>Touchpads</title> + <para> + Support for Synaptics touchpads (found in many laptops such as the Dell + Latitude series) can be enabled as follows: <programlisting> -services.xserver.synaptics.enable = true; +<xref linkend="opt-services.xserver.libinput.enable"/> = true; </programlisting> -The driver has many options (see <xref linkend="ch-options"/>). For -instance, the following enables two-finger scrolling: + The driver has many options (see <xref linkend="ch-options"/>). For + instance, the following disables tap-to-click behavior: <programlisting> -services.xserver.synaptics.twoFingerScroll = true; +<xref linkend="opt-services.xserver.libinput.tapping"/> = false; </programlisting> -</para> - -</simplesect> - - + Note: the use of <literal>services.xserver.synaptics</literal> is deprecated + since NixOS 17.09. + </para> + </simplesect> + <simplesect> + <title>GTK/Qt themes</title> + <para> + GTK themes can be installed either to user profile or system-wide (via + <literal>environment.systemPackages</literal>). To make Qt 5 applications + look similar to GTK2 ones, you can install <literal>qt5.qtbase.gtk</literal> + package into your system environment. It should work for all Qt 5 library + versions. + </para> + </simplesect> </chapter> diff --git a/nixos/doc/manual/configuration/xfce.xml b/nixos/doc/manual/configuration/xfce.xml new file mode 100644 index 000000000000..40e61d2bd691 --- /dev/null +++ b/nixos/doc/manual/configuration/xfce.xml @@ -0,0 +1,72 @@ +<chapter xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-xfce"> + <title>Xfce Desktop Environment</title> + <para> + To enable the Xfce Desktop Environment, set +<programlisting> +<link linkend="opt-services.xserver.desktopManager.default">services.xserver.desktopManager</link> = { + <link linkend="opt-services.xserver.desktopManager.xfce.enable">xfce.enable</link> = true; + <link linkend="opt-services.xserver.desktopManager.default">default</link> = "xfce"; +}; + </programlisting> + </para> + <para> + Optionally, <emphasis>compton</emphasis> can be enabled for nice graphical + effects, some example settings: +<programlisting> +<link linkend="opt-services.compton.enable">services.compton</link> = { + <link linkend="opt-services.compton.enable">enable</link> = true; + <link linkend="opt-services.compton.fade">fade</link> = true; + <link linkend="opt-services.compton.inactiveOpacity">inactiveOpacity</link> = "0.9"; + <link linkend="opt-services.compton.shadow">shadow</link> = true; + <link linkend="opt-services.compton.fadeDelta">fadeDelta</link> = 4; +}; + </programlisting> + </para> + <para> + Some Xfce programs are not installed automatically. To install them manually + (system wide), put them into your + <xref linkend="opt-environment.systemPackages"/>. + </para> + <simplesect> + <title>Thunar Volume Support</title> + <para> + To enable <emphasis>Thunar</emphasis> volume support, put +<programlisting> +<xref linkend="opt-services.xserver.desktopManager.xfce.enable"/> = true; + </programlisting> + into your <emphasis>configuration.nix</emphasis>. + </para> + </simplesect> + <simplesect> + <title>Polkit Authentication Agent</title> + <para> + There is no authentication agent automatically installed alongside Xfce. To + allow mounting of local (non-removable) filesystems, you will need to + install one. Installing <emphasis>polkit_gnome</emphasis>, a rebuild, logout + and login did the trick. + </para> + </simplesect> + <simplesect> + <title>Troubleshooting</title> + <para> + Even after enabling udisks2, volume management might not work. Thunar and/or + the desktop takes time to show up. Thunar will spit out this kind of message + on start (look at <command>journalctl --user -b</command>). +<programlisting> +Thunar:2410): GVFS-RemoteVolumeMonitor-WARNING **: remote volume monitor with dbus name org.gtk.Private.UDisks2VolumeMonitor is not supported + </programlisting> + This is caused by some needed GNOME services not running. This is all fixed + by enabling "Launch GNOME services on startup" in the Advanced tab of the + Session and Startup settings panel. Alternatively, you can run this command + to do the same thing. +<programlisting> +$ xfconf-query -c xfce4-session -p /compat/LaunchGNOME -s true + </programlisting> + A log-out and re-log will be needed for this to take effect. + </para> + </simplesect> +</chapter> diff --git a/nixos/doc/manual/default.nix b/nixos/doc/manual/default.nix index 87964e27bb9c..fef6b2f86c85 100644 --- a/nixos/doc/manual/default.nix +++ b/nixos/doc/manual/default.nix @@ -1,38 +1,83 @@ -{ pkgs, options, version, revision }: +{ pkgs, options, config, version, revision, extraSources ? [] }: with pkgs; -with pkgs.lib; let + lib = pkgs.lib; # Remove invisible and internal options. - optionsList = filter (opt: opt.visible && !opt.internal) (optionAttrSetToDocList options); + optionsListVisible = lib.filter (opt: opt.visible && !opt.internal) (lib.optionAttrSetToDocList options); # Replace functions by the string <function> substFunction = x: - if builtins.isAttrs x then mapAttrs (name: substFunction) x + if builtins.isAttrs x then lib.mapAttrs (name: substFunction) x else if builtins.isList x then map substFunction x - else if builtins.isFunction x then "<function>" + else if lib.isFunction x then "<function>" else x; - # Clean up declaration sites to not refer to the NixOS source tree. - optionsList' = flip map optionsList (opt: opt // { - declarations = map (fn: stripPrefix fn) opt.declarations; + # Generate DocBook documentation for a list of packages. This is + # what `relatedPackages` option of `mkOption` from + # ../../../lib/options.nix influences. + # + # Each element of `relatedPackages` can be either + # - a string: that will be interpreted as an attribute name from `pkgs`, + # - a list: that will be interpreted as an attribute path from `pkgs`, + # - an attrset: that can specify `name`, `path`, `package`, `comment` + # (either of `name`, `path` is required, the rest are optional). + genRelatedPackages = packages: + let + unpack = p: if lib.isString p then { name = p; } + else if lib.isList p then { path = p; } + else p; + describe = args: + let + title = args.title or null; + name = args.name or (lib.concatStringsSep "." args.path); + path = args.path or [ args.name ]; + package = args.package or (lib.attrByPath path (throw "Invalid package attribute path `${toString path}'") pkgs); + in "<listitem>" + + "<para><literal>${lib.optionalString (title != null) "${title} aka "}pkgs.${name} (${package.meta.name})</literal>" + + lib.optionalString (!package.meta.available) " <emphasis>[UNAVAILABLE]</emphasis>" + + ": ${package.meta.description or "???"}.</para>" + + lib.optionalString (args ? comment) "\n<para>${args.comment}</para>" + # Lots of `longDescription's break DocBook, so we just wrap them into <programlisting> + + lib.optionalString (package.meta ? longDescription) "\n<programlisting>${package.meta.longDescription}</programlisting>" + + "</listitem>"; + in "<itemizedlist>${lib.concatStringsSep "\n" (map (p: describe (unpack p)) packages)}</itemizedlist>"; + + optionsListDesc = lib.flip map optionsListVisible (opt: opt // { + # Clean up declaration sites to not refer to the NixOS source tree. + declarations = map stripAnyPrefixes opt.declarations; } - // optionalAttrs (opt ? example) { example = substFunction opt.example; } - // optionalAttrs (opt ? default) { default = substFunction opt.default; } - // optionalAttrs (opt ? type) { type = substFunction opt.type; }); - - prefix = toString ../../..; - - stripPrefix = fn: - if substring 0 (stringLength prefix) fn == prefix then - substring (stringLength prefix + 1) 1000 fn - else - fn; + // lib.optionalAttrs (opt ? example) { example = substFunction opt.example; } + // lib.optionalAttrs (opt ? default) { default = substFunction opt.default; } + // lib.optionalAttrs (opt ? type) { type = substFunction opt.type; } + // lib.optionalAttrs (opt ? relatedPackages && opt.relatedPackages != []) { relatedPackages = genRelatedPackages opt.relatedPackages; }); + + # We need to strip references to /nix/store/* from options, + # including any `extraSources` if some modules came from elsewhere, + # or else the build will fail. + # + # E.g. if some `options` came from modules in ${pkgs.customModules}/nix, + # you'd need to include `extraSources = [ pkgs.customModules ]` + prefixesToStrip = map (p: "${toString p}/") ([ ../../.. ] ++ extraSources); + stripAnyPrefixes = lib.flip (lib.fold lib.removePrefix) prefixesToStrip; + + # Custom "less" that pushes up all the things ending in ".enable*" + # and ".package*" + optionLess = a: b: + let + ise = lib.hasPrefix "enable"; + isp = lib.hasPrefix "package"; + cmp = lib.splitByAndCompare ise lib.compare + (lib.splitByAndCompare isp lib.compare lib.compare); + in lib.compareLists cmp a.loc b.loc < 0; + + # Customly sort option list for the man page. + optionsList = lib.sort optionLess optionsListDesc; # Convert the list of options into an XML file. - optionsXML = builtins.toFile "options.xml" (builtins.toXML optionsList'); + optionsXML = builtins.toFile "options.xml" (builtins.toXML optionsList); optionsDocBook = runCommand "options-db.xml" {} '' optionsXML=${optionsXML} @@ -43,20 +88,33 @@ let echo "for hints about the offending path)." exit 1 fi - ${libxslt}/bin/xsltproc \ + ${buildPackages.libxslt.bin}/bin/xsltproc \ --stringparam revision '${revision}' \ -o $out ${./options-to-docbook.xsl} $optionsXML ''; - sources = sourceFilesBySuffices ./. [".xml"]; + sources = lib.sourceFilesBySuffices ./. [".xml"]; + + modulesDoc = builtins.toFile "modules.xml" '' + <section xmlns:xi="http://www.w3.org/2001/XInclude" id="modules"> + ${(lib.concatMapStrings (path: '' + <xi:include href="${path}" /> + '') (lib.catAttrs "value" config.meta.doc))} + </section> + ''; + + generatedSources = runCommand "generated-docbook" {} '' + mkdir $out + ln -s ${modulesDoc} $out/modules.xml + ln -s ${optionsDocBook} $out/options-db.xml + printf "%s" "${version}" > $out/version + ''; copySources = '' cp -prd $sources/* . # */ + ln -s ${generatedSources} ./generated chmod -R u+w . - cp ${../../modules/services/databases/postgresql.xml} configuration/postgresql.xml - ln -s ${optionsDocBook} options-db.xml - echo "${version}" > version ''; toc = builtins.toFile "toc.xml" @@ -69,126 +127,205 @@ let </toc> ''; + manualXsltprocOptions = toString [ + "--param section.autolabel 1" + "--param section.label.includes.component.label 1" + "--stringparam html.stylesheet 'style.css overrides.css highlightjs/mono-blue.css'" + "--stringparam html.script './highlightjs/highlight.pack.js ./highlightjs/loader.js'" + "--param xref.with.number.and.title 1" + "--param toc.section.depth 3" + "--stringparam admon.style ''" + "--stringparam callout.graphics.extension .svg" + "--stringparam current.docid manual" + "--param chunk.section.depth 0" + "--param chunk.first.sections 1" + "--param use.id.as.filename 1" + "--stringparam generate.toc 'book toc appendix toc'" + "--stringparam chunk.toc ${toc}" + ]; + + manual-combined = runCommand "nixos-manual-combined" + { inherit sources; + nativeBuildInputs = [ buildPackages.libxml2.bin buildPackages.libxslt.bin ]; + meta.description = "The NixOS manual as plain docbook XML"; + } + '' + ${copySources} + + xmllint --xinclude --output ./manual-combined.xml ./manual.xml + xmllint --xinclude --noxincludenode \ + --output ./man-pages-combined.xml ./man-pages.xml + + # outputs the context of an xmllint error output + # LEN lines around the failing line are printed + function context { + # length of context + local LEN=6 + # lines to print before error line + local BEFORE=4 + + # xmllint output lines are: + # file.xml:1234: there was an error on line 1234 + while IFS=':' read -r file line rest; do + echo + if [[ -n "$rest" ]]; then + echo "$file:$line:$rest" + local FROM=$(($line>$BEFORE ? $line - $BEFORE : 1)) + # number lines & filter context + nl --body-numbering=a "$file" | sed -n "$FROM,+$LEN p" + else + if [[ -n "$line" ]]; then + echo "$file:$line" + else + echo "$file" + fi + fi + done + } + + function lintrng { + xmllint --debug --noout --nonet \ + --relaxng ${docbook5}/xml/rng/docbook/docbook.rng \ + "$1" \ + 2>&1 | context 1>&2 + # ^ redirect assumes xmllint doesn’t print to stdout + } + + lintrng manual-combined.xml + lintrng man-pages-combined.xml + + mkdir $out + cp manual-combined.xml $out/ + cp man-pages-combined.xml $out/ + ''; + + olinkDB = runCommand "manual-olinkdb" + { inherit sources; + nativeBuildInputs = [ buildPackages.libxml2.bin buildPackages.libxslt.bin ]; + } + '' + xsltproc \ + ${manualXsltprocOptions} \ + --stringparam collect.xref.targets only \ + --stringparam targets.filename "$out/manual.db" \ + --nonet \ + ${docbook5_xsl}/xml/xsl/docbook/xhtml/chunktoc.xsl \ + ${manual-combined}/manual-combined.xml + + cat > "$out/olinkdb.xml" <<EOF + <?xml version="1.0" encoding="utf-8"?> + <!DOCTYPE targetset SYSTEM + "file://${docbook5_xsl}/xml/xsl/docbook/common/targetdatabase.dtd" [ + <!ENTITY manualtargets SYSTEM "file://$out/manual.db"> + ]> + <targetset> + <targetsetinfo> + Allows for cross-referencing olinks between the manpages + and manual. + </targetsetinfo> + + <document targetdoc="manual">&manualtargets;</document> + </targetset> + EOF + ''; + in rec { + inherit generatedSources; # The NixOS options in JSON format. - optionsJSON = stdenv.mkDerivation { - name = "options-json"; - - buildCommand = '' + optionsJSON = runCommand "options-json" + { meta.description = "List of NixOS options in JSON format"; + } + '' # Export list of options in different format. dst=$out/share/doc/nixos mkdir -p $dst cp ${builtins.toFile "options.json" (builtins.unsafeDiscardStringContext (builtins.toJSON - (listToAttrs (map (o: { name = o.name; value = removeAttrs o ["name" "visible" "internal"]; }) optionsList')))) + (builtins.listToAttrs (map (o: { name = o.name; value = removeAttrs o ["name" "visible" "internal"]; }) optionsList)))) } $dst/options.json mkdir -p $out/nix-support echo "file json $dst/options.json" >> $out/nix-support/hydra-build-products ''; # */ - meta.description = "List of NixOS options in JSON format"; - }; - # Generate the NixOS manual. - manual = stdenv.mkDerivation { - name = "nixos-manual"; - - inherit sources; - - buildInputs = [ libxml2 libxslt ]; - - buildCommand = '' - ${copySources} - - # Check the validity of the manual sources. - xmllint --noout --nonet --xinclude --noxincludenode \ - --relaxng ${docbook5}/xml/rng/docbook/docbook.rng \ - manual.xml - + manual = runCommand "nixos-manual" + { inherit sources; + nativeBuildInputs = [ buildPackages.libxml2.bin buildPackages.libxslt.bin ]; + meta.description = "The NixOS manual in HTML format"; + allowedReferences = ["out"]; + } + '' # Generate the HTML manual. dst=$out/share/doc/nixos mkdir -p $dst xsltproc \ - --param section.autolabel 1 \ - --param section.label.includes.component.label 1 \ - --stringparam html.stylesheet style.css \ - --param xref.with.number.and.title 1 \ - --param toc.section.depth 3 \ - --stringparam admon.style "" \ - --stringparam callout.graphics.extension .gif \ - --param chunk.section.depth 0 \ - --param chunk.first.sections 1 \ - --param use.id.as.filename 1 \ - --stringparam generate.toc "book toc appendix toc" \ - --stringparam chunk.toc ${toc} \ - --nonet --xinclude --output $dst/ \ - ${docbook5_xsl}/xml/xsl/docbook/xhtml/chunktoc.xsl ./manual.xml + ${manualXsltprocOptions} \ + --stringparam target.database.document "${olinkDB}/olinkdb.xml" \ + --nonet --output $dst/ \ + ${docbook5_xsl}/xml/xsl/docbook/xhtml/chunktoc.xsl \ + ${manual-combined}/manual-combined.xml mkdir -p $dst/images/callouts - cp ${docbook5_xsl}/xml/xsl/docbook/images/callouts/*.gif $dst/images/callouts/ + cp ${docbook5_xsl}/xml/xsl/docbook/images/callouts/*.svg $dst/images/callouts/ - cp ${./style.css} $dst/style.css + cp ${../../../doc/style.css} $dst/style.css + cp ${../../../doc/overrides.css} $dst/overrides.css + cp -r ${pkgs.documentation-highlighter} $dst/highlightjs mkdir -p $out/nix-support echo "nix-build out $out" >> $out/nix-support/hydra-build-products echo "doc manual $dst" >> $out/nix-support/hydra-build-products ''; # */ - meta.description = "The NixOS manual in HTML format"; - - allowedReferences = ["out"]; - }; - manualPDF = stdenv.mkDerivation { - name = "nixos-manual-pdf"; + manualEpub = runCommand "nixos-manual-epub" + { inherit sources; + buildInputs = [ libxml2.bin libxslt.bin zip ]; + } + '' + # Generate the epub manual. + dst=$out/share/doc/nixos - inherit sources; + xsltproc \ + ${manualXsltprocOptions} \ + --stringparam target.database.document "${olinkDB}/olinkdb.xml" \ + --nonet --xinclude --output $dst/epub/ \ + ${docbook5_xsl}/xml/xsl/docbook/epub/docbook.xsl \ + ${manual-combined}/manual-combined.xml - buildInputs = [ libxml2 libxslt dblatex dblatex.tex ]; + mkdir -p $dst/epub/OEBPS/images/callouts + cp -r ${docbook5_xsl}/xml/xsl/docbook/images/callouts/*.svg $dst/epub/OEBPS/images/callouts # */ + echo "application/epub+zip" > mimetype + manual="$dst/nixos-manual.epub" + zip -0Xq "$manual" mimetype + cd $dst/epub && zip -Xr9D "$manual" * - buildCommand = '' - ${copySources} - - dst=$out/share/doc/nixos - mkdir -p $dst - xmllint --xinclude manual.xml | dblatex -o $dst/manual.pdf - \ - -P doc.collab.show=0 \ - -P latex.output.revhistory=0 + rm -rf $dst/epub mkdir -p $out/nix-support - echo "doc-pdf manual $dst/manual.pdf" >> $out/nix-support/hydra-build-products + echo "doc-epub manual $manual" >> $out/nix-support/hydra-build-products ''; - }; - - # Generate the NixOS manpages. - manpages = stdenv.mkDerivation { - name = "nixos-manpages"; - - inherit sources; - - buildInputs = [ libxml2 libxslt ]; - buildCommand = '' - ${copySources} - - # Check the validity of the manual sources. - xmllint --noout --nonet --xinclude --noxincludenode \ - --relaxng ${docbook5}/xml/rng/docbook/docbook.rng \ - ./man-pages.xml + # Generate the NixOS manpages. + manpages = runCommand "nixos-manpages" + { inherit sources; + nativeBuildInputs = [ buildPackages.libxml2.bin buildPackages.libxslt.bin ]; + allowedReferences = ["out"]; + } + '' # Generate manpages. mkdir -p $out/share/man - xsltproc --nonet --xinclude \ + xsltproc --nonet \ --param man.output.in.separate.dir 1 \ --param man.output.base.dir "'$out/share/man/'" \ --param man.endnotes.are.numbered 0 \ + --param man.break.after.slash 1 \ + --stringparam target.database.document "${olinkDB}/olinkdb.xml" \ ${docbook5_xsl}/xml/xsl/docbook/manpages/docbook.xsl \ - ./man-pages.xml + ${manual-combined}/man-pages-combined.xml ''; - allowedReferences = ["out"]; - }; - } diff --git a/nixos/doc/manual/development/assertions.xml b/nixos/doc/manual/development/assertions.xml new file mode 100644 index 000000000000..17c38ffcc717 --- /dev/null +++ b/nixos/doc/manual/development/assertions.xml @@ -0,0 +1,74 @@ +<section xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-assertions"> + <title>Warnings and Assertions</title> + + <para> + When configuration problems are detectable in a module, it is a good idea to + write an assertion or warning. Doing so provides clear feedback to the user + and prevents errors after the build. + </para> + + <para> + Although Nix has the <literal>abort</literal> and + <literal>builtins.trace</literal> + <link xlink:href="https://nixos.org/nix/manual/#ssec-builtins">functions</link> + to perform such tasks, they are not ideally suited for NixOS modules. Instead + of these functions, you can declare your warnings and assertions using the + NixOS module system. + </para> + + <section> + <title>Warnings</title> + + <para> + This is an example of using <literal>warnings</literal>. + </para> + +<programlisting> +<![CDATA[ +{ config, lib, ... }: +{ + config = lib.mkIf config.services.foo.enable { + warnings = + if config.services.foo.bar + then [ ''You have enabled the bar feature of the foo service. + This is known to cause some specific problems in certain situations. + '' ] + else []; + } +} +]]> +</programlisting> + </section> + + <section> + <title>Assertions</title> + + <para> + This example, extracted from the + <link xlink:href="https://github.com/NixOS/nixpkgs/blob/release-17.09/nixos/modules/services/logging/syslogd.nix"> + <literal>syslogd</literal> module </link> shows how to use + <literal>assertions</literal>. Since there can only be one active syslog + daemon at a time, an assertion is useful to prevent such a broken system + from being built. + </para> + +<programlisting> +<![CDATA[ +{ config, lib, ... }: +{ + config = lib.mkIf config.services.syslogd.enable { + assertions = + [ { assertion = !config.services.rsyslogd.enable; + message = "rsyslogd conflicts with syslogd"; + } + ]; + } +} +]]> +</programlisting> + </section> +</section> diff --git a/nixos/doc/manual/development/building-nixos.xml b/nixos/doc/manual/development/building-nixos.xml index 21c5bfe6a5b1..23d9ddf88a77 100644 --- a/nixos/doc/manual/development/building-nixos.xml +++ b/nixos/doc/manual/development/building-nixos.xml @@ -3,30 +3,25 @@ xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="sec-building-cd"> - -<title>Building Your Own NixOS CD</title> - -<para>Building a NixOS CD is as easy as configuring your own computer. The -idea is to use another module which will replace -your <filename>configuration.nix</filename> to configure the system that -would be installed on the CD.</para> - -<para>Default CD/DVD configurations are available -inside <filename>nixos/modules/installer/cd-dvd</filename>. To build them -you have to set <envar>NIXOS_CONFIG</envar> before -running <command>nix-build</command> to build the ISO. - + <title>Building Your Own NixOS CD</title> + <para> + Building a NixOS CD is as easy as configuring your own computer. The idea is + to use another module which will replace your + <filename>configuration.nix</filename> to configure the system that would be + installed on the CD. + </para> + <para> + Default CD/DVD configurations are available inside + <filename>nixos/modules/installer/cd-dvd</filename>. <screen> -$ nix-build -A config.system.build.isoImage -I nixos-config=modules/installer/cd-dvd/installation-cd-minimal.nix</screen> - -</para> - -<para>Before burning your CD/DVD, you can check the content of the image by mounting anywhere like -suggested by the following command: - +$ git clone https://github.com/NixOS/nixpkgs.git +$ cd nixpkgs/nixos +$ nix-build -A config.system.build.isoImage -I nixos-config=modules/installer/cd-dvd/installation-cd-minimal.nix default.nix</screen> + </para> + <para> + Before burning your CD/DVD, you can check the content of the image by + mounting anywhere like suggested by the following command: <screen> -$ mount -o loop -t iso9660 ./result/iso/cd.iso /mnt/iso</screen> - -</para> - -</chapter> \ No newline at end of file +# mount -o loop -t iso9660 ./result/iso/cd.iso /mnt/iso</screen> + </para> +</chapter> diff --git a/nixos/doc/manual/development/building-parts.xml b/nixos/doc/manual/development/building-parts.xml index cb8dee039c8e..eaffc0ef47c2 100644 --- a/nixos/doc/manual/development/building-parts.xml +++ b/nixos/doc/manual/development/building-parts.xml @@ -3,111 +3,119 @@ xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="sec-building-parts"> - -<title>Building Specific Parts of NixOS</title> - -<para>With the command <command>nix-build</command>, you can build -specific parts of your NixOS configuration. This is done as follows: - + <title>Building Specific Parts of NixOS</title> + <para> + With the command <command>nix-build</command>, you can build specific parts + of your NixOS configuration. This is done as follows: <screen> $ cd <replaceable>/path/to/nixpkgs/nixos</replaceable> $ nix-build -A config.<replaceable>option</replaceable></screen> - -where <replaceable>option</replaceable> is a NixOS option with type -“derivation” (i.e. something that can be built). Attributes of -interest include: - -<variablelist> - - <varlistentry> - <term><varname>system.build.toplevel</varname></term> + where <replaceable>option</replaceable> is a NixOS option with type + “derivation” (i.e. something that can be built). Attributes of interest + include: + <variablelist> + <varlistentry> + <term> + <varname>system.build.toplevel</varname> + </term> <listitem> - <para>The top-level option that builds the entire NixOS system. - Everything else in your configuration is indirectly pulled in by - this option. This is what <command>nixos-rebuild</command> - builds and what <filename>/run/current-system</filename> points - to afterwards.</para> - - <para>A shortcut to build this is: - + <para> + The top-level option that builds the entire NixOS system. Everything else + in your configuration is indirectly pulled in by this option. This is + what <command>nixos-rebuild</command> builds and what + <filename>/run/current-system</filename> points to afterwards. + </para> + <para> + A shortcut to build this is: <screen> $ nix-build -A system</screen> - </para> + </para> </listitem> - </varlistentry> - - <varlistentry> - <term><varname>system.build.manual.manual</varname></term> - <listitem><para>The NixOS manual.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>system.build.etc</varname></term> - <listitem><para>A tree of symlinks that form the static parts of - <filename>/etc</filename>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>system.build.initialRamdisk</varname></term> - <term><varname>system.build.kernel</varname></term> + </varlistentry> + <varlistentry> + <term> + <varname>system.build.manual.manual</varname> + </term> <listitem> - <para>The initial ramdisk and kernel of the system. This allows - a quick way to test whether the kernel and the initial ramdisk - boot correctly, by using QEMU’s <option>-kernel</option> and - <option>-initrd</option> options: - + <para> + The NixOS manual. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>system.build.etc</varname> + </term> + <listitem> + <para> + A tree of symlinks that form the static parts of + <filename>/etc</filename>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>system.build.initialRamdisk</varname> + </term> + <term> + <varname>system.build.kernel</varname> + </term> + <listitem> + <para> + The initial ramdisk and kernel of the system. This allows a quick way to + test whether the kernel and the initial ramdisk boot correctly, by using + QEMU’s <option>-kernel</option> and <option>-initrd</option> options: <screen> $ nix-build -A config.system.build.initialRamdisk -o initrd $ nix-build -A config.system.build.kernel -o kernel $ qemu-system-x86_64 -kernel ./kernel/bzImage -initrd ./initrd/initrd -hda /dev/null </screen> - - </para> + </para> </listitem> - </varlistentry> - - <varlistentry> - <term><varname>system.build.nixos-rebuild</varname></term> - <term><varname>system.build.nixos-install</varname></term> - <term><varname>system.build.nixos-generate-config</varname></term> + </varlistentry> + <varlistentry> + <term> + <varname>system.build.nixos-rebuild</varname> + </term> + <term> + <varname>system.build.nixos-install</varname> + </term> + <term> + <varname>system.build.nixos-generate-config</varname> + </term> <listitem> - <para>These build the corresponding NixOS commands.</para> + <para> + These build the corresponding NixOS commands. + </para> </listitem> - </varlistentry> - - <varlistentry> - <term><varname>systemd.units.<replaceable>unit-name</replaceable>.unit</varname></term> + </varlistentry> + <varlistentry> + <term> + <varname>systemd.units.<replaceable>unit-name</replaceable>.unit</varname> + </term> <listitem> - <para>This builds the unit with the specified name. Note that - since unit names contain dots - (e.g. <literal>httpd.service</literal>), you need to put them - between quotes, like this: - + <para> + This builds the unit with the specified name. Note that since unit names + contain dots (e.g. <literal>httpd.service</literal>), you need to put + them between quotes, like this: <screen> $ nix-build -A 'config.systemd.units."httpd.service".unit' </screen> - - You can also test individual units, without rebuilding the whole - system, by putting them in - <filename>/run/systemd/system</filename>: - + You can also test individual units, without rebuilding the whole system, + by putting them in <filename>/run/systemd/system</filename>: <screen> $ cp $(nix-build -A 'config.systemd.units."httpd.service".unit')/httpd.service \ /run/systemd/system/tmp-httpd.service -$ systemctl daemon-reload -$ systemctl start tmp-httpd.service +# systemctl daemon-reload +# systemctl start tmp-httpd.service </screen> - Note that the unit must not have the same name as any unit in - <filename>/etc/systemd/system</filename> since those take - precedence over <filename>/run/systemd/system</filename>. - That’s why the unit is installed as - <filename>tmp-httpd.service</filename> here.</para> + <filename>/etc/systemd/system</filename> since those take precedence over + <filename>/run/systemd/system</filename>. That’s why the unit is + installed as <filename>tmp-httpd.service</filename> here. + </para> </listitem> - </varlistentry> - -</variablelist> - -</para> - -</chapter> \ No newline at end of file + </varlistentry> + </variablelist> + </para> +</chapter> diff --git a/nixos/doc/manual/development/development.xml b/nixos/doc/manual/development/development.xml index 2983c76c770b..03dee6ff09bb 100644 --- a/nixos/doc/manual/development/development.xml +++ b/nixos/doc/manual/development/development.xml @@ -3,19 +3,18 @@ xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="ch-development"> - -<title>Development</title> - -<partintro> -<para>This chapter describes how you can modify and extend -NixOS.</para> -</partintro> - -<xi:include href="sources.xml" /> -<xi:include href="writing-modules.xml" /> -<xi:include href="building-parts.xml" /> -<xi:include href="building-nixos.xml" /> -<xi:include href="nixos-tests.xml" /> -<xi:include href="testing-installer.xml" /> - + <title>Development</title> + <partintro> + <para> + This chapter describes how you can modify and extend NixOS. + </para> + </partintro> + <xi:include href="sources.xml" /> + <xi:include href="writing-modules.xml" /> + <xi:include href="building-parts.xml" /> + <xi:include href="writing-documentation.xml" /> + <xi:include href="building-nixos.xml" /> + <xi:include href="nixos-tests.xml" /> + <xi:include href="testing-installer.xml" /> + <xi:include href="releases.xml" /> </part> diff --git a/nixos/doc/manual/development/importing-modules.xml b/nixos/doc/manual/development/importing-modules.xml new file mode 100644 index 000000000000..1c6a5671eda8 --- /dev/null +++ b/nixos/doc/manual/development/importing-modules.xml @@ -0,0 +1,56 @@ +<section xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-importing-modules"> + <title>Importing Modules</title> + + <para> + Sometimes NixOS modules need to be used in configuration but exist outside of + Nixpkgs. These modules can be imported: + </para> + +<programlisting> +{ config, lib, pkgs, ... }: + +{ + imports = + [ # Use a locally-available module definition in + # ./example-module/default.nix + ./example-module + ]; + + services.exampleModule.enable = true; +} +</programlisting> + + <para> + The environment variable <literal>NIXOS_EXTRA_MODULE_PATH</literal> is an + absolute path to a NixOS module that is included alongside the Nixpkgs NixOS + modules. Like any NixOS module, this module can import additional modules: + </para> + +<programlisting> +# ./module-list/default.nix +[ + ./example-module1 + ./example-module2 +] +</programlisting> + +<programlisting> +# ./extra-module/default.nix +{ imports = import ./module-list.nix; } +</programlisting> + +<programlisting> +# NIXOS_EXTRA_MODULE_PATH=/absolute/path/to/extra-module +{ config, lib, pkgs, ... }: + +{ + # No `imports` needed + + services.exampleModule1.enable = true; +} +</programlisting> +</section> diff --git a/nixos/doc/manual/development/meta-attributes.xml b/nixos/doc/manual/development/meta-attributes.xml new file mode 100644 index 000000000000..3d019a4987e1 --- /dev/null +++ b/nixos/doc/manual/development/meta-attributes.xml @@ -0,0 +1,63 @@ +<section xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-meta-attributes"> + <title>Meta Attributes</title> + + <para> + Like Nix packages, NixOS modules can declare meta-attributes to provide extra + information. Module meta attributes are defined in the + <filename + xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/misc/meta.nix">meta.nix</filename> + special module. + </para> + + <para> + <literal>meta</literal> is a top level attribute like + <literal>options</literal> and <literal>config</literal>. Available + meta-attributes are <literal>maintainers</literal> and + <literal>doc</literal>. + </para> + + <para> + Each of the meta-attributes must be defined at most once per module file. + </para> + +<programlisting> +{ config, lib, pkgs, ... }: +{ + options = { + ... + }; + + config = { + ... + }; + + meta = { + maintainers = with lib.maintainers; [ ericsagnes ]; <co + xml:id='modules-meta-1' /> + doc = ./default.xml; <co xml:id='modules-meta-2' /> + }; +} +</programlisting> + + <calloutlist> + <callout arearefs='modules-meta-1'> + <para> + <varname>maintainers</varname> contains a list of the module maintainers. + </para> + </callout> + <callout arearefs='modules-meta-2'> + <para> + <varname>doc</varname> points to a valid DocBook file containing the module + documentation. Its contents is automatically added to + <xref + linkend="ch-configuration"/>. Changes to a module documentation + have to be checked to not break building the NixOS manual: + </para> +<programlisting>$ nix-build nixos/release.nix -A manual</programlisting> + </callout> + </calloutlist> +</section> diff --git a/nixos/doc/manual/development/nixos-tests.xml b/nixos/doc/manual/development/nixos-tests.xml index c09c41ea3bdc..2695082e3867 100644 --- a/nixos/doc/manual/development/nixos-tests.xml +++ b/nixos/doc/manual/development/nixos-tests.xml @@ -3,18 +3,17 @@ xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="sec-nixos-tests"> - -<title>NixOS Tests</title> - -<para>When you add some feature to NixOS, you should write a test for -it. NixOS tests are kept in the directory <filename + <title>NixOS Tests</title> + <para> + When you add some feature to NixOS, you should write a test for it. NixOS + tests are kept in the directory + <filename xlink:href="https://github.com/NixOS/nixpkgs/tree/master/nixos/tests">nixos/tests</filename>, -and are executed (using Nix) by a testing framework that automatically -starts one or more virtual machines containing the NixOS system(s) -required for the test.</para> - -<xi:include href="writing-nixos-tests.xml" /> -<xi:include href="running-nixos-tests.xml" /> -<xi:include href="running-nixos-tests-interactively.xml" /> - + and are executed (using Nix) by a testing framework that automatically starts + one or more virtual machines containing the NixOS system(s) required for the + test. + </para> + <xi:include href="writing-nixos-tests.xml" /> + <xi:include href="running-nixos-tests.xml" /> + <xi:include href="running-nixos-tests-interactively.xml" /> </chapter> diff --git a/nixos/doc/manual/development/option-declarations.xml b/nixos/doc/manual/development/option-declarations.xml index ea5d1241876e..eee81bf64263 100644 --- a/nixos/doc/manual/development/option-declarations.xml +++ b/nixos/doc/manual/development/option-declarations.xml @@ -3,14 +3,12 @@ xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="sec-option-declarations"> + <title>Option Declarations</title> -<title>Option Declarations</title> - -<para>An option declaration specifies the name, type and description -of a NixOS configuration option. It is illegal to define an option -that hasn’t been declared in any module. A option declaration -generally looks like this: - + <para> + An option declaration specifies the name, type and description of a NixOS + configuration option. It is invalid to define an option that hasn’t been + declared in any module. An option declaration generally looks like this: <programlisting> options = { <replaceable>name</replaceable> = mkOption { @@ -21,130 +19,181 @@ options = { }; }; </programlisting> - -</para> - -<para>The function <varname>mkOption</varname> accepts the following arguments. - -<variablelist> - - <varlistentry> - <term><varname>type</varname></term> + The attribute names within the <replaceable>name</replaceable> attribute path + must be camel cased in general but should, as an exception, match the + <link +xlink:href="https://nixos.org/nixpkgs/manual/#sec-package-naming"> + package attribute name</link> when referencing a Nixpkgs package. For + example, the option <varname>services.nix-serve.bindAddress</varname> + references the <varname>nix-serve</varname> Nixpkgs package. + </para> + + <para> + The function <varname>mkOption</varname> accepts the following arguments. + <variablelist> + <varlistentry> + <term> + <varname>type</varname> + </term> <listitem> - <para>The type of the option (see below). It may be omitted, - but that’s not advisable since it may lead to errors that are - hard to diagnose.</para> + <para> + The type of the option (see <xref linkend='sec-option-types' />). It may + be omitted, but that’s not advisable since it may lead to errors that + are hard to diagnose. + </para> </listitem> - </varlistentry> - - <varlistentry> - <term><varname>default</varname></term> - <listitem> - <para>The default value used if no value is defined by any - module. A default is not required; in that case, if the option - value is ever used, an error will be thrown.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>example</varname></term> + </varlistentry> + <varlistentry> + <term> + <varname>default</varname> + </term> <listitem> - <para>An example value that will be shown in the NixOS manual.</para> + <para> + The default value used if no value is defined by any module. A default is + not required; but if a default is not given, then users of the module + will have to define the value of the option, otherwise an error will be + thrown. + </para> </listitem> - </varlistentry> - - <varlistentry> - <term><varname>description</varname></term> + </varlistentry> + <varlistentry> + <term> + <varname>example</varname> + </term> <listitem> - <para>A textual description of the option, in DocBook format, - that will be included in the NixOS manual.</para> + <para> + An example value that will be shown in the NixOS manual. + </para> </listitem> - </varlistentry> - -</variablelist> - -</para> - -<para>Here is a non-exhaustive list of option types: - -<variablelist> - - <varlistentry> - <term><varname>types.bool</varname></term> + </varlistentry> + <varlistentry> + <term> + <varname>description</varname> + </term> <listitem> - <para>A Boolean.</para> + <para> + A textual description of the option, in DocBook format, that will be + included in the NixOS manual. + </para> </listitem> - </varlistentry> - - <varlistentry> - <term><varname>types.int</varname></term> + </varlistentry> + </variablelist> + </para> + + <section xml:id="sec-option-declarations-eot"> + <title>Extensible Option Types</title> + + <para> + Extensible option types is a feature that allow to extend certain types + declaration through multiple module files. This feature only work with a + restricted set of types, namely <literal>enum</literal> and + <literal>submodules</literal> and any composed forms of them. + </para> + + <para> + Extensible option types can be used for <literal>enum</literal> options that + affects multiple modules, or as an alternative to related + <literal>enable</literal> options. + </para> + + <para> + As an example, we will take the case of display managers. There is a central + display manager module for generic display manager options and a module file + per display manager backend (slim, sddm, gdm ...). + </para> + + <para> + There are two approach to this module structure: + <itemizedlist> <listitem> - <para>An integer.</para> + <para> + Managing the display managers independently by adding an enable option to + every display manager module backend. (NixOS) + </para> </listitem> - </varlistentry> - - <varlistentry> - <term><varname>types.str</varname></term> <listitem> - <para>A string.</para> + <para> + Managing the display managers in the central module by adding an option + to select which display manager backend to use. + </para> </listitem> - </varlistentry> - - <varlistentry> - <term><varname>types.lines</varname></term> - <listitem> - <para>A string. If there are multiple definitions, they are - concatenated, with newline characters in between.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>types.path</varname></term> - <listitem> - <para>A path, defined as anything that, when coerced to a - string, starts with a slash. This includes derivations.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>types.package</varname></term> - <listitem> - <para>A derivation (such as <literal>pkgs.hello</literal>) or a - store path (such as - <filename>/nix/store/1ifi1cfbfs5iajmvwgrbmrnrw3a147h9-hello-2.10</filename>).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>types.listOf</varname> <replaceable>t</replaceable></term> - <listitem> - <para>A list of elements of type <replaceable>t</replaceable> - (e.g., <literal>types.listOf types.str</literal> is a list of - strings). Multiple definitions are concatenated together.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>types.attrsOf</varname> <replaceable>t</replaceable></term> - <listitem> - <para>A set of elements of type <replaceable>t</replaceable> - (e.g., <literal>types.attrsOf types.int</literal> is a set of - name/value pairs, the values being integers).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>types.nullOr</varname> <replaceable>t</replaceable></term> - <listitem> - <para>Either the value <literal>null</literal> or something of - type <replaceable>t</replaceable>.</para> - </listitem> - </varlistentry> - -</variablelist> - -You can also create new types using the function -<varname>mkOptionType</varname>. See -<filename>lib/types.nix</filename> in Nixpkgs for details.</para> - + </itemizedlist> + </para> + + <para> + Both approaches have problems. + </para> + + <para> + Making backends independent can quickly become hard to manage. For display + managers, there can be only one enabled at a time, but the type system can + not enforce this restriction as there is no relation between each backend + <literal>enable</literal> option. As a result, this restriction has to be + done explicitely by adding assertions in each display manager backend + module. + </para> + + <para> + On the other hand, managing the display managers backends in the central + module will require to change the central module option every time a new + backend is added or removed. + </para> + + <para> + By using extensible option types, it is possible to create a placeholder + option in the central module + (<xref linkend='ex-option-declaration-eot-service' + />), and to extend + it in each backend module + (<xref + linkend='ex-option-declaration-eot-backend-slim' />, + <xref + linkend='ex-option-declaration-eot-backend-sddm' />). + </para> + + <para> + As a result, <literal>displayManager.enable</literal> option values can be + added without changing the main service module file and the type system + automatically enforce that there can only be a single display manager + enabled. + </para> + + <example xml:id='ex-option-declaration-eot-service'> + <title>Extensible type placeholder in the service module</title> +<screen> +services.xserver.displayManager.enable = mkOption { + description = "Display manager to use"; + type = with types; nullOr (enum [ ]); +};</screen> + </example> + + <example xml:id='ex-option-declaration-eot-backend-slim'> + <title>Extending <literal>services.xserver.displayManager.enable</literal> in the <literal>slim</literal> module</title> +<screen> +services.xserver.displayManager.enable = mkOption { + type = with types; nullOr (enum [ "slim" ]); +};</screen> + </example> + + <example xml:id='ex-option-declaration-eot-backend-sddm'> + <title>Extending <literal>services.xserver.displayManager.enable</literal> in the <literal>sddm</literal> module</title> +<screen> +services.xserver.displayManager.enable = mkOption { + type = with types; nullOr (enum [ "sddm" ]); +};</screen> + </example> + + <para> + The placeholder declaration is a standard <literal>mkOption</literal> + declaration, but it is important that extensible option declarations only + use the <literal>type</literal> argument. + </para> + + <para> + Extensible option types work with any of the composed variants of + <literal>enum</literal> such as <literal>with types; nullOr (enum [ "foo" + "bar" ])</literal> or <literal>with types; listOf (enum [ "foo" "bar" + ])</literal>. + </para> + </section> </section> diff --git a/nixos/doc/manual/development/option-def.xml b/nixos/doc/manual/development/option-def.xml index 4e267ecfd1e3..580a5afd58cd 100644 --- a/nixos/doc/manual/development/option-def.xml +++ b/nixos/doc/manual/development/option-def.xml @@ -3,39 +3,36 @@ xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="sec-option-definitions"> + <title>Option Definitions</title> -<title>Option Definitions</title> - -<para>Option definitions are generally straight-forward bindings of values to option names, like - + <para> + Option definitions are generally straight-forward bindings of values to + option names, like <programlisting> config = { services.httpd.enable = true; }; </programlisting> - -However, sometimes you need to wrap an option definition or set of -option definitions in a <emphasis>property</emphasis> to achieve -certain effects:</para> - -<simplesect><title>Delaying Conditionals</title> - -<para>If a set of option definitions is conditional on the value of -another option, you may need to use <varname>mkIf</varname>. -Consider, for instance: - + However, sometimes you need to wrap an option definition or set of option + definitions in a <emphasis>property</emphasis> to achieve certain effects: + </para> + + <simplesect> + <title>Delaying Conditionals</title> + <para> + If a set of option definitions is conditional on the value of another + option, you may need to use <varname>mkIf</varname>. Consider, for instance: <programlisting> config = if config.services.httpd.enable then { environment.systemPackages = [ <replaceable>...</replaceable> ]; <replaceable>...</replaceable> } else {}; </programlisting> - -This definition will cause Nix to fail with an “infinite recursion” -error. Why? Because the value of -<option>config.services.httpd.enable</option> depends on the value -being constructed here. After all, you could also write the clearly -circular and contradictory: + This definition will cause Nix to fail with an “infinite recursion” + error. Why? Because the value of + <option>config.services.httpd.enable</option> depends on the value being + constructed here. After all, you could also write the clearly circular and + contradictory: <programlisting> config = if config.services.httpd.enable then { services.httpd.enable = false; @@ -43,56 +40,49 @@ config = if config.services.httpd.enable then { services.httpd.enable = true; }; </programlisting> - -The solution is to write: - + The solution is to write: <programlisting> config = mkIf config.services.httpd.enable { environment.systemPackages = [ <replaceable>...</replaceable> ]; <replaceable>...</replaceable> }; </programlisting> - -The special function <varname>mkIf</varname> causes the evaluation of -the conditional to be “pushed down” into the individual definitions, -as if you had written: - + The special function <varname>mkIf</varname> causes the evaluation of the + conditional to be “pushed down” into the individual definitions, as if + you had written: <programlisting> config = { environment.systemPackages = if config.services.httpd.enable then [ <replaceable>...</replaceable> ] else []; <replaceable>...</replaceable> }; </programlisting> - -</para> - -</simplesect> - -<simplesect><title>Setting Priorities</title> - -<para>A module can override the definitions of an option in other -modules by setting a <emphasis>priority</emphasis>. All option -definitions that do not have the lowest priority value are discarded. -By default, option definitions have priority 1000. You can specify an -explicit priority by using <varname>mkOverride</varname>, e.g. - + </para> + </simplesect> + + <simplesect> + <title>Setting Priorities</title> + <para> + A module can override the definitions of an option in other modules by + setting a <emphasis>priority</emphasis>. All option definitions that do not + have the lowest priority value are discarded. By default, option definitions + have priority 1000. You can specify an explicit priority by using + <varname>mkOverride</varname>, e.g. <programlisting> services.openssh.enable = mkOverride 10 false; </programlisting> - -This definition causes all other definitions with priorities above 10 -to be discarded. The function <varname>mkForce</varname> is -equal to <varname>mkOverride 50</varname>.</para> - -</simplesect> - -<simplesect><title>Merging Configurations</title> - -<para>In conjunction with <literal>mkIf</literal>, it is sometimes -useful for a module to return multiple sets of option definitions, to -be merged together as if they were declared in separate modules. This -can be done using <varname>mkMerge</varname>: - + This definition causes all other definitions with priorities above 10 to be + discarded. The function <varname>mkForce</varname> is equal to + <varname>mkOverride 50</varname>. + </para> + </simplesect> + + <simplesect> + <title>Merging Configurations</title> + <para> + In conjunction with <literal>mkIf</literal>, it is sometimes useful for a + module to return multiple sets of option definitions, to be merged together + as if they were declared in separate modules. This can be done using + <varname>mkMerge</varname>: <programlisting> config = mkMerge [ # Unconditional stuff. @@ -104,9 +94,6 @@ config = mkMerge }) ]; </programlisting> - -</para> - -</simplesect> - -</section> \ No newline at end of file + </para> + </simplesect> +</section> diff --git a/nixos/doc/manual/development/option-types.xml b/nixos/doc/manual/development/option-types.xml new file mode 100644 index 000000000000..47dd09158e91 --- /dev/null +++ b/nixos/doc/manual/development/option-types.xml @@ -0,0 +1,770 @@ +<section xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-option-types"> + <title>Options Types</title> + + <para> + Option types are a way to put constraints on the values a module option can + take. Types are also responsible of how values are merged in case of multiple + value definitions. + </para> + + <section> + <title>Basic Types</title> + + <para> + Basic types are the simplest available types in the module system. Basic + types include multiple string types that mainly differ in how definition + merging is handled. + </para> + + <variablelist> + <varlistentry> + <term> + <varname>types.attrs</varname> + </term> + <listitem> + <para> + A free-form attribute set. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>types.bool</varname> + </term> + <listitem> + <para> + A boolean, its values can be <literal>true</literal> or + <literal>false</literal>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>types.path</varname> + </term> + <listitem> + <para> + A filesystem path, defined as anything that when coerced to a string + starts with a slash. Even if derivations can be considered as path, the + more specific <literal>types.package</literal> should be preferred. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>types.package</varname> + </term> + <listitem> + <para> + A derivation or a store path. + </para> + </listitem> + </varlistentry> + </variablelist> + + <para> + Integer-related types: + </para> + + <variablelist> + <varlistentry> + <term> + <varname>types.int</varname> + </term> + <listitem> + <para> + A signed integer. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>types.ints.{s8, s16, s32}</varname> + </term> + <listitem> + <para> + Signed integers with a fixed length (8, 16 or 32 bits). They go from + <inlineequation><mathphrase>−2<superscript>n</superscript>/2</mathphrase> + </inlineequation> to <inlineequation> + <mathphrase>2<superscript>n</superscript>/2−1</mathphrase> + </inlineequation> respectively (e.g. <literal>−128</literal> to + <literal>127</literal> for 8 bits). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>types.ints.unsigned</varname> + </term> + <listitem> + <para> + An unsigned integer (that is >= 0). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>types.ints.{u8, u16, u32}</varname> + </term> + <listitem> + <para> + Unsigned integers with a fixed length (8, 16 or 32 bits). They go from + <inlineequation><mathphrase>0</mathphrase></inlineequation> to + <inlineequation> + <mathphrase>2<superscript>n</superscript>−1</mathphrase> + </inlineequation> respectively (e.g. <literal>0</literal> to + <literal>255</literal> for 8 bits). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>types.ints.positive</varname> + </term> + <listitem> + <para> + A positive integer (that is > 0). + </para> + </listitem> + </varlistentry> + </variablelist> + + <para> + String-related types: + </para> + + <variablelist> + <varlistentry> + <term> + <varname>types.str</varname> + </term> + <listitem> + <para> + A string. Multiple definitions cannot be merged. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>types.lines</varname> + </term> + <listitem> + <para> + A string. Multiple definitions are concatenated with a new line + <literal>"\n"</literal>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>types.commas</varname> + </term> + <listitem> + <para> + A string. Multiple definitions are concatenated with a comma + <literal>","</literal>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>types.envVar</varname> + </term> + <listitem> + <para> + A string. Multiple definitions are concatenated with a collon + <literal>":"</literal>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>types.strMatching</varname> + </term> + <listitem> + <para> + A string matching a specific regular expression. Multiple definitions + cannot be merged. The regular expression is processed using + <literal>builtins.match</literal>. + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + + <section> + <title>Value Types</title> + + <para> + Value types are types that take a value parameter. + </para> + + <variablelist> + <varlistentry> + <term> + <varname>types.enum</varname> <replaceable>l</replaceable> + </term> + <listitem> + <para> + One element of the list <replaceable>l</replaceable>, e.g. + <literal>types.enum [ "left" "right" ]</literal>. Multiple definitions + cannot be merged. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>types.separatedString</varname> <replaceable>sep</replaceable> + </term> + <listitem> + <para> + A string with a custom separator <replaceable>sep</replaceable>, e.g. + <literal>types.separatedString "|"</literal>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>types.ints.between</varname> <replaceable>lowest</replaceable> <replaceable>highest</replaceable> + </term> + <listitem> + <para> + An integer between <replaceable>lowest</replaceable> and + <replaceable>highest</replaceable> (both inclusive). Useful for creating + types like <literal>types.port</literal>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>types.submodule</varname> <replaceable>o</replaceable> + </term> + <listitem> + <para> + A set of sub options <replaceable>o</replaceable>. + <replaceable>o</replaceable> can be an attribute set or a function + returning an attribute set. Submodules are used in composed types to + create modular options. Submodule are detailed in + <xref + linkend='section-option-types-submodule' />. + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + + <section> + <title>Composed Types</title> + + <para> + Composed types are types that take a type as parameter. <literal>listOf + int</literal> and <literal>either int str</literal> are examples of composed + types. + </para> + + <variablelist> + <varlistentry> + <term> + <varname>types.listOf</varname> <replaceable>t</replaceable> + </term> + <listitem> + <para> + A list of <replaceable>t</replaceable> type, e.g. <literal>types.listOf + int</literal>. Multiple definitions are merged with list concatenation. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>types.attrsOf</varname> <replaceable>t</replaceable> + </term> + <listitem> + <para> + An attribute set of where all the values are of + <replaceable>t</replaceable> type. Multiple definitions result in the + joined attribute set. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>types.loaOf</varname> <replaceable>t</replaceable> + </term> + <listitem> + <para> + An attribute set or a list of <replaceable>t</replaceable> type. Multiple + definitions are merged according to the value. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>types.nullOr</varname> <replaceable>t</replaceable> + </term> + <listitem> + <para> + <literal>null</literal> or type <replaceable>t</replaceable>. Multiple + definitions are merged according to type <replaceable>t</replaceable>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>types.uniq</varname> <replaceable>t</replaceable> + </term> + <listitem> + <para> + Ensures that type <replaceable>t</replaceable> cannot be merged. It is + used to ensure option definitions are declared only once. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>types.either</varname> <replaceable>t1</replaceable> <replaceable>t2</replaceable> + </term> + <listitem> + <para> + Type <replaceable>t1</replaceable> or type <replaceable>t2</replaceable>, + e.g. <literal>with types; either int str</literal>. Multiple definitions + cannot be merged. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>types.coercedTo</varname> <replaceable>from</replaceable> <replaceable>f</replaceable> <replaceable>to</replaceable> + </term> + <listitem> + <para> + Type <replaceable>to</replaceable> or type + <replaceable>from</replaceable> which will be coerced to type + <replaceable>to</replaceable> using function <replaceable>f</replaceable> + which takes an argument of type <replaceable>from</replaceable> and + return a value of type <replaceable>to</replaceable>. Can be used to + preserve backwards compatibility of an option if its type was changed. + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + + <section xml:id='section-option-types-submodule'> + <title>Submodule</title> + + <para> + <literal>submodule</literal> is a very powerful type that defines a set of + sub-options that are handled like a separate module. + </para> + + <para> + It takes a parameter <replaceable>o</replaceable>, that should be a set, or + a function returning a set with an <literal>options</literal> key defining + the sub-options. Submodule option definitions are type-checked accordingly + to the <literal>options</literal> declarations. Of course, you can nest + submodule option definitons for even higher modularity. + </para> + + <para> + The option set can be defined directly + (<xref linkend='ex-submodule-direct' />) or as reference + (<xref linkend='ex-submodule-reference' />). + </para> + + <example xml:id='ex-submodule-direct'> + <title>Directly defined submodule</title> +<screen> +options.mod = mkOption { + description = "submodule example"; + type = with types; submodule { + options = { + foo = mkOption { + type = int; + }; + bar = mkOption { + type = str; + }; + }; + }; +};</screen> + </example> + + <example xml:id='ex-submodule-reference'> + <title>Submodule defined as a reference</title> +<screen> +let + modOptions = { + options = { + foo = mkOption { + type = int; + }; + bar = mkOption { + type = int; + }; + }; + }; +in +options.mod = mkOption { + description = "submodule example"; + type = with types; submodule modOptions; +};</screen> + </example> + + <para> + The <literal>submodule</literal> type is especially interesting when used + with composed types like <literal>attrsOf</literal> or + <literal>listOf</literal>. When composed with <literal>listOf</literal> + (<xref linkend='ex-submodule-listof-declaration' />), + <literal>submodule</literal> allows multiple definitions of the submodule + option set (<xref linkend='ex-submodule-listof-definition' />). + </para> + + <example xml:id='ex-submodule-listof-declaration'> + <title>Declaration of a list of submodules</title> +<screen> +options.mod = mkOption { + description = "submodule example"; + type = with types; listOf (submodule { + options = { + foo = mkOption { + type = int; + }; + bar = mkOption { + type = str; + }; + }; + }); +};</screen> + </example> + + <example xml:id='ex-submodule-listof-definition'> + <title>Definition of a list of submodules</title> +<screen> +config.mod = [ + { foo = 1; bar = "one"; } + { foo = 2; bar = "two"; } +];</screen> + </example> + + <para> + When composed with <literal>attrsOf</literal> + (<xref linkend='ex-submodule-attrsof-declaration' />), + <literal>submodule</literal> allows multiple named definitions of the + submodule option set (<xref linkend='ex-submodule-attrsof-definition' />). + </para> + + <example xml:id='ex-submodule-attrsof-declaration'> + <title>Declaration of attribute sets of submodules</title> +<screen> +options.mod = mkOption { + description = "submodule example"; + type = with types; attrsOf (submodule { + options = { + foo = mkOption { + type = int; + }; + bar = mkOption { + type = str; + }; + }; + }); +};</screen> + </example> + + <example xml:id='ex-submodule-attrsof-definition'> + <title>Declaration of attribute sets of submodules</title> +<screen> +config.mod.one = { foo = 1; bar = "one"; }; +config.mod.two = { foo = 2; bar = "two"; };</screen> + </example> + </section> + + <section> + <title>Extending types</title> + + <para> + Types are mainly characterized by their <literal>check</literal> and + <literal>merge</literal> functions. + </para> + + <variablelist> + <varlistentry> + <term> + <varname>check</varname> + </term> + <listitem> + <para> + The function to type check the value. Takes a value as parameter and + return a boolean. It is possible to extend a type check with the + <literal>addCheck</literal> function + (<xref + linkend='ex-extending-type-check-1' />), or to fully + override the check function + (<xref linkend='ex-extending-type-check-2' />). + </para> + <example xml:id='ex-extending-type-check-1'> + <title>Adding a type check</title> +<screen> +byte = mkOption { + description = "An integer between 0 and 255."; + type = addCheck types.int (x: x >= 0 && x <= 255); +};</screen> + </example> + <example xml:id='ex-extending-type-check-2'> + <title>Overriding a type check</title> +<screen> +nixThings = mkOption { + description = "words that start with 'nix'"; + type = types.str // { + check = (x: lib.hasPrefix "nix" x) + }; +};</screen> + </example> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>merge</varname> + </term> + <listitem> + <para> + Function to merge the options values when multiple values are set. The + function takes two parameters, <literal>loc</literal> the option path as + a list of strings, and <literal>defs</literal> the list of defined values + as a list. It is possible to override a type merge function for custom + needs. + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + + <section> + <title>Custom Types</title> + + <para> + Custom types can be created with the <literal>mkOptionType</literal> + function. As type creation includes some more complex topics such as + submodule handling, it is recommended to get familiar with + <filename + xlink:href="https://github.com/NixOS/nixpkgs/blob/master/lib/types.nix">types.nix</filename> + code before creating a new type. + </para> + + <para> + The only required parameter is <literal>name</literal>. + </para> + + <variablelist> + <varlistentry> + <term> + <varname>name</varname> + </term> + <listitem> + <para> + A string representation of the type function name. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>definition</varname> + </term> + <listitem> + <para> + Description of the type used in documentation. Give information of the + type and any of its arguments. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>check</varname> + </term> + <listitem> + <para> + A function to type check the definition value. Takes the definition value + as a parameter and returns a boolean indicating the type check result, + <literal>true</literal> for success and <literal>false</literal> for + failure. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>merge</varname> + </term> + <listitem> + <para> + A function to merge multiple definitions values. Takes two parameters: + </para> + <variablelist> + <varlistentry> + <term> + <replaceable>loc</replaceable> + </term> + <listitem> + <para> + The option path as a list of strings, e.g. <literal>["boot" "loader + "grub" "enable"]</literal>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <replaceable>defs</replaceable> + </term> + <listitem> + <para> + The list of sets of defined <literal>value</literal> and + <literal>file</literal> where the value was defined, e.g. <literal>[ { + file = "/foo.nix"; value = 1; } { file = "/bar.nix"; value = 2 } + ]</literal>. The <literal>merge</literal> function should return the + merged value or throw an error in case the values are impossible or + not meant to be merged. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>getSubOptions</varname> + </term> + <listitem> + <para> + For composed types that can take a submodule as type parameter, this + function generate sub-options documentation. It takes the current option + prefix as a list and return the set of sub-options. Usually defined in a + recursive manner by adding a term to the prefix, e.g. <literal>prefix: + elemType.getSubOptions (prefix ++ + [<replaceable>"prefix"</replaceable>])</literal> where + <replaceable>"prefix"</replaceable> is the newly added prefix. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>getSubModules</varname> + </term> + <listitem> + <para> + For composed types that can take a submodule as type parameter, this + function should return the type parameters submodules. If the type + parameter is called <literal>elemType</literal>, the function should just + recursively look into submodules by returning + <literal>elemType.getSubModules;</literal>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>substSubModules</varname> + </term> + <listitem> + <para> + For composed types that can take a submodule as type parameter, this + function can be used to substitute the parameter of a submodule type. It + takes a module as parameter and return the type with the submodule + options substituted. It is usually defined as a type function call with a + recursive call to <literal>substSubModules</literal>, e.g for a type + <literal>composedType</literal> that take an <literal>elemtype</literal> + type parameter, this function should be defined as <literal>m: + composedType (elemType.substSubModules m)</literal>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>typeMerge</varname> + </term> + <listitem> + <para> + A function to merge multiple type declarations. Takes the type to merge + <literal>functor</literal> as parameter. A <literal>null</literal> return + value means that type cannot be merged. + </para> + <variablelist> + <varlistentry> + <term> + <replaceable>f</replaceable> + </term> + <listitem> + <para> + The type to merge <literal>functor</literal>. + </para> + </listitem> + </varlistentry> + </variablelist> + <para> + Note: There is a generic <literal>defaultTypeMerge</literal> that work + with most of value and composed types. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>functor</varname> + </term> + <listitem> + <para> + An attribute set representing the type. It is used for type operations + and has the following keys: + </para> + <variablelist> + <varlistentry> + <term> + <varname>type</varname> + </term> + <listitem> + <para> + The type function. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>wrapped</varname> + </term> + <listitem> + <para> + Holds the type parameter for composed types. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>payload</varname> + </term> + <listitem> + <para> + Holds the value parameter for value types. The types that have a + <literal>payload</literal> are the <literal>enum</literal>, + <literal>separatedString</literal> and <literal>submodule</literal> + types. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>binOp</varname> + </term> + <listitem> + <para> + A binary operation that can merge the payloads of two same types. + Defined as a function that take two payloads as parameters and return + the payloads merged. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + </variablelist> + </section> +</section> diff --git a/nixos/doc/manual/development/releases.xml b/nixos/doc/manual/development/releases.xml new file mode 100755 index 000000000000..863110a1c7ca --- /dev/null +++ b/nixos/doc/manual/development/releases.xml @@ -0,0 +1,260 @@ +<chapter xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="ch-releases"> + <title>Releases</title> + <section xml:id="release-process"> + <title>Release process</title> + + <para> + Going through an example of releasing NixOS 17.09: + </para> + + <section xml:id="one-month-before-the-beta"> + <title>One month before the beta</title> + + <itemizedlist spacing="compact"> + <listitem> + <para> + Send an email to the nix-devel mailinglist as a warning about upcoming + beta "feature freeze" in a month. + </para> + </listitem> + <listitem> + <para> + Discuss with Eelco Dolstra and the community (via IRC, ML) about what + will reach the deadline. Any issue or Pull Request targeting the release + should be included in the release milestone. + </para> + </listitem> + </itemizedlist> + </section> + + <section xml:id="at-beta-release-time"> + <title>At beta release time</title> + + <itemizedlist spacing="compact"> + <listitem> + <para> + <link xlink:href="https://github.com/NixOS/nixpkgs/issues/13559">Create + an issue for tracking Zero Hydra Failures progress. ZHF is an effort to + get build failures down to zero.</link> + </para> + </listitem> + <listitem> + <para> + <literal>git tag -a -s -m "Release 17.09-beta" 17.09-beta + && git push --tags</literal> + </para> + </listitem> + <listitem> + <para> + From the master branch run <literal>git checkout -B + release-17.09</literal>. + </para> + </listitem> + <listitem> + <para> + <link xlink:href="https://github.com/NixOS/nixos-org-configurations/pull/18"> + Make sure a channel is created at http://nixos.org/channels/. </link> + </para> + </listitem> + <listitem> + <para> + <link xlink:href="https://github.com/NixOS/nixpkgs/settings/branches"> + Let a GitHub nixpkgs admin lock the branch on github for you. (so + developers can’t force push) </link> + </para> + </listitem> + <listitem> + <para> + <link xlink:href="https://github.com/NixOS/nixpkgs/compare/bdf161ed8d21...6b63c4616790"> + Bump the <literal>system.nixos.defaultChannel</literal> attribute in + <literal>nixos/modules/misc/version.nix</literal> </link> + </para> + </listitem> + <listitem> + <para> + <link xlink:href="https://github.com/NixOS/nixpkgs/commit/d6b08acd1ccac0d9d502c4b635e00b04d3387f06"> + Update <literal>versionSuffix</literal> in + <literal>nixos/release.nix</literal></link>, use <literal>git log + --format=%an|wc -l</literal> to get the commit count + </para> + </listitem> + <listitem> + <para> + <literal>echo -n "18.03" > .version</literal> on master. + </para> + </listitem> + <listitem> + <para> + <link xlink:href="https://github.com/NixOS/nixpkgs/commit/b8a4095003e27659092892a4708bb3698231a842"> + Pick a new name for the unstable branch. </link> + </para> + </listitem> + <listitem> + <para> + Create a new release notes file for the upcoming release + 1, in this + case <literal>rl-1803.xml</literal>. + </para> + </listitem> + <listitem> + <para> + Create two Hydra jobsets: release-17.09 and release-17.09-small with + <literal>stableBranch</literal> set to false. + </para> + </listitem> + <listitem> + <para> + Edit changelog at + <literal>nixos/doc/manual/release-notes/rl-1709.xml</literal> (double + check desktop versions are noted) + </para> + <itemizedlist spacing="compact"> + <listitem> + <para> + Get all new NixOS modules <literal>git diff + release-17.03..release-17.09 nixos/modules/module-list.nix|grep + ^+</literal> + </para> + </listitem> + <listitem> + <para> + Note systemd, kernel, glibc and Nix upgrades. + </para> + </listitem> + </itemizedlist> + </listitem> + </itemizedlist> + </section> + + <section xml:id="during-beta"> + <title>During Beta</title> + + <itemizedlist spacing="compact"> + <listitem> + <para> + Monitor the master branch for bugfixes and minor updates and cherry-pick + them to the release branch. + </para> + </listitem> + </itemizedlist> + </section> + + <section xml:id="before-the-final-release"> + <title>Before the final release</title> + + <itemizedlist spacing="compact"> + <listitem> + <para> + Re-check that the release notes are complete. + </para> + </listitem> + <listitem> + <para> + Release Nix (currently only Eelco Dolstra can do that). + <link xlink:href="https://github.com/NixOS/nixpkgs/commit/53710c752a85f00658882531bc90a23a3d1287e4"> + Make sure fallback is updated. </link> + </para> + </listitem> + <listitem> + <para> + <link xlink:href="https://github.com/NixOS/nixpkgs/commit/40fd9ae3ac8048758abdcfc7d28a78b5f22fe97e"> + Update README.md with new stable NixOS version information. </link> + </para> + </listitem> + <listitem> + <para> + Change <literal>stableBranch</literal> to true and wait for channel to + update. + </para> + </listitem> + </itemizedlist> + </section> + + <section xml:id="at-final-release-time"> + <title>At final release time</title> + + <itemizedlist spacing="compact"> + <listitem> + <para> + <literal>git tag -s -a -m "Release 15.09" 15.09</literal> + </para> + </listitem> + <listitem> + <para> + Update http://nixos.org/nixos/download.html and + http://nixos.org/nixos/manual in + https://github.com/NixOS/nixos-org-configurations + </para> + </listitem> + <listitem> + <para> + Get number of commits for the release: <literal>git log + release-14.04..release-14.12 --format=%an|wc -l</literal> + </para> + </listitem> + <listitem> + <para> + Commits by contributor: <literal>git log release-14.04..release-14.12 + --format=%an|sort|uniq -c|sort -rn</literal> + </para> + </listitem> + <listitem> + <para> + Send an email to nix-dev to announce the release with above information. + Best to check how previous email was formulated to see what needs to be + included. + </para> + </listitem> + </itemizedlist> + </section> + </section> + <section xml:id="release-schedule"> + <title>Release schedule</title> + + <informaltable> + <tgroup cols="2"> + <colspec align="left" /> + <colspec align="left" /> + <thead> + <row> + <entry> + Date + </entry> + <entry> + Event + </entry> + </row> + </thead> + <tbody> + <row> + <entry> + 2016-07-25 + </entry> + <entry> + Send email to nix-dev about upcoming branch-off + </entry> + </row> + <row> + <entry> + 2016-09-01 + </entry> + <entry><literal>release-16.09</literal> branch and corresponding jobsets are created, + change freeze + </entry> + </row> + <row> + <entry> + 2016-09-30 + </entry> + <entry> + NixOS 16.09 released + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </section> +</chapter> diff --git a/nixos/doc/manual/development/replace-modules.xml b/nixos/doc/manual/development/replace-modules.xml new file mode 100644 index 000000000000..7b103c36d907 --- /dev/null +++ b/nixos/doc/manual/development/replace-modules.xml @@ -0,0 +1,79 @@ +<section xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-replace-modules"> + <title>Replace Modules</title> + + <para> + Modules that are imported can also be disabled. The option declarations and + config implementation of a disabled module will be ignored, allowing another + to take it's place. This can be used to import a set of modules from another + channel while keeping the rest of the system on a stable release. + </para> + + <para> + <literal>disabledModules</literal> is a top level attribute like + <literal>imports</literal>, <literal>options</literal> and + <literal>config</literal>. It contains a list of modules that will be + disabled. This can either be the full path to the module or a string with the + filename relative to the modules path (eg. <nixpkgs/nixos/modules> for + nixos). + </para> + + <para> + This example will replace the existing postgresql module with the version + defined in the nixos-unstable channel while keeping the rest of the modules + and packages from the original nixos channel. This only overrides the module + definition, this won't use postgresql from nixos-unstable unless explicitly + configured to do so. + </para> + +<programlisting> +{ config, lib, pkgs, ... }: + +{ + disabledModules = [ "services/databases/postgresql.nix" ]; + + imports = + [ # Use postgresql service from nixos-unstable channel. + # sudo nix-channel --add http://nixos.org/channels/nixos-unstable nixos-unstable + <nixos-unstable/nixos/modules/services/databases/postgresql.nix> + ]; + + services.postgresql.enable = true; +} +</programlisting> + + <para> + This example shows how to define a custom module as a replacement for an + existing module. Importing this module will disable the original module + without having to know it's implementation details. + </para> + +<programlisting> +{ config, lib, pkgs, ... }: + +with lib; + +let + cfg = config.programs.man; +in + +{ + disabledModules = [ "services/programs/man.nix" ]; + + options = { + programs.man.enable = mkOption { + type = types.bool; + default = true; + description = "Whether to enable manual pages."; + }; + }; + + config = mkIf cfg.enabled { + warnings = [ "disabled manpages for production deployments." ]; + }; +} +</programlisting> +</section> diff --git a/nixos/doc/manual/development/running-nixos-tests-interactively.xml b/nixos/doc/manual/development/running-nixos-tests-interactively.xml index e47490777815..862b364a6d79 100644 --- a/nixos/doc/manual/development/running-nixos-tests-interactively.xml +++ b/nixos/doc/manual/development/running-nixos-tests-interactively.xml @@ -3,41 +3,38 @@ xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="sec-running-nixos-tests"> -<title>Running Tests interactively</title> - -<para>The test itself can be run interactively. This is -particularly useful when developing or debugging a test: + <title>Running Tests interactively</title> + <para> + The test itself can be run interactively. This is particularly useful when + developing or debugging a test: <screen> $ nix-build nixos/tests/login.nix -A driver $ ./result/bin/nixos-test-driver starting VDE switch for network 1 > </screen> - -You can then take any Perl statement, e.g. - + You can then take any Perl statement, e.g. <screen> > startAll > testScript > $machine->succeed("touch /tmp/foo") </screen> - -The function <command>testScript</command> executes the entire test -script and drops you back into the test driver command line upon its -completion. This allows you to inspect the state of the VMs after the -test (e.g. to debug the test script).</para> - -<para>To just start and experiment with the VMs, run: - + The function <command>testScript</command> executes the entire test script + and drops you back into the test driver command line upon its completion. + This allows you to inspect the state of the VMs after the test (e.g. to debug + the test script). + </para> + + <para> + To just start and experiment with the VMs, run: <screen> $ nix-build nixos/tests/login.nix -A driver $ ./result/bin/nixos-run-vms </screen> - -The script <command>nixos-run-vms</command> starts the virtual -machines defined by test. The root file system of the VMs is created -on the fly and kept across VM restarts in -<filename>./</filename><varname>hostname</varname><filename>.qcow2</filename>.</para> - + The script <command>nixos-run-vms</command> starts the virtual machines + defined by test. The root file system of the VMs is created on the fly and + kept across VM restarts in + <filename>./</filename><varname>hostname</varname><filename>.qcow2</filename>. + </para> </section> diff --git a/nixos/doc/manual/development/running-nixos-tests.xml b/nixos/doc/manual/development/running-nixos-tests.xml index 908c0a66a32d..eadbe1ea4f26 100644 --- a/nixos/doc/manual/development/running-nixos-tests.xml +++ b/nixos/doc/manual/development/running-nixos-tests.xml @@ -3,20 +3,18 @@ xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="sec-running-nixos-tests-interactively"> + <title>Running Tests</title> -<title>Running Tests</title> - -<para>You can run tests using <command>nix-build</command>. For -example, to run the test <filename + <para> + You can run tests using <command>nix-build</command>. For example, to run the + test + <filename xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/login.nix">login.nix</filename>, -you just do: - + you just do: <screen> $ nix-build '<nixpkgs/nixos/tests/login.nix>' </screen> - -or, if you don’t want to rely on <envar>NIX_PATH</envar>: - + or, if you don’t want to rely on <envar>NIX_PATH</envar>: <screen> $ cd /my/nixpkgs/nixos/tests $ nix-build login.nix @@ -26,16 +24,13 @@ machine: QEMU running (pid 8841) … 6 out of 6 tests succeeded </screen> - -After building/downloading all required dependencies, this will -perform a build that starts a QEMU/KVM virtual machine containing a -NixOS system. The virtual machine mounts the Nix store of the host; -this makes VM creation very fast, as no disk image needs to be -created. Afterwards, you can view a pretty-printed log of the test: - + After building/downloading all required dependencies, this will perform a + build that starts a QEMU/KVM virtual machine containing a NixOS system. The + virtual machine mounts the Nix store of the host; this makes VM creation very + fast, as no disk image needs to be created. Afterwards, you can view a + pretty-printed log of the test: <screen> $ firefox result/log.html </screen> - -</para> + </para> </section> diff --git a/nixos/doc/manual/development/sources.xml b/nixos/doc/manual/development/sources.xml index 879a31e32c59..c7b64cb84beb 100644 --- a/nixos/doc/manual/development/sources.xml +++ b/nixos/doc/manual/development/sources.xml @@ -3,107 +3,84 @@ xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="sec-getting-sources"> - -<title>Getting the Sources</title> - -<para>By default, NixOS’s <command>nixos-rebuild</command> command -uses the NixOS and Nixpkgs sources provided by the -<literal>nixos-unstable</literal> channel (kept in -<filename>/nix/var/nix/profiles/per-user/root/channels/nixos</filename>). -To modify NixOS, however, you should check out the latest sources from -Git. This is done using the following command: - -<screen> -$ nixos-checkout <replaceable>/my/sources</replaceable> -</screen> - -or - + <title>Getting the Sources</title> + <para> + By default, NixOS’s <command>nixos-rebuild</command> command uses the NixOS + and Nixpkgs sources provided by the <literal>nixos</literal> channel (kept in + <filename>/nix/var/nix/profiles/per-user/root/channels/nixos</filename>). To + modify NixOS, however, you should check out the latest sources from Git. This + is as follows: <screen> -$ mkdir -p <replaceable>/my/sources</replaceable> -$ cd <replaceable>/my/sources</replaceable> -$ nix-env -i git $ git clone git://github.com/NixOS/nixpkgs.git $ cd nixpkgs $ git remote add channels git://github.com/NixOS/nixpkgs-channels.git $ git remote update channels </screen> - -This will check out the latest NixOS sources to -<filename><replaceable>/my/sources</replaceable>/nixpkgs/nixos</filename> -and the Nixpkgs sources to -<filename><replaceable>/my/sources</replaceable>/nixpkgs</filename>. -(The NixOS source tree lives in a subdirectory of the Nixpkgs -repository.) The remote <literal>channels</literal> refers to a -read-only repository that tracks the Nixpkgs/NixOS channels (see <xref -linkend="sec-upgrading"/> for more information about channels). Thus, -the Git branch <literal>channels/nixos-14.12</literal> will contain -the latest built and tested version available in the -<literal>nixos-14.12</literal> channel.</para> - -<para>It’s often inconvenient to develop directly on the master -branch, since if somebody has just committed (say) a change to GCC, -then the binary cache may not have caught up yet and you’ll have to -rebuild everything from source. So you may want to create a local -branch based on your current NixOS version: - + This will check out the latest Nixpkgs sources to + <filename>./nixpkgs</filename> the NixOS sources to + <filename>./nixpkgs/nixos</filename>. (The NixOS source tree lives in a + subdirectory of the Nixpkgs repository.) The remote + <literal>channels</literal> refers to a read-only repository that tracks the + Nixpkgs/NixOS channels (see <xref linkend="sec-upgrading"/> for more + information about channels). Thus, the Git branch + <literal>channels/nixos-17.03</literal> will contain the latest built and + tested version available in the <literal>nixos-17.03</literal> channel. + </para> + <para> + It’s often inconvenient to develop directly on the master branch, since if + somebody has just committed (say) a change to GCC, then the binary cache may + not have caught up yet and you’ll have to rebuild everything from source. + So you may want to create a local branch based on your current NixOS version: <screen> $ nixos-version -14.04.273.ea1952b (Baboon) +17.09pre104379.6e0b727 (Hummingbird) -$ git checkout -b local ea1952b +$ git checkout -b local 6e0b727 </screen> - -Or, to base your local branch on the latest version available in a -NixOS channel: - + Or, to base your local branch on the latest version available in a NixOS + channel: <screen> $ git remote update channels -$ git checkout -b local channels/nixos-14.12 +$ git checkout -b local channels/nixos-17.03 </screen> - -(Replace <literal>nixos-14.12</literal> with the name of the channel -you want to use.) You can use <command>git merge</command> or -<command>git rebase</command> to keep your local branch in sync with -the channel, e.g. - + (Replace <literal>nixos-17.03</literal> with the name of the channel you want + to use.) You can use <command>git merge</command> or <command>git + rebase</command> to keep your local branch in sync with the channel, e.g. <screen> $ git remote update channels -$ git merge channels/nixos-14.12 +$ git merge channels/nixos-17.03 </screen> - -You can use <command>git cherry-pick</command> to copy commits from -your local branch to the upstream branch.</para> - -<para>If you want to rebuild your system using your (modified) -sources, you need to tell <command>nixos-rebuild</command> about them -using the <option>-I</option> flag: - + You can use <command>git cherry-pick</command> to copy commits from your + local branch to the upstream branch. + </para> + <para> + If you want to rebuild your system using your (modified) sources, you need to + tell <command>nixos-rebuild</command> about them using the + <option>-I</option> flag: <screen> -$ nixos-rebuild switch -I nixpkgs=<replaceable>/my/sources</replaceable>/nixpkgs +# nixos-rebuild switch -I nixpkgs=<replaceable>/my/sources</replaceable>/nixpkgs </screen> - -</para> - -<para>If you want <command>nix-env</command> to use the expressions in -<replaceable>/my/sources</replaceable>, use <command>nix-env -f -<replaceable>/my/sources</replaceable>/nixpkgs</command>, or change -the default by adding a symlink in -<filename>~/.nix-defexpr</filename>: - + </para> + <para> + If you want <command>nix-env</command> to use the expressions in + <replaceable>/my/sources</replaceable>, use <command>nix-env -f + <replaceable>/my/sources</replaceable>/nixpkgs</command>, or change the + default by adding a symlink in <filename>~/.nix-defexpr</filename>: <screen> $ ln -s <replaceable>/my/sources</replaceable>/nixpkgs ~/.nix-defexpr/nixpkgs </screen> - -You may want to delete the symlink -<filename>~/.nix-defexpr/channels_root</filename> to prevent root’s -NixOS channel from clashing with your own tree.</para> - + You may want to delete the symlink + <filename>~/.nix-defexpr/channels_root</filename> to prevent root’s NixOS + channel from clashing with your own tree (this may break the + command-not-found utility though). If you want to go back to the default + state, you may just remove the <filename>~/.nix-defexpr</filename> directory + completely, log out and log in again and it should have been recreated with a + link to the root channels. + </para> <!-- FIXME: not sure what this means. <para>You should not pass the base directory <filename><replaceable>/my/sources</replaceable></filename> to <command>nix-env</command>, as it will break after interpreting expressions in <filename>nixos/</filename> as packages.</para> --> - </chapter> diff --git a/nixos/doc/manual/development/testing-installer.xml b/nixos/doc/manual/development/testing-installer.xml index 87e40e326171..63f5f3de7f4d 100644 --- a/nixos/doc/manual/development/testing-installer.xml +++ b/nixos/doc/manual/development/testing-installer.xml @@ -3,25 +3,20 @@ xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="ch-testing-installer"> - -<title>Testing the Installer</title> - -<para>Building, burning, and booting from an installation CD is rather -tedious, so here is a quick way to see if the installer works -properly: - + <title>Testing the Installer</title> + <para> + Building, burning, and booting from an installation CD is rather tedious, so + here is a quick way to see if the installer works properly: <screen> -$ nix-build -A config.system.build.nixos-install -$ mount -t tmpfs none /mnt -$ ./result/bin/nixos-install</screen> - -To start a login shell in the new NixOS installation in -<filename>/mnt</filename>: - +# mount -t tmpfs none /mnt +# nixos-generate-config --root /mnt +$ nix-build '<nixpkgs/nixos>' -A config.system.build.nixos-install +# ./result/bin/nixos-install</screen> + To start a login shell in the new NixOS installation in + <filename>/mnt</filename>: <screen> -$ ./result/bin/nixos-install --chroot +$ nix-build '<nixpkgs/nixos>' -A config.system.build.nixos-enter +# ./result/bin/nixos-enter </screen> - -</para> - -</chapter> \ No newline at end of file + </para> +</chapter> diff --git a/nixos/doc/manual/development/writing-documentation.xml b/nixos/doc/manual/development/writing-documentation.xml new file mode 100644 index 000000000000..8ecdd1c770f2 --- /dev/null +++ b/nixos/doc/manual/development/writing-documentation.xml @@ -0,0 +1,149 @@ +<chapter xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-writing-documentation"> + <title>Writing NixOS Documentation</title> + <para> + As NixOS grows, so too does the need for a catalogue and explanation of its + extensive functionality. Collecting pertinent information from disparate + sources and presenting it in an accessible style would be a worthy + contribution to the project. + </para> + <section> + <title>Building the Manual</title> + + <para> + The DocBook sources of the <xref linkend="book-nixos-manual"/> are in the + <link xlink:href="https://github.com/NixOS/nixpkgs/tree/master/nixos/doc/manual"><filename>nixos/doc/manual</filename></link> + subdirectory of the Nixpkgs repository. + </para> + + <para> + You can quickly validate your edits with <command>make</command>: + </para> + +<screen> + $ cd /path/to/nixpkgs/nixos/doc/manual + $ make +</screen> + + <para> + Once you are done making modifications to the manual, it's important to + build it before committing. You can do that as follows: + </para> + +<screen>nix-build nixos/release.nix -A manual.x86_64-linux</screen> + + <para> + When this command successfully finishes, it will tell you where the manual + got generated. The HTML will be accessible through the + <filename>result</filename> symlink at + <filename>./result/share/doc/nixos/index.html</filename>. + </para> + </section> + <section> + <title>Editing DocBook XML</title> + + <para> + For general information on how to write in DocBook, see + <link xlink:href="http://www.docbook.org/tdg5/en/html/docbook.html"> DocBook + 5: The Definitive Guide</link>. + </para> + + <para> + Emacs nXML Mode is very helpful for editing DocBook XML because it validates + the document as you write, and precisely locates errors. To use it, see + <xref linkend="sec-emacs-docbook-xml"/>. + </para> + + <para> + <link xlink:href="http://pandoc.org">Pandoc</link> can generate DocBook XML + from a multitude of formats, which makes a good starting point. + <example xml:id="ex-pandoc-xml-conv"> + <title>Pandoc invocation to convert GitHub-Flavoured MarkDown to DocBook 5 XML</title> +<screen>pandoc -f markdown_github -t docbook5 docs.md -o my-section.md</screen> + </example> + Pandoc can also quickly convert a single <filename>section.xml</filename> to + HTML, which is helpful when drafting. + </para> + + <para> + Sometimes writing valid DocBook is simply too difficult. In this case, + submit your documentation updates in a + <link + xlink:href="https://github.com/NixOS/nixpkgs/issues/new">GitHub + Issue</link> and someone will handle the conversion to XML for you. + </para> + </section> + <section> + <title>Creating a Topic</title> + + <para> + You can use an existing topic as a basis for the new topic or create a topic + from scratch. + </para> + + <para> + Keep the following guidelines in mind when you create and add a topic: + <itemizedlist> + <listitem> + <para> + The NixOS + <link xlink:href="http://www.docbook.org/tdg5/en/html/book.html"><tag>book</tag></link> + element is in <filename>nixos/doc/manual/manual.xml</filename>. It + includes several + <link xlink:href="http://www.docbook.org/tdg5/en/html/book.html"><tag>part</tag>s</link> + which are in subdirectories. + </para> + </listitem> + <listitem> + <para> + Store the topic file in the same directory as the <tag>part</tag> to + which it belongs. If your topic is about configuring a NixOS module, then + the XML file can be stored alongside the module definition + <filename>nix</filename> file. + </para> + </listitem> + <listitem> + <para> + If you include multiple words in the file name, separate the words with a + dash. For example: <filename>ipv6-config.xml</filename>. + </para> + </listitem> + <listitem> + <para> + Make sure that the <tag>xml:id</tag> value is unique. You can use + abbreviations if the ID is too long. For example: + <varname>nixos-config</varname>. + </para> + </listitem> + <listitem> + <para> + Determine whether your topic is a chapter or a section. If you are + unsure, open an existing topic file and check whether the main element is + chapter or section. + </para> + </listitem> + </itemizedlist> + </para> + </section> + <section> + <title>Adding a Topic to the Book</title> + + <para> + Open the parent XML file and add an <varname>xi:include</varname> element to + the list of chapters with the file name of the topic that you created. If + you created a <tag>section</tag>, you add the file to the <tag>chapter</tag> + file. If you created a <tag>chapter</tag>, you add the file to the + <tag>part</tag> file. + </para> + + <para> + If the topic is about configuring a NixOS module, it can be automatically + included in the manual by using the <varname>meta.doc</varname> attribute. + See <xref + linkend="sec-meta-attributes"/> for an explanation. + </para> + </section> +</chapter> diff --git a/nixos/doc/manual/development/writing-modules.xml b/nixos/doc/manual/development/writing-modules.xml index a699e74e5f62..bbf793bb0be9 100644 --- a/nixos/doc/manual/development/writing-modules.xml +++ b/nixos/doc/manual/development/writing-modules.xml @@ -3,52 +3,54 @@ xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="sec-writing-modules"> - -<title>Writing NixOS Modules</title> - -<para>NixOS has a modular system for declarative configuration. This -system combines multiple <emphasis>modules</emphasis> to produce the -full system configuration. One of the modules that constitute the -configuration is <filename>/etc/nixos/configuration.nix</filename>. -Most of the others live in the <link + <title>Writing NixOS Modules</title> + <para> + NixOS has a modular system for declarative configuration. This system + combines multiple <emphasis>modules</emphasis> to produce the full system + configuration. One of the modules that constitute the configuration is + <filename>/etc/nixos/configuration.nix</filename>. Most of the others live in + the + <link xlink:href="https://github.com/NixOS/nixpkgs/tree/master/nixos/modules"><filename>nixos/modules</filename></link> -subdirectory of the Nixpkgs tree.</para> - -<para>Each NixOS module is a file that handles one logical aspect of -the configuration, such as a specific kind of hardware, a service, or -network settings. A module configuration does not have to handle -everything from scratch; it can use the functionality provided by -other modules for its implementation. Thus a module can -<emphasis>declare</emphasis> options that can be used by other -modules, and conversely can <emphasis>define</emphasis> options -provided by other modules in its own implementation. For example, the -module <link + subdirectory of the Nixpkgs tree. + </para> + <para> + Each NixOS module is a file that handles one logical aspect of the + configuration, such as a specific kind of hardware, a service, or network + settings. A module configuration does not have to handle everything from + scratch; it can use the functionality provided by other modules for its + implementation. Thus a module can <emphasis>declare</emphasis> options that + can be used by other modules, and conversely can <emphasis>define</emphasis> + options provided by other modules in its own implementation. For example, the + module + <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/security/pam.nix"><filename>pam.nix</filename></link> -declares the option <option>security.pam.services</option> that allows -other modules (e.g. <link + declares the option <option>security.pam.services</option> that allows other + modules (e.g. + <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/services/networking/ssh/sshd.nix"><filename>sshd.nix</filename></link>) -to define PAM services; and it defines the option -<option>environment.etc</option> (declared by <link + to define PAM services; and it defines the option + <option>environment.etc</option> (declared by + <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/system/etc/etc.nix"><filename>etc.nix</filename></link>) -to cause files to be created in -<filename>/etc/pam.d</filename>.</para> - -<para xml:id="para-module-syn">In <xref + to cause files to be created in <filename>/etc/pam.d</filename>. + </para> + <para xml:id="para-module-syn"> + In <xref linkend="sec-configuration-syntax"/>, we saw the following structure -of NixOS modules: - + of NixOS modules: <programlisting> { config, pkgs, ... }: { <replaceable>option definitions</replaceable> } </programlisting> - -This is actually an <emphasis>abbreviated</emphasis> form of module -that only defines options, but does not declare any. The structure of -full NixOS modules is shown in <xref linkend='ex-module-syntax' />.</para> - -<example xml:id='ex-module-syntax'><title>Structure of NixOS Modules</title> + This is actually an <emphasis>abbreviated</emphasis> form of module that only + defines options, but does not declare any. The structure of full NixOS + modules is shown in <xref linkend='ex-module-syntax' />. + </para> + <example xml:id='ex-module-syntax'> + <title>Structure of NixOS Modules</title> <programlisting> { config, pkgs, ... }: <co xml:id='module-syntax-1' /> @@ -65,111 +67,120 @@ full NixOS modules is shown in <xref linkend='ex-module-syntax' />.</para> <replaceable>option definitions</replaceable> <co xml:id='module-syntax-4' /> }; }</programlisting> -</example> - -<para>The meaning of each part is as follows. - -<calloutlist> - <callout arearefs='module-syntax-1'> - <para>This line makes the current Nix expression a function. The - variable <varname>pkgs</varname> contains Nixpkgs, while - <varname>config</varname> contains the full system configuration. - This line can be omitted if there is no reference to - <varname>pkgs</varname> and <varname>config</varname> inside the - module.</para> - </callout> - - <callout arearefs='module-syntax-2'> - <para>This list enumerates the paths to other NixOS modules that - should be included in the evaluation of the system configuration. - A default set of modules is defined in the file - <filename>modules/module-list.nix</filename>. These don't need to - be added in the import list.</para> - </callout> - - <callout arearefs='module-syntax-3'> - <para>The attribute <varname>options</varname> is a nested set of - <emphasis>option declarations</emphasis> (described below).</para> - </callout> - - <callout arearefs='module-syntax-4'> - <para>The attribute <varname>config</varname> is a nested set of - <emphasis>option definitions</emphasis> (also described - below).</para> - </callout> -</calloutlist> - -</para> - -<para><xref linkend='locate-example' /> shows a module that handles -the regular update of the “locate” database, an index of all files in -the file system. This module declares two options that can be defined -by other modules (typically the user’s -<filename>configuration.nix</filename>): -<option>services.locate.enable</option> (whether the database should -be updated) and <option>services.locate.period</option> (when the -update should be done). It implements its functionality by defining -two options declared by other modules: -<option>systemd.services</option> (the set of all systemd services) -and <option>services.cron.systemCronJobs</option> (the list of -commands to be executed periodically by <command>cron</command>).</para> - -<example xml:id='locate-example'><title>NixOS Module for the “locate” Service</title> + </example> + <para> + The meaning of each part is as follows. + <calloutlist> + <callout arearefs='module-syntax-1'> + <para> + This line makes the current Nix expression a function. The variable + <varname>pkgs</varname> contains Nixpkgs, while <varname>config</varname> + contains the full system configuration. This line can be omitted if there + is no reference to <varname>pkgs</varname> and <varname>config</varname> + inside the module. + </para> + </callout> + <callout arearefs='module-syntax-2'> + <para> + This list enumerates the paths to other NixOS modules that should be + included in the evaluation of the system configuration. A default set of + modules is defined in the file + <filename>modules/module-list.nix</filename>. These don't need to be added + in the import list. + </para> + </callout> + <callout arearefs='module-syntax-3'> + <para> + The attribute <varname>options</varname> is a nested set of + <emphasis>option declarations</emphasis> (described below). + </para> + </callout> + <callout arearefs='module-syntax-4'> + <para> + The attribute <varname>config</varname> is a nested set of + <emphasis>option definitions</emphasis> (also described below). + </para> + </callout> + </calloutlist> + </para> + <para> + <xref linkend='locate-example' /> shows a module that handles the regular + update of the “locate” database, an index of all files in the file + system. This module declares two options that can be defined by other modules + (typically the user’s <filename>configuration.nix</filename>): + <option>services.locate.enable</option> (whether the database should be + updated) and <option>services.locate.interval</option> (when the update + should be done). It implements its functionality by defining two options + declared by other modules: <option>systemd.services</option> (the set of all + systemd services) and <option>systemd.timers</option> (the list of commands + to be executed periodically by <command>systemd</command>). + </para> + <example xml:id='locate-example'> + <title>NixOS Module for the “locate” Service</title> <programlisting> { config, lib, pkgs, ... }: with lib; -let locatedb = "/var/cache/locatedb"; in - -{ - options = { - - services.locate = { - - enable = mkOption { - type = types.bool; - default = false; - description = '' - If enabled, NixOS will periodically update the database of - files used by the <command>locate</command> command. - ''; - }; - - period = mkOption { - type = types.str; - default = "15 02 * * *"; - description = '' - This option defines (in the format used by cron) when the - locate database is updated. The default is to update at - 02:15 at night every day. - ''; - }; +let + cfg = config.services.locate; +in { + options.services.locate = { + enable = mkOption { + type = types.bool; + default = false; + description = '' + If enabled, NixOS will periodically update the database of + files used by the <command>locate</command> command. + ''; + }; + interval = mkOption { + type = types.str; + default = "02:15"; + example = "hourly"; + description = '' + Update the locate database at this interval. Updates by + default at 2:15 AM every day. + + The format is described in + <citerefentry><refentrytitle>systemd.time</refentrytitle> + <manvolnum>7</manvolnum></citerefentry>. + ''; }; + # Other options omitted for documentation }; config = { - systemd.services.update-locatedb = { description = "Update Locate Database"; path = [ pkgs.su ]; script = '' - mkdir -m 0755 -p $(dirname ${locatedb}) - exec updatedb --localuser=nobody --output=${locatedb} --prunepaths='/tmp /var/tmp /run' + 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} ''; }; - services.cron.systemCronJobs = optional config.services.locate.enable - "${config.services.locate.period} root ${config.systemd.package}/bin/systemctl start update-locatedb.service"; - + systemd.timers.update-locatedb = mkIf cfg.enable + { description = "Update timer for locate database"; + partOf = [ "update-locatedb.service" ]; + wantedBy = [ "timers.target" ]; + timerConfig.OnCalendar = cfg.interval; + }; }; -}</programlisting> -</example> - -<xi:include href="option-declarations.xml" /> -<xi:include href="option-def.xml" /> - +} +</programlisting> + </example> + <xi:include href="option-declarations.xml" /> + <xi:include href="option-types.xml" /> + <xi:include href="option-def.xml" /> + <xi:include href="assertions.xml" /> + <xi:include href="meta-attributes.xml" /> + <xi:include href="importing-modules.xml" /> + <xi:include href="replace-modules.xml" /> </chapter> diff --git a/nixos/doc/manual/development/writing-nixos-tests.xml b/nixos/doc/manual/development/writing-nixos-tests.xml index b9da712b86f0..5935fbc049bd 100644 --- a/nixos/doc/manual/development/writing-nixos-tests.xml +++ b/nixos/doc/manual/development/writing-nixos-tests.xml @@ -3,11 +3,10 @@ xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="sec-writing-nixos-tests"> + <title>Writing Tests</title> -<title>Writing Tests</title> - -<para>A NixOS test is a Nix expression that has the following structure: - + <para> + A NixOS test is a Nix expression that has the following structure: <programlisting> import ./make-test.nix { @@ -32,238 +31,391 @@ import ./make-test.nix { ''; } </programlisting> - -The attribute <literal>testScript</literal> is a bit of Perl code that -executes the test (described below). During the test, it will start -one or more virtual machines, the configuration of which is described -by the attribute <literal>machine</literal> (if you need only one -machine in your test) or by the attribute <literal>nodes</literal> (if -you need multiple machines). For instance, <filename + The attribute <literal>testScript</literal> is a bit of Perl code that + executes the test (described below). During the test, it will start one or + more virtual machines, the configuration of which is described by the + attribute <literal>machine</literal> (if you need only one machine in your + test) or by the attribute <literal>nodes</literal> (if you need multiple + machines). For instance, + <filename xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/login.nix">login.nix</filename> -only needs a single machine to test whether users can log in on the -virtual console, whether device ownership is correctly maintained when -switching between consoles, and so on. On the other hand, <filename + only needs a single machine to test whether users can log in on the virtual + console, whether device ownership is correctly maintained when switching + between consoles, and so on. On the other hand, + <filename xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/nfs.nix">nfs.nix</filename>, -which tests NFS client and server functionality in the Linux kernel -(including whether locks are maintained across server crashes), -requires three machines: a server and two clients.</para> - -<para>There are a few special NixOS configuration options for test -VMs: + which tests NFS client and server functionality in the Linux kernel + (including whether locks are maintained across server crashes), requires + three machines: a server and two clients. + </para> + <para> + There are a few special NixOS configuration options for test VMs: <!-- FIXME: would be nice to generate this automatically. --> - -<variablelist> - - <varlistentry> - <term><option>virtualisation.memorySize</option></term> - <listitem><para>The memory of the VM in - megabytes.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>virtualisation.vlans</option></term> - <listitem><para>The virtual networks to which the VM is - connected. See <filename + <variablelist> + <varlistentry> + <term> + <option>virtualisation.memorySize</option> + </term> + <listitem> + <para> + The memory of the VM in megabytes. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <option>virtualisation.vlans</option> + </term> + <listitem> + <para> + The virtual networks to which the VM is connected. See + <filename xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/nat.nix">nat.nix</filename> - for an example.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>virtualisation.writableStore</option></term> - <listitem><para>By default, the Nix store in the VM is not - writable. If you enable this option, a writable union file system - is mounted on top of the Nix store to make it appear - writable. This is necessary for tests that run Nix operations that - modify the store.</para></listitem> - </varlistentry> - -</variablelist> - -For more options, see the module <filename -xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/virtualisation/qemu-vm.nix">qemu-vm.nix</filename>.</para> - -<para>The test script is a sequence of Perl statements that perform -various actions, such as starting VMs, executing commands in the VMs, -and so on. Each virtual machine is represented as an object stored in -the variable <literal>$<replaceable>name</replaceable></literal>, -where <replaceable>name</replaceable> is the identifier of the machine -(which is just <literal>machine</literal> if you didn’t specify -multiple machines using the <literal>nodes</literal> attribute). For -instance, the following starts the machine, waits until it has -finished booting, then executes a command and checks that the output -is more-or-less correct: - + for an example. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <option>virtualisation.writableStore</option> + </term> + <listitem> + <para> + By default, the Nix store in the VM is not writable. If you enable this + option, a writable union file system is mounted on top of the Nix store + to make it appear writable. This is necessary for tests that run Nix + operations that modify the store. + </para> + </listitem> + </varlistentry> + </variablelist> + For more options, see the module + <filename +xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/virtualisation/qemu-vm.nix">qemu-vm.nix</filename>. + </para> + + <para> + The test script is a sequence of Perl statements that perform various + actions, such as starting VMs, executing commands in the VMs, and so on. Each + virtual machine is represented as an object stored in the variable + <literal>$<replaceable>name</replaceable></literal>, where + <replaceable>name</replaceable> is the identifier of the machine (which is + just <literal>machine</literal> if you didn’t specify multiple machines + using the <literal>nodes</literal> attribute). For instance, the following + starts the machine, waits until it has finished booting, then executes a + command and checks that the output is more-or-less correct: <programlisting> $machine->start; $machine->waitForUnit("default.target"); $machine->succeed("uname") =~ /Linux/; </programlisting> - -The first line is actually unnecessary; machines are implicitly -started when you first execute an action on them (such as -<literal>waitForUnit</literal> or <literal>succeed</literal>). If you -have multiple machines, you can speed up the test by starting them in -parallel: - + The first line is actually unnecessary; machines are implicitly started when + you first execute an action on them (such as <literal>waitForUnit</literal> + or <literal>succeed</literal>). If you have multiple machines, you can speed + up the test by starting them in parallel: <programlisting> startAll; </programlisting> - -</para> - -<para>The following methods are available on machine objects: - -<variablelist> - - <varlistentry> - <term><methodname>start</methodname></term> - <listitem><para>Start the virtual machine. This method is - asynchronous — it does not wait for the machine to finish - booting.</para></listitem> - </varlistentry> - - <varlistentry> - <term><methodname>shutdown</methodname></term> - <listitem><para>Shut down the machine, waiting for the VM to - exit.</para></listitem> - </varlistentry> - - <varlistentry> - <term><methodname>crash</methodname></term> - <listitem><para>Simulate a sudden power failure, by telling the VM - to exit immediately.</para></listitem> - </varlistentry> - - <varlistentry> - <term><methodname>block</methodname></term> - <listitem><para>Simulate unplugging the Ethernet cable that - connects the machine to the other machines.</para></listitem> - </varlistentry> - - <varlistentry> - <term><methodname>unblock</methodname></term> - <listitem><para>Undo the effect of - <methodname>block</methodname>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><methodname>screenshot</methodname></term> - <listitem><para>Take a picture of the display of the virtual - machine, in PNG format. The screenshot is linked from the HTML - log.</para></listitem> - </varlistentry> - - <varlistentry> - <term><methodname>getScreenText</methodname></term> - <listitem><para>Return a textual representation of what is currently - visible on the machine's screen using optical character - recognition.</para> - <note><para>This requires passing <option>enableOCR</option> to the test - attribute set.</para></note></listitem> - </varlistentry> - - <varlistentry> - <term><methodname>sendMonitorCommand</methodname></term> - <listitem><para>Send a command to the QEMU monitor. This is rarely - used, but allows doing stuff such as attaching virtual USB disks - to a running machine.</para></listitem> - </varlistentry> - - <varlistentry> - <term><methodname>sendKeys</methodname></term> - <listitem><para>Simulate pressing keys on the virtual keyboard, - e.g., <literal>sendKeys("ctrl-alt-delete")</literal>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><methodname>sendChars</methodname></term> - <listitem><para>Simulate typing a sequence of characters on the - virtual keyboard, e.g., <literal>sendKeys("foobar\n")</literal> - will type the string <literal>foobar</literal> followed by the - Enter key.</para></listitem> - </varlistentry> - - <varlistentry> - <term><methodname>execute</methodname></term> - <listitem><para>Execute a shell command, returning a list - <literal>(<replaceable>status</replaceable>, - <replaceable>stdout</replaceable>)</literal>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><methodname>succeed</methodname></term> - <listitem><para>Execute a shell command, raising an exception if - the exit status is not zero, otherwise returning the standard - output.</para></listitem> - </varlistentry> - - <varlistentry> - <term><methodname>fail</methodname></term> - <listitem><para>Like <methodname>succeed</methodname>, but raising - an exception if the command returns a zero status.</para></listitem> - </varlistentry> - - <varlistentry> - <term><methodname>waitUntilSucceeds</methodname></term> - <listitem><para>Repeat a shell command with 1-second intervals - until it succeeds.</para></listitem> - </varlistentry> - - <varlistentry> - <term><methodname>waitUntilFails</methodname></term> - <listitem><para>Repeat a shell command with 1-second intervals - until it fails.</para></listitem> - </varlistentry> - - <varlistentry> - <term><methodname>waitForUnit</methodname></term> - <listitem><para>Wait until the specified systemd unit has reached - the “active” state.</para></listitem> - </varlistentry> - - <varlistentry> - <term><methodname>waitForFile</methodname></term> - <listitem><para>Wait until the specified file - exists.</para></listitem> - </varlistentry> - - <varlistentry> - <term><methodname>waitForOpenPort</methodname></term> - <listitem><para>Wait until a process is listening on the given TCP - port (on <literal>localhost</literal>, at least).</para></listitem> - </varlistentry> - - <varlistentry> - <term><methodname>waitForClosedPort</methodname></term> - <listitem><para>Wait until nobody is listening on the given TCP - port.</para></listitem> - </varlistentry> - - <varlistentry> - <term><methodname>waitForX</methodname></term> - <listitem><para>Wait until the X11 server is accepting - connections.</para></listitem> - </varlistentry> - - <varlistentry> - <term><methodname>waitForText</methodname></term> - <listitem><para>Wait until the supplied regular expressions matches - the textual contents of the screen by using optical character recognition - (see <methodname>getScreenText</methodname>).</para> - <note><para>This requires passing <option>enableOCR</option> to the test - attribute set.</para></note></listitem> - </varlistentry> - - <varlistentry> - <term><methodname>waitForWindow</methodname></term> - <listitem><para>Wait until an X11 window has appeared whose name - matches the given regular expression, e.g., - <literal>waitForWindow(qr/Terminal/)</literal>.</para></listitem> - </varlistentry> - -</variablelist> - -</para> - -</section> \ No newline at end of file + </para> + + <para> + The following methods are available on machine objects: + <variablelist> + <varlistentry> + <term> + <methodname>start</methodname> + </term> + <listitem> + <para> + Start the virtual machine. This method is asynchronous — it does not + wait for the machine to finish booting. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <methodname>shutdown</methodname> + </term> + <listitem> + <para> + Shut down the machine, waiting for the VM to exit. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <methodname>crash</methodname> + </term> + <listitem> + <para> + Simulate a sudden power failure, by telling the VM to exit immediately. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <methodname>block</methodname> + </term> + <listitem> + <para> + Simulate unplugging the Ethernet cable that connects the machine to the + other machines. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <methodname>unblock</methodname> + </term> + <listitem> + <para> + Undo the effect of <methodname>block</methodname>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <methodname>screenshot</methodname> + </term> + <listitem> + <para> + Take a picture of the display of the virtual machine, in PNG format. The + screenshot is linked from the HTML log. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <methodname>getScreenText</methodname> + </term> + <listitem> + <para> + Return a textual representation of what is currently visible on the + machine's screen using optical character recognition. + </para> + <note> + <para> + This requires passing <option>enableOCR</option> to the test attribute + set. + </para> + </note> + </listitem> + </varlistentry> + <varlistentry> + <term> + <methodname>sendMonitorCommand</methodname> + </term> + <listitem> + <para> + Send a command to the QEMU monitor. This is rarely used, but allows doing + stuff such as attaching virtual USB disks to a running machine. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <methodname>sendKeys</methodname> + </term> + <listitem> + <para> + Simulate pressing keys on the virtual keyboard, e.g., + <literal>sendKeys("ctrl-alt-delete")</literal>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <methodname>sendChars</methodname> + </term> + <listitem> + <para> + Simulate typing a sequence of characters on the virtual keyboard, e.g., + <literal>sendKeys("foobar\n")</literal> will type the string + <literal>foobar</literal> followed by the Enter key. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <methodname>execute</methodname> + </term> + <listitem> + <para> + Execute a shell command, returning a list + <literal>(<replaceable>status</replaceable>, + <replaceable>stdout</replaceable>)</literal>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <methodname>succeed</methodname> + </term> + <listitem> + <para> + Execute a shell command, raising an exception if the exit status is not + zero, otherwise returning the standard output. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <methodname>fail</methodname> + </term> + <listitem> + <para> + Like <methodname>succeed</methodname>, but raising an exception if the + command returns a zero status. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <methodname>waitUntilSucceeds</methodname> + </term> + <listitem> + <para> + Repeat a shell command with 1-second intervals until it succeeds. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <methodname>waitUntilFails</methodname> + </term> + <listitem> + <para> + Repeat a shell command with 1-second intervals until it fails. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <methodname>waitForUnit</methodname> + </term> + <listitem> + <para> + Wait until the specified systemd unit has reached the “active” state. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <methodname>waitForFile</methodname> + </term> + <listitem> + <para> + Wait until the specified file exists. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <methodname>waitForOpenPort</methodname> + </term> + <listitem> + <para> + Wait until a process is listening on the given TCP port (on + <literal>localhost</literal>, at least). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <methodname>waitForClosedPort</methodname> + </term> + <listitem> + <para> + Wait until nobody is listening on the given TCP port. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <methodname>waitForX</methodname> + </term> + <listitem> + <para> + Wait until the X11 server is accepting connections. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <methodname>waitForText</methodname> + </term> + <listitem> + <para> + Wait until the supplied regular expressions matches the textual contents + of the screen by using optical character recognition (see + <methodname>getScreenText</methodname>). + </para> + <note> + <para> + This requires passing <option>enableOCR</option> to the test attribute + set. + </para> + </note> + </listitem> + </varlistentry> + <varlistentry> + <term> + <methodname>waitForWindow</methodname> + </term> + <listitem> + <para> + Wait until an X11 window has appeared whose name matches the given + regular expression, e.g., <literal>waitForWindow(qr/Terminal/)</literal>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <methodname>copyFileFromHost</methodname> + </term> + <listitem> + <para> + Copies a file from host to machine, e.g., + <literal>copyFileFromHost("myfile", "/etc/my/important/file")</literal>. + </para> + <para> + The first argument is the file on the host. The file needs to be + accessible while building the nix derivation. The second argument is the + location of the file on the machine. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <methodname>systemctl</methodname> + </term> + <listitem> + <para> + Runs <literal>systemctl</literal> commands with optional support for + <literal>systemctl --user</literal> + </para> + <para> +<programlisting> + $machine->systemctl("list-jobs --no-pager"); // runs `systemctl list-jobs --no-pager` + $machine->systemctl("list-jobs --no-pager", "any-user"); // spawns a shell for `any-user` and runs `systemctl --user list-jobs --no-pager` + </programlisting> + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + + <para> + To test user units declared by <literal>systemd.user.services</literal> the + optional <literal>$user</literal> argument can be used: +<programlisting> + $machine->start; + $machine->waitForX; + $machine->waitForUnit("xautolock.service", "x-session-user"); + </programlisting> + This applies to <literal>systemctl</literal>, <literal>getUnitInfo</literal>, + <literal>waitForUnit</literal>, <literal>startJob</literal> and + <literal>stopJob</literal>. + </para> +</section> diff --git a/nixos/doc/manual/installation/changing-config.xml b/nixos/doc/manual/installation/changing-config.xml index aa31742434e4..680160a3cb7e 100644 --- a/nixos/doc/manual/installation/changing-config.xml +++ b/nixos/doc/manual/installation/changing-config.xml @@ -2,89 +2,84 @@ xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="sec-changing-config"> - -<title>Changing the Configuration</title> - -<para>The file <filename>/etc/nixos/configuration.nix</filename> -contains the current configuration of your machine. Whenever you’ve -changed something to that file, you should do - + <title>Changing the Configuration</title> + <para> + The file <filename>/etc/nixos/configuration.nix</filename> contains the + current configuration of your machine. Whenever you’ve + <link linkend="ch-configuration">changed something</link> in that file, you + should do <screen> -$ nixos-rebuild switch</screen> - -to build the new configuration, make it the default configuration for -booting, and try to realise the configuration in the running system -(e.g., by restarting system services).</para> - -<warning><para>These commands must be executed as root, so you should -either run them from a root shell or by prefixing them with -<literal>sudo -i</literal>.</para></warning> - -<para>You can also do - +# nixos-rebuild switch</screen> + to build the new configuration, make it the default configuration for + booting, and try to realise the configuration in the running system (e.g., by + restarting system services). + </para> + <warning> + <para> + These commands must be executed as root, so you should either run them from + a root shell or by prefixing them with <literal>sudo -i</literal>. + </para> + </warning> + <para> + You can also do <screen> -$ nixos-rebuild test</screen> - -to build the configuration and switch the running system to it, but -without making it the boot default. So if (say) the configuration -locks up your machine, you can just reboot to get back to a working -configuration.</para> - -<para>There is also - +# nixos-rebuild test</screen> + to build the configuration and switch the running system to it, but without + making it the boot default. So if (say) the configuration locks up your + machine, you can just reboot to get back to a working configuration. + </para> + <para> + There is also <screen> -$ nixos-rebuild boot</screen> - -to build the configuration and make it the boot default, but not -switch to it now (so it will only take effect after the next -reboot).</para> - -<para>You can make your configuration show up in a different submenu -of the GRUB 2 boot screen by giving it a different <emphasis>profile -name</emphasis>, e.g. - +# nixos-rebuild boot</screen> + to build the configuration and make it the boot default, but not switch to it + now (so it will only take effect after the next reboot). + </para> + <para> + You can make your configuration show up in a different submenu of the GRUB 2 + boot screen by giving it a different <emphasis>profile name</emphasis>, e.g. <screen> -$ nixos-rebuild switch -p test </screen> - -which causes the new configuration (and previous ones created using -<literal>-p test</literal>) to show up in the GRUB submenu “NixOS - -Profile 'test'”. This can be useful to separate test configurations -from “stable” configurations.</para> - -<para>Finally, you can do - +# nixos-rebuild switch -p test </screen> + which causes the new configuration (and previous ones created using + <literal>-p test</literal>) to show up in the GRUB submenu “NixOS - Profile + 'test'”. This can be useful to separate test configurations from + “stable” configurations. + </para> + <para> + Finally, you can do <screen> $ nixos-rebuild build</screen> - -to build the configuration but nothing more. This is useful to see -whether everything compiles cleanly.</para> - -<para>If you have a machine that supports hardware virtualisation, you -can also test the new configuration in a sandbox by building and -running a QEMU <emphasis>virtual machine</emphasis> that contains the -desired configuration. Just do - + to build the configuration but nothing more. This is useful to see whether + everything compiles cleanly. + </para> + <para> + If you have a machine that supports hardware virtualisation, you can also + test the new configuration in a sandbox by building and running a QEMU + <emphasis>virtual machine</emphasis> that contains the desired configuration. + Just do <screen> $ nixos-rebuild build-vm $ ./result/bin/run-*-vm </screen> - -The VM does not have any data from your host system, so your existing -user accounts and home directories will not be available. You can -forward ports on the host to the guest. For instance, the following -will forward host port 2222 to guest port 22 (SSH): - + The VM does not have any data from your host system, so your existing user + accounts and home directories will not be available unless you have set + <literal>mutableUsers = false</literal>. Another way is to temporarily add + the following to your configuration: +<screen> +<link linkend="opt-users.users._name__.initialHashedPassword">users.extraUsers.your-user.initialHashedPassword</link> = "test"; +</screen> + <emphasis>Important:</emphasis> delete the $hostname.qcow2 file if you have + started the virtual machine at least once without the right users, otherwise + the changes will not get picked up. You can forward ports on the host to the + guest. For instance, the following will forward host port 2222 to guest port + 22 (SSH): <screen> $ QEMU_NET_OPTS="hostfwd=tcp::2222-:22" ./result/bin/run-*-vm </screen> - -allowing you to log in via SSH (assuming you have set the appropriate -passwords or SSH authorized keys): - + allowing you to log in via SSH (assuming you have set the appropriate + passwords or SSH authorized keys): <screen> $ ssh -p 2222 localhost </screen> - -</para> - + </para> </chapter> diff --git a/nixos/doc/manual/installation/installation.xml b/nixos/doc/manual/installation/installation.xml index ee61bedc4183..d4276be95d68 100644 --- a/nixos/doc/manual/installation/installation.xml +++ b/nixos/doc/manual/installation/installation.xml @@ -3,19 +3,15 @@ xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="ch-installation"> - -<title>Installation</title> - -<partintro> - -<para>This section describes how to obtain, install, and configure -NixOS for first-time use.</para> - -</partintro> - -<xi:include href="obtaining.xml" /> -<xi:include href="installing.xml" /> -<xi:include href="changing-config.xml" /> -<xi:include href="upgrading.xml" /> - + <title>Installation</title> + <partintro> + <para> + This section describes how to obtain, install, and configure NixOS for + first-time use. + </para> + </partintro> + <xi:include href="obtaining.xml" /> + <xi:include href="installing.xml" /> + <xi:include href="changing-config.xml" /> + <xi:include href="upgrading.xml" /> </part> diff --git a/nixos/doc/manual/installation/installing-from-other-distro.xml b/nixos/doc/manual/installation/installing-from-other-distro.xml new file mode 100644 index 000000000000..c55aa90267fb --- /dev/null +++ b/nixos/doc/manual/installation/installing-from-other-distro.xml @@ -0,0 +1,356 @@ +<!-- vim: set expandtab ts=2 softtabstop=2 shiftwidth=2 smarttab textwidth=80 wrapmargin=2 --> +<section + xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-installing-from-other-distro"> + <title>Installing from another Linux distribution</title> + + <para> + Because Nix (the package manager) & Nixpkgs (the Nix packages collection) + can both be installed on any (most?) Linux distributions, they can be used to + install NixOS in various creative ways. You can, for instance: + </para> + + <orderedlist> + <listitem> + <para> + Install NixOS on another partition, from your existing Linux distribution + (without the use of a USB or optical device!) + </para> + </listitem> + <listitem> + <para> + Install NixOS on the same partition (in place!), from your existing + non-NixOS Linux distribution using <literal>NIXOS_LUSTRATE</literal>. + </para> + </listitem> + <listitem> + <para> + Install NixOS on your hard drive from the Live CD of any Linux + distribution. + </para> + </listitem> + </orderedlist> + + <para> + The first steps to all these are the same: + </para> + + <orderedlist> + <listitem> + <para> + Install the Nix package manager: + </para> + <para> + Short version: + </para> +<screen> +$ curl https://nixos.org/nix/install | sh +$ . $HOME/.nix-profile/etc/profile.d/nix.sh # …or open a fresh shell</screen> + <para> + More details in the + <link + xlink:href="https://nixos.org/nix/manual/#chap-quick-start"> + Nix manual</link> + </para> + </listitem> + <listitem> + <para> + Switch to the NixOS channel: + </para> + <para> + If you've just installed Nix on a non-NixOS distribution, you will be on + the <literal>nixpkgs</literal> channel by default. + </para> +<screen> +$ nix-channel --list +nixpkgs https://nixos.org/channels/nixpkgs-unstable</screen> + <para> + As that channel gets released without running the NixOS tests, it will be + safer to use the <literal>nixos-*</literal> channels instead: + </para> +<screen> +$ nix-channel --add https://nixos.org/channels/nixos-<replaceable>version</replaceable> nixpkgs</screen> + <para> + You may want to throw in a <literal>nix-channel --update</literal> for good + measure. + </para> + </listitem> + <listitem> + <para> + Install the NixOS installation tools: + </para> + <para> + You'll need <literal>nixos-generate-config</literal> and + <literal>nixos-install</literal> and we'll throw in some man pages and + <literal>nixos-enter</literal> just in case you want to chroot into your + NixOS partition. They are installed by default on NixOS, but you don't have + NixOS yet.. + </para> +<screen>$ nix-env -iE "_: with import <nixpkgs/nixos> { configuration = {}; }; with config.system.build; [ nixos-generate-config nixos-install nixos-enter manual.manpages ]"</screen> + </listitem> + <listitem> + <note> + <para> + The following 5 steps are only for installing NixOS to another partition. + For installing NixOS in place using <literal>NIXOS_LUSTRATE</literal>, + skip ahead. + </para> + </note> + <para> + Prepare your target partition: + </para> + <para> + At this point it is time to prepare your target partition. Please refer to + the partitioning, file-system creation, and mounting steps of + <xref linkend="sec-installation" /> + </para> + <para> + If you're about to install NixOS in place using + <literal>NIXOS_LUSTRATE</literal> there is nothing to do for this step. + </para> + </listitem> + <listitem> + <para> + Generate your NixOS configuration: + </para> +<screen>$ sudo `which nixos-generate-config` --root /mnt</screen> + <para> + You'll probably want to edit the configuration files. Refer to the + <literal>nixos-generate-config</literal> step in + <xref + linkend="sec-installation" /> for more + information. + </para> + <para> + Consider setting up the NixOS bootloader to give you the ability to boot on + your existing Linux partition. For instance, if you're using GRUB and your + existing distribution is running Ubuntu, you may want to add something like + this to your <literal>configuration.nix</literal>: + </para> +<programlisting> +<xref linkend="opt-boot.loader.grub.extraEntries"/> = '' + menuentry "Ubuntu" { + search --set=ubuntu --fs-uuid 3cc3e652-0c1f-4800-8451-033754f68e6e + configfile "($ubuntu)/boot/grub/grub.cfg" + } +'';</programlisting> + <para> + (You can find the appropriate UUID for your partition in + <literal>/dev/disk/by-uuid</literal>) + </para> + </listitem> + <listitem> + <para> + Create the <literal>nixbld</literal> group and user on your original + distribution: + </para> +<screen> +$ sudo groupadd -g 30000 nixbld +$ sudo useradd -u 30000 -g nixbld -G nixbld nixbld</screen> + </listitem> + <listitem> + <para> + Download/build/install NixOS: + </para> + <warning> + <para> + Once you complete this step, you might no longer be able to boot on + existing systems without the help of a rescue USB drive or similar. + </para> + </warning> +<screen>$ sudo PATH="$PATH" NIX_PATH="$NIX_PATH" `which nixos-install` --root /mnt</screen> + <para> + Again, please refer to the <literal>nixos-install</literal> step in + <xref linkend="sec-installation" /> for more information. + </para> + <para> + That should be it for installation to another partition! + </para> + </listitem> + <listitem> + <para> + Optionally, you may want to clean up your non-NixOS distribution: + </para> +<screen> +$ sudo userdel nixbld +$ sudo groupdel nixbld</screen> + <para> + If you do not wish to keep the Nix package manager installed either, run + something like <literal>sudo rm -rv ~/.nix-* /nix</literal> and remove the + line that the Nix installer added to your <literal>~/.profile</literal>. + </para> + </listitem> + <listitem> + <note> + <para> + The following steps are only for installing NixOS in place using + <literal>NIXOS_LUSTRATE</literal>: + </para> + </note> + <para> + Generate your NixOS configuration: + </para> +<screen>$ sudo `which nixos-generate-config` --root /</screen> + <para> + Note that this will place the generated configuration files in + <literal>/etc/nixos</literal>. You'll probably want to edit the + configuration files. Refer to the <literal>nixos-generate-config</literal> + step in <xref + linkend="sec-installation" /> for more + information. + </para> + <para> + You'll likely want to set a root password for your first boot using the + configuration files because you won't have a chance to enter a password + until after you reboot. You can initalize the root password to an empty one + with this line: (and of course don't forget to set one once you've rebooted + or to lock the account with <literal>sudo passwd -l root</literal> if you + use <literal>sudo</literal>) + </para> +<programlisting> +<link linkend="opt-users.users._name__.initialHashedPassword">users.extraUsers.root.initialHashedPassword</link> = ""; + </programlisting> + </listitem> + <listitem> + <para> + Build the NixOS closure and install it in the <literal>system</literal> + profile: + </para> +<screen>$ nix-env -p /nix/var/nix/profiles/system -f '<nixpkgs/nixos>' -I nixos-config=/etc/nixos/configuration.nix -iA system</screen> + </listitem> + <listitem> + <para> + Change ownership of the <literal>/nix</literal> tree to root (since your + Nix install was probably single user): + </para> +<screen>$ sudo chown -R 0.0 /nix</screen> + </listitem> + <listitem> + <para> + Set up the <literal>/etc/NIXOS</literal> and + <literal>/etc/NIXOS_LUSTRATE</literal> files: + </para> + <para> + <literal>/etc/NIXOS</literal> officializes that this is now a NixOS + partition (the bootup scripts require its presence). + </para> + <para> + <literal>/etc/NIXOS_LUSTRATE</literal> tells the NixOS bootup scripts to + move <emphasis>everything</emphasis> that's in the root partition to + <literal>/old-root</literal>. This will move your existing distribution out + of the way in the very early stages of the NixOS bootup. There are + exceptions (we do need to keep NixOS there after all), so the NixOS + lustrate process will not touch: + </para> + <itemizedlist> + <listitem> + <para> + The <literal>/nix</literal> directory + </para> + </listitem> + <listitem> + <para> + The <literal>/boot</literal> directory + </para> + </listitem> + <listitem> + <para> + Any file or directory listed in <literal>/etc/NIXOS_LUSTRATE</literal> + (one per line) + </para> + </listitem> + </itemizedlist> + <note> + <para> + Support for <literal>NIXOS_LUSTRATE</literal> was added in NixOS 16.09. + The act of "lustrating" refers to the wiping of the existing distribution. + Creating <literal>/etc/NIXOS_LUSTRATE</literal> can also be used on NixOS + to remove all mutable files from your root partition (anything that's not + in <literal>/nix</literal> or <literal>/boot</literal> gets "lustrated" on + the next boot. + </para> + <para> + lustrate /ˈlʌstreɪt/ verb. + </para> + <para> + purify by expiatory sacrifice, ceremonial washing, or some other ritual + action. + </para> + </note> + <para> + Let's create the files: + </para> +<screen> +$ sudo touch /etc/NIXOS +$ sudo touch /etc/NIXOS_LUSTRATE + </screen> + <para> + Let's also make sure the NixOS configuration files are kept once we reboot + on NixOS: + </para> +<screen> +$ echo etc/nixos | sudo tee -a /etc/NIXOS_LUSTRATE + </screen> + </listitem> + <listitem> + <para> + Finally, move the <literal>/boot</literal> directory of your current + distribution out of the way (the lustrate process will take care of the + rest once you reboot, but this one must be moved out now because NixOS + needs to install its own boot files: + </para> + <warning> + <para> + Once you complete this step, your current distribution will no longer be + bootable! If you didn't get all the NixOS configuration right, especially + those settings pertaining to boot loading and root partition, NixOS may + not be bootable either. Have a USB rescue device ready in case this + happens. + </para> + </warning> +<screen> +$ sudo mv -v /boot /boot.bak && + sudo /nix/var/nix/profiles/system/bin/switch-to-configuration boot</screen> + <para> + Cross your fingers, reboot, hopefully you should get a NixOS prompt! + </para> + </listitem> + <listitem> + <para> + If for some reason you want to revert to the old distribution, you'll need + to boot on a USB rescue disk and do something along these lines: + </para> +<screen> +# mkdir root +# mount /dev/sdaX root +# mkdir root/nixos-root +# mv -v root/* root/nixos-root/ +# mv -v root/nixos-root/old-root/* root/ +# mv -v root/boot.bak root/boot # We had renamed this by hand earlier +# umount root +# reboot</screen> + <para> + This may work as is or you might also need to reinstall the boot loader + </para> + <para> + And of course, if you're happy with NixOS and no longer need the old + distribution: + </para> +<screen>sudo rm -rf /old-root</screen> + </listitem> + <listitem> + <para> + It's also worth noting that this whole process can be automated. This is + especially useful for Cloud VMs, where provider do not provide NixOS. For + instance, + <link + xlink:href="https://github.com/elitak/nixos-infect">nixos-infect</link> + uses the lustrate process to convert Digital Ocean droplets to NixOS from + other distributions automatically. + </para> + </listitem> + </orderedlist> +</section> diff --git a/nixos/doc/manual/installation/installing-pxe.xml b/nixos/doc/manual/installation/installing-pxe.xml new file mode 100644 index 000000000000..94199e5e028d --- /dev/null +++ b/nixos/doc/manual/installation/installing-pxe.xml @@ -0,0 +1,50 @@ +<section xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-booting-from-pxe"> + <title>Booting from the <quote>netboot</quote> media (PXE)</title> + + <para> + Advanced users may wish to install NixOS using an existing PXE or iPXE setup. + </para> + + <para> + These instructions assume that you have an existing PXE or iPXE + infrastructure and simply want to add the NixOS installer as another option. + To build the necessary files from a recent version of nixpkgs, you can run: + </para> + +<programlisting> +nix-build -A netboot nixos/release.nix +</programlisting> + + <para> + This will create a <literal>result</literal> directory containing: * + <literal>bzImage</literal> – the Linux kernel * <literal>initrd</literal> + – the initrd file * <literal>netboot.ipxe</literal> – an example ipxe + script demonstrating the appropriate kernel command line arguments for this + image + </para> + + <para> + If you’re using plain PXE, configure your boot loader to use the + <literal>bzImage</literal> and <literal>initrd</literal> files and have it + provide the same kernel command line arguments found in + <literal>netboot.ipxe</literal>. + </para> + + <para> + If you’re using iPXE, depending on how your HTTP/FTP/etc. server is + configured you may be able to use <literal>netboot.ipxe</literal> unmodified, + or you may need to update the paths to the files to match your server’s + directory layout + </para> + + <para> + In the future we may begin making these files available as build products + from hydra at which point we will update this documentation with instructions + on how to obtain them either for placing on a dedicated TFTP server or to + boot them directly over the internet. + </para> +</section> diff --git a/nixos/doc/manual/installation/installing-uefi.xml b/nixos/doc/manual/installation/installing-uefi.xml deleted file mode 100644 index 90d18695447c..000000000000 --- a/nixos/doc/manual/installation/installing-uefi.xml +++ /dev/null @@ -1,47 +0,0 @@ -<section xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="sec-uefi-installation"> - -<title>UEFI Installation</title> - -<para>NixOS can also be installed on UEFI systems. The procedure -is by and large the same as a BIOS installation, with the following -changes: - -<itemizedlist> - <listitem> - <para>You should boot the live CD in UEFI mode (consult your - specific hardware's documentation for instructions). You may find - the <link - xlink:href="http://www.rodsbooks.com/refind">rEFInd - boot manager</link> useful.</para> - </listitem> - <listitem> - <para>Instead of <command>fdisk</command>, you should use - <command>gdisk</command> to partition your disks. You will need to - have a separate partition for <filename>/boot</filename> with - partition code EF00, and it should be formatted as a - <literal>vfat</literal> filesystem.</para> - </listitem> - <listitem> - <para>You must set <option>boot.loader.gummiboot.enable</option> to - <literal>true</literal>. <command>nixos-generate-config</command> - should do this automatically for new configurations when booted in - UEFI mode.</para> - </listitem> - <listitem> - <para>After having mounted your installation partition to - <code>/mnt</code>, you must mount the <code>boot</code> partition - to <code>/mnt/boot</code>.</para> - </listitem> - <listitem> - <para>You may want to look at the options starting with - <option>boot.loader.efi</option> and <option>boot.loader.gummiboot</option> - as well.</para> - </listitem> -</itemizedlist> -</para> - -</section> diff --git a/nixos/doc/manual/installation/installing-usb.xml b/nixos/doc/manual/installation/installing-usb.xml index 5def6e8753fe..c5934111749c 100644 --- a/nixos/doc/manual/installation/installing-usb.xml +++ b/nixos/doc/manual/installation/installing-usb.xml @@ -3,28 +3,66 @@ xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="sec-booting-from-usb"> + <title>Booting from a USB Drive</title> -<title>Booting from a USB Drive</title> + <para> + For systems without CD drive, the NixOS live CD can be booted from a USB + stick. You can use the <command>dd</command> utility to write the image: + <command>dd if=<replaceable>path-to-image</replaceable> + of=<replaceable>/dev/sdb</replaceable></command>. Be careful about specifying + the correct drive; you can use the <command>lsblk</command> command to get a + list of block devices. + </para> -<para>For systems without CD drive, the NixOS live CD can be booted from -a USB stick. For non-UEFI installations, -<link xlink:href="http://unetbootin.sourceforge.net/">unetbootin</link> -will work. For UEFI installations, you should mount the ISO, copy its contents -verbatim to your drive, then either: - -<itemizedlist> - <listitem> - <para>Change the label of the disk partition to the label of the ISO - (visible with the blkid command), or</para> - </listitem> - <listitem> - <para>Edit <filename>loader/entries/nixos-livecd.conf</filename> on the drive - and change the <literal>root=</literal> field in the <literal>options</literal> - line to point to your drive (see the documentation on <literal>root=</literal> - in <link xlink:href="https://www.kernel.org/doc/Documentation/kernel-parameters.txt"> - the kernel documentation</link> for more details).</para> - </listitem> -</itemizedlist> -</para> + <para> + On macOS: +<programlisting> +$ diskutil list +[..] +/dev/diskN (external, physical): + #: TYPE NAME SIZE IDENTIFIER +[..] +$ diskutil unmountDisk diskN +Unmount of all volumes on diskN was successful +$ sudo dd bs=1m if=nix.iso of=/dev/rdiskN +</programlisting> + Using the 'raw' <command>rdiskN</command> device instead of + <command>diskN</command> completes in minutes instead of hours. After + <command>dd</command> completes, a GUI dialog "The disk you inserted was not + readable by this computer" will pop up, which can be ignored. + </para> + <para> + The <command>dd</command> utility will write the image verbatim to the drive, + making it the recommended option for both UEFI and non-UEFI installations. + For non-UEFI installations, you can alternatively use + <link xlink:href="http://unetbootin.sourceforge.net/">unetbootin</link>. If + you cannot use <command>dd</command> for a UEFI installation, you can also + mount the ISO, copy its contents verbatim to your drive, then either: + <itemizedlist> + <listitem> + <para> + Change the label of the disk partition to the label of the ISO (visible + with the blkid command), or + </para> + </listitem> + <listitem> + <para> + Edit <filename>loader/entries/nixos-livecd.conf</filename> on the drive + and change the <literal>root=</literal> field in the + <literal>options</literal> line to point to your drive (see the + documentation on <literal>root=</literal> in + <link xlink:href="https://www.kernel.org/doc/Documentation/admin-guide/kernel-parameters.txt"> + the kernel documentation</link> for more details). + </para> + </listitem> + <listitem> + <para> + If you want to load the contents of the ISO to ram after bootin (So you + can remove the stick after bootup) you can append the parameter + <literal>copytoram</literal> to the <literal>options</literal> field. + </para> + </listitem> + </itemizedlist> + </para> </section> diff --git a/nixos/doc/manual/installation/installing-virtualbox-guest.xml b/nixos/doc/manual/installation/installing-virtualbox-guest.xml new file mode 100644 index 000000000000..da78b480f5aa --- /dev/null +++ b/nixos/doc/manual/installation/installing-virtualbox-guest.xml @@ -0,0 +1,99 @@ +<section xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-instaling-virtualbox-guest"> + <title>Installing in a VirtualBox guest</title> + + <para> + Installing NixOS into a VirtualBox guest is convenient for users who want to + try NixOS without installing it on bare metal. If you want to use a pre-made + VirtualBox appliance, it is available at + <link + xlink:href="https://nixos.org/nixos/download.html">the downloads + page</link>. If you want to set up a VirtualBox guest manually, follow these + instructions: + </para> + + <orderedlist> + <listitem> + <para> + Add a New Machine in VirtualBox with OS Type "Linux / Other Linux" + </para> + </listitem> + <listitem> + <para> + Base Memory Size: 768 MB or higher. + </para> + </listitem> + <listitem> + <para> + New Hard Disk of 8 GB or higher. + </para> + </listitem> + <listitem> + <para> + Mount the CD-ROM with the NixOS ISO (by clicking on CD/DVD-ROM) + </para> + </listitem> + <listitem> + <para> + Click on Settings / System / Processor and enable PAE/NX + </para> + </listitem> + <listitem> + <para> + Click on Settings / System / Acceleration and enable "VT-x/AMD-V" + acceleration + </para> + </listitem> + <listitem> + <para> + Save the settings, start the virtual machine, and continue installation + like normal + </para> + </listitem> + </orderedlist> + + <para> + There are a few modifications you should make in configuration.nix. Enable + booting: + </para> + +<programlisting> +<xref linkend="opt-boot.loader.grub.device"/> = "/dev/sda"; +</programlisting> + + <para> + Also remove the fsck that runs at startup. It will always fail to run, + stopping your boot until you press <literal>*</literal>. + </para> + +<programlisting> +<xref linkend="opt-boot.initrd.checkJournalingFS"/> = false; +</programlisting> + + <para> + Shared folders can be given a name and a path in the host system in the + VirtualBox settings (Machine / Settings / Shared Folders, then click on the + "Add" icon). Add the following to the + <literal>/etc/nixos/configuration.nix</literal> to auto-mount them: + </para> + +<programlisting> +{ config, pkgs, ...} : +{ + ... + + fileSystems."/virtualboxshare" = { + fsType = "vboxsf"; + device = "nameofthesharedfolder"; + options = [ "rw" ]; + }; +} +</programlisting> + + <para> + The folder will be available directly under the root directory. + </para> +</section> diff --git a/nixos/doc/manual/installation/installing.xml b/nixos/doc/manual/installation/installing.xml index 6d734cd8caca..6066d025adbf 100644 --- a/nixos/doc/manual/installation/installing.xml +++ b/nixos/doc/manual/installation/installing.xml @@ -3,273 +3,445 @@ xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="sec-installation"> - -<title>Installing NixOS</title> - -<orderedlist> - - <listitem><para>Boot from the CD.</para></listitem> - - <listitem><para>The CD contains a basic NixOS installation. (It - also contains Memtest86+, useful if you want to test new hardware). - When it’s finished booting, it should have detected most of your - hardware.</para></listitem> - - <listitem><para>The NixOS manual is available on virtual console 8 - (press Alt+F8 to access).</para></listitem> - - <listitem><para>You get logged in as <literal>root</literal> - (with empty password).</para></listitem> - - <listitem><para>If you downloaded the graphical ISO image, you can - run <command>start display-manager</command> to start KDE.</para></listitem> - - <listitem><para>The boot process should have brought up networking (check - <command>ip a</command>). Networking is necessary for the - installer, since it will download lots of stuff (such as source - tarballs or Nixpkgs channel binaries). It’s best if you have a DHCP - server on your network. Otherwise configure networking manually - using <command>ifconfig</command>.</para> - <para>To manually configure the network on the graphical installer, - first disable network-manager with - <command>systemctl stop network-manager</command>.</para></listitem> - - <listitem><para>The NixOS installer doesn’t do any partitioning or - formatting yet, so you need to that yourself. Use the following - commands: - - <itemizedlist> - - <listitem><para>For partitioning: - <command>fdisk</command>.</para></listitem> - - <listitem><para>For initialising Ext4 partitions: - <command>mkfs.ext4</command>. It is recommended that you assign a - unique symbolic label to the file system using the option - <option>-L <replaceable>label</replaceable></option>, since this - makes the file system configuration independent from device - changes. For example: - + <title>Installing NixOS</title> + <para> + NixOS can be installed on BIOS or UEFI systems. The procedure for a UEFI + installation is by and large the same as a BIOS installation. The differences + are mentioned in the steps that follow. + </para> + <orderedlist> + <listitem> + <para> + Boot from the CD. + </para> + <variablelist> + <varlistentry> + <term> + UEFI systems + </term> + <listitem> + <para> + You should boot the live CD in UEFI mode (consult your specific + hardware's documentation for instructions). You may find the + <link xlink:href="http://www.rodsbooks.com/refind">rEFInd boot + manager</link> useful. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + <listitem> + <para> + The CD contains a basic NixOS installation. (It also contains Memtest86+, + useful if you want to test new hardware). When it’s finished booting, it + should have detected most of your hardware. + </para> + </listitem> + <listitem> + <para> + The NixOS manual is available on virtual console 8 (press Alt+F8 to access) + or by running <command>nixos-help</command>. + </para> + </listitem> + <listitem> + <para> + You get logged in as <literal>root</literal> (with empty password). + </para> + </listitem> + <listitem> + <para> + If you downloaded the graphical ISO image, you can run <command>systemctl + start display-manager</command> to start KDE. If you want to continue on + the terminal, you can use <command>loadkeys</command> to switch to your + preferred keyboard layout. (We even provide neo2 via <command>loadkeys de + neo</command>!) + </para> + </listitem> + <listitem> + <para> + The boot process should have brought up networking (check <command>ip + a</command>). Networking is necessary for the installer, since it will + download lots of stuff (such as source tarballs or Nixpkgs channel + binaries). It’s best if you have a DHCP server on your network. Otherwise + configure networking manually using <command>ifconfig</command>. + </para> + <para> + To manually configure the network on the graphical installer, first disable + network-manager with <command>systemctl stop network-manager</command>. + </para> + <para> + To manually configure the wifi on the minimal installer, run + <command>wpa_supplicant -B -i interface -c <(wpa_passphrase 'SSID' + 'key')</command>. + </para> + </listitem> + <listitem> + <para> + If you would like to continue the installation from a different machine you + need to activate the SSH daemon via <literal>systemctl start + sshd</literal>. In order to be able to login you also need to set a + password for <literal>root</literal> using <literal>passwd</literal>. + </para> + </listitem> + <listitem> + <para> + The NixOS installer doesn’t do any partitioning or formatting yet, so you + need to do that yourself. Use the following commands: + <itemizedlist> + <listitem> + <para> + For partitioning: <command>fdisk</command>. <screen> -$ mkfs.ext4 -L nixos /dev/sda1</screen> - - </para></listitem> - - <listitem><para>For creating swap partitions: - <command>mkswap</command>. Again it’s recommended to assign a - label to the swap partition: <option>-L - <replaceable>label</replaceable></option>.</para></listitem> - - <listitem><para>For creating LVM volumes, the LVM commands, e.g., - +# fdisk /dev/sda # <lineannotation>(or whatever device you want to install on)</lineannotation> +-- for UEFI systems only +> n # <lineannotation>(create a new partition for /boot)</lineannotation> +> 3 # <lineannotation>(make it a partition number 3)</lineannotation> +> # <lineannotation>(press enter to accept the default)</lineannotation> +> +512M # <lineannotation>(the size of the UEFI boot partition)</lineannotation> +> t # <lineannotation>(change the partition type ...)</lineannotation> +> 3 # <lineannotation>(... of the boot partition ...)</lineannotation> +> 1 # <lineannotation>(... to 'UEFI System')</lineannotation> +-- for BIOS or UEFI systems +> n # <lineannotation>(create a new partition for /swap)</lineannotation> +> 2 # <lineannotation>(make it a partition number 2)</lineannotation> +> # <lineannotation>(press enter to accept the default)</lineannotation> +> +8G # <lineannotation>(the size of the swap partition, set to whatever you like)</lineannotation> +> n # <lineannotation>(create a new partition for /)</lineannotation> +> 1 # <lineannotation>(make it a partition number 1)</lineannotation> +> # <lineannotation>(press enter to accept the default)</lineannotation> +> # <lineannotation>(press enter to accept the default and use the rest of the remaining space)</lineannotation> +> a # <lineannotation>(make the partition bootable)</lineannotation> +> x # <lineannotation>(enter expert mode)</lineannotation> +> f # <lineannotation>(fix up the partition ordering)</lineannotation> +> r # <lineannotation>(exit expert mode)</lineannotation> +> w # <lineannotation>(write the partition table to disk and exit)</lineannotation></screen> + </para> + </listitem> + <listitem> + <para> + For initialising Ext4 partitions: <command>mkfs.ext4</command>. It is + recommended that you assign a unique symbolic label to the file system + using the option <option>-L <replaceable>label</replaceable></option>, + since this makes the file system configuration independent from device + changes. For example: <screen> -$ pvcreate /dev/sda1 /dev/sdb1 -$ vgcreate MyVolGroup /dev/sda1 /dev/sdb1 -$ lvcreate --size 2G --name bigdisk MyVolGroup -$ lvcreate --size 1G --name smalldisk MyVolGroup</screen> - - </para></listitem> - - <listitem><para>For creating software RAID devices, use - <command>mdadm</command>.</para></listitem> - - </itemizedlist> - - </para></listitem> - - <listitem><para>Mount the target file system on which NixOS should - be installed on <filename>/mnt</filename>, e.g. - +# mkfs.ext4 -L nixos /dev/sda1</screen> + </para> + </listitem> + <listitem> + <para> + For creating swap partitions: <command>mkswap</command>. Again it’s + recommended to assign a label to the swap partition: <option>-L + <replaceable>label</replaceable></option>. For example: <screen> -$ mount /dev/disk/by-label/nixos /mnt +# mkswap -L swap /dev/sda2</screen> + </para> + </listitem> + <listitem> + <variablelist> + <varlistentry> + <term> + UEFI systems + </term> + <listitem> + <para> + For creating boot partitions: <command>mkfs.fat</command>. Again + it’s recommended to assign a label to the boot partition: + <option>-n <replaceable>label</replaceable></option>. For example: +<screen> +# mkfs.fat -F 32 -n boot /dev/sda3</screen> + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + <listitem> + <para> + For creating LVM volumes, the LVM commands, e.g., + <command>pvcreate</command>, <command>vgcreate</command>, and + <command>lvcreate</command>. + </para> + </listitem> + <listitem> + <para> + For creating software RAID devices, use <command>mdadm</command>. + </para> + </listitem> + </itemizedlist> + </para> + </listitem> + <listitem> + <para> + Mount the target file system on which NixOS should be installed on + <filename>/mnt</filename>, e.g. +<screen> +# mount /dev/disk/by-label/nixos /mnt </screen> - - </para></listitem> - - <listitem><para>If your machine has a limited amount of memory, you - may want to activate swap devices now (<command>swapon - <replaceable>device</replaceable></command>). The installer (or - rather, the build actions that it may spawn) may need quite a bit of - RAM, depending on your configuration.</para></listitem> - + </para> + </listitem> <listitem> - - <para>You now need to create a file - <filename>/mnt/etc/nixos/configuration.nix</filename> that - specifies the intended configuration of the system. This is - because NixOS has a <emphasis>declarative</emphasis> configuration - model: you create or edit a description of the desired - configuration of your system, and then NixOS takes care of making - it happen. The syntax of the NixOS configuration file is - described in <xref linkend="sec-configuration-syntax"/>, while a - list of available configuration options appears in <xref - linkend="ch-options"/>. A minimal example is shown in <xref - linkend="ex-config"/>.</para> - - <para>The command <command>nixos-generate-config</command> can - generate an initial configuration file for you: - + <variablelist> + <varlistentry> + <term> + UEFI systems + </term> + <listitem> + <para> + Mount the boot file system on <filename>/mnt/boot</filename>, e.g. <screen> -$ nixos-generate-config --root /mnt</screen> - - You should then edit - <filename>/mnt/etc/nixos/configuration.nix</filename> to suit your - needs: - +# mkdir -p /mnt/boot +# mount /dev/disk/by-label/boot /mnt/boot +</screen> + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + <listitem> + <para> + If your machine has a limited amount of memory, you may want to activate + swap devices now (<command>swapon + <replaceable>device</replaceable></command>). The installer (or rather, the + build actions that it may spawn) may need quite a bit of RAM, depending on + your configuration. +<screen> +# swapon /dev/sda2</screen> + </para> + </listitem> + <listitem> + <para> + You now need to create a file + <filename>/mnt/etc/nixos/configuration.nix</filename> that specifies the + intended configuration of the system. This is because NixOS has a + <emphasis>declarative</emphasis> configuration model: you create or edit a + description of the desired configuration of your system, and then NixOS + takes care of making it happen. The syntax of the NixOS configuration file + is described in <xref linkend="sec-configuration-syntax"/>, while a list of + available configuration options appears in + <xref + linkend="ch-options"/>. A minimal example is shown in + <xref + linkend="ex-config"/>. + </para> + <para> + The command <command>nixos-generate-config</command> can generate an + initial configuration file for you: <screen> -$ nano /mnt/etc/nixos/configuration.nix +# nixos-generate-config --root /mnt</screen> + You should then edit <filename>/mnt/etc/nixos/configuration.nix</filename> + to suit your needs: +<screen> +# nano /mnt/etc/nixos/configuration.nix </screen> - - If you’re using the graphical ISO image, other editors may be - available (such as <command>vim</command>). If you have network - access, you can also install other editors — for instance, you can - install Emacs by running <literal>nix-env -i - emacs</literal>.</para> - - <para>You <emphasis>must</emphasis> set the option - <option>boot.loader.grub.device</option> to specify on which disk - the GRUB boot loader is to be installed. Without it, NixOS cannot - boot.</para> - - <para>Another critical option is <option>fileSystems</option>, - specifying the file systems that need to be mounted by NixOS. - However, you typically don’t need to set it yourself, because + If you’re using the graphical ISO image, other editors may be available + (such as <command>vim</command>). If you have network access, you can also + install other editors — for instance, you can install Emacs by running + <literal>nix-env -i emacs</literal>. + </para> + <variablelist> + <varlistentry> + <term> + BIOS systems + </term> + <listitem> + <para> + You <emphasis>must</emphasis> set the option + <xref linkend="opt-boot.loader.grub.device"/> to specify on which disk + the GRUB boot loader is to be installed. Without it, NixOS cannot boot. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + UEFI systems + </term> + <listitem> + <para> + You <emphasis>must</emphasis> set the option + <xref linkend="opt-boot.loader.systemd-boot.enable"/> to + <literal>true</literal>. <command>nixos-generate-config</command> should + do this automatically for new configurations when booted in UEFI mode. + </para> + <para> + You may want to look at the options starting with + <option><link linkend="opt-boot.loader.efi.canTouchEfiVariables">boot.loader.efi</link></option> + and + <option><link linkend="opt-boot.loader.systemd-boot.enable">boot.loader.systemd</link></option> + as well. + </para> + </listitem> + </varlistentry> + </variablelist> + <para> + If there are other operating systems running on the machine before + installing NixOS, the <xref linkend="opt-boot.loader.grub.useOSProber"/> + option can be set to <literal>true</literal> to automatically add them to + the grub menu. + </para> + <para> + Another critical option is <option>fileSystems</option>, specifying the + file systems that need to be mounted by NixOS. However, you typically + don’t need to set it yourself, because <command>nixos-generate-config</command> sets it automatically in - <filename>/mnt/etc/nixos/hardware-configuration.nix</filename> - from your currently mounted file systems. (The configuration file + <filename>/mnt/etc/nixos/hardware-configuration.nix</filename> from your + currently mounted file systems. (The configuration file <filename>hardware-configuration.nix</filename> is included from - <filename>configuration.nix</filename> and will be overwritten by - future invocations of <command>nixos-generate-config</command>; - thus, you generally should not modify it.)</para> - - <note><para>Depending on your hardware configuration or type of - file system, you may need to set the option - <option>boot.initrd.kernelModules</option> to include the kernel - modules that are necessary for mounting the root file system, - otherwise the installed system will not be able to boot. (If this - happens, boot from the CD again, mount the target file system on - <filename>/mnt</filename>, fix - <filename>/mnt/etc/nixos/configuration.nix</filename> and rerun - <filename>nixos-install</filename>.) In most cases, - <command>nixos-generate-config</command> will figure out the - required modules.</para></note> - - <para>Examples of real-world NixOS configuration files can be - found at <link - xlink:href="https://nixos.org/repos/nix/configurations/trunk/"/>.</para> - + <filename>configuration.nix</filename> and will be overwritten by future + invocations of <command>nixos-generate-config</command>; thus, you + generally should not modify it.) + </para> + <note> + <para> + Depending on your hardware configuration or type of file system, you may + need to set the option <option>boot.initrd.kernelModules</option> to + include the kernel modules that are necessary for mounting the root file + system, otherwise the installed system will not be able to boot. (If this + happens, boot from the CD again, mount the target file system on + <filename>/mnt</filename>, fix + <filename>/mnt/etc/nixos/configuration.nix</filename> and rerun + <filename>nixos-install</filename>.) In most cases, + <command>nixos-generate-config</command> will figure out the required + modules. + </para> + </note> </listitem> - - <listitem><para>Do the installation: - + <listitem> + <para> + Do the installation: <screen> -$ nixos-install</screen> - - Cross fingers. If this fails due to a temporary problem (such as - a network issue while downloading binaries from the NixOS binary - cache), you can just re-run <command>nixos-install</command>. - Otherwise, fix your <filename>configuration.nix</filename> and - then re-run <command>nixos-install</command>.</para> - - <para>As the last step, <command>nixos-install</command> will ask - you to set the password for the <literal>root</literal> user, e.g. - +# nixos-install</screen> + Cross fingers. If this fails due to a temporary problem (such as a network + issue while downloading binaries from the NixOS binary cache), you can just + re-run <command>nixos-install</command>. Otherwise, fix your + <filename>configuration.nix</filename> and then re-run + <command>nixos-install</command>. + </para> + <para> + As the last step, <command>nixos-install</command> will ask you to set the + password for the <literal>root</literal> user, e.g. <screen> setting root password... Enter new UNIX password: *** Retype new UNIX password: *** -</screen> - - </para> - + </screen> + <note> + <para> + To prevent the password prompt, set + <code><xref linkend="opt-users.mutableUsers"/> = false;</code> in + <filename>configuration.nix</filename>, which allows unattended + installation necessary in automation. + </para> + </note> + </para> </listitem> - - <listitem><para>If everything went well: - + <listitem> + <para> + If everything went well: <screen> -$ reboot</screen> - - </para></listitem> - + # reboot</screen> + </para> + </listitem> <listitem> - - <para>You should now be able to boot into the installed NixOS. The - GRUB boot menu shows a list of <emphasis>available - configurations</emphasis> (initially just one). Every time you - change the NixOS configuration (see <link - linkend="sec-changing-config">Changing Configuration</link> ), a - new item is added to the menu. This allows you to easily roll back - to a previous configuration if something goes wrong.</para> - - <para>You should log in and change the <literal>root</literal> - password with <command>passwd</command>.</para> - - <para>You’ll probably want to create some user accounts as well, - which can be done with <command>useradd</command>: - + <para> + You should now be able to boot into the installed NixOS. The GRUB boot menu + shows a list of <emphasis>available configurations</emphasis> (initially + just one). Every time you change the NixOS configuration (see + <link + linkend="sec-changing-config">Changing Configuration</link> + ), a new item is added to the menu. This allows you to easily roll back to + a previous configuration if something goes wrong. + </para> + <para> + You should log in and change the <literal>root</literal> password with + <command>passwd</command>. + </para> + <para> + You’ll probably want to create some user accounts as well, which can be + done with <command>useradd</command>: <screen> $ useradd -c 'Eelco Dolstra' -m eelco $ passwd eelco</screen> - - </para> - - <para>You may also want to install some software. For instance, - + </para> + <para> + You may also want to install some software. For instance, <screen> $ nix-env -qa \*</screen> - shows what packages are available, and - <screen> $ nix-env -i w3m</screen> - - install the <literal>w3m</literal> browser.</para> - + install the <literal>w3m</literal> browser. + </para> </listitem> - -</orderedlist> - -<para>To summarise, <xref linkend="ex-install-sequence" /> shows a -typical sequence of commands for installing NixOS on an empty hard -drive (here <filename>/dev/sda</filename>). <xref linkend="ex-config" -/> shows a corresponding configuration Nix expression.</para> - -<example xml:id='ex-install-sequence'><title>Commands for Installing NixOS on <filename>/dev/sda</filename></title> + </orderedlist> + <para> + To summarise, <xref linkend="ex-install-sequence" /> shows a typical sequence + of commands for installing NixOS on an empty hard drive (here + <filename>/dev/sda</filename>). <xref linkend="ex-config" +/> shows a + corresponding configuration Nix expression. + </para> + <example xml:id='ex-install-sequence'> + <title>Commands for Installing NixOS on <filename>/dev/sda</filename></title> <screen> -$ fdisk /dev/sda # <lineannotation>(or whatever device you want to install on)</lineannotation> -$ mkfs.ext4 -L nixos /dev/sda1 -$ mkswap -L swap /dev/sda2 -$ swapon /dev/sda2 -$ mount /dev/disk/by-label/nixos /mnt -$ nixos-generate-config --root /mnt -$ nano /mnt/etc/nixos/configuration.nix -$ nixos-install -$ reboot</screen> -</example> - -<example xml:id='ex-config'><title>NixOS Configuration</title> +# fdisk /dev/sda # <lineannotation>(or whatever device you want to install on)</lineannotation> +-- for UEFI systems only +> n # <lineannotation>(create a new partition for /boot)</lineannotation> +> 3 # <lineannotation>(make it a partition number 3)</lineannotation> +> # <lineannotation>(press enter to accept the default)</lineannotation> +> +512M # <lineannotation>(the size of the UEFI boot partition)</lineannotation> +> t # <lineannotation>(change the partition type ...)</lineannotation> +> 3 # <lineannotation>(... of the boot partition ...)</lineannotation> +> 1 # <lineannotation>(... to 'UEFI System')</lineannotation> +-- for BIOS or UEFI systems +> n # <lineannotation>(create a new partition for /swap)</lineannotation> +> 2 # <lineannotation>(make it a partition number 2)</lineannotation> +> # <lineannotation>(press enter to accept the default)</lineannotation> +> +8G # <lineannotation>(the size of the swap partition)</lineannotation> +> n # <lineannotation>(create a new partition for /)</lineannotation> +> 1 # <lineannotation>(make it a partition number 1)</lineannotation> +> # <lineannotation>(press enter to accept the default)</lineannotation> +> # <lineannotation>(press enter to accept the default and use the rest of the remaining space)</lineannotation> +> a # <lineannotation>(make the partition bootable)</lineannotation> +> x # <lineannotation>(enter expert mode)</lineannotation> +> f # <lineannotation>(fix up the partition ordering)</lineannotation> +> r # <lineannotation>(exit expert mode)</lineannotation> +> w # <lineannotation>(write the partition table to disk and exit)</lineannotation> +# mkfs.ext4 -L nixos /dev/sda1 +# mkswap -L swap /dev/sda2 +# swapon /dev/sda2 +# mkfs.fat -F 32 -n boot /dev/sda3 # <lineannotation>(for UEFI systems only)</lineannotation> +# mount /dev/disk/by-label/nixos /mnt +# mkdir -p /mnt/boot # <lineannotation>(for UEFI systems only)</lineannotation> +# mount /dev/disk/by-label/boot /mnt/boot # <lineannotation>(for UEFI systems only)</lineannotation> +# nixos-generate-config --root /mnt +# nano /mnt/etc/nixos/configuration.nix +# nixos-install +# reboot</screen> + </example> + <example xml:id='ex-config'> + <title>NixOS Configuration</title> <screen> -{ config, pkgs, ... }: +{ config, pkgs, ... }: { + imports = [ + # Include the results of the hardware scan. + ./hardware-configuration.nix + ]; -{ - imports = - [ # Include the results of the hardware scan. - ./hardware-configuration.nix - ]; - - boot.loader.grub.device = "/dev/sda"; + <xref linkend="opt-boot.loader.grub.device"/> = "/dev/sda"; # <lineannotation>(for BIOS systems only)</lineannotation> + <xref linkend="opt-boot.loader.systemd-boot.enable"/> = true; # <lineannotation>(for UEFI systems only)</lineannotation> # Note: setting fileSystems is generally not # necessary, since nixos-generate-config figures them out # automatically in hardware-configuration.nix. - #fileSystems."/".device = "/dev/disk/by-label/nixos"; + #<link linkend="opt-fileSystems._name__.device">fileSystems."/".device</link> = "/dev/disk/by-label/nixos"; # Enable the OpenSSH server. services.sshd.enable = true; -}</screen> -</example> - -<xi:include href="installing-uefi.xml" /> -<xi:include href="installing-usb.xml" /> - +} + </screen> + </example> + <xi:include href="installing-usb.xml" /> + <xi:include href="installing-pxe.xml" /> + <xi:include href="installing-virtualbox-guest.xml" /> + <xi:include href="installing-from-other-distro.xml" /> </chapter> diff --git a/nixos/doc/manual/installation/obtaining.xml b/nixos/doc/manual/installation/obtaining.xml index afd6c9543f70..56af5c0e25a0 100644 --- a/nixos/doc/manual/installation/obtaining.xml +++ b/nixos/doc/manual/installation/obtaining.xml @@ -3,47 +3,52 @@ xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="sec-obtaining"> - -<title>Obtaining NixOS</title> - -<para>NixOS ISO images can be downloaded from the <link -xlink:href="http://nixos.org/nixos/download.html">NixOS -download page</link>. There are a number of installation options. If -you happen to have an optical drive and a spare CD, burning the -image to CD and booting from that is probably the easiest option. -Most people will need to prepare a USB stick to boot from. -Unetbootin is recommended and the process is described in brief below. -Note that systems which use UEFI require some additional manual steps. -If you run into difficulty a number of alternative methods are presented -in the <link -xlink:href="https://nixos.org/wiki/Installing_NixOS_from_a_USB_stick">NixOS -Wiki</link>.</para> - -<para>As an alternative to installing NixOS yourself, you can get a -running NixOS system through several other means: - -<itemizedlist> - <listitem> - <para>Using virtual appliances in Open Virtualization Format (OVF) - that can be imported into VirtualBox. These are available from - the <link xlink:href="http://nixos.org/nixos/download.html">NixOS - download page</link>.</para> - </listitem> - <listitem> - <para>Using AMIs for Amazon’s EC2. To find one for your region - and instance type, please refer to the <link - xlink:href="https://github.com/NixOS/nixops/blob/master/nix/ec2-amis.nix">list - of most recent AMIs</link>.</para> - </listitem> - <listitem> - <para>Using NixOps, the NixOS-based cloud deployment tool, which - allows you to provision VirtualBox and EC2 NixOS instances from - declarative specifications. Check out the <link - xlink:href="https://github.com/NixOS/nixops">NixOps - homepage</link> for details.</para> - </listitem> -</itemizedlist> - -</para> - + <title>Obtaining NixOS</title> + <para> + NixOS ISO images can be downloaded from the + <link +xlink:href="http://nixos.org/nixos/download.html">NixOS download + page</link>. There are a number of installation options. If you happen to + have an optical drive and a spare CD, burning the image to CD and booting + from that is probably the easiest option. Most people will need to prepare a + USB stick to boot from. <xref linkend="sec-booting-from-usb"/> describes the + preferred method to prepare a USB stick. A number of alternative methods are + presented in the + <link +xlink:href="https://nixos.wiki/wiki/NixOS_Installation_Guide#Making_the_installation_media">NixOS + Wiki</link>. + </para> + <para> + As an alternative to installing NixOS yourself, you can get a running NixOS + system through several other means: + <itemizedlist> + <listitem> + <para> + Using virtual appliances in Open Virtualization Format (OVF) that can be + imported into VirtualBox. These are available from the + <link xlink:href="http://nixos.org/nixos/download.html">NixOS download + page</link>. + </para> + </listitem> + <listitem> + <para> + Using AMIs for Amazon’s EC2. To find one for your region and instance + type, please refer to the + <link + xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/virtualisation/ec2-amis.nix">list + of most recent AMIs</link>. + </para> + </listitem> + <listitem> + <para> + Using NixOps, the NixOS-based cloud deployment tool, which allows you to + provision VirtualBox and EC2 NixOS instances from declarative + specifications. Check out the + <link + xlink:href="https://nixos.org/nixops">NixOps homepage</link> for + details. + </para> + </listitem> + </itemizedlist> + </para> </chapter> diff --git a/nixos/doc/manual/installation/upgrading.xml b/nixos/doc/manual/installation/upgrading.xml index c4812cc637c3..20355812ec63 100644 --- a/nixos/doc/manual/installation/upgrading.xml +++ b/nixos/doc/manual/installation/upgrading.xml @@ -2,135 +2,130 @@ xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="sec-upgrading"> - -<title>Upgrading NixOS</title> - -<para>The best way to keep your NixOS installation up to date is to -use one of the NixOS <emphasis>channels</emphasis>. A channel is a -Nix mechanism for distributing Nix expressions and associated -binaries. The NixOS channels are updated automatically from NixOS’s -Git repository after certain tests have passed and all packages have -been built. These channels are: - -<itemizedlist> - <listitem> - <para><emphasis>Stable channels</emphasis>, such as <literal - xlink:href="https://nixos.org/channels/nixos-14.12">nixos-14.12</literal>. - These only get conservative bug fixes and package upgrades. For - instance, a channel update may cause the Linux kernel on your - system to be upgraded from 3.4.66 to 3.4.67 (a minor bug fix), but - not from 3.4.<replaceable>x</replaceable> to - 3.11.<replaceable>x</replaceable> (a major change that has the - potential to break things). Stable channels are generally - maintained until the next stable branch is created.</para> + <title>Upgrading NixOS</title> + <para> + The best way to keep your NixOS installation up to date is to use one of the + NixOS <emphasis>channels</emphasis>. A channel is a Nix mechanism for + distributing Nix expressions and associated binaries. The NixOS channels are + updated automatically from NixOS’s Git repository after certain tests have + passed and all packages have been built. These channels are: + <itemizedlist> + <listitem> + <para> + <emphasis>Stable channels</emphasis>, such as + <literal + xlink:href="https://nixos.org/channels/nixos-17.03">nixos-17.03</literal>. + These only get conservative bug fixes and package upgrades. For instance, + a channel update may cause the Linux kernel on your system to be upgraded + from 4.9.16 to 4.9.17 (a minor bug fix), but not from + 4.9.<replaceable>x</replaceable> to 4.11.<replaceable>x</replaceable> (a + major change that has the potential to break things). Stable channels are + generally maintained until the next stable branch is created. + </para> <para></para> - </listitem> - <listitem> - <para>The <emphasis>unstable channel</emphasis>, <literal + </listitem> + <listitem> + <para> + The <emphasis>unstable channel</emphasis>, + <literal xlink:href="https://nixos.org/channels/nixos-unstable">nixos-unstable</literal>. - This corresponds to NixOS’s main development branch, and may thus - see radical changes between channel updates. It’s not recommended - for production systems.</para> - </listitem> - <listitem> - <para><emphasis>Small channels</emphasis>, such as <literal - xlink:href="https://nixos.org/channels/nixos-14.12-small">nixos-14.12-small</literal> - or <literal - xlink:href="https://nixos.org/channels/nixos-unstable-small">nixos-unstable-small</literal>. These - are identical to the stable and unstable channels described above, - except that they contain fewer binary packages. This means they - get updated faster than the regular channels (for instance, when a - critical security patch is committed to NixOS’s source tree), but - may require more packages to be built from source than - usual. They’re mostly intended for server environments and as such - contain few GUI applications.</para> - </listitem> -</itemizedlist> - -To see what channels are available, go to <link -xlink:href="https://nixos.org/channels"/>. (Note that the URIs of the -various channels redirect to a directory that contains the channel’s -latest version and includes ISO images and VirtualBox -appliances.)</para> - -<para>When you first install NixOS, you’re automatically subscribed to -the NixOS channel that corresponds to your installation source. For -instance, if you installed from a 14.12 ISO, you will be subscribed to -the <literal>nixos-14.12</literal> channel. To see which NixOS -channel you’re subscribed to, run the following as root: - + This corresponds to NixOS’s main development branch, and may thus see + radical changes between channel updates. It’s not recommended for + production systems. + </para> + </listitem> + <listitem> + <para> + <emphasis>Small channels</emphasis>, such as + <literal + xlink:href="https://nixos.org/channels/nixos-17.03-small">nixos-17.03-small</literal> + or + <literal + xlink:href="https://nixos.org/channels/nixos-unstable-small">nixos-unstable-small</literal>. + These are identical to the stable and unstable channels described above, + except that they contain fewer binary packages. This means they get + updated faster than the regular channels (for instance, when a critical + security patch is committed to NixOS’s source tree), but may require + more packages to be built from source than usual. They’re mostly + intended for server environments and as such contain few GUI applications. + </para> + </listitem> + </itemizedlist> + To see what channels are available, go to + <link +xlink:href="https://nixos.org/channels"/>. (Note that the URIs of the + various channels redirect to a directory that contains the channel’s latest + version and includes ISO images and VirtualBox appliances.) + </para> + <para> + When you first install NixOS, you’re automatically subscribed to the NixOS + channel that corresponds to your installation source. For instance, if you + installed from a 17.03 ISO, you will be subscribed to the + <literal>nixos-17.03</literal> channel. To see which NixOS channel you’re + subscribed to, run the following as root: <screen> -$ nix-channel --list | grep nixos +# nix-channel --list | grep nixos nixos https://nixos.org/channels/nixos-unstable </screen> - -To switch to a different NixOS channel, do - + To switch to a different NixOS channel, do <screen> -$ nix-channel --add https://nixos.org/channels/<replaceable>channel-name</replaceable> nixos +# nix-channel --add https://nixos.org/channels/<replaceable>channel-name</replaceable> nixos </screen> - -(Be sure to include the <literal>nixos</literal> parameter at the -end.) For instance, to use the NixOS 14.12 stable channel: - + (Be sure to include the <literal>nixos</literal> parameter at the end.) For + instance, to use the NixOS 17.03 stable channel: <screen> -$ nix-channel --add https://nixos.org/channels/nixos-14.12 nixos +# nix-channel --add https://nixos.org/channels/nixos-17.03 nixos </screen> - -If you have a server, you may want to use the “small” channel instead: - + If you have a server, you may want to use the “small” channel instead: <screen> -$ nix-channel --add https://nixos.org/channels/nixos-14.12-small nixos +# nix-channel --add https://nixos.org/channels/nixos-17.03-small nixos </screen> - -And if you want to live on the bleeding edge: - + And if you want to live on the bleeding edge: <screen> -$ nix-channel --add https://nixos.org/channels/nixos-unstable nixos +# nix-channel --add https://nixos.org/channels/nixos-unstable nixos </screen> - -</para> - -<para>You can then upgrade NixOS to the latest version in your chosen -channel by running - + </para> + <para> + You can then upgrade NixOS to the latest version in your chosen channel by + running <screen> -$ nixos-rebuild switch --upgrade +# nixos-rebuild switch --upgrade </screen> - -which is equivalent to the more verbose <literal>nix-channel --update -nixos; nixos-rebuild switch</literal>.</para> - -<warning><para>It is generally safe to switch back and forth between -channels. The only exception is that a newer NixOS may also have a -newer Nix version, which may involve an upgrade of Nix’s database -schema. This cannot be undone easily, so in that case you will not be -able to go back to your original channel.</para></warning> - - -<section><title>Automatic Upgrades</title> - -<para>You can keep a NixOS system up-to-date automatically by adding -the following to <filename>configuration.nix</filename>: - + which is equivalent to the more verbose <literal>nix-channel --update nixos; + nixos-rebuild switch</literal>. + </para> + <note> + <para> + Channels are set per user. This means that running <literal> nix-channel + --add</literal> as a non root user (or without sudo) will not affect + configuration in <literal>/etc/nixos/configuration.nix</literal> + </para> + </note> + <warning> + <para> + It is generally safe to switch back and forth between channels. The only + exception is that a newer NixOS may also have a newer Nix version, which may + involve an upgrade of Nix’s database schema. This cannot be undone easily, + so in that case you will not be able to go back to your original channel. + </para> + </warning> + <section> + <title>Automatic Upgrades</title> + + <para> + You can keep a NixOS system up-to-date automatically by adding the following + to <filename>configuration.nix</filename>: <programlisting> -system.autoUpgrade.enable = true; +<xref linkend="opt-system.autoUpgrade.enable"/> = true; </programlisting> - -This enables a periodically executed systemd service named -<literal>nixos-upgrade.service</literal>. It runs -<command>nixos-rebuild switch --upgrade</command> to upgrade NixOS to -the latest version in the current channel. (To see when the service -runs, see <command>systemctl list-timers</command>.) You can also -specify a channel explicitly, e.g. - + This enables a periodically executed systemd service named + <literal>nixos-upgrade.service</literal>. It runs <command>nixos-rebuild + switch --upgrade</command> to upgrade NixOS to the latest version in the + current channel. (To see when the service runs, see <command>systemctl + list-timers</command>.) You can also specify a channel explicitly, e.g. <programlisting> -system.autoUpgrade.channel = https://nixos.org/channels/nixos-15.09; +<xref linkend="opt-system.autoUpgrade.channel"/> = https://nixos.org/channels/nixos-17.03; </programlisting> - -</para> - -</section> - - + </para> + </section> </chapter> diff --git a/nixos/doc/manual/man-configuration.xml b/nixos/doc/manual/man-configuration.xml index d49369d2c584..9f30b7925101 100644 --- a/nixos/doc/manual/man-configuration.xml +++ b/nixos/doc/manual/man-configuration.xml @@ -1,38 +1,31 @@ <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude"> - -<refmeta> - <refentrytitle><filename>configuration.nix</filename></refentrytitle> - <manvolnum>5</manvolnum> + <refmeta> + <refentrytitle><filename>configuration.nix</filename> + </refentrytitle><manvolnum>5</manvolnum> <refmiscinfo class="source">NixOS</refmiscinfo> - <!-- <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo> --> -</refmeta> - -<refnamediv> - <refname><filename>configuration.nix</filename></refname> - <refpurpose>NixOS system configuration specification</refpurpose> -</refnamediv> - - -<refsection><title>Description</title> - -<para>The file <filename>/etc/nixos/configuration.nix</filename> -contains the declarative specification of your NixOS system -configuration. The command <command>nixos-rebuild</command> takes -this file and realises the system configuration specified -therein.</para> - -</refsection> - - -<refsection><title>Options</title> - -<para>You can use the following options in -<filename>configuration.nix</filename>.</para> - -<xi:include href="options-db.xml" /> - -</refsection> - +<!-- <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo> --> + </refmeta> + <refnamediv> + <refname><filename>configuration.nix</filename> + </refname><refpurpose>NixOS system configuration specification</refpurpose> + </refnamediv> + <refsection> + <title>Description</title> + <para> + The file <filename>/etc/nixos/configuration.nix</filename> contains the + declarative specification of your NixOS system configuration. The command + <command>nixos-rebuild</command> takes this file and realises the system + configuration specified therein. + </para> + </refsection> + <refsection> + <title>Options</title> + <para> + You can use the following options in <filename>configuration.nix</filename>. + </para> + <xi:include href="./generated/options-db.xml" + xpointer="configuration-variable-list" /> + </refsection> </refentry> diff --git a/nixos/doc/manual/man-nixos-build-vms.xml b/nixos/doc/manual/man-nixos-build-vms.xml index f37677629d0c..87e4f3dae869 100644 --- a/nixos/doc/manual/man-nixos-build-vms.xml +++ b/nixos/doc/manual/man-nixos-build-vms.xml @@ -1,110 +1,120 @@ <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude"> - -<refmeta> - <refentrytitle><command>nixos-build-vms</command></refentrytitle> - <manvolnum>8</manvolnum> + <refmeta> + <refentrytitle><command>nixos-build-vms</command> + </refentrytitle><manvolnum>8</manvolnum> <refmiscinfo class="source">NixOS</refmiscinfo> - <!-- <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo> --> -</refmeta> - -<refnamediv> - <refname><command>nixos-build-vms</command></refname> - <refpurpose>build a network of virtual machines from a network of NixOS configurations</refpurpose> -</refnamediv> - -<refsynopsisdiv> +<!-- <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo> --> + </refmeta> + <refnamediv> + <refname><command>nixos-build-vms</command> + </refname><refpurpose>build a network of virtual machines from a network of NixOS configurations</refpurpose> + </refnamediv> + <refsynopsisdiv> <cmdsynopsis> - <command>nixos-build-vms</command> - <arg><option>--show-trace</option></arg> - <arg><option>--no-out-link</option></arg> - <arg><option>--help</option></arg> - <arg choice="plain"><replaceable>network.nix</replaceable></arg> + <command>nixos-build-vms</command> + <arg> + <option>--show-trace</option> + </arg> + + <arg> + <option>--no-out-link</option> + </arg> + + <arg> + <option>--help</option> + </arg> + + <arg choice="plain"> + <replaceable>network.nix</replaceable> + </arg> </cmdsynopsis> -</refsynopsisdiv> - -<refsection><title>Description</title> - -<para>This command builds a network of QEMU-KVM virtual machines of a Nix expression -specifying a network of NixOS machines. The virtual network can be started by -executing the <filename>bin/run-vms</filename> shell script that is generated by -this command. By default, a <filename>result</filename> symlink is produced that -points to the generated virtual network. -</para> - -<para>A network Nix expression has the following structure: - + </refsynopsisdiv> + <refsection> + <title>Description</title> + <para> + This command builds a network of QEMU-KVM virtual machines of a Nix + expression specifying a network of NixOS machines. The virtual network can + be started by executing the <filename>bin/run-vms</filename> shell script + that is generated by this command. By default, a <filename>result</filename> + symlink is produced that points to the generated virtual network. + </para> + <para> + A network Nix expression has the following structure: <screen> { test1 = {pkgs, config, ...}: { services.openssh.enable = true; - nixpkgs.system = "i686-linux"; + nixpkgs.localSystem.system = "i686-linux"; deployment.targetHost = "test1.example.net"; - + # Other NixOS options }; - + test2 = {pkgs, config, ...}: { services.openssh.enable = true; services.httpd.enable = true; environment.systemPackages = [ pkgs.lynx ]; - nixpkgs.system = "x86_64-linux"; + nixpkgs.localSystem.system = "x86_64-linux"; deployment.targetHost = "test2.example.net"; - + # Other NixOS options }; } </screen> - -Each attribute in the expression represents a machine in the network -(e.g. <varname>test1</varname> and <varname>test2</varname>) -referring to a function defining a NixOS configuration. -In each NixOS configuration, two attributes have a special meaning. -The <varname>deployment.targetHost</varname> specifies the address -(domain name or IP address) -of the system which is used by <command>ssh</command> to perform -remote deployment operations. The <varname>nixpkgs.system</varname> -attribute can be used to specify an architecture for the target machine, -such as <varname>i686-linux</varname> which builds a 32-bit NixOS -configuration. Omitting this property will build the configuration -for the same architecture as the host system. -</para> - -</refsection> - -<refsection><title>Options</title> - -<para>This command accepts the following options:</para> - -<variablelist> - - <varlistentry> - <term><option>--show-trace</option></term> + Each attribute in the expression represents a machine in the network (e.g. + <varname>test1</varname> and <varname>test2</varname>) referring to a + function defining a NixOS configuration. In each NixOS configuration, two + attributes have a special meaning. The + <varname>deployment.targetHost</varname> specifies the address (domain name + or IP address) of the system which is used by <command>ssh</command> to + perform remote deployment operations. The + <varname>nixpkgs.localSystem.system</varname> attribute can be used to + specify an architecture for the target machine, such as + <varname>i686-linux</varname> which builds a 32-bit NixOS configuration. + Omitting this property will build the configuration for the same + architecture as the host system. + </para> + </refsection> + <refsection> + <title>Options</title> + <para> + This command accepts the following options: + </para> + <variablelist> + <varlistentry> + <term> + <option>--show-trace</option> + </term> <listitem> - <para>Shows a trace of the output.</para> + <para> + Shows a trace of the output. + </para> </listitem> - </varlistentry> - - <varlistentry> - <term><option>--no-out-link</option></term> + </varlistentry> + <varlistentry> + <term> + <option>--no-out-link</option> + </term> <listitem> - <para>Do not create a 'result' symlink.</para> + <para> + Do not create a 'result' symlink. + </para> </listitem> - </varlistentry> - - <varlistentry> - <term><option>-h</option>, <option>--help</option></term> + </varlistentry> + <varlistentry> + <term> + <option>-h</option>, <option>--help</option> + </term> <listitem> - <para>Shows the usage of this command to the user.</para> + <para> + Shows the usage of this command to the user. + </para> </listitem> - </varlistentry> - -</variablelist> - -</refsection> - - + </varlistentry> + </variablelist> + </refsection> </refentry> diff --git a/nixos/doc/manual/man-nixos-enter.xml b/nixos/doc/manual/man-nixos-enter.xml new file mode 100644 index 000000000000..42edaa1ae5b6 --- /dev/null +++ b/nixos/doc/manual/man-nixos-enter.xml @@ -0,0 +1,138 @@ +<refentry xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude"> + <refmeta> + <refentrytitle><command>nixos-enter</command> + </refentrytitle><manvolnum>8</manvolnum> + <refmiscinfo class="source">NixOS</refmiscinfo> +<!-- <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo> --> + </refmeta> + <refnamediv> + <refname><command>nixos-enter</command> + </refname><refpurpose>run a command in a NixOS chroot environment</refpurpose> + </refnamediv> + <refsynopsisdiv> + <cmdsynopsis> + <command>nixos-enter</command> + <arg> + <arg choice='plain'> + <option>--root</option> + </arg> + <replaceable>root</replaceable> + </arg> + + <arg> + <arg choice='plain'> + <option>--system</option> + </arg> + <replaceable>system</replaceable> + </arg> + + <arg> + <arg choice='plain'> + <option>-c</option> + </arg> + <replaceable>shell-command</replaceable> + </arg> + + <arg> + <arg choice='plain'> + <option>--help</option> + </arg> + </arg> + + <arg> + <arg choice='plain'> + <option>--</option> + </arg> + <replaceable>arguments</replaceable> + </arg> + </cmdsynopsis> + </refsynopsisdiv> + <refsection> + <title>Description</title> + <para> + This command runs a command in a NixOS chroot environment, that is, in a + filesystem hierarchy previously prepared using + <command>nixos-install</command>. + </para> + </refsection> + <refsection> + <title>Options</title> + <para> + This command accepts the following options: + </para> + <variablelist> + <varlistentry> + <term> + <option>--root</option> + </term> + <listitem> + <para> + The path to the NixOS system you want to enter. It defaults to + <filename>/mnt</filename>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <option>--system</option> + </term> + <listitem> + <para> + The NixOS system configuration to use. It defaults to + <filename>/nix/var/nix/profiles/system</filename>. You can enter a + previous NixOS configuration by specifying a path such as + <filename>/nix/var/nix/profiles/system-106-link</filename>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <option>--command</option> + </term> + <term> + <option>-c</option> + </term> + <listitem> + <para> + The bash command to execute. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <option>--</option> + </term> + <listitem> + <para> + Interpret the remaining arguments as the program name and arguments to be + invoked. The program is not executed in a shell. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsection> + <refsection> + <title>Examples</title> + <para> + Start an interactive shell in the NixOS installation in + <filename>/mnt</filename>: + </para> +<screen> +# nixos-enter /mnt +</screen> + <para> + Run a shell command: + </para> +<screen> +# nixos-enter -c 'ls -l /; cat /proc/mounts' +</screen> + <para> + Run a non-shell command: + </para> +<screen> +# nixos-enter -- cat /proc/mounts +</screen> + </refsection> +</refentry> diff --git a/nixos/doc/manual/man-nixos-generate-config.xml b/nixos/doc/manual/man-nixos-generate-config.xml index e4fba4a40a97..1227873f5780 100644 --- a/nixos/doc/manual/man-nixos-generate-config.xml +++ b/nixos/doc/manual/man-nixos-generate-config.xml @@ -1,152 +1,164 @@ <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude"> - -<refmeta> - <refentrytitle><command>nixos-generate-config</command></refentrytitle> - <manvolnum>8</manvolnum> + <refmeta> + <refentrytitle><command>nixos-generate-config</command> + </refentrytitle><manvolnum>8</manvolnum> <refmiscinfo class="source">NixOS</refmiscinfo> - <!-- <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo> --> -</refmeta> - -<refnamediv> - <refname><command>nixos-generate-config</command></refname> - <refpurpose>generate NixOS configuration modules</refpurpose> -</refnamediv> - -<refsynopsisdiv> +<!-- <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo> --> + </refmeta> + <refnamediv> + <refname><command>nixos-generate-config</command> + </refname><refpurpose>generate NixOS configuration modules</refpurpose> + </refnamediv> + <refsynopsisdiv> <cmdsynopsis> - <command>nixos-generate-config</command> - <arg><option>--force</option></arg> - <arg> - <arg choice='plain'><option>--root</option></arg> - <replaceable>root</replaceable> + <command>nixos-generate-config</command> + <arg> + <option>--force</option> + </arg> + + <arg> + <arg choice='plain'> + <option>--root</option> </arg> - <arg> - <arg choice='plain'><option>--dir</option></arg> - <replaceable>dir</replaceable> + <replaceable>root</replaceable> + </arg> + + <arg> + <arg choice='plain'> + <option>--dir</option> </arg> + <replaceable>dir</replaceable> + </arg> </cmdsynopsis> -</refsynopsisdiv> - - -<refsection><title>Description</title> - -<para>This command writes two NixOS configuration modules: - -<variablelist> - - <varlistentry> - <term><option>/etc/nixos/hardware-configuration.nix</option></term> + </refsynopsisdiv> + <refsection> + <title>Description</title> + <para> + This command writes two NixOS configuration modules: + <variablelist> + <varlistentry> + <term> + <option>/etc/nixos/hardware-configuration.nix</option> + </term> + <listitem> + <para> + This module sets NixOS configuration options based on your current + hardware configuration. In particular, it sets the + <option>fileSystem</option> option to reflect all currently mounted file + systems, the <option>swapDevices</option> option to reflect active swap + devices, and the <option>boot.initrd.*</option> options to ensure that + the initial ramdisk contains any kernel modules necessary for mounting + the root file system. + </para> + <para> + If this file already exists, it is overwritten. Thus, you should not + modify it manually. Rather, you should include it from your + <filename>/etc/nixos/configuration.nix</filename>, and re-run + <command>nixos-generate-config</command> to update it whenever your + hardware configuration changes. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <option>/etc/nixos/configuration.nix</option> + </term> + <listitem> + <para> + This is the main NixOS system configuration module. If it already + exists, it’s left unchanged. Otherwise, + <command>nixos-generate-config</command> will write a template for you + to customise. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsection> + <refsection> + <title>Options</title> + <para> + This command accepts the following options: + </para> + <variablelist> + <varlistentry> + <term> + <option>--root</option> + </term> <listitem> - <para>This module sets NixOS configuration options based on your - current hardware configuration. In particular, it sets the - <option>fileSystem</option> option to reflect all currently - mounted file systems, the <option>swapDevices</option> option to - reflect active swap devices, and the - <option>boot.initrd.*</option> options to ensure that the - initial ramdisk contains any kernel modules necessary for - mounting the root file system.</para> - - <para>If this file already exists, it is overwritten. Thus, you - should not modify it manually. Rather, you should include it - from your <filename>/etc/nixos/configuration.nix</filename>, and - re-run <command>nixos-generate-config</command> to update it - whenever your hardware configuration changes.</para> + <para> + If this option is given, treat the directory + <replaceable>root</replaceable> as the root of the file system. This + means that configuration files will be written to + <filename><replaceable>root</replaceable>/etc/nixos</filename>, and that + any file systems outside of <replaceable>root</replaceable> are ignored + for the purpose of generating the <option>fileSystems</option> option. + </para> </listitem> - </varlistentry> - - <varlistentry> - <term><option>/etc/nixos/configuration.nix</option></term> + </varlistentry> + <varlistentry> + <term> + <option>--dir</option> + </term> <listitem> - <para>This is the main NixOS system configuration module. If it - already exists, it’s left unchanged. Otherwise, - <command>nixos-generate-config</command> will write a template - for you to customise.</para> + <para> + If this option is given, write the configuration files to the directory + <replaceable>dir</replaceable> instead of + <filename>/etc/nixos</filename>. + </para> </listitem> - </varlistentry> - -</variablelist> - -</para> - -</refsection> - - -<refsection><title>Options</title> - -<para>This command accepts the following options:</para> - -<variablelist> - - <varlistentry> - <term><option>--root</option></term> + </varlistentry> + <varlistentry> + <term> + <option>--force</option> + </term> <listitem> - <para>If this option is given, treat the directory - <replaceable>root</replaceable> as the root of the file system. - This means that configuration files will be written to - <filename><replaceable>root</replaceable>/etc/nixos</filename>, - and that any file systems outside of - <replaceable>root</replaceable> are ignored for the purpose of - generating the <option>fileSystems</option> option.</para> + <para> + Overwrite <filename>/etc/nixos/configuration.nix</filename> if it already + exists. + </para> </listitem> - </varlistentry> - - <varlistentry> - <term><option>--dir</option></term> + </varlistentry> + <varlistentry> + <term> + <option>--no-filesystems</option> + </term> <listitem> - <para>If this option is given, write the configuration files to - the directory <replaceable>dir</replaceable> instead of - <filename>/etc/nixos</filename>.</para> + <para> + Omit everything concerning file systems and swap devices from the + hardware configuration. + </para> </listitem> - </varlistentry> - - <varlistentry> - <term><option>--force</option></term> + </varlistentry> + <varlistentry> + <term> + <option>--show-hardware-config</option> + </term> <listitem> - <para>Overwrite - <filename>/etc/nixos/configuration.nix</filename> if it already - exists.</para> + <para> + Don't generate <filename>configuration.nix</filename> or + <filename>hardware-configuration.nix</filename> and print the hardware + configuration to stdout only. + </para> </listitem> - </varlistentry> - - <varlistentry> - <term><option>--no-filesystems</option></term> - <listitem> - <para>Omit everything concerning file system information - (which includes swap devices) from the hardware configuration.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--show-hardware-config</option></term> - <listitem> - <para>Don't generate <filename>configuration.nix</filename> or - <filename>hardware-configuration.nix</filename> and print the - hardware configuration to stdout only.</para> - </listitem> - </varlistentry> - -</variablelist> - -</refsection> - - -<refsection><title>Examples</title> - -<para>This command is typically used during NixOS installation to -write initial configuration modules. For example, if you created and -mounted the target file systems on <filename>/mnt</filename> and -<filename>/mnt/boot</filename>, you would run: - + </varlistentry> + </variablelist> + </refsection> + <refsection> + <title>Examples</title> + <para> + This command is typically used during NixOS installation to write initial + configuration modules. For example, if you created and mounted the target + file systems on <filename>/mnt</filename> and + <filename>/mnt/boot</filename>, you would run: <screen> $ nixos-generate-config --root /mnt </screen> - -The resulting file -<filename>/mnt/etc/nixos/hardware-configuration.nix</filename> might -look like this: - + The resulting file + <filename>/mnt/etc/nixos/hardware-configuration.nix</filename> might look + like this: <programlisting> # Do not modify this file! It was generated by ‘nixos-generate-config’ # and may be overwritten by future invocations. Please make changes @@ -165,13 +177,13 @@ look like this: fileSystems."/" = { device = "/dev/disk/by-label/nixos"; fsType = "ext3"; - options = "rw,data=ordered,relatime"; + options = [ "rw" "data=ordered" "relatime" ]; }; fileSystems."/boot" = { device = "/dev/sda1"; fsType = "ext3"; - options = "rw,errors=continue,user_xattr,acl,barrier=1,data=writeback,relatime"; + options = [ "rw" "errors=continue" "user_xattr" "acl" "barrier=1" "data=writeback" "relatime" ]; }; swapDevices = @@ -181,28 +193,22 @@ look like this: nix.maxJobs = 8; } </programlisting> - -It will also create a basic -<filename>/mnt/etc/nixos/configuration.nix</filename>, which you -should edit to customise the logical configuration of your system. -This file includes the result of the hardware scan as follows: - + It will also create a basic + <filename>/mnt/etc/nixos/configuration.nix</filename>, which you should edit + to customise the logical configuration of your system. This file includes + the result of the hardware scan as follows: <programlisting> imports = [ ./hardware-configuration.nix ]; </programlisting> -</para> - -<para>After installation, if your hardware configuration changes, you -can run: - + </para> + <para> + After installation, if your hardware configuration changes, you can run: <screen> $ nixos-generate-config </screen> - -to update <filename>/etc/nixos/hardware-configuration.nix</filename>. -Your <filename>/etc/nixos/configuration.nix</filename> will -<emphasis>not</emphasis> be overwritten.</para> - -</refsection> - + to update <filename>/etc/nixos/hardware-configuration.nix</filename>. Your + <filename>/etc/nixos/configuration.nix</filename> will + <emphasis>not</emphasis> be overwritten. + </para> + </refsection> </refentry> diff --git a/nixos/doc/manual/man-nixos-install.xml b/nixos/doc/manual/man-nixos-install.xml index 7ad1be1ec105..25f4f40613ac 100644 --- a/nixos/doc/manual/man-nixos-install.xml +++ b/nixos/doc/manual/man-nixos-install.xml @@ -1,185 +1,259 @@ <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude"> - -<refmeta> - <refentrytitle><command>nixos-install</command></refentrytitle> - <manvolnum>8</manvolnum> + <refmeta> + <refentrytitle><command>nixos-install</command> + </refentrytitle><manvolnum>8</manvolnum> <refmiscinfo class="source">NixOS</refmiscinfo> - <!-- <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo> --> -</refmeta> - -<refnamediv> - <refname><command>nixos-install</command></refname> - <refpurpose>install bootloader and NixOS</refpurpose> -</refnamediv> - -<refsynopsisdiv> +<!-- <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo> --> + </refmeta> + <refnamediv> + <refname><command>nixos-install</command> + </refname><refpurpose>install bootloader and NixOS</refpurpose> + </refnamediv> + <refsynopsisdiv> <cmdsynopsis> - <command>nixos-install</command> - <arg> - <arg choice='plain'><option>-I</option></arg> - <replaceable>path</replaceable> + <command>nixos-install</command> + <arg> + <arg choice='plain'> + <option>-I</option> </arg> - <arg> - <arg choice='plain'><option>--root</option></arg> - <replaceable>root</replaceable> + <replaceable>path</replaceable> + </arg> + + <arg> + <arg choice='plain'> + <option>--root</option> </arg> - <arg> - <group choice='req'> - <arg choice='plain'><option>--max-jobs</option></arg> - <arg choice='plain'><option>-j</option></arg> - </group> - <replaceable>number</replaceable> + <replaceable>root</replaceable> + </arg> + + <arg> + <arg choice='plain'> + <option>--system</option> </arg> - <arg> - <option>--cores</option> - <replaceable>number</replaceable> + <replaceable>path</replaceable> + </arg> + + <arg> + <arg choice='plain'> + <option>--no-channel-copy</option> </arg> - <arg> - <option>--option</option> - <replaceable>name</replaceable> - <replaceable>value</replaceable> + </arg> + + <arg> + <arg choice='plain'> + <option>--no-root-passwd</option> </arg> - <arg> - <arg choice='plain'><option>--show-trace</option></arg> + </arg> + + <arg> + <arg choice='plain'> + <option>--no-bootloader</option> </arg> - <arg> - <arg choice='plain'><option>--chroot</option></arg> + </arg> + + <arg> + <group choice='req'> + <arg choice='plain'> + <option>--max-jobs</option> </arg> - <arg> - <arg choice='plain'><option>--help</option></arg> + + <arg choice='plain'> + <option>-j</option> </arg> + </group> <replaceable>number</replaceable> + </arg> + + <arg> + <option>--cores</option> <replaceable>number</replaceable> + </arg> + + <arg> + <option>--option</option> <replaceable>name</replaceable> <replaceable>value</replaceable> + </arg> + + <arg> + <arg choice='plain'> + <option>--show-trace</option> + </arg> + </arg> + + <arg> + <arg choice='plain'> + <option>--help</option> + </arg> + </arg> </cmdsynopsis> -</refsynopsisdiv> - - -<refsection><title>Description</title> - -<para>This command installs NixOS in the file system mounted on -<filename>/mnt</filename>, based on the NixOS configuration specified -in <filename>/mnt/etc/nixos/configuration.nix</filename>. It performs -the following steps: - -<itemizedlist> - - <listitem><para>It copies Nix and its dependencies to - <filename>/mnt/nix/store</filename>.</para></listitem> - - <listitem><para>It runs Nix in <filename>/mnt</filename> to build - the NixOS configuration specified in - <filename>/mnt/etc/nixos/configuration.nix</filename>.</para></listitem> - - <listitem><para>It installs the GRUB boot loader on the device - specified in the option <option>boot.loader.grub.device</option>, - and generates a GRUB configuration file that boots into the NixOS - configuration just installed.</para></listitem> - - <listitem><para>It prompts you for a password for the root - account.</para></listitem> - -</itemizedlist> - -</para> - -<para>This command is idempotent: if it is interrupted or fails due to -a temporary problem (e.g. a network issue), you can safely re-run -it.</para> - -</refsection> - -<refsection><title>Options</title> - -<para>This command accepts the following options:</para> - -<variablelist> - - <varlistentry> - <term><option>--root</option></term> + </refsynopsisdiv> + <refsection> + <title>Description</title> + <para> + This command installs NixOS in the file system mounted on + <filename>/mnt</filename>, based on the NixOS configuration specified in + <filename>/mnt/etc/nixos/configuration.nix</filename>. It performs the + following steps: + <itemizedlist> + <listitem> + <para> + It copies Nix and its dependencies to + <filename>/mnt/nix/store</filename>. + </para> + </listitem> + <listitem> + <para> + It runs Nix in <filename>/mnt</filename> to build the NixOS configuration + specified in <filename>/mnt/etc/nixos/configuration.nix</filename>. + </para> + </listitem> + <listitem> + <para> + It installs the GRUB boot loader on the device specified in the option + <option>boot.loader.grub.device</option> (unless + <option>--no-bootloader</option> is specified), and generates a GRUB + configuration file that boots into the NixOS configuration just + installed. + </para> + </listitem> + <listitem> + <para> + It prompts you for a password for the root account (unless + <option>--no-root-passwd</option> is specified). + </para> + </listitem> + </itemizedlist> + </para> + <para> + This command is idempotent: if it is interrupted or fails due to a temporary + problem (e.g. a network issue), you can safely re-run it. + </para> + </refsection> + <refsection> + <title>Options</title> + <para> + This command accepts the following options: + </para> + <variablelist> + <varlistentry> + <term> + <option>--root</option> + </term> + <listitem> + <para> + Defaults to <filename>/mnt</filename>. If this option is given, treat the + directory <replaceable>root</replaceable> as the root of the NixOS + installation. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <option>--system</option> + </term> + <listitem> + <para> + If this option is provided, <command>nixos-install</command> will install + the specified closure rather than attempt to build one from + <filename>/mnt/etc/nixos/configuration.nix</filename>. + </para> + <para> + The closure must be an appropriately configured NixOS system, with boot + loader and partition configuration that fits the target host. Such a + closure is typically obtained with a command such as <command>nix-build + -I nixos-config=./configuration.nix '<nixos>' -A system + --no-out-link</command> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <option>-I</option> + </term> + <listitem> + <para> + Add a path to the Nix expression search path. This option may be given + multiple times. See the NIX_PATH environment variable for information on + the semantics of the Nix search path. Paths added through + <replaceable>-I</replaceable> take precedence over NIX_PATH. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <option>--max-jobs</option> + </term> + <term> + <option>-j</option> + </term> <listitem> - <para>Defaults to <filename>/mnt</filename>. If this option is given, treat the directory - <replaceable>root</replaceable> as the root of the NixOS installation. - </para> + <para> + Sets the maximum number of build jobs that Nix will perform in parallel + to the specified number. The default is <literal>1</literal>. A higher + value is useful on SMP systems or to exploit I/O latency. + </para> </listitem> - </varlistentry> - - <varlistentry> - <term><option>-I</option></term> + </varlistentry> + <varlistentry> + <term> + <option>--cores</option> + </term> <listitem> - <para>Add a path to the Nix expression search path. This option may be given multiple times. - See the NIX_PATH environment variable for information on the semantics of the Nix search path. - Paths added through <replaceable>-I</replaceable> take precedence over NIX_PATH.</para> + <para> + Sets the value of the <envar>NIX_BUILD_CORES</envar> environment variable + in the invocation of builders. Builders can use this variable at their + discretion to control the maximum amount of parallelism. For instance, in + Nixpkgs, if the derivation attribute + <varname>enableParallelBuilding</varname> is set to + <literal>true</literal>, the builder passes the + <option>-j<replaceable>N</replaceable></option> flag to GNU Make. The + value <literal>0</literal> means that the builder should use all + available CPU cores in the system. + </para> </listitem> - </varlistentry> - - <varlistentry><term><option>--max-jobs</option></term> - <term><option>-j</option></term> - - <listitem><para>Sets the maximum number of build jobs that Nix will - perform in parallel to the specified number. The default is <literal>1</literal>. - A higher value is useful on SMP systems or to exploit I/O latency.</para></listitem> - - </varlistentry> - - - <varlistentry><term><option>--cores</option></term> - - <listitem><para>Sets the value of the <envar>NIX_BUILD_CORES</envar> - environment variable in the invocation of builders. Builders can - use this variable at their discretion to control the maximum amount - of parallelism. For instance, in Nixpkgs, if the derivation - attribute <varname>enableParallelBuilding</varname> is set to - <literal>true</literal>, the builder passes the - <option>-j<replaceable>N</replaceable></option> flag to GNU Make. - The value <literal>0</literal> means that the builder should use all - available CPU cores in the system.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--option</option> <replaceable>name</replaceable> <replaceable>value</replaceable></term> - - <listitem><para>Set the Nix configuration option - <replaceable>name</replaceable> to <replaceable>value</replaceable>.</para></listitem> - - </varlistentry> - - <varlistentry> - <term><option>--show-trace</option></term> + </varlistentry> + <varlistentry> + <term> + <option>--option</option> <replaceable>name</replaceable> <replaceable>value</replaceable> + </term> <listitem> - <para>Causes Nix to print out a stack trace in case of Nix expression evaluation errors.</para> + <para> + Set the Nix configuration option <replaceable>name</replaceable> to + <replaceable>value</replaceable>. + </para> </listitem> - </varlistentry> - - <varlistentry> - <term><option>--chroot</option></term> + </varlistentry> + <varlistentry> + <term> + <option>--show-trace</option> + </term> <listitem> - <para>Chroot into given installation. Any additional arguments passed are going to be executed inside the chroot. - </para> + <para> + Causes Nix to print out a stack trace in case of Nix expression + evaluation errors. + </para> </listitem> - </varlistentry> - - <varlistentry> - <term><option>--help</option></term> + </varlistentry> + <varlistentry> + <term> + <option>--help</option> + </term> <listitem> - <para>Synonym for <command>man nixos-install</command>.</para> + <para> + Synonym for <command>man nixos-install</command>. + </para> </listitem> - </varlistentry> - -</variablelist> - -</refsection> - - -<refsection><title>Examples</title> - -<para>A typical NixOS installation is done by creating and mounting a -file system on <filename>/mnt</filename>, generating a NixOS -configuration in -<filename>/mnt/etc/nixos/configuration.nix</filename>, and running -<command>nixos-install</command>. For instance, if we want to install -NixOS on an <literal>ext4</literal> file system created in -<filename>/dev/sda1</filename>: - + </varlistentry> + </variablelist> + </refsection> + <refsection> + <title>Examples</title> + <para> + A typical NixOS installation is done by creating and mounting a file system + on <filename>/mnt</filename>, generating a NixOS configuration in + <filename>/mnt/etc/nixos/configuration.nix</filename>, and running + <command>nixos-install</command>. For instance, if we want to install NixOS + on an <literal>ext4</literal> file system created in + <filename>/dev/sda1</filename>: <screen> $ mkfs.ext4 /dev/sda1 $ mount /dev/sda1 /mnt @@ -188,9 +262,6 @@ $ # edit /mnt/etc/nixos/configuration.nix $ nixos-install $ reboot </screen> - -</para> - -</refsection> - + </para> + </refsection> </refentry> diff --git a/nixos/doc/manual/man-nixos-option.xml b/nixos/doc/manual/man-nixos-option.xml index 2875336c67e5..d436cce742a2 100644 --- a/nixos/doc/manual/man-nixos-option.xml +++ b/nixos/doc/manual/man-nixos-option.xml @@ -1,59 +1,108 @@ <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude"> - -<refmeta> - <refentrytitle><command>nixos-option</command></refentrytitle> - <manvolnum>8</manvolnum> + <refmeta> + <refentrytitle><command>nixos-option</command> + </refentrytitle><manvolnum>8</manvolnum> <refmiscinfo class="source">NixOS</refmiscinfo> - <!-- <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo> --> -</refmeta> - -<refnamediv> - <refname><command>nixos-option</command></refname> - <refpurpose>inspect a NixOS configuration</refpurpose> -</refnamediv> - -<refsynopsisdiv> +<!-- <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo> --> + </refmeta> + <refnamediv> + <refname><command>nixos-option</command> + </refname><refpurpose>inspect a NixOS configuration</refpurpose> + </refnamediv> + <refsynopsisdiv> <cmdsynopsis> - <command>nixos-option</command> - <arg choice='plain'><replaceable>option.name</replaceable></arg> + <command>nixos-option</command> + <arg> + <option>-I</option> <replaceable>path</replaceable> + </arg> + + <arg> + <option>--verbose</option> + </arg> + + <arg> + <option>--xml</option> + </arg> + + <arg choice="plain"> + <replaceable>option.name</replaceable> + </arg> </cmdsynopsis> -</refsynopsisdiv> - - -<refsection><title>Description</title> - -<para>This command evaluates the configuration specified in -<filename>/etc/nixos/configuration.nix</filename> and returns the properties -of the option name given as argument.</para> - -<para>When the option name is not an option, the command prints the list of -attributes contained in the attribute set.</para> - -</refsection> - -<refsection><title>Environment</title> - -<variablelist> - - <varlistentry> - <term><envar>NIXOS_CONFIG</envar></term> + </refsynopsisdiv> + <refsection> + <title>Description</title> + <para> + This command evaluates the configuration specified in + <filename>/etc/nixos/configuration.nix</filename> and returns the properties + of the option name given as argument. + </para> + <para> + When the option name is not an option, the command prints the list of + attributes contained in the attribute set. + </para> + </refsection> + <refsection> + <title>Options</title> + <para> + This command accepts the following options: + </para> + <variablelist> + <varlistentry> + <term> + <option>-I</option> <replaceable>path</replaceable> + </term> <listitem> - <para>Path to the main NixOS configuration module. Defaults to - <filename>/etc/nixos/configuration.nix</filename>.</para> + <para> + This option is passed to the underlying + <command>nix-instantiate</command> invocation. + </para> </listitem> - </varlistentry> - -</variablelist> - -</refsection> - - -<refsection><title>Examples</title> - -<para>Investigate option values: - + </varlistentry> + <varlistentry> + <term> + <option>--verbose</option> + </term> + <listitem> + <para> + This option enables verbose mode, which currently is just the Bash + <command>set</command> <option>-x</option> debug mode. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <option>--xml</option> + </term> + <listitem> + <para> + This option causes the output to be rendered as XML. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsection> + <refsection> + <title>Environment</title> + <variablelist> + <varlistentry> + <term> + <envar>NIXOS_CONFIG</envar> + </term> + <listitem> + <para> + Path to the main NixOS configuration module. Defaults to + <filename>/etc/nixos/configuration.nix</filename>. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsection> + <refsection> + <title>Examples</title> + <para> + Investigate option values: <screen>$ nixos-option boot.loader This attribute set contains: generationsDir @@ -64,7 +113,7 @@ $ nixos-option boot.loader.grub.enable Value: true -Default: +Default: true Description: @@ -75,16 +124,14 @@ Declared by: Defined by: "/nix/var/nix/profiles/per-user/root/channels/nixos/nixpkgs/nixos/modules/system/boot/loader/grub/grub.nix" -</screen></para> - -</refsection> - -<refsection><title>Bugs</title> - -<para>The author listed in the following section is wrong. If there is any - other bug, please report to Nicolas Pierron.</para> - -</refsection> - - +</screen> + </para> + </refsection> + <refsection> + <title>Bugs</title> + <para> + The author listed in the following section is wrong. If there is any other + bug, please report to Nicolas Pierron. + </para> + </refsection> </refentry> diff --git a/nixos/doc/manual/man-nixos-rebuild.xml b/nixos/doc/manual/man-nixos-rebuild.xml index c529737c3bf3..551a65f5e96b 100644 --- a/nixos/doc/manual/man-nixos-rebuild.xml +++ b/nixos/doc/manual/man-nixos-rebuild.xml @@ -1,348 +1,468 @@ <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude"> - -<refmeta> - <refentrytitle><command>nixos-rebuild</command></refentrytitle> - <manvolnum>8</manvolnum> + <refmeta> + <refentrytitle><command>nixos-rebuild</command> + </refentrytitle><manvolnum>8</manvolnum> <refmiscinfo class="source">NixOS</refmiscinfo> - <!-- <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo> --> -</refmeta> - -<refnamediv> - <refname><command>nixos-rebuild</command></refname> - <refpurpose>reconfigure a NixOS machine</refpurpose> -</refnamediv> - -<refsynopsisdiv> +<!-- <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo> --> + </refmeta> + <refnamediv> + <refname><command>nixos-rebuild</command> + </refname><refpurpose>reconfigure a NixOS machine</refpurpose> + </refnamediv> + <refsynopsisdiv> <cmdsynopsis> - <command>nixos-rebuild</command> - <group choice='req'> - <arg choice='plain'><option>switch</option></arg> - <arg choice='plain'><option>boot</option></arg> - <arg choice='plain'><option>test</option></arg> - <arg choice='plain'><option>build</option></arg> - <arg choice='plain'><option>dry-build</option></arg> - <arg choice='plain'><option>dry-activate</option></arg> - <arg choice='plain'><option>build-vm</option></arg> - <arg choice='plain'><option>build-vm-with-bootloader</option></arg> + <command>nixos-rebuild</command><group choice='req'> + <arg choice='plain'> + <option>switch</option> + </arg> + + <arg choice='plain'> + <option>boot</option> + </arg> + + <arg choice='plain'> + <option>test</option> + </arg> + + <arg choice='plain'> + <option>build</option> + </arg> + + <arg choice='plain'> + <option>dry-build</option> + </arg> + + <arg choice='plain'> + <option>dry-activate</option> + </arg> + + <arg choice='plain'> + <option>build-vm</option> + </arg> + + <arg choice='plain'> + <option>build-vm-with-bootloader</option> + </arg> </group> - <sbr /> - <arg><option>--upgrade</option></arg> - <arg><option>--install-grub</option></arg> - <arg><option>--no-build-nix</option></arg> - <arg><option>--fast</option></arg> - <arg><option>--rollback</option></arg> - <sbr /> - <arg> - <group choice='req'> - <arg choice='plain'><option>--profile-name</option></arg> - <arg choice='plain'><option>-p</option></arg> - </group> - <replaceable>name</replaceable> + <sbr /> + <arg> + <option>--upgrade</option> + </arg> + + <arg> + <option>--install-bootloader</option> + </arg> + + <arg> + <option>--no-build-nix</option> + </arg> + + <arg> + <option>--fast</option> + </arg> + + <arg> + <option>--rollback</option> + </arg> + <sbr /> + <arg> + <group choice='req'> + <arg choice='plain'> + <option>--profile-name</option> </arg> - <sbr /> - <arg><option>--show-trace</option></arg> + + <arg choice='plain'> + <option>-p</option> + </arg> + </group> <replaceable>name</replaceable> + </arg> + <sbr /> + <arg> + <option>--show-trace</option> + </arg> </cmdsynopsis> -</refsynopsisdiv> - - -<refsection><title>Description</title> - -<para>This command updates the system so that it corresponds to the -configuration specified in -<filename>/etc/nixos/configuration.nix</filename>. Thus, every time -you modify <filename>/etc/nixos/configuration.nix</filename> or any -NixOS module, you must run <command>nixos-rebuild</command> to make -the changes take effect. It builds the new system in -<filename>/nix/store</filename>, runs its activation script, and stop -and (re)starts any system services if needed.</para> - -<para>This command has one required argument, which specifies the -desired operation. It must be one of the following: - -<variablelist> - - <varlistentry> - <term><option>switch</option></term> - <listitem> - <para>Build and activate the new configuration, and make it the - boot default. That is, the configuration is added to the GRUB - boot menu as the default meny entry, so that subsequent reboots - will boot the system into the new configuration. Previous - configurations activated with <command>nixos-rebuild - switch</command> or <command>nixos-rebuild boot</command> remain - available in the GRUB menu.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>boot</option></term> - <listitem> - <para>Build the new configuration and make it the boot default - (as with <command>nixos-rebuild switch</command>), but do not - activate it. That is, the system continues to run the previous - configuration until the next reboot.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>test</option></term> - <listitem> - <para>Build and activate the new configuration, but do not add - it to the GRUB boot menu. Thus, if you reboot the system (or if - it crashes), you will automatically revert to the default - configuration (i.e. the configuration resulting from the last - call to <command>nixos-rebuild switch</command> or - <command>nixos-rebuild boot</command>).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>build</option></term> - <listitem> - <para>Build the new configuration, but neither activate it nor - add it to the GRUB boot menu. It leaves a symlink named - <filename>result</filename> in the current directory, which - points to the output of the top-level “system” derivation. This - is essentially the same as doing + </refsynopsisdiv> + <refsection> + <title>Description</title> + <para> + This command updates the system so that it corresponds to the configuration + specified in <filename>/etc/nixos/configuration.nix</filename>. Thus, every + time you modify <filename>/etc/nixos/configuration.nix</filename> or any + NixOS module, you must run <command>nixos-rebuild</command> to make the + changes take effect. It builds the new system in + <filename>/nix/store</filename>, runs its activation script, and stop and + (re)starts any system services if needed. + </para> + <para> + This command has one required argument, which specifies the desired + operation. It must be one of the following: + <variablelist> + <varlistentry> + <term> + <option>switch</option> + </term> + <listitem> + <para> + Build and activate the new configuration, and make it the boot default. + That is, the configuration is added to the GRUB boot menu as the default + menu entry, so that subsequent reboots will boot the system into the new + configuration. Previous configurations activated with + <command>nixos-rebuild switch</command> or <command>nixos-rebuild + boot</command> remain available in the GRUB menu. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <option>boot</option> + </term> + <listitem> + <para> + Build the new configuration and make it the boot default (as with + <command>nixos-rebuild switch</command>), but do not activate it. That + is, the system continues to run the previous configuration until the + next reboot. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <option>test</option> + </term> + <listitem> + <para> + Build and activate the new configuration, but do not add it to the GRUB + boot menu. Thus, if you reboot the system (or if it crashes), you will + automatically revert to the default configuration (i.e. the + configuration resulting from the last call to <command>nixos-rebuild + switch</command> or <command>nixos-rebuild boot</command>). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <option>build</option> + </term> + <listitem> + <para> + Build the new configuration, but neither activate it nor add it to the + GRUB boot menu. It leaves a symlink named <filename>result</filename> in + the current directory, which points to the output of the top-level + “system” derivation. This is essentially the same as doing <screen> $ nix-build /path/to/nixpkgs/nixos -A system </screen> - Note that you do not need to be <literal>root</literal> to run - <command>nixos-rebuild build</command>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>dry-build</option></term> - <listitem> - <para>Show what store paths would be built or downloaded by any - of the operations above, but otherwise do nothing.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>dry-activate</option></term> - <listitem> - <para>Build the new configuration, but instead of activating it, - show what changes would be performed by the activation (i.e. by - <command>nixos-rebuild test</command>). For - instance, this command will print which systemd units would be - restarted. The list of changes is not guaranteed to be - complete.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>build-vm</option></term> - <listitem> - <para>Build a script that starts a NixOS virtual machine with - the desired configuration. It leaves a symlink - <filename>result</filename> in the current directory that points - (under - <filename>result/bin/run-<replaceable>hostname</replaceable>-vm</filename>) - at the script that starts the VM. Thus, to test a NixOS - configuration in a virtual machine, you should do the following: + Note that you do not need to be <literal>root</literal> to run + <command>nixos-rebuild build</command>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <option>dry-build</option> + </term> + <listitem> + <para> + Show what store paths would be built or downloaded by any of the + operations above, but otherwise do nothing. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <option>dry-activate</option> + </term> + <listitem> + <para> + Build the new configuration, but instead of activating it, show what + changes would be performed by the activation (i.e. by + <command>nixos-rebuild test</command>). For instance, this command will + print which systemd units would be restarted. The list of changes is not + guaranteed to be complete. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <option>build-vm</option> + </term> + <listitem> + <para> + Build a script that starts a NixOS virtual machine with the desired + configuration. It leaves a symlink <filename>result</filename> in the + current directory that points (under + <filename>result/bin/run-<replaceable>hostname</replaceable>-vm</filename>) + at the script that starts the VM. Thus, to test a NixOS configuration in + a virtual machine, you should do the following: <screen> $ nixos-rebuild build-vm $ ./result/bin/run-*-vm -</screen></para> - - <para>The VM is implemented using the <literal>qemu</literal> - package. For best performance, you should load the - <literal>kvm-intel</literal> or <literal>kvm-amd</literal> - kernel modules to get hardware virtualisation.</para> - - <para>The VM mounts the Nix store of the host through the 9P - file system. The host Nix store is read-only, so Nix commands - that modify the Nix store will not work in the VM. This - includes commands such as <command>nixos-rebuild</command>; to - change the VM’s configuration, you must halt the VM and re-run - the commands above. +</screen> </para> - - <para>The VM has its own <literal>ext3</literal> root file - system, which is automatically created when the VM is first - started, and is persistent across reboots of the VM. It is - stored in - <literal>./<replaceable>hostname</replaceable>.qcow2</literal>. - <!-- The entire file system hierarchy of the host is available in - the VM under <filename>/hostfs</filename>.--></para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>build-vm-with-bootloader</option></term> - <listitem> - <para>Like <option>build-vm</option>, but boots using the - regular boot loader of your configuration (e.g., GRUB 1 or 2), - rather than booting directly into the kernel and initial ramdisk - of the system. This allows you to test whether the boot loader - works correctly. However, it does not guarantee that your NixOS - configuration will boot successfully on the host hardware (i.e., - after running <command>nixos-rebuild switch</command>), because - the hardware and boot loader configuration in the VM are - different. The boot loader is installed on an automatically - generated virtual disk containing a <filename>/boot</filename> - partition, which is mounted read-only in the VM.</para> - </listitem> - </varlistentry> - -</variablelist> - -</para> - - -</refsection> - - -<refsection><title>Options</title> - -<para>This command accepts the following options:</para> - -<variablelist> - - <varlistentry> - <term><option>--upgrade</option></term> + <para> + The VM is implemented using the <literal>qemu</literal> package. For + best performance, you should load the <literal>kvm-intel</literal> or + <literal>kvm-amd</literal> kernel modules to get hardware + virtualisation. + </para> + <para> + The VM mounts the Nix store of the host through the 9P file system. The + host Nix store is read-only, so Nix commands that modify the Nix store + will not work in the VM. This includes commands such as + <command>nixos-rebuild</command>; to change the VM’s configuration, + you must halt the VM and re-run the commands above. + </para> + <para> + The VM has its own <literal>ext3</literal> root file system, which is + automatically created when the VM is first started, and is persistent + across reboots of the VM. It is stored in + <literal>./<replaceable>hostname</replaceable>.qcow2</literal>. +<!-- The entire file system hierarchy of the host is available in + the VM under <filename>/hostfs</filename>.--> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <option>build-vm-with-bootloader</option> + </term> + <listitem> + <para> + Like <option>build-vm</option>, but boots using the regular boot loader + of your configuration (e.g., GRUB 1 or 2), rather than booting directly + into the kernel and initial ramdisk of the system. This allows you to + test whether the boot loader works correctly. However, it does not + guarantee that your NixOS configuration will boot successfully on the + host hardware (i.e., after running <command>nixos-rebuild + switch</command>), because the hardware and boot loader configuration in + the VM are different. The boot loader is installed on an automatically + generated virtual disk containing a <filename>/boot</filename> + partition, which is mounted read-only in the VM. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsection> + <refsection> + <title>Options</title> + <para> + This command accepts the following options: + </para> + <variablelist> + <varlistentry> + <term> + <option>--upgrade</option> + </term> <listitem> - <para>Fetch the latest version of NixOS from the NixOS - channel.</para> + <para> + Fetch the latest version of NixOS from the NixOS channel. + </para> </listitem> - </varlistentry> - - <varlistentry> - <term><option>--install-grub</option></term> + </varlistentry> + <varlistentry> + <term> + <option>--install-bootloader</option> + </term> <listitem> - <para>Causes the GRUB boot loader to be (re)installed on the - device specified by the - <varname>boot.loader.grub.device</varname> configuration - option.</para> + <para> + Causes the boot loader to be (re)installed on the device specified by the + relevant configuration options. + </para> </listitem> - </varlistentry> - - <varlistentry> - <term><option>--no-build-nix</option></term> + </varlistentry> + <varlistentry> + <term> + <option>--no-build-nix</option> + </term> <listitem> - <para>Normally, <command>nixos-rebuild</command> first builds - the <varname>nixUnstable</varname> attribute in Nixpkgs, and - uses the resulting instance of the Nix package manager to build - the new system configuration. This is necessary if the NixOS - modules use features not provided by the currently installed - version of Nix. This option disables building a new Nix.</para> + <para> + Normally, <command>nixos-rebuild</command> first builds the + <varname>nixUnstable</varname> attribute in Nixpkgs, and uses the + resulting instance of the Nix package manager to build the new system + configuration. This is necessary if the NixOS modules use features not + provided by the currently installed version of Nix. This option disables + building a new Nix. + </para> </listitem> - </varlistentry> - - <varlistentry> - <term><option>--fast</option></term> + </varlistentry> + <varlistentry> + <term> + <option>--fast</option> + </term> <listitem> - <para>Equivalent to <option>--no-build-nix</option> - <option>--show-trace</option>. This option is useful if you - call <command>nixos-rebuild</command> frequently (e.g. if you’re - hacking on a NixOS module).</para> + <para> + Equivalent to <option>--no-build-nix</option> + <option>--show-trace</option>. This option is useful if you call + <command>nixos-rebuild</command> frequently (e.g. if you’re hacking on + a NixOS module). + </para> </listitem> - </varlistentry> - - <varlistentry> - <term><option>--rollback</option></term> + </varlistentry> + <varlistentry> + <term> + <option>--rollback</option> + </term> <listitem> - <para>Instead of building a new configuration as specified by - <filename>/etc/nixos/configuration.nix</filename>, roll back to - the previous configuration. (The previous configuration is - defined as the one before the “current” generation of the - Nix profile <filename>/nix/var/nix/profiles/system</filename>.)</para> + <para> + Instead of building a new configuration as specified by + <filename>/etc/nixos/configuration.nix</filename>, roll back to the + previous configuration. (The previous configuration is defined as the one + before the “current” generation of the Nix profile + <filename>/nix/var/nix/profiles/system</filename>.) + </para> </listitem> - </varlistentry> - - <varlistentry> - <term><option>--profile-name</option></term> - <term><option>-p</option></term> + </varlistentry> + <varlistentry> + <term> + <option>--profile-name</option> + </term> + <term> + <option>-p</option> + </term> <listitem> - <para>Instead of using the Nix profile - <filename>/nix/var/nix/profiles/system</filename> to keep track - of the current and previous system configurations, use + <para> + Instead of using the Nix profile + <filename>/nix/var/nix/profiles/system</filename> to keep track of the + current and previous system configurations, use <filename>/nix/var/nix/profiles/system-profiles/<replaceable>name</replaceable></filename>. - When you use GRUB 2, for every system profile created with this - flag, NixOS will create a submenu named “NixOS - Profile - '<replaceable>name</replaceable>'” in GRUB’s boot menu, - containing the current and previous configurations of this - profile.</para> - - <para>For instance, if you want to test a configuration file - named <filename>test.nix</filename> without affecting the - default system profile, you would do: - + When you use GRUB 2, for every system profile created with this flag, + NixOS will create a submenu named “NixOS - Profile + '<replaceable>name</replaceable>'” in GRUB’s boot menu, containing + the current and previous configurations of this profile. + </para> + <para> + For instance, if you want to test a configuration file named + <filename>test.nix</filename> without affecting the default system + profile, you would do: <screen> $ nixos-rebuild switch -p test -I nixos-config=./test.nix </screen> - - The new configuration will appear in the GRUB 2 submenu “NixOS - Profile - 'test'”.</para> + The new configuration will appear in the GRUB 2 submenu “NixOS - + Profile 'test'”. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <option>--build-host</option> + </term> + <listitem> + <para> + Instead of building the new configuration locally, use the specified host + to perform the build. The host needs to be accessible with ssh, and must + be able to perform Nix builds. If the option + <option>--target-host</option> is not set, the build will be copied back + to the local machine when done. + </para> + <para> + Note that, if <option>--no-build-nix</option> is not specified, Nix will + be built both locally and remotely. This is because the configuration + will always be evaluated locally even though the building might be + performed remotely. + </para> + <para> + You can include a remote user name in the host name + (<replaceable>user@host</replaceable>). You can also set ssh options by + defining the <envar>NIX_SSHOPTS</envar> environment variable. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <option>--target-host</option> + </term> + <listitem> + <para> + Specifies the NixOS target host. By setting this to something other than + <replaceable>localhost</replaceable>, the system activation will happen + on the remote host instead of the local machine. The remote host needs to + be accessible over ssh, and for the commands <option>switch</option>, + <option>boot</option> and <option>test</option> you need root access. + </para> + <para> + If <option>--build-host</option> is not explicitly specified, + <option>--build-host</option> will implicitly be set to the same value as + <option>--target-host</option>. So, if you only specify + <option>--target-host</option> both building and activation will take + place remotely (and no build artifacts will be copied to the local + machine). + </para> + <para> + You can include a remote user name in the host name + (<replaceable>user@host</replaceable>). You can also set ssh options by + defining the <envar>NIX_SSHOPTS</envar> environment variable. + </para> + </listitem> + </varlistentry> + </variablelist> + <para> + In addition, <command>nixos-rebuild</command> accepts various Nix-related + flags, including <option>--max-jobs</option> / <option>-j</option>, + <option>--show-trace</option>, <option>--keep-failed</option>, + <option>--keep-going</option> and <option>--verbose</option> / + <option>-v</option>. See the Nix manual for details. + </para> + </refsection> + <refsection> + <title>Environment</title> + <variablelist> + <varlistentry> + <term> + <envar>NIXOS_CONFIG</envar> + </term> + <listitem> + <para> + Path to the main NixOS configuration module. Defaults to + <filename>/etc/nixos/configuration.nix</filename>. + </para> </listitem> - </varlistentry> - -</variablelist> - -<para>In addition, <command>nixos-rebuild</command> accepts various -Nix-related flags, including <option>--max-jobs</option> / -<option>-j</option>, <option>--show-trace</option>, -<option>--keep-failed</option>, <option>--keep-going</option> and -<option>--verbose</option> / <option>-v</option>. See -the Nix manual for details.</para> - -</refsection> - - -<refsection><title>Environment</title> - -<variablelist> - - <varlistentry> - <term><envar>NIXOS_CONFIG</envar></term> + </varlistentry> + <varlistentry> + <term> + <envar>NIX_SSHOPTS</envar> + </term> <listitem> - <para>Path to the main NixOS configuration module. Defaults to - <filename>/etc/nixos/configuration.nix</filename>.</para> + <para> + Additional options to be passed to <command>ssh</command> on the command + line. + </para> </listitem> - </varlistentry> - -</variablelist> - -</refsection> - - -<refsection><title>Files</title> - -<variablelist> - - <varlistentry> - <term><filename>/run/current-system</filename></term> + </varlistentry> + </variablelist> + </refsection> + <refsection> + <title>Files</title> + <variablelist> + <varlistentry> + <term> + <filename>/run/current-system</filename> + </term> <listitem> - <para>A symlink to the currently active system configuration in - the Nix store.</para> + <para> + A symlink to the currently active system configuration in the Nix store. + </para> </listitem> - </varlistentry> - - <varlistentry> - <term><filename>/nix/var/nix/profiles/system</filename></term> + </varlistentry> + <varlistentry> + <term> + <filename>/nix/var/nix/profiles/system</filename> + </term> <listitem> - <para>The Nix profile that contains the current and previous - system configurations. Used to generate the GRUB boot - menu.</para> + <para> + The Nix profile that contains the current and previous system + configurations. Used to generate the GRUB boot menu. + </para> </listitem> - </varlistentry> - -</variablelist> - -</refsection> - - -<refsection><title>Bugs</title> - -<para>This command should be renamed to something more -descriptive.</para> - -</refsection> - - - + </varlistentry> + </variablelist> + </refsection> + <refsection> + <title>Bugs</title> + <para> + This command should be renamed to something more descriptive. + </para> + </refsection> </refentry> diff --git a/nixos/doc/manual/man-nixos-version.xml b/nixos/doc/manual/man-nixos-version.xml new file mode 100644 index 000000000000..931c4a5ad029 --- /dev/null +++ b/nixos/doc/manual/man-nixos-version.xml @@ -0,0 +1,112 @@ +<refentry xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude"> + <refmeta> + <refentrytitle><command>nixos-version</command> + </refentrytitle><manvolnum>8</manvolnum> + <refmiscinfo class="source">NixOS</refmiscinfo> + </refmeta> + <refnamediv> + <refname><command>nixos-version</command> + </refname><refpurpose>show the NixOS version</refpurpose> + </refnamediv> + <refsynopsisdiv> + <cmdsynopsis> + <command>nixos-version</command> + <arg> + <option>--hash</option> + </arg> + + <arg> + <option>--revision</option> + </arg> + </cmdsynopsis> + </refsynopsisdiv> + <refsection> + <title>Description</title> + <para> + This command shows the version of the currently active NixOS configuration. + For example: +<screen>$ nixos-version +16.03.1011.6317da4 (Emu) +</screen> + The version consists of the following elements: + <variablelist> + <varlistentry> + <term> + <literal>16.03</literal> + </term> + <listitem> + <para> + The NixOS release, indicating the year and month in which it was + released (e.g. March 2016). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <literal>1011</literal> + </term> + <listitem> + <para> + The number of commits in the Nixpkgs Git repository between the start of + the release branch and the commit from which this version was built. + This ensures that NixOS versions are monotonically increasing. It is + <literal>git</literal> when the current NixOS configuration was built + from a checkout of the Nixpkgs Git repository rather than from a NixOS + channel. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <literal>6317da4</literal> + </term> + <listitem> + <para> + The first 7 characters of the commit in the Nixpkgs Git repository from + which this version was built. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <literal>Emu</literal> + </term> + <listitem> + <para> + The code name of the NixOS release. The first letter of the code name + indicates that this is the N'th stable NixOS release; for example, Emu + is the fifth release. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsection> + <refsection> + <title>Options</title> + <para> + This command accepts the following options: + </para> + <variablelist> + <varlistentry> + <term> + <option>--hash</option> + </term> + <term> + <option>--revision</option> + </term> + <listitem> + <para> + Show the full SHA1 hash of the Git commit from which this configuration + was built, e.g. +<screen>$ nixos-version --hash +6317da40006f6bc2480c6781999c52d88dde2acf +</screen> + </para> + </listitem> + </varlistentry> + </variablelist> + </refsection> +</refentry> diff --git a/nixos/doc/manual/man-pages.xml b/nixos/doc/manual/man-pages.xml index 97a2c16d406e..0390dda6468f 100644 --- a/nixos/doc/manual/man-pages.xml +++ b/nixos/doc/manual/man-pages.xml @@ -1,31 +1,20 @@ <reference xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude"> - - <title>NixOS Reference Pages</title> - - <info> - - <author> - <personname> - <firstname>Eelco</firstname> - <surname>Dolstra</surname> - </personname> - <contrib>Author</contrib> - </author> - - <copyright> - <year>2007-2015</year> - <holder>Eelco Dolstra</holder> - </copyright> - - </info> - - <xi:include href="man-configuration.xml" /> - <xi:include href="man-nixos-build-vms.xml" /> - <xi:include href="man-nixos-generate-config.xml" /> - <xi:include href="man-nixos-install.xml" /> - <xi:include href="man-nixos-option.xml" /> - <xi:include href="man-nixos-rebuild.xml" /> - + <title>NixOS Reference Pages</title> + <info> + <author><personname><firstname>Eelco</firstname><surname>Dolstra</surname></personname> + <contrib>Author</contrib> + </author> + <copyright><year>2007-2018</year><holder>Eelco Dolstra</holder> + </copyright> + </info> + <xi:include href="man-configuration.xml" /> + <xi:include href="man-nixos-build-vms.xml" /> + <xi:include href="man-nixos-generate-config.xml" /> + <xi:include href="man-nixos-install.xml" /> + <xi:include href="man-nixos-enter.xml" /> + <xi:include href="man-nixos-option.xml" /> + <xi:include href="man-nixos-rebuild.xml" /> + <xi:include href="man-nixos-version.xml" /> </reference> diff --git a/nixos/doc/manual/manual.xml b/nixos/doc/manual/manual.xml index 736d1d4eff71..61b21203f500 100644 --- a/nixos/doc/manual/manual.xml +++ b/nixos/doc/manual/manual.xml @@ -3,42 +3,46 @@ xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="book-nixos-manual"> - - <info> - <title>NixOS Manual</title> - <subtitle>Version <xi:include href="version" parse="text" /></subtitle> - </info> - - <preface> - <title>Preface</title> - - <para>This manual describes how to install, use and extend NixOS, - a Linux distribution based on the purely functional package - management system Nix.</para> - - <para>If you encounter problems, please report them on the - <literal - xlink:href="http://lists.science.uu.nl/mailman/listinfo/nix-dev">nix-dev@lists.science.uu.nl</literal> - mailing list or on the <link + <info> + <title>NixOS Manual</title> + <subtitle>Version <xi:include href="./generated/version" parse="text" /> + </subtitle> + </info> + <preface> + <title>Preface</title> + <para> + This manual describes how to install, use and extend NixOS, a Linux + distribution based on the purely functional package management system Nix. + </para> + <para> + If you encounter problems, please report them on the + <literal + xlink:href="https://groups.google.com/forum/#!forum/nix-devel">nix-devel</literal> + mailing list or on the <link xlink:href="irc://irc.freenode.net/#nixos"> - <literal>#nixos</literal> channel on Freenode</link>. Bugs should - be reported in <link - xlink:href="https://github.com/NixOS/nixpkgs/issues">NixOS’ GitHub - issue tracker</link>.</para> - - </preface> - - <xi:include href="installation/installation.xml" /> - <xi:include href="configuration/configuration.xml" /> - <xi:include href="administration/running.xml" /> - <!-- <xi:include href="userconfiguration.xml" /> --> - <xi:include href="development/development.xml" /> - - <appendix xml:id="ch-options"> - <title>Configuration Options</title> - <xi:include href="options-db.xml" /> - </appendix> - - <xi:include href="release-notes/release-notes.xml" /> - + <literal>#nixos</literal> channel on Freenode</link>. Bugs should be + reported in + <link + xlink:href="https://github.com/NixOS/nixpkgs/issues">NixOS’ + GitHub issue tracker</link>. + </para> + <note> + <para> + Commands prefixed with <literal>#</literal> have to be run as root, either + requiring to login as root user or temporarily switching to it using + <literal>sudo</literal> for example. + </para> + </note> + </preface> + <xi:include href="installation/installation.xml" /> + <xi:include href="configuration/configuration.xml" /> + <xi:include href="administration/running.xml" /> +<!-- <xi:include href="userconfiguration.xml" /> --> + <xi:include href="development/development.xml" /> + <appendix xml:id="ch-options"> + <title>Configuration Options</title> + <xi:include href="./generated/options-db.xml" + xpointer="configuration-variable-list" /> + </appendix> + <xi:include href="release-notes/release-notes.xml" /> </book> diff --git a/nixos/doc/manual/options-to-docbook.xsl b/nixos/doc/manual/options-to-docbook.xsl index cd30ae36ae59..43a69806a2b0 100644 --- a/nixos/doc/manual/options-to-docbook.xsl +++ b/nixos/doc/manual/options-to-docbook.xsl @@ -11,12 +11,13 @@ <xsl:output method='xml' encoding="UTF-8" /> <xsl:param name="revision" /> + <xsl:param name="program" /> <xsl:template match="/expr/list"> - - <variablelist> - + <appendix> + <title>Configuration Options</title> + <variablelist xml:id="configuration-variable-list"> <xsl:for-each select="attrs"> <xsl:variable name="id" select="concat('opt-', str:replace(str:replace(str:replace(str:replace(attr[@name = 'name']/string/@value, '*', '_'), '<', '_'), '>', '_'), '?', '_'))" /> <varlistentry> @@ -69,6 +70,15 @@ </para> </xsl:if> + <xsl:if test="attr[@name = 'relatedPackages']"> + <para> + <emphasis>Related packages:</emphasis> + <xsl:text> </xsl:text> + <xsl:value-of disable-output-escaping="yes" + select="attr[@name = 'relatedPackages']/string/@value" /> + </para> + </xsl:if> + <xsl:if test="count(attr[@name = 'declarations']/list/*) != 0"> <para> <emphasis>Declared by:</emphasis> @@ -90,7 +100,7 @@ </xsl:for-each> </variablelist> - + </appendix> </xsl:template> @@ -188,7 +198,7 @@ </xsl:otherwise> </xsl:choose> </xsl:when> - <xsl:when test="$revision != 'local' and contains(@value, 'nixops') and contains(@value, '/nix/')"> + <xsl:when test="$revision != 'local' and $program = 'nixops' and contains(@value, '/nix/')"> <xsl:attribute name="xlink:href">https://github.com/NixOS/nixops/blob/<xsl:value-of select="$revision"/>/nix/<xsl:value-of select="substring-after(@value, '/nix/')"/></xsl:attribute> </xsl:when> <xsl:otherwise> diff --git a/nixos/doc/manual/release-notes/release-notes.xml b/nixos/doc/manual/release-notes/release-notes.xml index 6ed99315a7af..94f176186b6e 100644 --- a/nixos/doc/manual/release-notes/release-notes.xml +++ b/nixos/doc/manual/release-notes/release-notes.xml @@ -3,16 +3,19 @@ xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="ch-release-notes"> - -<title>Release Notes</title> - -<para>This section lists the release notes for each stable version of NixOS -and current unstable revision.</para> - -<xi:include href="rl-unstable.xml" /> -<xi:include href="rl-1509.xml" /> -<xi:include href="rl-1412.xml" /> -<xi:include href="rl-1404.xml" /> -<xi:include href="rl-1310.xml" /> - + <title>Release Notes</title> + <para> + This section lists the release notes for each stable version of NixOS and + current unstable revision. + </para> + <xi:include href="rl-1809.xml" /> + <xi:include href="rl-1803.xml" /> + <xi:include href="rl-1709.xml" /> + <xi:include href="rl-1703.xml" /> + <xi:include href="rl-1609.xml" /> + <xi:include href="rl-1603.xml" /> + <xi:include href="rl-1509.xml" /> + <xi:include href="rl-1412.xml" /> + <xi:include href="rl-1404.xml" /> + <xi:include href="rl-1310.xml" /> </appendix> diff --git a/nixos/doc/manual/release-notes/rl-1310.xml b/nixos/doc/manual/release-notes/rl-1310.xml index 583912d70738..248bab70c36b 100644 --- a/nixos/doc/manual/release-notes/rl-1310.xml +++ b/nixos/doc/manual/release-notes/rl-1310.xml @@ -3,9 +3,9 @@ xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="sec-release-13.10"> + <title>Release 13.10 (“Aardvark”, 2013/10/31)</title> -<title>Release 13.10 (“Aardvark”, 2013/10/31)</title> - -<para>This is the first stable release branch of NixOS.</para> - + <para> + This is the first stable release branch of NixOS. + </para> </section> diff --git a/nixos/doc/manual/release-notes/rl-1404.xml b/nixos/doc/manual/release-notes/rl-1404.xml index 36f67ed88b0b..8d8cea4303a3 100644 --- a/nixos/doc/manual/release-notes/rl-1404.xml +++ b/nixos/doc/manual/release-notes/rl-1404.xml @@ -3,158 +3,177 @@ xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="sec-release-14.04"> - -<title>Release 14.04 (“Baboon”, 2014/04/30)</title> - -<para>This is the second stable release branch of NixOS. In addition -to numerous new and upgraded packages and modules, this release has -the following highlights: - -<itemizedlist> - - <listitem><para>Installation on UEFI systems is now supported. See - <xref linkend="sec-uefi-installation"/> for - details.</para></listitem> - - <listitem><para>Systemd has been updated to version 212, which has - <link xlink:href="http://cgit.freedesktop.org/systemd/systemd/plain/NEWS?id=v212">numerous - improvements</link>. NixOS now automatically starts systemd user - instances when you log in. You can define global user units through - the <option>systemd.unit.*</option> options.</para></listitem> - - <listitem><para>NixOS is now based on Glibc 2.19 and GCC - 4.8.</para></listitem> - - <listitem><para>The default Linux kernel has been updated to - 3.12.</para></listitem> - - <listitem><para>KDE has been updated to 4.12.</para></listitem> - - <listitem><para>GNOME 3.10 experimental support has been added.</para></listitem> - - <listitem><para>Nix has been updated to 1.7 (<link - xlink:href="http://nixos.org/nix/manual/#ssec-relnotes-1.7">details</link>).</para></listitem> - - <listitem><para>NixOS now supports fully declarative management of - users and groups. If you set <option>users.mutableUsers</option> to - <literal>false</literal>, then the contents of - <filename>/etc/passwd</filename> and <filename>/etc/group</filename> - will be <link + <title>Release 14.04 (“Baboon”, 2014/04/30)</title> + + <para> + This is the second stable release branch of NixOS. In addition to numerous + new and upgraded packages and modules, this release has the following + highlights: + <itemizedlist> + <listitem> + <para> + Installation on UEFI systems is now supported. See + <xref linkend="sec-installation"/> for details. + </para> + </listitem> + <listitem> + <para> + Systemd has been updated to version 212, which has + <link xlink:href="http://cgit.freedesktop.org/systemd/systemd/plain/NEWS?id=v212">numerous + improvements</link>. NixOS now automatically starts systemd user instances + when you log in. You can define global user units through the + <option>systemd.unit.*</option> options. + </para> + </listitem> + <listitem> + <para> + NixOS is now based on Glibc 2.19 and GCC 4.8. + </para> + </listitem> + <listitem> + <para> + The default Linux kernel has been updated to 3.12. + </para> + </listitem> + <listitem> + <para> + KDE has been updated to 4.12. + </para> + </listitem> + <listitem> + <para> + GNOME 3.10 experimental support has been added. + </para> + </listitem> + <listitem> + <para> + Nix has been updated to 1.7 + (<link + xlink:href="http://nixos.org/nix/manual/#ssec-relnotes-1.7">details</link>). + </para> + </listitem> + <listitem> + <para> + NixOS now supports fully declarative management of users and groups. If + you set <option>users.mutableUsers</option> to <literal>false</literal>, + then the contents of <filename>/etc/passwd</filename> and + <filename>/etc/group</filename> will be + <link xlink:href="https://www.usenix.org/legacy/event/lisa02/tech/full_papers/traugott/traugott_html/">congruent</link> - to your NixOS configuration. For instance, if you remove a user from - <option>users.extraUsers</option> and run - <command>nixos-rebuild</command>, the user account will cease to - exist. Also, imperative commands for managing users and groups, such - as <command>useradd</command>, are no longer available. If - <option>users.mutableUsers</option> is <literal>true</literal> (the - default), then behaviour is unchanged from NixOS - 13.10.</para></listitem> - - <listitem><para>NixOS now has basic container support, meaning you - can easily run a NixOS instance as a container in a NixOS host - system. These containers are suitable for testing and - experimentation but not production use, since they’re not fully - isolated from the host. See <xref linkend="ch-containers"/> for - details.</para></listitem> - - <listitem><para>Systemd units provided by packages can now be - overridden from the NixOS configuration. For instance, if a package - <literal>foo</literal> provides systemd units, you can say: - + to your NixOS configuration. For instance, if you remove a user from + <option>users.extraUsers</option> and run + <command>nixos-rebuild</command>, the user account will cease to exist. + Also, imperative commands for managing users and groups, such as + <command>useradd</command>, are no longer available. If + <option>users.mutableUsers</option> is <literal>true</literal> (the + default), then behaviour is unchanged from NixOS 13.10. + </para> + </listitem> + <listitem> + <para> + NixOS now has basic container support, meaning you can easily run a NixOS + instance as a container in a NixOS host system. These containers are + suitable for testing and experimentation but not production use, since + they’re not fully isolated from the host. See + <xref linkend="ch-containers"/> for details. + </para> + </listitem> + <listitem> + <para> + Systemd units provided by packages can now be overridden from the NixOS + configuration. For instance, if a package <literal>foo</literal> provides + systemd units, you can say: <programlisting> systemd.packages = [ pkgs.foo ]; </programlisting> - - to enable those units. You can then set or override unit options in - the usual way, e.g. - + to enable those units. You can then set or override unit options in the + usual way, e.g. <programlisting> systemd.services.foo.wantedBy = [ "multi-user.target" ]; systemd.services.foo.serviceConfig.MemoryLimit = "512M"; </programlisting> - - </para></listitem> - -</itemizedlist> - -</para> - -<para>When upgrading from a previous release, please be aware of the -following incompatible changes: - -<itemizedlist> - - <listitem><para>Nixpkgs no longer exposes unfree packages by - default. If your NixOS configuration requires unfree packages from - Nixpkgs, you need to enable support for them explicitly by setting: - + </para> + </listitem> + </itemizedlist> + </para> + + <para> + When upgrading from a previous release, please be aware of the following + incompatible changes: + <itemizedlist> + <listitem> + <para> + Nixpkgs no longer exposes unfree packages by default. If your NixOS + configuration requires unfree packages from Nixpkgs, you need to enable + support for them explicitly by setting: <programlisting> nixpkgs.config.allowUnfree = true; </programlisting> - - Otherwise, you get an error message such as: - + Otherwise, you get an error message such as: <screen> error: package ‘nvidia-x11-331.49-3.12.17’ in ‘…/nvidia-x11/default.nix:56’ has an unfree license, refusing to evaluate </screen> - - </para></listitem> - - <listitem><para>The Adobe Flash player is no longer enabled by - default in the Firefox and Chromium wrappers. To enable it, you must - set: - + </para> + </listitem> + <listitem> + <para> + The Adobe Flash player is no longer enabled by default in the Firefox and + Chromium wrappers. To enable it, you must set: <programlisting> nixpkgs.config.allowUnfree = true; nixpkgs.config.firefox.enableAdobeFlash = true; # for Firefox nixpkgs.config.chromium.enableAdobeFlash = true; # for Chromium </programlisting> - - </para></listitem> - - <listitem><para>The firewall is now enabled by default. If you don’t - want this, you need to disable it explicitly: - + </para> + </listitem> + <listitem> + <para> + The firewall is now enabled by default. If you don’t want this, you need + to disable it explicitly: <programlisting> networking.firewall.enable = false; </programlisting> - - </para></listitem> - - <listitem><para>The option - <option>boot.loader.grub.memtest86</option> has been renamed to - <option>boot.loader.grub.memtest86.enable</option>.</para></listitem> - - <listitem><para>The <literal>mysql55</literal> service has been - merged into the <literal>mysql</literal> service, which no longer - sets a default for the option - <option>services.mysql.package</option>.</para></listitem> - - <listitem><para>Package variants are now differentiated by suffixing - the name, rather than the version. For instance, - <filename>sqlite-3.8.4.3-interactive</filename> is now called - <filename>sqlite-interactive-3.8.4.3</filename>. This ensures that - <literal>nix-env -i sqlite</literal> is unambiguous, and that - <literal>nix-env -u</literal> won’t “upgrade” - <literal>sqlite</literal> to <literal>sqlite-interactive</literal> - or vice versa. Notably, this change affects the Firefox wrapper - (which provides plugins), as it is now called - <literal>firefox-wrapper</literal>. So when using - <command>nix-env</command>, you should do <literal>nix-env -e - firefox; nix-env -i firefox-wrapper</literal> if you want to keep - using the wrapper. This change does not affect declarative package - management, since attribute names like - <literal>pkgs.firefoxWrapper</literal> were already - unambiguous.</para></listitem> - - <listitem><para>The symlink <filename>/etc/ca-bundle.crt</filename> - is gone. Programs should instead use the environment variable - <envar>OPENSSL_X509_CERT_FILE</envar> (which points to - <filename>/etc/ssl/certs/ca-bundle.crt</filename>).</para></listitem> - -</itemizedlist> - -</para> - + </para> + </listitem> + <listitem> + <para> + The option <option>boot.loader.grub.memtest86</option> has been renamed to + <option>boot.loader.grub.memtest86.enable</option>. + </para> + </listitem> + <listitem> + <para> + The <literal>mysql55</literal> service has been merged into the + <literal>mysql</literal> service, which no longer sets a default for the + option <option>services.mysql.package</option>. + </para> + </listitem> + <listitem> + <para> + Package variants are now differentiated by suffixing the name, rather than + the version. For instance, <filename>sqlite-3.8.4.3-interactive</filename> + is now called <filename>sqlite-interactive-3.8.4.3</filename>. This + ensures that <literal>nix-env -i sqlite</literal> is unambiguous, and that + <literal>nix-env -u</literal> won’t “upgrade” + <literal>sqlite</literal> to <literal>sqlite-interactive</literal> or vice + versa. Notably, this change affects the Firefox wrapper (which provides + plugins), as it is now called <literal>firefox-wrapper</literal>. So when + using <command>nix-env</command>, you should do <literal>nix-env -e + firefox; nix-env -i firefox-wrapper</literal> if you want to keep using + the wrapper. This change does not affect declarative package management, + since attribute names like <literal>pkgs.firefoxWrapper</literal> were + already unambiguous. + </para> + </listitem> + <listitem> + <para> + The symlink <filename>/etc/ca-bundle.crt</filename> is gone. Programs + should instead use the environment variable + <envar>OPENSSL_X509_CERT_FILE</envar> (which points to + <filename>/etc/ssl/certs/ca-bundle.crt</filename>). + </para> + </listitem> + </itemizedlist> + </para> </section> diff --git a/nixos/doc/manual/release-notes/rl-1412.xml b/nixos/doc/manual/release-notes/rl-1412.xml index 42b51cd4a8ef..4d93aa644c1d 100644 --- a/nixos/doc/manual/release-notes/rl-1412.xml +++ b/nixos/doc/manual/release-notes/rl-1412.xml @@ -3,175 +3,465 @@ xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="sec-release-14.12"> + <title>Release 14.12 (“Caterpillar”, 2014/12/30)</title> -<title>Release 14.12 (“Caterpillar”, 2014/12/30)</title> + <para> + In addition to numerous new and upgraded packages, this release has the + following highlights: + <itemizedlist> + <listitem> + <para> + Systemd has been updated to version 217, which has numerous + <link xlink:href="http://lists.freedesktop.org/archives/systemd-devel/2014-October/024662.html">improvements.</link> + </para> + </listitem> + <listitem> + <para> + <link xlink:href="http://thread.gmane.org/gmane.linux.distributions.nixos/15165"> + Nix has been updated to 1.8.</link> + </para> + </listitem> + <listitem> + <para> + NixOS is now based on Glibc 2.20. + </para> + </listitem> + <listitem> + <para> + KDE has been updated to 4.14. + </para> + </listitem> + <listitem> + <para> + The default Linux kernel has been updated to 3.14. + </para> + </listitem> + <listitem> + <para> + If <option>users.mutableUsers</option> is enabled (the default), changes + made to the declaration of a user or group will be correctly realised when + running <command>nixos-rebuild</command>. For instance, removing a user + specification from <filename>configuration.nix</filename> will cause the + actual user account to be deleted. If <option>users.mutableUsers</option> + is disabled, it is no longer necessary to specify UIDs or GIDs; if + omitted, they are allocated dynamically. + </para> + </listitem> + </itemizedlist> + </para> -<para>In addition to numerous new and upgraded packages, this release has the following highlights: + <para> + Following new services were added since the last release: + <itemizedlist> + <listitem> + <para> + <literal>atftpd</literal> + </para> + </listitem> + <listitem> + <para> + <literal>bosun</literal> + </para> + </listitem> + <listitem> + <para> + <literal>bspwm</literal> + </para> + </listitem> + <listitem> + <para> + <literal>chronos</literal> + </para> + </listitem> + <listitem> + <para> + <literal>collectd</literal> + </para> + </listitem> + <listitem> + <para> + <literal>consul</literal> + </para> + </listitem> + <listitem> + <para> + <literal>cpuminer-cryptonight</literal> + </para> + </listitem> + <listitem> + <para> + <literal>crashplan</literal> + </para> + </listitem> + <listitem> + <para> + <literal>dnscrypt-proxy</literal> + </para> + </listitem> + <listitem> + <para> + <literal>docker-registry</literal> + </para> + </listitem> + <listitem> + <para> + <literal>docker</literal> + </para> + </listitem> + <listitem> + <para> + <literal>etcd</literal> + </para> + </listitem> + <listitem> + <para> + <literal>fail2ban</literal> + </para> + </listitem> + <listitem> + <para> + <literal>fcgiwrap</literal> + </para> + </listitem> + <listitem> + <para> + <literal>fleet</literal> + </para> + </listitem> + <listitem> + <para> + <literal>fluxbox</literal> + </para> + </listitem> + <listitem> + <para> + <literal>gdm</literal> + </para> + </listitem> + <listitem> + <para> + <literal>geoclue2</literal> + </para> + </listitem> + <listitem> + <para> + <literal>gitlab</literal> + </para> + </listitem> + <listitem> + <para> + <literal>gitolite</literal> + </para> + </listitem> + <listitem> + <para> + <literal>gnome3.gnome-documents</literal> + </para> + </listitem> + <listitem> + <para> + <literal>gnome3.gnome-online-miners</literal> + </para> + </listitem> + <listitem> + <para> + <literal>gnome3.gvfs</literal> + </para> + </listitem> + <listitem> + <para> + <literal>gnome3.seahorse</literal> + </para> + </listitem> + <listitem> + <para> + <literal>hbase</literal> + </para> + </listitem> + <listitem> + <para> + <literal>i2pd</literal> + </para> + </listitem> + <listitem> + <para> + <literal>influxdb</literal> + </para> + </listitem> + <listitem> + <para> + <literal>kubernetes</literal> + </para> + </listitem> + <listitem> + <para> + <literal>liquidsoap</literal> + </para> + </listitem> + <listitem> + <para> + <literal>lxc</literal> + </para> + </listitem> + <listitem> + <para> + <literal>mailpile</literal> + </para> + </listitem> + <listitem> + <para> + <literal>mesos</literal> + </para> + </listitem> + <listitem> + <para> + <literal>mlmmj</literal> + </para> + </listitem> + <listitem> + <para> + <literal>monetdb</literal> + </para> + </listitem> + <listitem> + <para> + <literal>mopidy</literal> + </para> + </listitem> + <listitem> + <para> + <literal>neo4j</literal> + </para> + </listitem> + <listitem> + <para> + <literal>nsd</literal> + </para> + </listitem> + <listitem> + <para> + <literal>openntpd</literal> + </para> + </listitem> + <listitem> + <para> + <literal>opentsdb</literal> + </para> + </listitem> + <listitem> + <para> + <literal>openvswitch</literal> + </para> + </listitem> + <listitem> + <para> + <literal>parallels-guest</literal> + </para> + </listitem> + <listitem> + <para> + <literal>peerflix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>phd</literal> + </para> + </listitem> + <listitem> + <para> + <literal>polipo</literal> + </para> + </listitem> + <listitem> + <para> + <literal>prosody</literal> + </para> + </listitem> + <listitem> + <para> + <literal>radicale</literal> + </para> + </listitem> + <listitem> + <para> + <literal>redmine</literal> + </para> + </listitem> + <listitem> + <para> + <literal>riemann</literal> + </para> + </listitem> + <listitem> + <para> + <literal>scollector</literal> + </para> + </listitem> + <listitem> + <para> + <literal>seeks</literal> + </para> + </listitem> + <listitem> + <para> + <literal>siproxd</literal> + </para> + </listitem> + <listitem> + <para> + <literal>strongswan</literal> + </para> + </listitem> + <listitem> + <para> + <literal>tcsd</literal> + </para> + </listitem> + <listitem> + <para> + <literal>teamspeak3</literal> + </para> + </listitem> + <listitem> + <para> + <literal>thermald</literal> + </para> + </listitem> + <listitem> + <para> + <literal>torque/mrom</literal> + </para> + </listitem> + <listitem> + <para> + <literal>torque/server</literal> + </para> + </listitem> + <listitem> + <para> + <literal>uhub</literal> + </para> + </listitem> + <listitem> + <para> + <literal>unifi</literal> + </para> + </listitem> + <listitem> + <para> + <literal>znc</literal> + </para> + </listitem> + <listitem> + <para> + <literal>zookeeper</literal> + </para> + </listitem> + </itemizedlist> + </para> -<itemizedlist> - -<listitem><para>Systemd has been updated to version 217, which has numerous -<link xlink:href="http://lists.freedesktop.org/archives/systemd-devel/2014-October/024662.html">improvements.</link></para></listitem> - -<listitem><para><link xlink:href="http://thread.gmane.org/gmane.linux.distributions.nixos/15165"> -Nix has been updated to 1.8.</link></para></listitem> - -<listitem><para>NixOS is now based on Glibc 2.20.</para></listitem> - -<listitem><para>KDE has been updated to 4.14.</para></listitem> - -<listitem><para>The default Linux kernel has been updated to 3.14.</para></listitem> - -<listitem><para>If <option>users.mutableUsers</option> is enabled (the -default), changes made to the declaration of a user or group will be -correctly realised when running <command>nixos-rebuild</command>. For -instance, removing a user specification from -<filename>configuration.nix</filename> will cause the actual user -account to be deleted. If <option>users.mutableUsers</option> is -disabled, it is no longer necessary to specify UIDs or GIDs; if -omitted, they are allocated dynamically.</para></listitem> - -</itemizedlist></para> - -<para>Following new services were added since the last release: - -<itemizedlist> -<listitem><para><literal>atftpd</literal></para></listitem> -<listitem><para><literal>bosun</literal></para></listitem> -<listitem><para><literal>bspwm</literal></para></listitem> -<listitem><para><literal>chronos</literal></para></listitem> -<listitem><para><literal>collectd</literal></para></listitem> -<listitem><para><literal>consul</literal></para></listitem> -<listitem><para><literal>cpuminer-cryptonight</literal></para></listitem> -<listitem><para><literal>crashplan</literal></para></listitem> -<listitem><para><literal>dnscrypt-proxy</literal></para></listitem> -<listitem><para><literal>docker-registry</literal></para></listitem> -<listitem><para><literal>docker</literal></para></listitem> -<listitem><para><literal>etcd</literal></para></listitem> -<listitem><para><literal>fail2ban</literal></para></listitem> -<listitem><para><literal>fcgiwrap</literal></para></listitem> -<listitem><para><literal>fleet</literal></para></listitem> -<listitem><para><literal>fluxbox</literal></para></listitem> -<listitem><para><literal>gdm</literal></para></listitem> -<listitem><para><literal>geoclue2</literal></para></listitem> -<listitem><para><literal>gitlab</literal></para></listitem> -<listitem><para><literal>gitolite</literal></para></listitem> -<listitem><para><literal>gnome3.gnome-documents</literal></para></listitem> -<listitem><para><literal>gnome3.gnome-online-miners</literal></para></listitem> -<listitem><para><literal>gnome3.gvfs</literal></para></listitem> -<listitem><para><literal>gnome3.seahorse</literal></para></listitem> -<listitem><para><literal>hbase</literal></para></listitem> -<listitem><para><literal>i2pd</literal></para></listitem> -<listitem><para><literal>influxdb</literal></para></listitem> -<listitem><para><literal>kubernetes</literal></para></listitem> -<listitem><para><literal>liquidsoap</literal></para></listitem> -<listitem><para><literal>lxc</literal></para></listitem> -<listitem><para><literal>mailpile</literal></para></listitem> -<listitem><para><literal>mesos</literal></para></listitem> -<listitem><para><literal>mlmmj</literal></para></listitem> -<listitem><para><literal>monetdb</literal></para></listitem> -<listitem><para><literal>mopidy</literal></para></listitem> -<listitem><para><literal>neo4j</literal></para></listitem> -<listitem><para><literal>nsd</literal></para></listitem> -<listitem><para><literal>openntpd</literal></para></listitem> -<listitem><para><literal>opentsdb</literal></para></listitem> -<listitem><para><literal>openvswitch</literal></para></listitem> -<listitem><para><literal>parallels-guest</literal></para></listitem> -<listitem><para><literal>peerflix</literal></para></listitem> -<listitem><para><literal>phd</literal></para></listitem> -<listitem><para><literal>polipo</literal></para></listitem> -<listitem><para><literal>prosody</literal></para></listitem> -<listitem><para><literal>radicale</literal></para></listitem> -<listitem><para><literal>redmine</literal></para></listitem> -<listitem><para><literal>riemann</literal></para></listitem> -<listitem><para><literal>scollector</literal></para></listitem> -<listitem><para><literal>seeks</literal></para></listitem> -<listitem><para><literal>siproxd</literal></para></listitem> -<listitem><para><literal>strongswan</literal></para></listitem> -<listitem><para><literal>tcsd</literal></para></listitem> -<listitem><para><literal>teamspeak3</literal></para></listitem> -<listitem><para><literal>thermald</literal></para></listitem> -<listitem><para><literal>torque/mrom</literal></para></listitem> -<listitem><para><literal>torque/server</literal></para></listitem> -<listitem><para><literal>uhub</literal></para></listitem> -<listitem><para><literal>unifi</literal></para></listitem> -<listitem><para><literal>znc</literal></para></listitem> -<listitem><para><literal>zookeeper</literal></para></listitem> -</itemizedlist> -</para> - -<para>When upgrading from a previous release, please be aware of the -following incompatible changes: - -<itemizedlist> - -<listitem><para>The default version of Apache httpd is now 2.4. If -you use the <option>extraConfig</option> option to pass literal -Apache configuration text, you may need to update it — see <link + <para> + When upgrading from a previous release, please be aware of the following + incompatible changes: + <itemizedlist> + <listitem> + <para> + The default version of Apache httpd is now 2.4. If you use the + <option>extraConfig</option> option to pass literal Apache configuration + text, you may need to update it — see + <link xlink:href="http://httpd.apache.org/docs/2.4/upgrading.html">Apache’s -documentation</link> for details. If you wish to continue to use -httpd 2.2, add the following line to your NixOS configuration: - + documentation</link> for details. If you wish to continue to use httpd + 2.2, add the following line to your NixOS configuration: <programlisting> services.httpd.package = pkgs.apacheHttpd_2_2; </programlisting> - -</para></listitem> - -<listitem><para>PHP 5.3 has been removed because it is no longer -supported by the PHP project. A <link -xlink:href="http://php.net/migration54">migration guide</link> is -available.</para></listitem> - -<listitem><para>The host side of a container virtual Ethernet pair -is now called <literal>ve-<replaceable>container-name</replaceable></literal> -rather than <literal>c-<replaceable>container-name</replaceable></literal>.</para></listitem> - -<listitem><para>GNOME 3.10 support has been dropped. The default GNOME version is now 3.12.</para></listitem> - -<listitem><para>VirtualBox has been upgraded to 4.3.20 release. Users -may be required to run <command>rm -rf /tmp/.vbox*</command>. The line -<literal>imports = [ <nixpkgs/nixos/modules/programs/virtualbox.nix> ]</literal> is -no longer necessary, use <literal>services.virtualboxHost.enable = -true</literal> instead. -</para> -<para>Also, hardening mode is now enabled by default, which means that unless you want to use -USB support, you no longer need to be a member of the <literal>vboxusers</literal> group. -</para></listitem> - -<listitem><para>Chromium has been updated to 39.0.2171.65. <option>enablePepperPDF</option> is now enabled by default. -<literal>chromium*Wrapper</literal> packages no longer exist, because upstream removed NSAPI support. -<literal>chromium-stable</literal> has been renamed to <literal>chromium</literal>. -</para></listitem> - -<listitem><para>Python packaging documentation is now part of nixpkgs manual. To override -the python packages available to a custom python you now use <literal>pkgs.pythonFull.buildEnv.override</literal> -instead of <literal>pkgs.pythonFull.override</literal>. -</para></listitem> - -<listitem><para><literal>boot.resumeDevice = "8:6"</literal> is no longer supported. Most users will -want to leave it undefined, which takes the swap partitions automatically. There is an evaluation -assertion to ensure that the string starts with a slash. -</para></listitem> - -<listitem><para>The system-wide default timezone for NixOS installations -changed from <literal>CET</literal> to <literal>UTC</literal>. To choose -a different timezone for your system, configure -<literal>time.timeZone</literal> in -<literal>configuration.nix</literal>. A fairly complete list of possible -values for that setting is available at <link -xlink:href="https://en.wikipedia.org/wiki/List_of_tz_database_time_zones"/>.</para></listitem> - -<listitem><para>GNU screen has been updated to 4.2.1, which breaks -the ability to connect to sessions created by older versions of -screen.</para></listitem> - -<listitem><para>The Intel GPU driver was updated to the 3.x prerelease -version (used by most distributions) and supports DRI3 -now.</para></listitem> - -</itemizedlist> - -</para> - + </para> + </listitem> + <listitem> + <para> + PHP 5.3 has been removed because it is no longer supported by the PHP + project. A <link +xlink:href="http://php.net/migration54">migration + guide</link> is available. + </para> + </listitem> + <listitem> + <para> + The host side of a container virtual Ethernet pair is now called + <literal>ve-<replaceable>container-name</replaceable></literal> rather + than <literal>c-<replaceable>container-name</replaceable></literal>. + </para> + </listitem> + <listitem> + <para> + GNOME 3.10 support has been dropped. The default GNOME version is now + 3.12. + </para> + </listitem> + <listitem> + <para> + VirtualBox has been upgraded to 4.3.20 release. Users may be required to + run <command>rm -rf /tmp/.vbox*</command>. The line <literal>imports = [ + <nixpkgs/nixos/modules/programs/virtualbox.nix> ]</literal> is no + longer necessary, use <literal>services.virtualboxHost.enable = + true</literal> instead. + </para> + <para> + Also, hardening mode is now enabled by default, which means that unless + you want to use USB support, you no longer need to be a member of the + <literal>vboxusers</literal> group. + </para> + </listitem> + <listitem> + <para> + Chromium has been updated to 39.0.2171.65. + <option>enablePepperPDF</option> is now enabled by default. + <literal>chromium*Wrapper</literal> packages no longer exist, because + upstream removed NSAPI support. <literal>chromium-stable</literal> has + been renamed to <literal>chromium</literal>. + </para> + </listitem> + <listitem> + <para> + Python packaging documentation is now part of nixpkgs manual. To override + the python packages available to a custom python you now use + <literal>pkgs.pythonFull.buildEnv.override</literal> instead of + <literal>pkgs.pythonFull.override</literal>. + </para> + </listitem> + <listitem> + <para> + <literal>boot.resumeDevice = "8:6"</literal> is no longer supported. Most + users will want to leave it undefined, which takes the swap partitions + automatically. There is an evaluation assertion to ensure that the string + starts with a slash. + </para> + </listitem> + <listitem> + <para> + The system-wide default timezone for NixOS installations changed from + <literal>CET</literal> to <literal>UTC</literal>. To choose a different + timezone for your system, configure <literal>time.timeZone</literal> in + <literal>configuration.nix</literal>. A fairly complete list of possible + values for that setting is available at + <link +xlink:href="https://en.wikipedia.org/wiki/List_of_tz_database_time_zones"/>. + </para> + </listitem> + <listitem> + <para> + GNU screen has been updated to 4.2.1, which breaks the ability to connect + to sessions created by older versions of screen. + </para> + </listitem> + <listitem> + <para> + The Intel GPU driver was updated to the 3.x prerelease version (used by + most distributions) and supports DRI3 now. + </para> + </listitem> + </itemizedlist> + </para> </section> diff --git a/nixos/doc/manual/release-notes/rl-1509.xml b/nixos/doc/manual/release-notes/rl-1509.xml index a68baa0d8078..2465f370cf13 100644 --- a/nixos/doc/manual/release-notes/rl-1509.xml +++ b/nixos/doc/manual/release-notes/rl-1509.xml @@ -3,375 +3,640 @@ xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="sec-release-15.09"> + <title>Release 15.09 (“Dingo”, 2015/09/30)</title> -<title>Release 15.09 (“Dingo”, 2015/09/30)</title> - -<para>In addition to numerous new and upgraded packages, this release -has the following highlights:</para> - -<itemizedlist> + <para> + In addition to numerous new and upgraded packages, this release has the + following highlights: + </para> + <itemizedlist> <listitem> - <para>The <link xlink:href="http://haskell.org/">Haskell</link> - packages infrastructure has been re-designed from the ground up - ("Haskell NG"). NixOS now distributes the latest version - of every single package registered on <link - xlink:href="http://hackage.haskell.org/">Hackage</link> -- well in - excess of 8,000 Haskell packages. Detailed instructions on how to - use that infrastructure can be found in the <link + <para> + The <link xlink:href="http://haskell.org/">Haskell</link> packages + infrastructure has been re-designed from the ground up ("Haskell + NG"). NixOS now distributes the latest version of every single package + registered on + <link + xlink:href="http://hackage.haskell.org/">Hackage</link> -- well + in excess of 8,000 Haskell packages. Detailed instructions on how to use + that infrastructure can be found in the + <link xlink:href="http://nixos.org/nixpkgs/manual/#users-guide-to-the-haskell-infrastructure">User's - Guide to the Haskell Infrastructure</link>. Users migrating from an - earlier release may find helpful information below, in the list of - backwards-incompatible changes. Furthermore, we distribute 51(!) - additional Haskell package sets that provide every single <link + Guide to the Haskell Infrastructure</link>. Users migrating from an earlier + release may find helpful information below, in the list of + backwards-incompatible changes. Furthermore, we distribute 51(!) additional + Haskell package sets that provide every single + <link xlink:href="http://www.stackage.org/">LTS Haskell</link> release - since version 0.0 as well as the most recent <link + since version 0.0 as well as the most recent + <link xlink:href="http://www.stackage.org/">Stackage Nightly</link> - snapshot. The announcement <link - xlink:href="http://lists.science.uu.nl/pipermail/nix-dev/2015-September/018138.html">"Full - Stackage Support in Nixpkgs"</link> gives additional - details.</para> + snapshot. The announcement + <link + xlink:href="https://nixos.org/nix-dev/2015-September/018138.html">"Full + Stackage Support in Nixpkgs"</link> gives additional details. + </para> </listitem> - <listitem> - <para>Nix has been updated to version 1.10, which among other - improvements enables cryptographic signatures on binary caches for - improved security.</para> + <para> + Nix has been updated to version 1.10, which among other improvements + enables cryptographic signatures on binary caches for improved security. + </para> </listitem> - <listitem> - <para>You can now keep your NixOS system up to date automatically - by setting - + <para> + You can now keep your NixOS system up to date automatically by setting <programlisting> system.autoUpgrade.enable = true; </programlisting> - - This will cause the system to periodically check for updates in - your current channel and run <command>nixos-rebuild</command>.</para> + This will cause the system to periodically check for updates in your + current channel and run <command>nixos-rebuild</command>. + </para> </listitem> - <listitem> - <para>This release is based on Glibc 2.21, GCC 4.9 and Linux - 3.18.</para> + <para> + This release is based on Glibc 2.21, GCC 4.9 and Linux 3.18. + </para> </listitem> - <listitem> - <para>GNOME has been upgraded to 3.16. - </para> + <para> + GNOME has been upgraded to 3.16. + </para> </listitem> - <listitem> - <para>Xfce has been upgraded to 4.12. - </para> + <para> + Xfce has been upgraded to 4.12. + </para> </listitem> - <listitem> - <para>KDE 5 has been upgraded to KDE Frameworks 5.10, - Plasma 5.3.2 and Applications 15.04.3. - KDE 4 has been updated to kdelibs-4.14.10. - </para> + <para> + KDE 5 has been upgraded to KDE Frameworks 5.10, Plasma 5.3.2 and + Applications 15.04.3. KDE 4 has been updated to kdelibs-4.14.10. + </para> </listitem> - <listitem> - <para>E19 has been upgraded to 0.16.8.15. - </para> + <para> + E19 has been upgraded to 0.16.8.15. + </para> </listitem> + </itemizedlist> -</itemizedlist> - - -<para>The following new services were added since the last release: - + <para> + The following new services were added since the last release: <itemizedlist> - <listitem><para><literal>services/mail/exim.nix</literal></para></listitem> - <listitem><para><literal>services/misc/apache-kafka.nix</literal></para></listitem> - <listitem><para><literal>services/misc/canto-daemon.nix</literal></para></listitem> - <listitem><para><literal>services/misc/confd.nix</literal></para></listitem> - <listitem><para><literal>services/misc/devmon.nix</literal></para></listitem> - <listitem><para><literal>services/misc/gitit.nix</literal></para></listitem> - <listitem><para><literal>services/misc/ihaskell.nix</literal></para></listitem> - <listitem><para><literal>services/misc/mbpfan.nix</literal></para></listitem> - <listitem><para><literal>services/misc/mediatomb.nix</literal></para></listitem> - <listitem><para><literal>services/misc/mwlib.nix</literal></para></listitem> - <listitem><para><literal>services/misc/parsoid.nix</literal></para></listitem> - <listitem><para><literal>services/misc/plex.nix</literal></para></listitem> - <listitem><para><literal>services/misc/ripple-rest.nix</literal></para></listitem> - <listitem><para><literal>services/misc/ripple-data-api.nix</literal></para></listitem> - <listitem><para><literal>services/misc/subsonic.nix</literal></para></listitem> - <listitem><para><literal>services/misc/sundtek.nix</literal></para></listitem> - <listitem><para><literal>services/monitoring/cadvisor.nix</literal></para></listitem> - <listitem><para><literal>services/monitoring/das_watchdog.nix</literal></para></listitem> - <listitem><para><literal>services/monitoring/grafana.nix</literal></para></listitem> - <listitem><para><literal>services/monitoring/riemann-tools.nix</literal></para></listitem> - <listitem><para><literal>services/monitoring/teamviewer.nix</literal></para></listitem> - <listitem><para><literal>services/network-filesystems/u9fs.nix</literal></para></listitem> - <listitem><para><literal>services/networking/aiccu.nix</literal></para></listitem> - <listitem><para><literal>services/networking/asterisk.nix</literal></para></listitem> - <listitem><para><literal>services/networking/bird.nix</literal></para></listitem> - <listitem><para><literal>services/networking/charybdis.nix</literal></para></listitem> - <listitem><para><literal>services/networking/docker-registry-server.nix</literal></para></listitem> - <listitem><para><literal>services/networking/fan.nix</literal></para></listitem> - <listitem><para><literal>services/networking/firefox/sync-server.nix</literal></para></listitem> - <listitem><para><literal>services/networking/gateone.nix</literal></para></listitem> - <listitem><para><literal>services/networking/heyefi.nix</literal></para></listitem> - <listitem><para><literal>services/networking/i2p.nix</literal></para></listitem> - <listitem><para><literal>services/networking/lambdabot.nix</literal></para></listitem> - <listitem><para><literal>services/networking/mstpd.nix</literal></para></listitem> - <listitem><para><literal>services/networking/nix-serve.nix</literal></para></listitem> - <listitem><para><literal>services/networking/nylon.nix</literal></para></listitem> - <listitem><para><literal>services/networking/racoon.nix</literal></para></listitem> - <listitem><para><literal>services/networking/skydns.nix</literal></para></listitem> - <listitem><para><literal>services/networking/shout.nix</literal></para></listitem> - <listitem><para><literal>services/networking/softether.nix</literal></para></listitem> - <listitem><para><literal>services/networking/sslh.nix</literal></para></listitem> - <listitem><para><literal>services/networking/tinc.nix</literal></para></listitem> - <listitem><para><literal>services/networking/tlsdated.nix</literal></para></listitem> - <listitem><para><literal>services/networking/tox-bootstrapd.nix</literal></para></listitem> - <listitem><para><literal>services/networking/tvheadend.nix</literal></para></listitem> - <listitem><para><literal>services/networking/zerotierone.nix</literal></para></listitem> - <listitem><para><literal>services/scheduling/marathon.nix</literal></para></listitem> - <listitem><para><literal>services/security/fprintd.nix</literal></para></listitem> - <listitem><para><literal>services/security/hologram.nix</literal></para></listitem> - <listitem><para><literal>services/security/munge.nix</literal></para></listitem> - <listitem><para><literal>services/system/cloud-init.nix</literal></para></listitem> - <listitem><para><literal>services/web-servers/shellinabox.nix</literal></para></listitem> - <listitem><para><literal>services/web-servers/uwsgi.nix</literal></para></listitem> - <listitem><para><literal>services/x11/unclutter.nix</literal></para></listitem> - <listitem><para><literal>services/x11/display-managers/sddm.nix</literal></para></listitem> - <listitem><para><literal>system/boot/coredump.nix</literal></para></listitem> - <listitem><para><literal>system/boot/loader/loader.nix</literal></para></listitem> - <listitem><para><literal>system/boot/loader/generic-extlinux-compatible</literal></para></listitem> - <listitem><para><literal>system/boot/networkd.nix</literal></para></listitem> - <listitem><para><literal>system/boot/resolved.nix</literal></para></listitem> - <listitem><para><literal>system/boot/timesyncd.nix</literal></para></listitem> - <listitem><para><literal>tasks/filesystems/exfat.nix</literal></para></listitem> - <listitem><para><literal>tasks/filesystems/ntfs.nix</literal></para></listitem> - <listitem><para><literal>tasks/filesystems/vboxsf.nix</literal></para></listitem> - <listitem><para><literal>virtualisation/virtualbox-host.nix</literal></para></listitem> - <listitem><para><literal>virtualisation/vmware-guest.nix</literal></para></listitem> - <listitem><para><literal>virtualisation/xen-dom0.nix</literal></para></listitem> + <listitem> + <para> + <literal>services/mail/exim.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/misc/apache-kafka.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/misc/canto-daemon.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/misc/confd.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/misc/devmon.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/misc/gitit.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/misc/ihaskell.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/misc/mbpfan.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/misc/mediatomb.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/misc/mwlib.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/misc/parsoid.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/misc/plex.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/misc/ripple-rest.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/misc/ripple-data-api.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/misc/subsonic.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/misc/sundtek.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/monitoring/cadvisor.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/monitoring/das_watchdog.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/monitoring/grafana.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/monitoring/riemann-tools.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/monitoring/teamviewer.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/network-filesystems/u9fs.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/networking/aiccu.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/networking/asterisk.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/networking/bird.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/networking/charybdis.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/networking/docker-registry-server.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/networking/fan.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/networking/firefox/sync-server.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/networking/gateone.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/networking/heyefi.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/networking/i2p.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/networking/lambdabot.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/networking/mstpd.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/networking/nix-serve.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/networking/nylon.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/networking/racoon.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/networking/skydns.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/networking/shout.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/networking/softether.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/networking/sslh.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/networking/tinc.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/networking/tlsdated.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/networking/tox-bootstrapd.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/networking/tvheadend.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/networking/zerotierone.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/scheduling/marathon.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/security/fprintd.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/security/hologram.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/security/munge.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/system/cloud-init.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/web-servers/shellinabox.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/web-servers/uwsgi.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/x11/unclutter.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/x11/display-managers/sddm.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>system/boot/coredump.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>system/boot/loader/loader.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>system/boot/loader/generic-extlinux-compatible</literal> + </para> + </listitem> + <listitem> + <para> + <literal>system/boot/networkd.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>system/boot/resolved.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>system/boot/timesyncd.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>tasks/filesystems/exfat.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>tasks/filesystems/ntfs.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>tasks/filesystems/vboxsf.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>virtualisation/virtualbox-host.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>virtualisation/vmware-guest.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>virtualisation/xen-dom0.nix</literal> + </para> + </listitem> </itemizedlist> -</para> - - -<para>When upgrading from a previous release, please be aware of the -following incompatible changes: - -<itemizedlist> - -<listitem><para><command>sshd</command> no longer supports DSA and ECDSA -host keys by default. If you have existing systems with such host keys -and want to continue to use them, please set + </para> + <para> + When upgrading from a previous release, please be aware of the following + incompatible changes: + <itemizedlist> + <listitem> + <para> + <command>sshd</command> no longer supports DSA and ECDSA host keys by + default. If you have existing systems with such host keys and want to + continue to use them, please set <programlisting> -system.stateVersion = "14.12"; +system.nixos.stateVersion = "14.12"; </programlisting> - -The new option <option>system.stateVersion</option> ensures that -certain configuration changes that could break existing systems (such -as the <command>sshd</command> host key setting) will maintain -compatibility with the specified NixOS release. NixOps sets the state -version of existing deployments automatically.</para></listitem> - -<listitem><para><command>cron</command> is no longer enabled by -default, unless you have a non-empty -<option>services.cron.systemCronJobs</option>. To force -<command>cron</command> to be enabled, set -<option>services.cron.enable = true</option>.</para></listitem> - -<listitem><para>Nix now requires binary caches to be cryptographically -signed. If you have unsigned binary caches that you want to continue -to use, you should set <option>nix.requireSignedBinaryCaches = -false</option>.</para></listitem> - -<listitem><para>Steam now doesn't need root rights to work. Instead of using -<literal>*-steam-chrootenv</literal>, you should now just run <literal>steam</literal>. -<literal>steamChrootEnv</literal> package was renamed to <literal>steam</literal>, -and old <literal>steam</literal> package -- to <literal>steamOriginal</literal>. -</para></listitem> - -<listitem><para>CMPlayer has been renamed to bomi upstream. Package -<literal>cmplayer</literal> was accordingly renamed to -<literal>bomi</literal> </para></listitem> - -<listitem><para>Atom Shell has been renamed to Electron upstream. Package <literal>atom-shell</literal> -was accordingly renamed to <literal>electron</literal> -</para></listitem> - -<listitem><para>Elm is not released on Hackage anymore. You should now use <literal>elmPackages.elm</literal> -which contains the latest Elm platform.</para></listitem> - -<listitem> - <para>The CUPS printing service has been updated to version - <literal>2.0.2</literal>. Furthermore its systemd service has been - renamed to <literal>cups.service</literal>.</para> - - <para>Local printers are no longer shared or advertised by - default. This behavior can be changed by enabling - <option>services.printing.defaultShared</option> or - <option>services.printing.browsing</option> respectively.</para> -</listitem> - -<listitem> - <para> - The VirtualBox host and guest options have been named more - consistently. They can now found in - <option>virtualisation.virtualbox.host.*</option> instead of - <option>services.virtualboxHost.*</option> and - <option>virtualisation.virtualbox.guest.*</option> instead of - <option>services.virtualboxGuest.*</option>. - </para> - - <para> - Also, there now is support for the <literal>vboxsf</literal> file - system using the <option>fileSystems</option> configuration - attribute. An example of how this can be used in a configuration: - + The new option <option>system.nixos.stateVersion</option> ensures that + certain configuration changes that could break existing systems (such as + the <command>sshd</command> host key setting) will maintain compatibility + with the specified NixOS release. NixOps sets the state version of + existing deployments automatically. + </para> + </listitem> + <listitem> + <para> + <command>cron</command> is no longer enabled by default, unless you have a + non-empty <option>services.cron.systemCronJobs</option>. To force + <command>cron</command> to be enabled, set <option>services.cron.enable = + true</option>. + </para> + </listitem> + <listitem> + <para> + Nix now requires binary caches to be cryptographically signed. If you have + unsigned binary caches that you want to continue to use, you should set + <option>nix.requireSignedBinaryCaches = false</option>. + </para> + </listitem> + <listitem> + <para> + Steam now doesn't need root rights to work. Instead of using + <literal>*-steam-chrootenv</literal>, you should now just run + <literal>steam</literal>. <literal>steamChrootEnv</literal> package was + renamed to <literal>steam</literal>, and old <literal>steam</literal> + package -- to <literal>steamOriginal</literal>. + </para> + </listitem> + <listitem> + <para> + CMPlayer has been renamed to bomi upstream. Package + <literal>cmplayer</literal> was accordingly renamed to + <literal>bomi</literal> + </para> + </listitem> + <listitem> + <para> + Atom Shell has been renamed to Electron upstream. Package + <literal>atom-shell</literal> was accordingly renamed to + <literal>electron</literal> + </para> + </listitem> + <listitem> + <para> + Elm is not released on Hackage anymore. You should now use + <literal>elmPackages.elm</literal> which contains the latest Elm platform. + </para> + </listitem> + <listitem> + <para> + The CUPS printing service has been updated to version + <literal>2.0.2</literal>. Furthermore its systemd service has been renamed + to <literal>cups.service</literal>. + </para> + <para> + Local printers are no longer shared or advertised by default. This + behavior can be changed by enabling + <option>services.printing.defaultShared</option> or + <option>services.printing.browsing</option> respectively. + </para> + </listitem> + <listitem> + <para> + The VirtualBox host and guest options have been named more consistently. + They can now found in <option>virtualisation.virtualbox.host.*</option> + instead of <option>services.virtualboxHost.*</option> and + <option>virtualisation.virtualbox.guest.*</option> instead of + <option>services.virtualboxGuest.*</option>. + </para> + <para> + Also, there now is support for the <literal>vboxsf</literal> file system + using the <option>fileSystems</option> configuration attribute. An example + of how this can be used in a configuration: <programlisting> fileSystems."/shiny" = { device = "myshinysharedfolder"; fsType = "vboxsf"; }; </programlisting> - - </para> -</listitem> - -<listitem> - <para> - "<literal>nix-env -qa</literal>" no longer discovers - Haskell packages by name. The only packages visible in the global - scope are <literal>ghc</literal>, <literal>cabal-install</literal>, - and <literal>stack</literal>, but all other packages are hidden. The - reason for this inconvenience is the sheer size of the Haskell - package set. Name-based lookups are expensive, and most - <literal>nix-env -qa</literal> operations would become much slower - if we'd add the entire Hackage database into the top level attribute - set. Instead, the list of Haskell packages can be displayed by - running: - </para> - <programlisting> + </para> + </listitem> + <listitem> + <para> + "<literal>nix-env -qa</literal>" no longer discovers Haskell + packages by name. The only packages visible in the global scope are + <literal>ghc</literal>, <literal>cabal-install</literal>, and + <literal>stack</literal>, but all other packages are hidden. The reason + for this inconvenience is the sheer size of the Haskell package set. + Name-based lookups are expensive, and most <literal>nix-env -qa</literal> + operations would become much slower if we'd add the entire Hackage + database into the top level attribute set. Instead, the list of Haskell + packages can be displayed by running: + </para> +<programlisting> nix-env -f "<nixpkgs>" -qaP -A haskellPackages </programlisting> - <para> - Executable programs written in Haskell can be installed with: - </para> - <programlisting> + <para> + Executable programs written in Haskell can be installed with: + </para> +<programlisting> nix-env -f "<nixpkgs>" -iA haskellPackages.pandoc </programlisting> - <para> - Installing Haskell <emphasis>libraries</emphasis> this way, however, is no - longer supported. See the next item for more details. - </para> -</listitem> - -<listitem> - <para> - Previous versions of NixOS came with a feature called - <literal>ghc-wrapper</literal>, a small script that allowed GHC to - transparently pick up on libraries installed in the user's profile. This - feature has been deprecated; <literal>ghc-wrapper</literal> was removed - from the distribution. The proper way to register Haskell libraries with - the compiler now is the <literal>haskellPackages.ghcWithPackages</literal> - function. The <link + <para> + Installing Haskell <emphasis>libraries</emphasis> this way, however, is no + longer supported. See the next item for more details. + </para> + </listitem> + <listitem> + <para> + Previous versions of NixOS came with a feature called + <literal>ghc-wrapper</literal>, a small script that allowed GHC to + transparently pick up on libraries installed in the user's profile. This + feature has been deprecated; <literal>ghc-wrapper</literal> was removed + from the distribution. The proper way to register Haskell libraries with + the compiler now is the <literal>haskellPackages.ghcWithPackages</literal> + function. The + <link xlink:href="http://nixos.org/nixpkgs/manual/#users-guide-to-the-haskell-infrastructure">User's - Guide to the Haskell Infrastructure</link> provides more information about - this subject. - </para> -</listitem> - -<listitem> - <para> - All Haskell builds that have been generated with version 1.x of - the <literal>cabal2nix</literal> utility are now invalid and need - to be re-generated with a current version of - <literal>cabal2nix</literal> to function. The most recent version - of this tool can be installed by running - <literal>nix-env -i cabal2nix</literal>. - </para> -</listitem> - -<listitem> - <para> - The <literal>haskellPackages</literal> set in Nixpkgs used to have a - function attribute called <literal>extension</literal> that users - could override in their <literal>~/.nixpkgs/config.nix</literal> - files to configure additional attributes, etc. That function still - exists, but it's now called <literal>overrides</literal>. - </para> -</listitem> - -<listitem> - <para> - The OpenBLAS library has been updated to version - <literal>0.2.14</literal>. Support for the - <literal>x86_64-darwin</literal> platform was added. Dynamic - architecture detection was enabled; OpenBLAS now selects - microarchitecture-optimized routines at runtime, so optimal - performance is achieved without the need to rebuild OpenBLAS - locally. OpenBLAS has replaced ATLAS in most packages which use an - optimized BLAS or LAPACK implementation. - </para> -</listitem> - -<listitem> - <para> - The <literal>phpfpm</literal> is now using the default PHP version - (<literal>pkgs.php</literal>) instead of PHP 5.4 (<literal>pkgs.php54</literal>). - </para> -</listitem> - -<listitem> - <para> - The <literal>locate</literal> service no longer indexes the Nix store - by default, preventing packages with potentially numerous versions from - cluttering the output. Indexing the store can be activated by setting - <option>services.locate.includeStore = true</option>. - </para> -</listitem> - -<listitem> - <para> - The Nix expression search path (<envar>NIX_PATH</envar>) no longer - contains <filename>/etc/nixos/nixpkgs</filename> by default. You - can override <envar>NIX_PATH</envar> by setting - <option>nix.nixPath</option>. - </para> -</listitem> - -<listitem> - <para> - Python 2.6 has been marked as broken (as it no longer recieves - security updates from upstream). - </para> -</listitem> - -<listitem> - <para> - Any use of module arguments such as <varname>pkgs</varname> to access - library functions, or to define <literal>imports</literal> attributes - will now lead to an infinite loop at the time of the evaluation. - </para> - - <para> - In case of an infinite loop, use the <command>--show-trace</command> - command line argument and read the line just above the error message. - + Guide to the Haskell Infrastructure</link> provides more information about + this subject. + </para> + </listitem> + <listitem> + <para> + All Haskell builds that have been generated with version 1.x of the + <literal>cabal2nix</literal> utility are now invalid and need to be + re-generated with a current version of <literal>cabal2nix</literal> to + function. The most recent version of this tool can be installed by running + <literal>nix-env -i cabal2nix</literal>. + </para> + </listitem> + <listitem> + <para> + The <literal>haskellPackages</literal> set in Nixpkgs used to have a + function attribute called <literal>extension</literal> that users could + override in their <literal>~/.nixpkgs/config.nix</literal> files to + configure additional attributes, etc. That function still exists, but it's + now called <literal>overrides</literal>. + </para> + </listitem> + <listitem> + <para> + The OpenBLAS library has been updated to version + <literal>0.2.14</literal>. Support for the + <literal>x86_64-darwin</literal> platform was added. Dynamic architecture + detection was enabled; OpenBLAS now selects microarchitecture-optimized + routines at runtime, so optimal performance is achieved without the need + to rebuild OpenBLAS locally. OpenBLAS has replaced ATLAS in most packages + which use an optimized BLAS or LAPACK implementation. + </para> + </listitem> + <listitem> + <para> + The <literal>phpfpm</literal> is now using the default PHP version + (<literal>pkgs.php</literal>) instead of PHP 5.4 + (<literal>pkgs.php54</literal>). + </para> + </listitem> + <listitem> + <para> + The <literal>locate</literal> service no longer indexes the Nix store by + default, preventing packages with potentially numerous versions from + cluttering the output. Indexing the store can be activated by setting + <option>services.locate.includeStore = true</option>. + </para> + </listitem> + <listitem> + <para> + The Nix expression search path (<envar>NIX_PATH</envar>) no longer + contains <filename>/etc/nixos/nixpkgs</filename> by default. You can + override <envar>NIX_PATH</envar> by setting <option>nix.nixPath</option>. + </para> + </listitem> + <listitem> + <para> + Python 2.6 has been marked as broken (as it no longer receives security + updates from upstream). + </para> + </listitem> + <listitem> + <para> + Any use of module arguments such as <varname>pkgs</varname> to access + library functions, or to define <literal>imports</literal> attributes will + now lead to an infinite loop at the time of the evaluation. + </para> + <para> + In case of an infinite loop, use the <command>--show-trace</command> + command line argument and read the line just above the error message. <screen> $ nixos-rebuild build --show-trace … while evaluating the module argument `pkgs' in "/etc/nixos/my-module.nix": infinite recursion encountered </screen> - </para> - - - <para> - Any use of <literal>pkgs.lib</literal>, should be replaced by - <varname>lib</varname>, after adding it as argument of the module. The - following module - + </para> + <para> + Any use of <literal>pkgs.lib</literal>, should be replaced by + <varname>lib</varname>, after adding it as argument of the module. The + following module <programlisting> { config, pkgs, ... }: @@ -384,9 +649,7 @@ with pkgs.lib; config = mkIf config.foo { … }; } </programlisting> - - should be modified to look like: - + should be modified to look like: <programlisting> { config, pkgs, lib, ... }: @@ -399,13 +662,11 @@ with lib; config = mkIf config.foo { <replaceable>option definition</replaceable> }; } </programlisting> - </para> - - <para> - When <varname>pkgs</varname> is used to download other projects to - import their modules, and only in such cases, it should be replaced by - <literal>(import <nixpkgs> {})</literal>. The following module - + </para> + <para> + When <varname>pkgs</varname> is used to download other projects to import + their modules, and only in such cases, it should be replaced by + <literal>(import <nixpkgs> {})</literal>. The following module <programlisting> { config, pkgs, ... }: @@ -420,9 +681,7 @@ in imports = [ "${myProject}/module.nix" ]; } </programlisting> - - should be modified to look like: - + should be modified to look like: <programlisting> { config, pkgs, ... }: @@ -437,55 +696,55 @@ in imports = [ "${myProject}/module.nix" ]; } </programlisting> - </para> - -</listitem> - -</itemizedlist> -</para> - - -<para>Other notable improvements: - -<itemizedlist> - - <listitem><para>The nixos and nixpkgs channels were unified, - so one <emphasis>can</emphasis> use <literal>nix-env -iA nixos.bash</literal> - instead of <literal>nix-env -iA nixos.pkgs.bash</literal>. - See <link xlink:href="https://github.com/NixOS/nixpkgs/commit/2cd7c1f198">the commit</link> for details. - </para></listitem> + </para> + </listitem> + </itemizedlist> + </para> - <listitem> + <para> + Other notable improvements: + <itemizedlist> + <listitem> <para> - Users running an SSH server who worry about the quality of their - <literal>/etc/ssh/moduli</literal> file with respect to the - <link + The nixos and nixpkgs channels were unified, so one + <emphasis>can</emphasis> use <literal>nix-env -iA nixos.bash</literal> + instead of <literal>nix-env -iA nixos.pkgs.bash</literal>. See + <link xlink:href="https://github.com/NixOS/nixpkgs/commit/2cd7c1f198">the + commit</link> for details. + </para> + </listitem> + <listitem> + <para> + Users running an SSH server who worry about the quality of their + <literal>/etc/ssh/moduli</literal> file with respect to the + <link xlink:href="https://stribika.github.io/2015/01/04/secure-secure-shell.html">vulnerabilities - discovered in the Diffie-Hellman key exchange</link> can now - replace OpenSSH's default version with one they generated - themselves using the new - <option>services.openssh.moduliFile</option> option. - </para> - </listitem> - - <listitem> <para> - A newly packaged TeX Live 2015 is provided in <literal>pkgs.texlive</literal>, - split into 6500 nix packages. For basic user documentation see - <link xlink:href="https://github.com/NixOS/nixpkgs/blob/release-15.09/pkgs/tools/typesetting/tex/texlive-new/default.nix#L1" - >the source</link>. - Beware of <link xlink:href="https://github.com/NixOS/nixpkgs/issues/9757" - >an issue</link> when installing a too large package set. - - The plan is to deprecate and maybe delete the original TeX packages - until the next release. - </para> </listitem> - - <listitem><para> - <option>buildEnv.env</option> on all Python interpreters - is now available for nix-shell interoperability. - </para> </listitem> -</itemizedlist> - -</para> - + discovered in the Diffie-Hellman key exchange</link> can now replace + OpenSSH's default version with one they generated themselves using the new + <option>services.openssh.moduliFile</option> option. + </para> + </listitem> + <listitem> + <para> + A newly packaged TeX Live 2015 is provided in + <literal>pkgs.texlive</literal>, split into 6500 nix packages. For basic + user documentation see + <link xlink:href="https://github.com/NixOS/nixpkgs/blob/release-15.09/pkgs/tools/typesetting/tex/texlive/default.nix#L1" + >the + source</link>. Beware of + <link xlink:href="https://github.com/NixOS/nixpkgs/issues/9757" + >an + issue</link> when installing a too large package set. The plan is to + deprecate and maybe delete the original TeX packages until the next + release. + </para> + </listitem> + <listitem> + <para> + <option>buildEnv.env</option> on all Python interpreters is now available + for nix-shell interoperability. + </para> + </listitem> + </itemizedlist> + </para> </section> diff --git a/nixos/doc/manual/release-notes/rl-1603.xml b/nixos/doc/manual/release-notes/rl-1603.xml new file mode 100644 index 000000000000..9b512c4b1e58 --- /dev/null +++ b/nixos/doc/manual/release-notes/rl-1603.xml @@ -0,0 +1,671 @@ +<section xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-release-16.03"> + <title>Release 16.03 (“Emu”, 2016/03/31)</title> + + <para> + In addition to numerous new and upgraded packages, this release has the + following highlights: + </para> + + <itemizedlist> + <listitem> + <para> + Systemd 229, bringing + <link + xlink:href="https://github.com/systemd/systemd/blob/v229/NEWS">numerous + improvements</link> over 217. + </para> + </listitem> + <listitem> + <para> + Linux 4.4 (was 3.18). + </para> + </listitem> + <listitem> + <para> + GCC 5.3 (was 4.9). Note that GCC 5 + <link + xlink:href="https://gcc.gnu.org/onlinedocs/libstdc++/manual/using_dual_abi.html">changes + the C++ ABI in an incompatible way</link>; this may cause problems if you + try to link objects compiled with different versions of GCC. + </para> + </listitem> + <listitem> + <para> + Glibc 2.23 (was 2.21). + </para> + </listitem> + <listitem> + <para> + Binutils 2.26 (was 2.23.1). See #909 + </para> + </listitem> + <listitem> + <para> + Improved support for ensuring + <link + xlink:href="https://reproducible-builds.org/">bitwise + reproducible builds</link>. For example, <literal>stdenv</literal> now sets + the environment variable + <envar + xlink:href="https://reproducible-builds.org/specs/source-date-epoch/">SOURCE_DATE_EPOCH</envar> + to a deterministic value, and Nix has + <link + xlink:href="http://nixos.org/nix/manual/#ssec-relnotes-1.11">gained + an option</link> to repeat a build a number of times to test determinism. + An ongoing project, the goal of exact reproducibility is to allow binaries + to be verified independently (e.g., a user might only trust binaries that + appear in three independent binary caches). + </para> + </listitem> + <listitem> + <para> + Perl 5.22. + </para> + </listitem> + </itemizedlist> + + <para> + The following new services were added since the last release: + <itemizedlist> + <listitem> + <para> + <literal>services/monitoring/longview.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>hardware/video/webcam/facetimehd.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>i18n/input-method/default.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>i18n/input-method/fcitx.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>i18n/input-method/ibus.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>i18n/input-method/nabi.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>i18n/input-method/uim.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>programs/fish.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>security/acme.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>security/audit.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>security/oath.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/hardware/irqbalance.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/mail/dspam.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/mail/opendkim.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/mail/postsrsd.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/mail/rspamd.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/mail/rmilter.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/misc/autofs.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/misc/bepasty.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/misc/calibre-server.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/misc/cfdyndns.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/misc/gammu-smsd.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/misc/mathics.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/misc/matrix-synapse.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/misc/octoprint.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/monitoring/hdaps.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/monitoring/heapster.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/monitoring/longview.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/network-filesystems/netatalk.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/network-filesystems/xtreemfs.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/networking/autossh.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/networking/dnschain.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/networking/gale.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/networking/miniupnpd.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/networking/namecoind.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/networking/ostinato.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/networking/pdnsd.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/networking/shairport-sync.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/networking/supplicant.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/search/kibana.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/security/haka.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/security/physlock.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/web-apps/pump.io.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/x11/hardware/libinput.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/x11/window-managers/windowlab.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>system/boot/initrd-network.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>system/boot/initrd-ssh.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>system/boot/loader/loader.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>system/boot/networkd.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>system/boot/resolved.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>virtualisation/lxd.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>virtualisation/rkt.nix</literal> + </para> + </listitem> + </itemizedlist> + </para> + + <para> + When upgrading from a previous release, please be aware of the following + incompatible changes: + </para> + + <itemizedlist> + <listitem> + <para> + We no longer produce graphical ISO images and VirtualBox images for + <literal>i686-linux</literal>. A minimal ISO image is still provided. + </para> + </listitem> + <listitem> + <para> + Firefox and similar browsers are now <emphasis>wrapped by + default</emphasis>. The package and attribute names are plain + <literal>firefox</literal> or <literal>midori</literal>, etc. + Backward-compatibility attributes were set up, but note that + <command>nix-env -u</command> will <emphasis>not</emphasis> update your + current <literal>firefox-with-plugins</literal>; you have to uninstall it + and install <literal>firefox</literal> instead. + </para> + </listitem> + <listitem> + <para> + <command>wmiiSnap</command> has been replaced with + <command>wmii_hg</command>, but + <command>services.xserver.windowManager.wmii.enable</command> has been + updated respectively so this only affects you if you have explicitly + installed <command>wmiiSnap</command>. + </para> + </listitem> + <listitem> + <para> + <literal>jobs</literal> NixOS option has been removed. It served as + compatibility layer between Upstart jobs and SystemD services. All services + have been rewritten to use <literal>systemd.services</literal> + </para> + </listitem> + <listitem> + <para> + <command>wmiimenu</command> is removed, as it has been removed by the + developers upstream. Use <command>wimenu</command> from the + <command>wmii-hg</command> package. + </para> + </listitem> + <listitem> + <para> + Gitit is no longer automatically added to the module list in NixOS and as + such there will not be any manual entries for it. You will need to add an + import statement to your NixOS configuration in order to use it, e.g. +<programlisting><![CDATA[ +{ + imports = [ <nixpkgs/nixos/modules/services/misc/gitit.nix> ]; +} +]]></programlisting> + will include the Gitit service configuration options. + </para> + </listitem> + <listitem> + <para> + <command>nginx</command> does not accept flags for enabling and disabling + modules anymore. Instead it accepts <literal>modules</literal> argument, + which is a list of modules to be built in. All modules now reside in + <literal>nginxModules</literal> set. Example configuration: +<programlisting><![CDATA[ +nginx.override { + modules = [ nginxModules.rtmp nginxModules.dav nginxModules.moreheaders ]; +} +]]></programlisting> + </para> + </listitem> + <listitem> + <para> + <command>s3sync</command> is removed, as it hasn't been developed by + upstream for 4 years and only runs with ruby 1.8. For an actively-developer + alternative look at <command>tarsnap</command> and others. + </para> + </listitem> + <listitem> + <para> + <command>ruby_1_8</command> has been removed as it's not supported from + upstream anymore and probably contains security issues. + </para> + </listitem> + <listitem> + <para> + <literal>tidy-html5</literal> package is removed. Upstream only provided + <literal>(lib)tidy5</literal> during development, and now they went back to + <literal>(lib)tidy</literal> to work as a drop-in replacement of the + original package that has been unmaintained for years. You can (still) use + the <literal>html-tidy</literal> package, which got updated to a stable + release from this new upstream. + </para> + </listitem> + <listitem> + <para> + <literal>extraDeviceOptions</literal> argument is removed from + <literal>bumblebee</literal> package. Instead there are now two separate + arguments: <literal>extraNvidiaDeviceOptions</literal> and + <literal>extraNouveauDeviceOptions</literal> for setting extra X11 options + for nvidia and nouveau drivers, respectively. + </para> + </listitem> + <listitem> + <para> + The <literal>Ctrl+Alt+Backspace</literal> key combination no longer kills + the X server by default. There's a new option + <option>services.xserver.enableCtrlAltBackspace</option> allowing to enable + the combination again. + </para> + </listitem> + <listitem> + <para> + <literal>emacsPackagesNg</literal> now contains all packages from the ELPA, + MELPA, and MELPA Stable repositories. + </para> + </listitem> + <listitem> + <para> + Data directory for Postfix MTA server is moved from + <filename>/var/postfix</filename> to <filename>/var/lib/postfix</filename>. + Old configurations are migrated automatically. + <literal>service.postfix</literal> module has also received many + improvements, such as correct directories' access rights, new + <literal>aliasFiles</literal> and <literal>mapFiles</literal> options and + more. + </para> + </listitem> + <listitem> + <para> + Filesystem options should now be configured as a list of strings, not a + comma-separated string. The old style will continue to work, but print a + warning, until the 16.09 release. An example of the new style: +<programlisting> +fileSystems."/example" = { + device = "/dev/sdc"; + fsType = "btrfs"; + options = [ "noatime" "compress=lzo" "space_cache" "autodefrag" ]; +}; +</programlisting> + </para> + </listitem> + <listitem> + <para> + CUPS, installed by <literal>services.printing</literal> module, now has its + data directory in <filename>/var/lib/cups</filename>. Old configurations + from <filename>/etc/cups</filename> are moved there automatically, but + there might be problems. Also configuration options + <literal>services.printing.cupsdConf</literal> and + <literal>services.printing.cupsdFilesConf</literal> were removed because + they had been allowing one to override configuration variables required for + CUPS to work at all on NixOS. For most use cases, + <literal>services.printing.extraConf</literal> and new option + <literal>services.printing.extraFilesConf</literal> should be enough; if + you encounter a situation when they are not, please file a bug. + </para> + <para> + There are also Gutenprint improvements; in particular, a new option + <literal>services.printing.gutenprint</literal> is added to enable + automatic updating of Gutenprint PPMs; it's greatly recommended to enable + it instead of adding <literal>gutenprint</literal> to the + <literal>drivers</literal> list. + </para> + </listitem> + <listitem> + <para> + <literal>services.xserver.vaapiDrivers</literal> has been removed. Use + <literal>hardware.opengl.extraPackages{,32}</literal> instead. You can also + specify VDPAU drivers there. + </para> + </listitem> + <listitem> + <para> + <literal>programs.ibus</literal> moved to + <literal>i18n.inputMethod.ibus</literal>. The option + <literal>programs.ibus.plugins</literal> changed to + <literal>i18n.inputMethod.ibus.engines</literal> and the option to enable + ibus changed from <literal>programs.ibus.enable</literal> to + <literal>i18n.inputMethod.enabled</literal>. + <literal>i18n.inputMethod.enabled</literal> should be set to the used input + method name, <literal>"ibus"</literal> for ibus. An example of the new + style: +<programlisting> +i18n.inputMethod.enabled = "ibus"; +i18n.inputMethod.ibus.engines = with pkgs.ibus-engines; [ anthy mozc ]; +</programlisting> + That is equivalent to the old version: +<programlisting> +programs.ibus.enable = true; +programs.ibus.plugins = with pkgs; [ ibus-anthy mozc ]; +</programlisting> + </para> + </listitem> + <listitem> + <para> + <literal>services.udev.extraRules</literal> option now writes rules to + <filename>99-local.rules</filename> instead of + <filename>10-local.rules</filename>. This makes all the user rules apply + after others, so their results wouldn't be overriden by anything else. + </para> + </listitem> + <listitem> + <para> + Large parts of the <literal>services.gitlab</literal> module has been been + rewritten. There are new configuration options available. The + <literal>stateDir</literal> option was renamned to + <literal>statePath</literal> and the <literal>satellitesDir</literal> + option was removed. Please review the currently available options. + </para> + </listitem> + <listitem> + <para> + The option <option>services.nsd.zones.<name>.data</option> no longer + interpret the dollar sign ($) as a shell variable, as such it should not be + escaped anymore. Thus the following zone data: + </para> +<programlisting> +\$ORIGIN example.com. +\$TTL 1800 +@ IN SOA ns1.vpn.nbp.name. admin.example.com. ( + </programlisting> + <para> + Should modified to look like the actual file expected by nsd: + </para> +<programlisting> +$ORIGIN example.com. +$TTL 1800 +@ IN SOA ns1.vpn.nbp.name. admin.example.com. ( + </programlisting> + </listitem> + <listitem> + <para> + <literal>service.syncthing.dataDir</literal> options now has to point to + exact folder where syncthing is writing to. Example configuration should + look something like: + </para> +<programlisting> +services.syncthing = { + enable = true; + dataDir = "/home/somebody/.syncthing"; + user = "somebody"; +}; + </programlisting> + </listitem> + <listitem> + <para> + <literal>networking.firewall.allowPing</literal> is now enabled by default. + Users are encouraged to configure an appropriate rate limit for their + machines using the Kernel interface at + <filename>/proc/sys/net/ipv4/icmp_ratelimit</filename> and + <filename>/proc/sys/net/ipv6/icmp/ratelimit</filename> or using the + firewall itself, i.e. by setting the NixOS option + <literal>networking.firewall.pingLimit</literal>. + </para> + </listitem> + <listitem> + <para> + Systems with some broadcom cards used to result into a generated config + that is no longer accepted. If you get errors like +<screen>error: path ‘/nix/store/*-broadcom-sta-*’ does not exist and cannot be created</screen> + you should either re-run <command>nixos-generate-config</command> or + manually replace + <literal>"${config.boot.kernelPackages.broadcom_sta}"</literal> by + <literal>config.boot.kernelPackages.broadcom_sta</literal> in your + <filename>/etc/nixos/hardware-configuration.nix</filename>. More discussion + is on <link xlink:href="https://github.com/NixOS/nixpkgs/pull/12595"> the + github issue</link>. + </para> + </listitem> + <listitem> + <para> + The <literal>services.xserver.startGnuPGAgent</literal> option has been + removed. GnuPG 2.1.x changed the way the gpg-agent works, and that new + approach no longer requires (or even supports) the "start everything as a + child of the agent" scheme we've implemented in NixOS for older versions. + To configure the gpg-agent for your X session, add the following code to + <filename>~/.bashrc</filename> or some file that’s sourced when your + shell is started: +<programlisting> +GPG_TTY=$(tty) +export GPG_TTY + </programlisting> + If you want to use gpg-agent for SSH, too, add the following to your + session initialization (e.g. + <literal>displayManager.sessionCommands</literal>) +<programlisting> +gpg-connect-agent /bye +unset SSH_AGENT_PID +export SSH_AUTH_SOCK="''${HOME}/.gnupg/S.gpg-agent.ssh" + </programlisting> + and make sure that +<programlisting> +enable-ssh-support + </programlisting> + is included in your <filename>~/.gnupg/gpg-agent.conf</filename>. You will + need to use <command>ssh-add</command> to re-add your ssh keys. If gpg’s + automatic transformation of the private keys to the new format fails, you + will need to re-import your private keyring as well: +<programlisting> +gpg --import ~/.gnupg/secring.gpg + </programlisting> + The <command>gpg-agent(1)</command> man page has more details about this + subject, i.e. in the "EXAMPLES" section. + </para> + </listitem> + </itemizedlist> + + <para> + Other notable improvements: + <itemizedlist> +<!-- + <listitem> + <para>The <command>command-not-found</command> hook was extended. + Apart from <literal>$NIX_AUTO_INSTALL</literal> variable, + it newly also checks for <literal>$NIX_AUTO_RUN</literal> + which causes it to directly run the missing commands via + <command>nix-shell</command> (without installing anything).</para> + </listitem> + --> + <listitem> + <para> + <literal>ejabberd</literal> module is brought back and now works on NixOS. + </para> + </listitem> + <listitem> + <para> + Input method support was improved. New NixOS modules (fcitx, nabi and + uim), fcitx engines (chewing, hangul, m17n, mozc and table-other) and ibus + engines (hangul and m17n) have been added. + </para> + </listitem> + </itemizedlist> + </para> +</section> diff --git a/nixos/doc/manual/release-notes/rl-1609.xml b/nixos/doc/manual/release-notes/rl-1609.xml new file mode 100644 index 000000000000..4a2343edc970 --- /dev/null +++ b/nixos/doc/manual/release-notes/rl-1609.xml @@ -0,0 +1,277 @@ +<section xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-release-16.09"> + <title>Release 16.09 (“Flounder”, 2016/09/30)</title> + + <para> + In addition to numerous new and upgraded packages, this release has the + following highlights: + </para> + + <itemizedlist> + <listitem> + <para> + Many NixOS configurations and Nix packages now use significantly less disk + space, thanks to the + <link + xlink:href="https://github.com/NixOS/nixpkgs/issues/7117">extensive + work on closure size reduction</link>. For example, the closure size of a + minimal NixOS container went down from ~424 MiB in 16.03 to ~212 MiB in + 16.09, while the closure size of Firefox went from ~651 MiB to ~259 MiB. + </para> + </listitem> + <listitem> + <para> + To improve security, packages are now + <link + xlink:href="https://github.com/NixOS/nixpkgs/pull/12895">built + using various hardening features</link>. See the Nixpkgs manual for more + information. + </para> + </listitem> + <listitem> + <para> + Support for PXE netboot. See <xref + linkend="sec-booting-from-pxe" /> + for documentation. + </para> + </listitem> + <listitem> + <para> + X.org server 1.18. If you use the <literal>ati_unfree</literal> driver, + 1.17 is still used due to an ABI incompatibility. + </para> + </listitem> + <listitem> + <para> + This release is based on Glibc 2.24, GCC 5.4.0 and systemd 231. The default + Linux kernel remains 4.4. + </para> + </listitem> + </itemizedlist> + + <para> + The following new services were added since the last release: + </para> + + <itemizedlist> + <listitem> + <para> + <literal>(this will get automatically generated at release time)</literal> + </para> + </listitem> + </itemizedlist> + + <para> + When upgrading from a previous release, please be aware of the following + incompatible changes: + </para> + + <itemizedlist> + <listitem> + <para> + A large number of packages have been converted to use the multiple outputs + feature of Nix to greatly reduce the amount of required disk space, as + mentioned above. This may require changes to any custom packages to make + them build again; see the relevant chapter in the Nixpkgs manual for more + information. (Additional caveat to packagers: some packaging conventions + related to multiple-output packages + <link xlink:href="https://github.com/NixOS/nixpkgs/pull/14766">were + changed</link> late (August 2016) in the release cycle and differ from the + initial introduction of multiple outputs.) + </para> + </listitem> + <listitem> + <para> + Previous versions of Nixpkgs had support for all versions of the LTS + Haskell package set. That support has been dropped. The previously provided + <literal>haskell.packages.lts-x_y</literal> package sets still exist in + name to aviod breaking user code, but these package sets don't actually + contain the versions mandated by the corresponding LTS release. Instead, + our package set it loosely based on the latest available LTS release, i.e. + LTS 7.x at the time of this writing. New releases of NixOS and Nixpkgs will + drop those old names entirely. + <link + xlink:href="https://nixos.org/nix-dev/2016-June/020585.html">The + motivation for this change</link> has been discussed at length on the + <literal>nix-dev</literal> mailing list and in + <link + xlink:href="https://github.com/NixOS/nixpkgs/issues/14897">Github + issue #14897</link>. Development strategies for Haskell hackers who want to + rely on Nix and NixOS have been described in + <link + xlink:href="https://nixos.org/nix-dev/2016-June/020642.html">another + nix-dev article</link>. + </para> + </listitem> + <listitem> + <para> + Shell aliases for systemd sub-commands + <link xlink:href="https://github.com/NixOS/nixpkgs/pull/15598">were + dropped</link>: <command>start</command>, <command>stop</command>, + <command>restart</command>, <command>status</command>. + </para> + </listitem> + <listitem> + <para> + Redis now binds to 127.0.0.1 only instead of listening to all network + interfaces. This is the default behavior of Redis 3.2 + </para> + </listitem> + <listitem> + <para> + <literal>/var/empty</literal> is now immutable. Activation script runs + <command>chattr +i</command> to forbid any modifications inside the folder. + See <link xlink:href="https://github.com/NixOS/nixpkgs/pull/18365"> the + pull request</link> for what bugs this caused. + </para> + </listitem> + <listitem> + <para> + Gitlab's maintainance script <command>gitlab-runner</command> was removed + and split up into the more clearer <command>gitlab-run</command> and + <command>gitlab-rake</command> scripts, because + <command>gitlab-runner</command> is a component of Gitlab CI. + </para> + </listitem> + <listitem> + <para> + <literal>services.xserver.libinput.accelProfile</literal> default changed + from <literal>flat</literal> to <literal>adaptive</literal>, as per + <link xlink:href="https://wayland.freedesktop.org/libinput/doc/latest/group__config.html#gad63796972347f318b180e322e35cee79"> + official documentation</link>. + </para> + </listitem> + <listitem> + <para> + <literal>fonts.fontconfig.ultimate.rendering</literal> was removed because + our presets were obsolete for some time. New presets are hardcoded into + FreeType; you can select a preset via + <literal>fonts.fontconfig.ultimate.preset</literal>. You can customize + those presets via ordinary environment variables, using + <literal>environment.variables</literal>. + </para> + </listitem> + <listitem> + <para> + The <literal>audit</literal> service is no longer enabled by default. Use + <literal>security.audit.enable = true</literal> to explicitly enable it. + </para> + </listitem> + <listitem> + <para> + <literal>pkgs.linuxPackages.virtualbox</literal> now contains only the + kernel modules instead of the VirtualBox user space binaries. If you want + to reference the user space binaries, you have to use the new + <literal>pkgs.virtualbox</literal> instead. + </para> + </listitem> + <listitem> + <para> + <literal>goPackages</literal> was replaced with separated Go applications + in appropriate <literal>nixpkgs</literal> categories. Each Go package uses + its own dependency set. There's also a new <literal>go2nix</literal> tool + introduced to generate a Go package definition from its Go source + automatically. + </para> + </listitem> + <listitem> + <para> + <literal>services.mongodb.extraConfig</literal> configuration format was + changed to YAML. + </para> + </listitem> + <listitem> + <para> + PHP has been upgraded to 7.0 + </para> + </listitem> + </itemizedlist> + + <para> + Other notable improvements: + </para> + + <itemizedlist> + <listitem> + <para> + Revamped grsecurity/PaX support. There is now only a single general-purpose + distribution kernel and the configuration interface has been streamlined. + Desktop users should be able to simply set +<programlisting>security.grsecurity.enable = true</programlisting> + to get a reasonably secure system without having to sacrifice too much + functionality. + </para> + </listitem> + <listitem> + <para> + Special filesystems, like <literal>/proc</literal>, <literal>/run</literal> + and others, now have the same mount options as recommended by systemd and + are unified across different places in NixOS. Mount options are updated + during <command>nixos-rebuild switch</command> if possible. One benefit + from this is improved security — most such filesystems are now mounted + with <literal>noexec</literal>, <literal>nodev</literal> and/or + <literal>nosuid</literal> options. + </para> + </listitem> + <listitem> + <para> + The reverse path filter was interfering with DHCPv4 server operation in the + past. An exception for DHCPv4 and a new option to log packets that were + dropped due to the reverse path filter was added + (<literal>networking.firewall.logReversePathDrops</literal>) for easier + debugging. + </para> + </listitem> + <listitem> + <para> + Containers configuration within + <literal>containers.<name>.config</literal> is + <link + xlink:href="https://github.com/NixOS/nixpkgs/pull/17365">now + properly typed and checked</link>. In particular, partial configurations + are merged correctly. + </para> + </listitem> + <listitem> + <para> + The directory container setuid wrapper programs, + <filename>/var/setuid-wrappers</filename>, + <link + xlink:href="https://github.com/NixOS/nixpkgs/pull/18124">is now + updated atomically to prevent failures if the switch to a new configuration + is interrupted.</link> + </para> + </listitem> + <listitem> + <para> + <literal>services.xserver.startGnuPGAgent</literal> has been removed due to + GnuPG 2.1.x bump. See + <link + xlink:href="https://github.com/NixOS/nixpkgs/commit/5391882ebd781149e213e8817fba6ac3c503740c"> + how to achieve similar behavior</link>. You might need to <literal>pkill + gpg-agent</literal> after the upgrade to prevent a stale agent being in the + way. + </para> + </listitem> + <listitem> + <para> + <link xlink:href="https://github.com/NixOS/nixpkgs/commit/e561edc322d275c3687fec431935095cfc717147"> + Declarative users could share the uid due to the bug in the script handling + conflict resolution. </link> + </para> + </listitem> + <listitem> + <para> + Gummi boot has been replaced using systemd-boot. + </para> + </listitem> + <listitem> + <para> + Hydra package and NixOS module were added for convenience. + </para> + </listitem> + </itemizedlist> +</section> diff --git a/nixos/doc/manual/release-notes/rl-1703.xml b/nixos/doc/manual/release-notes/rl-1703.xml new file mode 100644 index 000000000000..6ca79e2bc00d --- /dev/null +++ b/nixos/doc/manual/release-notes/rl-1703.xml @@ -0,0 +1,817 @@ +<section xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-release-17.03"> + <title>Release 17.03 (“Gorilla”, 2017/03/31)</title> + + <section xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-release-17.03-highlights"> + <title>Highlights</title> + + <para> + In addition to numerous new and upgraded packages, this release has the + following highlights: + </para> + + <itemizedlist> + <listitem> + <para> + Nixpkgs is now extensible through overlays. See the + <link + xlink:href="https://nixos.org/nixpkgs/manual/#sec-overlays-install">Nixpkgs + manual</link> for more information. + </para> + </listitem> + <listitem> + <para> + This release is based on Glibc 2.25, GCC 5.4.0 and systemd 232. The + default Linux kernel is 4.9 and Nix is at 1.11.8. + </para> + </listitem> + <listitem> + <para> + The default desktop environment now is KDE's Plasma 5. KDE 4 has been + removed + </para> + </listitem> + <listitem> + <para> + The setuid wrapper functionality now supports setting capabilities. + </para> + </listitem> + <listitem> + <para> + X.org server uses branch 1.19. Due to ABI incompatibilities, + <literal>ati_unfree</literal> keeps forcing 1.17 and + <literal>amdgpu-pro</literal> starts forcing 1.18. + </para> + </listitem> + <listitem> + <para> + Cross compilation has been rewritten. See the nixpkgs manual for details. + The most obvious breaking change is that in derivations there is no + <literal>.nativeDrv</literal> nor <literal>.crossDrv</literal> are now + cross by default, not native. + </para> + </listitem> + <listitem> + <para> + The <literal>overridePackages</literal> function has been rewritten to be + replaced by + <link + xlink:href="https://nixos.org/nixpkgs/manual/#sec-overlays-install"> + overlays</link> + </para> + </listitem> + <listitem> + <para> + Packages in nixpkgs can be marked as insecure through listed + vulnerabilities. See the + <link + xlink:href="https://nixos.org/nixpkgs/manual/#sec-allow-insecure">Nixpkgs + manual</link> for more information. + </para> + </listitem> + <listitem> + <para> + PHP now defaults to PHP 7.1 + </para> + </listitem> + </itemizedlist> + </section> + + <section xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-release-17.03-new-services"> + <title>New Services</title> + + <para> + The following new services were added since the last release: + </para> + + <itemizedlist> + <listitem> + <para> + <literal>hardware/ckb.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>hardware/mcelog.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>hardware/usb-wwan.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>hardware/video/capture/mwprocapture.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>programs/adb.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>programs/chromium.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>programs/gphoto2.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>programs/java.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>programs/mtr.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>programs/oblogout.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>programs/vim.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>programs/wireshark.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>security/dhparams.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/audio/ympd.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/computing/boinc/client.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/continuous-integration/buildbot/master.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/continuous-integration/buildbot/worker.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/continuous-integration/gitlab-runner.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/databases/riak-cs.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/databases/stanchion.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/desktops/gnome3/gnome-terminal-server.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/editors/infinoted.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/hardware/illum.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/hardware/trezord.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/logging/journalbeat.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/mail/offlineimap.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/mail/postgrey.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/misc/couchpotato.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/misc/docker-registry.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/misc/errbot.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/misc/geoip-updater.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/misc/gogs.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/misc/leaps.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/misc/nix-optimise.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/misc/ssm-agent.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/misc/sssd.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/monitoring/arbtt.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/monitoring/netdata.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/monitoring/prometheus/default.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/monitoring/prometheus/alertmanager.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/monitoring/prometheus/blackbox-exporter.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/monitoring/prometheus/json-exporter.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/monitoring/prometheus/nginx-exporter.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/monitoring/prometheus/node-exporter.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/monitoring/prometheus/snmp-exporter.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/monitoring/prometheus/unifi-exporter.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/monitoring/prometheus/varnish-exporter.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/monitoring/sysstat.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/monitoring/telegraf.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/monitoring/vnstat.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/network-filesystems/cachefilesd.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/network-filesystems/glusterfs.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/network-filesystems/ipfs.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/networking/dante.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/networking/dnscrypt-wrapper.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/networking/fakeroute.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/networking/flannel.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/networking/htpdate.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/networking/miredo.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/networking/nftables.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/networking/powerdns.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/networking/pdns-recursor.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/networking/quagga.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/networking/redsocks.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/networking/wireguard.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/system/cgmanager.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/torrent/opentracker.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/web-apps/atlassian/confluence.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/web-apps/atlassian/crowd.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/web-apps/atlassian/jira.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/web-apps/frab.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/web-apps/nixbot.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/web-apps/selfoss.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/web-apps/quassel-webserver.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/x11/unclutter-xfixes.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/x11/urxvtd.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>system/boot/systemd-nspawn.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>virtualisation/ecs-agent.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>virtualisation/lxcfs.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>virtualisation/openstack/keystone.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>virtualisation/openstack/glance.nix</literal> + </para> + </listitem> + </itemizedlist> + </section> + + <section xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-release-17.03-incompatibilities"> + <title>Backward Incompatibilities</title> + + <para> + When upgrading from a previous release, please be aware of the following + incompatible changes: + </para> + + <itemizedlist> + <listitem> + <para> + Derivations have no <literal>.nativeDrv</literal> nor + <literal>.crossDrv</literal> and are now cross by default, not native. + </para> + </listitem> + <listitem> + <para> + <literal>stdenv.overrides</literal> is now expected to take + <literal>self</literal> and <literal>super</literal> arguments. See + <literal>lib.trivial.extends</literal> for what those parameters + represent. + </para> + </listitem> + <listitem> + <para> + <literal>ansible</literal> now defaults to ansible version 2 as version 1 + has been removed due to a serious + <link + xlink:href="https://www.computest.nl/advisories/CT-2017-0109_Ansible.txt"> + vulnerability</link> unpatched by upstream. + </para> + </listitem> + <listitem> + <para> + <literal>gnome</literal> alias has been removed along with + <literal>gtk</literal>, <literal>gtkmm</literal> and several others. Now + you need to use versioned attributes, like <literal>gnome3</literal>. + </para> + </listitem> + <listitem> + <para> + The attribute name of the Radicale daemon has been changed from + <literal>pythonPackages.radicale</literal> to <literal>radicale</literal>. + </para> + </listitem> + <listitem> + <para> + The <literal>stripHash</literal> bash function in + <literal>stdenv</literal> changed according to its documentation; it now + outputs the stripped name to <literal>stdout</literal> instead of putting + it in the variable <literal>strippedName</literal>. + </para> + </listitem> + <listitem> + <para> + PHP now scans for extra configuration .ini files in /etc/php.d instead of + /etc. This prevents accidentally loading non-PHP .ini files that may be in + /etc. + </para> + </listitem> + <listitem> + <para> + Two lone top-level dict dbs moved into <literal>dictdDBs</literal>. This + affects: <literal>dictdWordnet</literal> which is now at + <literal>dictdDBs.wordnet</literal> and <literal>dictdWiktionary</literal> + which is now at <literal>dictdDBs.wiktionary</literal> + </para> + </listitem> + <listitem> + <para> + Parsoid service now uses YAML configuration format. + <literal>service.parsoid.interwikis</literal> is now called + <literal>service.parsoid.wikis</literal> and is a list of either API URLs + or attribute sets as specified in parsoid's documentation. + </para> + </listitem> + <listitem> + <para> + <literal>Ntpd</literal> was replaced by + <literal>systemd-timesyncd</literal> as the default service to synchronize + system time with a remote NTP server. The old behavior can be restored by + setting <literal>services.ntp.enable</literal> to <literal>true</literal>. + Upstream time servers for all NTP implementations are now configured using + <literal>networking.timeServers</literal>. + </para> + </listitem> + <listitem> + <para> + <literal>service.nylon</literal> is now declared using named instances. As + an example: +<programlisting> + services.nylon = { + enable = true; + acceptInterface = "br0"; + bindInterface = "tun1"; + port = 5912; + }; +</programlisting> + should be replaced with: +<programlisting> + services.nylon.myvpn = { + enable = true; + acceptInterface = "br0"; + bindInterface = "tun1"; + port = 5912; + }; +</programlisting> + this enables you to declare a SOCKS proxy for each uplink. + </para> + </listitem> + <listitem> + <para> + <literal>overridePackages</literal> function no longer exists. It is + replaced by + <link + xlink:href="https://nixos.org/nixpkgs/manual/#sec-overlays-install"> + overlays</link>. For example, the following code: +<programlisting> + let + pkgs = import <nixpkgs> {}; + in + pkgs.overridePackages (self: super: ...) +</programlisting> + should be replaced by: +<programlisting> + let + pkgs = import <nixpkgs> {}; + in + import pkgs.path { overlays = [(self: super: ...)]; } +</programlisting> + </para> + </listitem> + <listitem> + <para> + Autoloading connection tracking helpers is now disabled by default. This + default was also changed in the Linux kernel and is considered insecure if + not configured properly in your firewall. If you need connection tracking + helpers (i.e. for active FTP) please enable + <literal>networking.firewall.autoLoadConntrackHelpers</literal> and tune + <literal>networking.firewall.connectionTrackingModules</literal> to suit + your needs. + </para> + </listitem> + <listitem> + <para> + <literal>local_recipient_maps</literal> is not set to empty value by + Postfix service. It's an insecure default as stated by Postfix + documentation. Those who want to retain this setting need to set it via + <literal>services.postfix.extraConfig</literal>. + </para> + </listitem> + <listitem> + <para> + Iputils no longer provide ping6 and traceroute6. The functionality of + these tools has been integrated into ping and traceroute respectively. To + enforce an address family the new flags <literal>-4</literal> and + <literal>-6</literal> have been added. One notable incompatibility is that + specifying an interface (for link-local IPv6 for instance) is no longer + done with the <literal>-I</literal> flag, but by encoding the interface + into the address (<literal>ping fe80::1%eth0</literal>). + </para> + </listitem> + <listitem> + <para> + The socket handling of the <literal>services.rmilter</literal> module has + been fixed and refactored. As rmilter doesn't support binding to more than + one socket, the options <literal>bindUnixSockets</literal> and + <literal>bindInetSockets</literal> have been replaced by + <literal>services.rmilter.bindSocket.*</literal>. The default is still a + unix socket in <literal>/run/rmilter/rmilter.sock</literal>. Refer to the + options documentation for more information. + </para> + </listitem> + <listitem> + <para> + The <literal>fetch*</literal> functions no longer support md5, please use + sha256 instead. + </para> + </listitem> + <listitem> + <para> + The dnscrypt-proxy module interface has been streamlined around the + <option>extraArgs</option> option. Where possible, legacy option + declarations are mapped to <option>extraArgs</option> but will emit + warnings. The <option>resolverList</option> has been outright removed: to + use an unlisted resolver, use the <option>customResolver</option> option. + </para> + </listitem> + <listitem> + <para> + torbrowser now stores local state under + <filename>~/.local/share/tor-browser</filename> by default. Any browser + profile data from the old location, <filename>~/.torbrowser4</filename>, + must be migrated manually. + </para> + </listitem> + <listitem> + <para> + The ihaskell, monetdb, offlineimap and sitecopy services have been + removed. + </para> + </listitem> + </itemizedlist> + </section> + + <section xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-release-17.03-notable-changes"> + <title>Other Notable Changes</title> + + <itemizedlist> + <listitem> + <para> + Module type system have a new extensible option types feature that allow + to extend certain types, such as enum, through multiple option + declarations of the same option across multiple modules. + </para> + </listitem> + <listitem> + <para> + <literal>jre</literal> now defaults to GTK+ UI by default. This improves + visual consistency and makes Java follow system font style, improving the + situation on HighDPI displays. This has a cost of increased closure size; + for server and other headless workloads it's recommended to use + <literal>jre_headless</literal>. + </para> + </listitem> + <listitem> + <para> + Python 2.6 interpreter and package set have been removed. + </para> + </listitem> + <listitem> + <para> + The Python 2.7 interpreter does not use modules anymore. Instead, all + CPython interpreters now include the whole standard library except for + `tkinter`, which is available in the Python package set. + </para> + </listitem> + <listitem> + <para> + Python 2.7, 3.5 and 3.6 are now built deterministically and 3.4 mostly. + Minor modifications had to be made to the interpreters in order to + generate deterministic bytecode. This has security implications and is + relevant for those using Python in a <literal>nix-shell</literal>. See the + Nixpkgs manual for details. + </para> + </listitem> + <listitem> + <para> + The Python package sets now use a fixed-point combinator and the sets are + available as attributes of the interpreters. + </para> + </listitem> + <listitem> + <para> + The Python function <literal>buildPythonPackage</literal> has been + improved and can be used to build from Setuptools source, Flit source, and + precompiled Wheels. + </para> + </listitem> + <listitem> + <para> + When adding new or updating current Python libraries, the expressions + should be put in separate files in + <literal>pkgs/development/python-modules</literal> and called from + <literal>python-packages.nix</literal>. + </para> + </listitem> + <listitem> + <para> + The dnscrypt-proxy service supports synchronizing the list of public + resolvers without working DNS resolution. This fixes issues caused by the + resolver list becoming outdated. It also improves the viability of + DNSCrypt only configurations. + </para> + </listitem> + <listitem> + <para> + Containers using bridged networking no longer lose their connection after + changes to the host networking. + </para> + </listitem> + <listitem> + <para> + ZFS supports pool auto scrubbing. + </para> + </listitem> + <listitem> + <para> + The bind DNS utilities (e.g. dig) have been split into their own output + and are now also available in <literal>pkgs.dnsutils</literal> and it is + no longer necessary to pull in all of <literal>bind</literal> to use them. + </para> + </listitem> + <listitem> + <para> + Per-user configuration was moved from <filename>~/.nixpkgs</filename> to + <filename>~/.config/nixpkgs</filename>. The former is still valid for + <filename>config.nix</filename> for backwards compatibility. + </para> + </listitem> + </itemizedlist> + </section> +</section> diff --git a/nixos/doc/manual/release-notes/rl-1709.xml b/nixos/doc/manual/release-notes/rl-1709.xml new file mode 100644 index 000000000000..795c51d2923d --- /dev/null +++ b/nixos/doc/manual/release-notes/rl-1709.xml @@ -0,0 +1,899 @@ +<section xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-release-17.09"> + <title>Release 17.09 (“Hummingbird”, 2017/09/??)</title> + + <section xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-release-17.09-highlights"> + <title>Highlights</title> + + <para> + In addition to numerous new and upgraded packages, this release has the + following highlights: + </para> + + <itemizedlist> + <listitem> + <para> + The GNOME version is now 3.24. KDE Plasma was upgraded to 5.10, KDE + Applications to 17.08.1 and KDE Frameworks to 5.37. + </para> + </listitem> + <listitem> + <para> + The user handling now keeps track of deallocated UIDs/GIDs. When a user or + group is revived, this allows it to be allocated the UID/GID it had + before. A consequence is that UIDs and GIDs are no longer reused. + </para> + </listitem> + <listitem> + <para> + The module option <option>services.xserver.xrandrHeads</option> now causes + the first head specified in this list to be set as the primary head. Apart + from that, it's now possible to also set additional options by using an + attribute set, for example: +<programlisting> +{ services.xserver.xrandrHeads = [ + "HDMI-0" + { + output = "DVI-0"; + primary = true; + monitorConfig = '' + Option "Rotate" "right" + ''; + } + ]; +} +</programlisting> + This will set the <literal>DVI-0</literal> output to be the primary head, + even though <literal>HDMI-0</literal> is the first head in the list. + </para> + </listitem> + <listitem> + <para> + The handling of SSL in the <literal>services.nginx</literal> module has + been cleaned up, renaming the misnamed <literal>enableSSL</literal> to + <literal>onlySSL</literal> which reflects its original intention. This is + not to be used with the already existing <literal>forceSSL</literal> which + creates a second non-SSL virtual host redirecting to the SSL virtual host. + This by chance had worked earlier due to specific implementation details. + In case you had specified both please remove the + <literal>enableSSL</literal> option to keep the previous behaviour. + </para> + <para> + Another <literal>addSSL</literal> option has been introduced to configure + both a non-SSL virtual host and an SSL virtual host with the same + configuration. + </para> + <para> + Options to configure <literal>resolver</literal> options and + <literal>upstream</literal> blocks have been introduced. See their + information for further details. + </para> + <para> + The <literal>port</literal> option has been replaced by a more generic + <literal>listen</literal> option which makes it possible to specify + multiple addresses, ports and SSL configs dependant on the new SSL + handling mentioned above. + </para> + </listitem> + </itemizedlist> + </section> + + <section xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-release-17.09-new-services"> + <title>New Services</title> + + <para> + The following new services were added since the last release: + </para> + + <itemizedlist> + <listitem> + <para> + <literal>config/fonts/fontconfig-penultimate.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>config/fonts/fontconfig-ultimate.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>config/terminfo.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>hardware/sensor/iio.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>hardware/nitrokey.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>hardware/raid/hpsa.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>programs/browserpass.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>programs/gnupg.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>programs/qt5ct.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>programs/slock.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>programs/thefuck.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>security/auditd.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>security/lock-kernel-modules.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>service-managers/docker.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>service-managers/trivial.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/admin/salt/master.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/admin/salt/minion.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/audio/slimserver.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/cluster/kubernetes/default.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/cluster/kubernetes/dns.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/cluster/kubernetes/dashboard.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/continuous-integration/hail.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/databases/clickhouse.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/databases/postage.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/desktops/gnome3/gnome-disks.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/desktops/gnome3/gpaste.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/logging/SystemdJournal2Gelf.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/logging/heartbeat.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/logging/journalwatch.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/logging/syslogd.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/mail/mailhog.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/mail/nullmailer.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/misc/airsonic.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/misc/autorandr.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/misc/exhibitor.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/misc/fstrim.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/misc/gollum.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/misc/irkerd.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/misc/jackett.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/misc/radarr.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/misc/snapper.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/monitoring/osquery.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/monitoring/prometheus/collectd-exporter.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/monitoring/prometheus/fritzbox-exporter.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/network-filesystems/kbfs.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/networking/dnscache.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/networking/fireqos.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/networking/iwd.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/networking/keepalived/default.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/networking/keybase.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/networking/lldpd.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/networking/matterbridge.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/networking/squid.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/networking/tinydns.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/networking/xrdp.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/security/shibboleth-sp.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/security/sks.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/security/sshguard.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/security/torify.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/security/usbguard.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/security/vault.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/system/earlyoom.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/system/saslauthd.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/web-apps/nexus.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/web-apps/pgpkeyserver-lite.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/web-apps/piwik.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/web-servers/lighttpd/collectd.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/web-servers/minio.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/x11/display-managers/xpra.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>services/x11/xautolock.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>tasks/filesystems/bcachefs.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>tasks/powertop.nix</literal> + </para> + </listitem> + </itemizedlist> + </section> + + <section xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-release-17.09-incompatibilities"> + <title>Backward Incompatibilities</title> + + <para> + When upgrading from a previous release, please be aware of the following + incompatible changes: + </para> + + <itemizedlist> + <listitem> + <para> + <emphasis role="strong"> In an Qemu-based virtualization environment, the + network interface names changed from i.e. <literal>enp0s3</literal> to + <literal>ens3</literal>. </emphasis> + </para> + <para> + This is due to a kernel configuration change. The new naming is consistent + with those of other Linux distributions with systemd. See + <link xlink:href="https://github.com/NixOS/nixpkgs/issues/29197">#29197</link> + for more information. + </para> + <para> + A machine is affected if the <literal>virt-what</literal> tool either + returns <literal>qemu</literal> or <literal>kvm</literal> + <emphasis>and</emphasis> has interface names used in any part of its NixOS + configuration, in particular if a static network configuration with + <literal>networking.interfaces</literal> is used. + </para> + <para> + Before rebooting affected machines, please ensure: + <itemizedlist> + <listitem> + <para> + Change the interface names in your NixOS configuration. The first + interface will be called <literal>ens3</literal>, the second one + <literal>ens8</literal> and starting from there incremented by 1. + </para> + </listitem> + <listitem> + <para> + After changing the interface names, rebuild your system with + <literal>nixos-rebuild boot</literal> to activate the new configuration + after a reboot. If you switch to the new configuration right away you + might lose network connectivity! If using <literal>nixops</literal>, + deploy with <literal>nixops deploy --force-reboot</literal>. + </para> + </listitem> + </itemizedlist> + </para> + </listitem> + <listitem> + <para> + The following changes apply if the <literal>stateVersion</literal> is + changed to 17.09 or higher. For <literal>stateVersion = "17.03"</literal> + or lower the old behavior is preserved. + </para> + <itemizedlist> + <listitem> + <para> + The <literal>postgres</literal> default version was changed from 9.5 to + 9.6. + </para> + </listitem> + <listitem> + <para> + The <literal>postgres</literal> superuser name has changed from + <literal>root</literal> to <literal>postgres</literal> to more closely + follow what other Linux distributions are doing. + </para> + </listitem> + <listitem> + <para> + The <literal>postgres</literal> default <literal>dataDir</literal> has + changed from <literal>/var/db/postgres</literal> to + <literal>/var/lib/postgresql/$psqlSchema</literal> where $psqlSchema is + 9.6 for example. + </para> + </listitem> + <listitem> + <para> + The <literal>mysql</literal> default <literal>dataDir</literal> has + changed from <literal>/var/mysql</literal> to + <literal>/var/lib/mysql</literal>. + </para> + </listitem> + <listitem> + <para> + Radicale's default package has changed from 1.x to 2.x. Instructions to + migrate can be found <link xlink:href="http://radicale.org/1to2/"> here + </link>. It is also possible to use the newer version by setting the + <literal>package</literal> to <literal>radicale2</literal>, which is + done automatically when <literal>stateVersion</literal> is 17.09 or + higher. The <literal>extraArgs</literal> option has been added to allow + passing the data migration arguments specified in the instructions; see + the + <filename xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/radicale.nix">radicale.nix</filename> + NixOS test for an example migration. + </para> + </listitem> + </itemizedlist> + </listitem> + <listitem> + <para> + The <literal>aiccu</literal> package was removed. This is due to SixXS + <link xlink:href="https://www.sixxs.net/main/"> sunsetting</link> its IPv6 + tunnel. + </para> + </listitem> + <listitem> + <para> + The <literal>fanctl</literal> package and <literal>fan</literal> module + have been removed due to the developers not upstreaming their iproute2 + patches and lagging with compatibility to recent iproute2 versions. + </para> + </listitem> + <listitem> + <para> + Top-level <literal>idea</literal> package collection was renamed. All + JetBrains IDEs are now at <literal>jetbrains</literal>. + </para> + </listitem> + <listitem> + <para> + <literal>flexget</literal>'s state database cannot be upgraded to its new + internal format, requiring removal of any existing + <literal>db-config.sqlite</literal> which will be automatically recreated. + </para> + </listitem> + <listitem> + <para> + The <literal>ipfs</literal> service now doesn't ignore the + <literal>dataDir</literal> option anymore. If you've ever set this option + to anything other than the default you'll have to either unset it (so the + default gets used) or migrate the old data manually with +<programlisting> +dataDir=<valueOfDataDir> +mv /var/lib/ipfs/.ipfs/* $dataDir +rmdir /var/lib/ipfs/.ipfs +</programlisting> + </para> + </listitem> + <listitem> + <para> + The <literal>caddy</literal> service was previously using an extra + <literal>.caddy</literal> directory in the data directory specified with + the <literal>dataDir</literal> option. The contents of the + <literal>.caddy</literal> directory are now expected to be in the + <literal>dataDir</literal>. + </para> + </listitem> + <listitem> + <para> + The <literal>ssh-agent</literal> user service is not started by default + anymore. Use <literal>programs.ssh.startAgent</literal> to enable it if + needed. There is also a new <literal>programs.gnupg.agent</literal> module + that creates a <literal>gpg-agent</literal> user service. It can also + serve as a SSH agent if <literal>enableSSHSupport</literal> is set. + </para> + </listitem> + <listitem> + <para> + The <literal>services.tinc.networks.<name>.listenAddress</literal> + option had a misleading name that did not correspond to its behavior. It + now correctly defines the ip to listen for incoming connections on. To + keep the previous behaviour, use + <literal>services.tinc.networks.<name>.bindToAddress</literal> + instead. Refer to the description of the options for more details. + </para> + </listitem> + <listitem> + <para> + <literal>tlsdate</literal> package and module were removed. This is due to + the project being dead and not building with openssl 1.1. + </para> + </listitem> + <listitem> + <para> + <literal>wvdial</literal> package and module were removed. This is due to + the project being dead and not building with openssl 1.1. + </para> + </listitem> + <listitem> + <para> + <literal>cc-wrapper</literal>'s setup-hook now exports a number of + environment variables corresponding to binutils binaries, (e.g. + <envar>LD</envar>, <envar>STRIP</envar>, <envar>RANLIB</envar>, etc). This + is done to prevent packages' build systems guessing, which is harder to + predict, especially when cross-compiling. However, some packages have + broken due to this—their build systems either not supporting, or + claiming to support without adequate testing, taking such environment + variables as parameters. + </para> + </listitem> + <listitem> + <para> + <literal>services.firefox.syncserver</literal> now runs by default as a + non-root user. To accomodate this change, the default sqlite database + location has also been changed. Migration should work automatically. Refer + to the description of the options for more details. + </para> + </listitem> + <listitem> + <para> + The <literal>compiz</literal> window manager and package was removed. The + system support had been broken for several years. + </para> + </listitem> + <listitem> + <para> + Touchpad support should now be enabled through <literal>libinput</literal> + as <literal>synaptics</literal> is now deprecated. See the option + <literal>services.xserver.libinput.enable</literal>. + </para> + </listitem> + <listitem> + <para> + grsecurity/PaX support has been dropped, following upstream's decision to + cease free support. See + <link xlink:href="https://grsecurity.net/passing_the_baton.php"> + upstream's announcement</link> for more information. No complete + replacement for grsecurity/PaX is available presently. + </para> + </listitem> + <listitem> + <para> + <literal>services.mysql</literal> now has declarative configuration of + databases and users with the <literal>ensureDatabases</literal> and + <literal>ensureUsers</literal> options. + </para> + <para> + These options will never delete existing databases and users, especially + not when the value of the options are changed. + </para> + <para> + The MySQL users will be identified using + <link xlink:href="https://mariadb.com/kb/en/library/authentication-plugin-unix-socket/"> + Unix socket authentication</link>. This authenticates the Unix user with + the same name only, and that without the need for a password. + </para> + <para> + If you have previously created a MySQL <literal>root</literal> user + <emphasis>with a password</emphasis>, you will need to add + <literal>root</literal> user for unix socket authentication before using + the new options. This can be done by running the following SQL script: +<programlisting language="sql"> +CREATE USER 'root'@'%' IDENTIFIED BY ''; +GRANT ALL PRIVILEGES ON *.* TO 'root'@'%' WITH GRANT OPTION; +FLUSH PRIVILEGES; + +-- Optionally, delete the password-authenticated user: +-- DROP USER 'root'@'localhost'; +</programlisting> + </para> + </listitem> + <listitem> + <para> + <literal>services.mysqlBackup</literal> now works by default without any + user setup, including for users other than <literal>mysql</literal>. + </para> + <para> + By default, the <literal>mysql</literal> user is no longer the user which + performs the backup. Instead a system account + <literal>mysqlbackup</literal> is used. + </para> + <para> + The <literal>mysqlBackup</literal> service is also now using systemd + timers instead of <literal>cron</literal>. + </para> + <para> + Therefore, the <literal>services.mysqlBackup.period</literal> option no + longer exists, and has been replaced with + <literal>services.mysqlBackup.calendar</literal>, which is in the format + of + <link + xlink:href="https://www.freedesktop.org/software/systemd/man/systemd.time.html#Calendar%20Events">systemd.time(7)</link>. + </para> + <para> + If you expect to be sent an e-mail when the backup fails, consider using a + script which monitors the systemd journal for errors. Regretfully, at + present there is no built-in functionality for this. + </para> + <para> + You can check that backups still work by running <command>systemctl start + mysql-backup</command> then <command>systemctl status + mysql-backup</command>. + </para> + </listitem> + <listitem> + <para> + Templated systemd services e.g <literal>container@name</literal> are now + handled currectly when switching to a new configuration, resulting in them + being reloaded. + </para> + </listitem> + <listitem> + <para> + Steam: the <literal>newStdcpp</literal> parameter was removed and should + not be needed anymore. + </para> + </listitem> + <listitem> + <para> + Redis has been updated to version 4 which mandates a cluster mass-restart, + due to changes in the network handling, in order to ensure compatibility + with networks NATing traffic. + </para> + </listitem> + </itemizedlist> + </section> + + <section xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-release-17.09-notable-changes"> + <title>Other Notable Changes</title> + + <itemizedlist> + <listitem> + <para> + Modules can now be disabled by using + <link + xlink:href="https://nixos.org/nixpkgs/manual/#sec-replace-modules"> + disabledModules</link>, allowing another to take it's place. This can be + used to import a set of modules from another channel while keeping the + rest of the system on a stable release. + </para> + </listitem> + <listitem> + <para> + Updated to FreeType 2.7.1, including a new TrueType engine. The new engine + replaces the Infinality engine which was the default in NixOS. The default + font rendering settings are now provided by fontconfig-penultimate, + replacing fontconfig-ultimate; the new defaults are less invasive and + provide rendering that is more consistent with other systems and hopefully + with each font designer's intent. Some system-wide configuration has been + removed from the Fontconfig NixOS module where user Fontconfig settings + are available. + </para> + </listitem> + <listitem> + <para> + ZFS/SPL have been updated to 0.7.0, <literal>zfsUnstable, + splUnstable</literal> have therefore been removed. + </para> + </listitem> + <listitem> + <para> + The <option>time.timeZone</option> option now allows the value + <literal>null</literal> in addition to timezone strings. This value allows + changing the timezone of a system imperatively using <command>timedatectl + set-timezone</command>. The default timezone is still UTC. + </para> + </listitem> + <listitem> + <para> + Nixpkgs overlays may now be specified with a file as well as a directory. + The value of <literal><nixpkgs-overlays></literal> may be a file, and + <filename>~/.config/nixpkgs/overlays.nix</filename> can be used instead of + the <filename>~/.config/nixpkgs/overlays</filename> directory. + </para> + <para> + See the overlays chapter of the Nixpkgs manual for more details. + </para> + </listitem> + <listitem> + <para> + Definitions for <filename>/etc/hosts</filename> can now be specified + declaratively with <literal>networking.hosts</literal>. + </para> + </listitem> + <listitem> + <para> + Two new options have been added to the installer loader, in addition to + the default having changed. The kernel log verbosity has been lowered to + the upstream default for the default options, in order to not spam the + console when e.g. joining a network. + </para> + <para> + This therefore leads to adding a new <literal>debug</literal> option to + set the log level to the previous verbose mode, to make debugging easier, + but still accessible easily. + </para> + <para> + Additionally a <literal>copytoram</literal> option has been added, which + makes it possible to remove the install medium after booting. This allows + tethering from your phone after booting from it. + </para> + </listitem> + <listitem> + <para> + <literal>services.gitlab-runner.configOptions</literal> has been added to + specify the configuration of gitlab-runners declaratively. + </para> + </listitem> + <listitem> + <para> + <literal>services.jenkins.plugins</literal> has been added to install + plugins easily, this can be generated with jenkinsPlugins2nix. + </para> + </listitem> + <listitem> + <para> + <literal>services.postfix.config</literal> has been added to specify the + main.cf with NixOS options. Additionally other options have been added to + the postfix module and has been improved further. + </para> + </listitem> + <listitem> + <para> + The GitLab package and module have been updated to the latest 10.0 + release. + </para> + </listitem> + <listitem> + <para> + The <literal>systemd-boot</literal> boot loader now lists the NixOS + version, kernel version and build date of all bootable generations. + </para> + </listitem> + <listitem> + <para> + The dnscrypt-proxy service now defaults to using a random upstream + resolver, selected from the list of public non-logging resolvers with + DNSSEC support. Existing configurations can be migrated to this mode of + operation by omitting the + <option>services.dnscrypt-proxy.resolverName</option> option or setting it + to <literal>"random"</literal>. + </para> + </listitem> + </itemizedlist> + </section> +</section> diff --git a/nixos/doc/manual/release-notes/rl-1803.xml b/nixos/doc/manual/release-notes/rl-1803.xml new file mode 100644 index 000000000000..c14679eea071 --- /dev/null +++ b/nixos/doc/manual/release-notes/rl-1803.xml @@ -0,0 +1,855 @@ +<section xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-release-18.03"> + <title>Release 18.03 (“Impala”, 2018/04/04)</title> + + <section xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-release-18.03-highlights"> + <title>Highlights</title> + + <para> + In addition to numerous new and upgraded packages, this release has the + following highlights: + </para> + + <itemizedlist> + <listitem> + <para> + End of support is planned for end of October 2018, handing over to 18.09. + </para> + </listitem> + <listitem> + <para> + Platform support: x86_64-linux and x86_64-darwin since release time (the + latter isn't NixOS, really). Binaries for aarch64-linux are available, but + no channel exists yet, as it's waiting for some test fixes, etc. + </para> + </listitem> + <listitem> + <para> + Nix now defaults to 2.0; see its + <link xlink:href="https://nixos.org/nix/manual/#ssec-relnotes-2.0">release + notes</link>. + </para> + </listitem> + <listitem> + <para> + Core version changes: linux: 4.9 -> 4.14, glibc: 2.25 -> 2.26, gcc: 6 -> + 7, systemd: 234 -> 237. + </para> + </listitem> + <listitem> + <para> + Desktop version changes: gnome: 3.24 -> 3.26, (KDE) plasma-desktop: 5.10 + -> 5.12. + </para> + </listitem> + <listitem> + <para> + MariaDB 10.2, updated from 10.1, is now the default MySQL implementation. + While upgrading a few changes have been made to the infrastructure + involved: + <itemizedlist> + <listitem> + <para> + <literal>libmysql</literal> has been deprecated, please use + <literal>mysql.connector-c</literal> instead, a compatibility passthru + has been added to the MySQL packages. + </para> + </listitem> + <listitem> + <para> + The <literal>mysql57</literal> package has a new + <literal>static</literal> output containing the static libraries + including <literal>libmysqld.a</literal> + </para> + </listitem> + </itemizedlist> + </para> + </listitem> + <listitem> + <para> + PHP now defaults to PHP 7.2, updated from 7.1. + </para> + </listitem> + </itemizedlist> + </section> + + <section xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-release-18.03-new-services"> + <title>New Services</title> + + <para> + The following new services were added since the last release: + </para> + + <itemizedlist> + <listitem> + <para> + <literal>./config/krb5/default.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./hardware/digitalbitbox.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./misc/label.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./programs/ccache.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./programs/criu.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./programs/digitalbitbox/default.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./programs/less.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./programs/npm.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./programs/plotinus.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./programs/rootston.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./programs/systemtap.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./programs/sway.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./programs/udevil.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./programs/way-cooler.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./programs/yabar.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./programs/zsh/zsh-autoenv.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/backup/borgbackup.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/backup/crashplan-small-business.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/desktops/dleyna-renderer.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/desktops/dleyna-server.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/desktops/pipewire.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/desktops/gnome3/chrome-gnome-shell.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/desktops/gnome3/tracker-miners.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/hardware/fwupd.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/hardware/interception-tools.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/hardware/u2f.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/hardware/usbmuxd.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/mail/clamsmtp.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/mail/dkimproxy-out.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/mail/pfix-srsd.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/misc/gitea.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/misc/home-assistant.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/misc/ihaskell.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/misc/logkeys.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/misc/novacomd.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/misc/osrm.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/misc/plexpy.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/misc/pykms.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/misc/tzupdate.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/monitoring/fusion-inventory.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/monitoring/prometheus/exporters.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/network-filesystems/beegfs.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/network-filesystems/davfs2.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/network-filesystems/openafs/client.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/network-filesystems/openafs/server.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/network-filesystems/ceph.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/networking/aria2.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/networking/monero.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/networking/nghttpx/default.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/networking/nixops-dns.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/networking/rxe.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/networking/stunnel.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/web-apps/matomo.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/web-apps/restya-board.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/web-servers/mighttpd2.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/x11/fractalart.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./system/boot/binfmt.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./system/boot/grow-partition.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./tasks/filesystems/ecryptfs.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./virtualisation/hyperv-guest.nix</literal> + </para> + </listitem> + </itemizedlist> + </section> + + <section xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-release-18.03-incompatibilities"> + <title>Backward Incompatibilities</title> + + <para> + When upgrading from a previous release, please be aware of the following + incompatible changes: + </para> + + <itemizedlist> + <listitem> + <para> + <literal>sound.enable</literal> now defaults to false. + </para> + </listitem> + <listitem> + <para> + Dollar signs in options under <option>services.postfix</option> are passed + verbatim to Postfix, which will interpret them as the beginning of a + parameter expression. This was already true for string-valued options in + the previous release, but not for list-valued options. If you need to pass + literal dollar signs through Postfix, double them. + </para> + </listitem> + <listitem> + <para> + The <literal>postage</literal> package (for web-based PostgreSQL + administration) has been renamed to <literal>pgmanage</literal>. The + corresponding module has also been renamed. To migrate please rename all + <option>services.postage</option> options to + <option>services.pgmanage</option>. + </para> + </listitem> + <listitem> + <para> + Package attributes starting with a digit have been prefixed with an + underscore sign. This is to avoid quoting in the configuration and other + issues with command-line tools like <literal>nix-env</literal>. The change + affects the following packages: + <itemizedlist> + <listitem> + <para> + <literal>2048-in-terminal</literal> → + <literal>_2048-in-terminal</literal> + </para> + </listitem> + <listitem> + <para> + <literal>90secondportraits</literal> → + <literal>_90secondportraits</literal> + </para> + </listitem> + <listitem> + <para> + <literal>2bwm</literal> → <literal>_2bwm</literal> + </para> + </listitem> + <listitem> + <para> + <literal>389-ds-base</literal> → <literal>_389-ds-base</literal> + </para> + </listitem> + </itemizedlist> + </para> + </listitem> + <listitem> + <para> + <emphasis role="strong"> The OpenSSH service no longer enables support for + DSA keys by default, which could cause a system lock out. Update your keys + or, unfavorably, re-enable DSA support manually. </emphasis> + </para> + <para> + DSA support was + <link xlink:href="https://www.openssh.com/legacy.html">deprecated in + OpenSSH 7.0</link>, due to it being too weak. To re-enable support, add + <literal>PubkeyAcceptedKeyTypes +ssh-dss</literal> to the end of your + <option>services.openssh.extraConfig</option>. + </para> + <para> + After updating the keys to be stronger, anyone still on a pre-17.03 + version is safe to jump to 17.03, as vetted + <link xlink:href="https://search.nix.gsc.io/?q=stateVersion">here</link>. + </para> + </listitem> + <listitem> + <para> + The <literal>openssh</literal> package now includes Kerberos support by + default; the <literal>openssh_with_kerberos</literal> package is now a + deprecated alias. If you do not want Kerberos support, you can do + <literal>openssh.override { withKerberos = false; }</literal>. Note, this + also applies to the <literal>openssh_hpn</literal> package. + </para> + </listitem> + <listitem> + <para> + <literal>cc-wrapper</literal> has been split in two; there is now also a + <literal>bintools-wrapper</literal>. The most commonly used files in + <filename>nix-support</filename> are now split between the two wrappers. + Some commonly used ones, like + <filename>nix-support/dynamic-linker</filename>, are duplicated for + backwards compatability, even though they rightly belong only in + <literal>bintools-wrapper</literal>. Other more obscure ones are just + moved. + </para> + </listitem> + <listitem> + <para> + The propagation logic has been changed. The new logic, along with new + types of dependencies that go with, is thoroughly documented in the + "Specifying dependencies" section of the "Standard Environment" chapter of + the nixpkgs manual. +<!-- That's <xref linkend="ssec-stdenv-attributes"> were we to merge the manuals. --> + The old logic isn't but is easy to describe: dependencies were propagated + as the same type of dependency no matter what. In practice, that means + that many <function>propagatedNativeBuildInputs</function> should instead + be <function>propagatedBuildInputs</function>. Thankfully, that was and is + the least used type of dependency. Also, it means that some + <function>propagatedBuildInputs</function> should instead be + <function>depsTargetTargetPropagated</function>. Other types dependencies + should be unaffected. + </para> + </listitem> + <listitem> + <para> + <literal>lib.addPassthru drv passthru</literal> is removed. Use + <literal>lib.extendDerivation true passthru drv</literal> instead. + </para> + </listitem> + <listitem> + <para> + The <literal>memcached</literal> service no longer accept dynamic socket + paths via <option>services.memcached.socket</option>. Unix sockets can be + still enabled by <option>services.memcached.enableUnixSocket</option> and + will be accessible at <literal>/run/memcached/memcached.sock</literal>. + </para> + </listitem> + <listitem> + <para> + The <varname>hardware.amdHybridGraphics.disable</varname> option was + removed for lack of a maintainer. If you still need this module, you may + wish to include a copy of it from an older version of nixos in your + imports. + </para> + </listitem> + <listitem> + <para> + The merging of config options for + <varname>services.postfix.config</varname> was buggy. Previously, if other + options in the Postfix module like + <varname>services.postfix.useSrs</varname> were set and the user set + config options that were also set by such options, the resulting config + wouldn't include all options that were needed. They are now merged + correctly. If config options need to be overridden, + <literal>lib.mkForce</literal> or <literal>lib.mkOverride</literal> can be + used. + </para> + </listitem> + <listitem> + <para> + The following changes apply if the <literal>stateVersion</literal> is + changed to 18.03 or higher. For <literal>stateVersion = "17.09"</literal> + or lower the old behavior is preserved. + </para> + <itemizedlist> + <listitem> + <para> + <literal>matrix-synapse</literal> uses postgresql by default instead of + sqlite. Migration instructions can be found + <link xlink:href="https://github.com/matrix-org/synapse/blob/master/docs/postgres.rst#porting-from-sqlite"> + here </link>. + </para> + </listitem> + </itemizedlist> + </listitem> + <listitem> + <para> + The <literal>jid</literal> package has been removed, due to maintenance + overhead of a go package having non-versioned dependencies. + </para> + </listitem> + <listitem> + <para> + When using <option>services.xserver.libinput</option> (enabled by default + in GNOME), it now handles all input devices, not just touchpads. As a + result, you might need to re-evaluate any custom Xorg configuration. In + particular, <literal>Option "XkbRules" "base"</literal> may result in + broken keyboard layout. + </para> + </listitem> + <listitem> + <para> + The <literal>attic</literal> package was removed. A maintained fork called + <link xlink:href="https://www.borgbackup.org/">Borg</link> should be used + instead. Migration instructions can be found + <link xlink:href="http://borgbackup.readthedocs.io/en/stable/usage/upgrade.html#attic-and-borg-0-xx-to-borg-1-x">here</link>. + </para> + </listitem> + <listitem> + <para> + The Piwik analytics software was renamed to Matomo: + <itemizedlist> + <listitem> + <para> + The package <literal>pkgs.piwik</literal> was renamed to + <literal>pkgs.matomo</literal>. + </para> + </listitem> + <listitem> + <para> + The service <literal>services.piwik</literal> was renamed to + <literal>services.matomo</literal>. + </para> + </listitem> + <listitem> + <para> + The data directory <filename>/var/lib/piwik</filename> was renamed to + <filename>/var/lib/matomo</filename>. All files will be moved + automatically on first startup, but you might need to adjust your + backup scripts. + </para> + </listitem> + <listitem> + <para> + The default <option>serverName</option> for the nginx configuration + changed from <literal>piwik.${config.networking.hostName}</literal> to + <literal>matomo.${config.networking.hostName}.${config.networking.domain}</literal> + if <option>config.networking.domain</option> is set, + <literal>matomo.${config.networking.hostName}</literal> if it is not + set. If you change your <option>serverName</option>, remember you'll + need to update the <literal>trustedHosts[]</literal> array in + <filename>/var/lib/matomo/config/config.ini.php</filename> as well. + </para> + </listitem> + <listitem> + <para> + The <literal>piwik</literal> user was renamed to + <literal>matomo</literal>. The service will adjust ownership + automatically for files in the data directory. If you use unix socket + authentication, remember to give the new <literal>matomo</literal> user + access to the database and to change the <literal>username</literal> to + <literal>matomo</literal> in the <literal>[database]</literal> section + of <filename>/var/lib/matomo/config/config.ini.php</filename>. + </para> + </listitem> + <listitem> + <para> + If you named your database `piwik`, you might want to rename it to + `matomo` to keep things clean, but this is neither enforced nor + required. + </para> + </listitem> + </itemizedlist> + </para> + </listitem> + <listitem> + <para> + <literal>nodejs-4_x</literal> is end-of-life. + <literal>nodejs-4_x</literal>, <literal>nodejs-slim-4_x</literal> and + <literal>nodePackages_4_x</literal> are removed. + </para> + </listitem> + <listitem> + <para> + The <literal>pump.io</literal> NixOS module was removed. It is now + maintained as an + <link xlink:href="https://github.com/rvl/pump.io-nixos">external + module</link>. + </para> + </listitem> + <listitem> + <para> + The Prosody XMPP server has received a major update. The following modules + were renamed: + <itemizedlist> + <listitem> + <para> + <option>services.prosody.modules.httpserver</option> is now + <option>services.prosody.modules.http_files</option> + </para> + </listitem> + <listitem> + <para> + <option>services.prosody.modules.console</option> is now + <option>services.prosody.modules.admin_telnet</option> + </para> + </listitem> + </itemizedlist> + </para> + <para> + Many new modules are now core modules, most notably + <option>services.prosody.modules.carbons</option> and + <option>services.prosody.modules.mam</option>. + </para> + <para> + The better-performing <literal>libevent</literal> backend is now enabled + by default. + </para> + <para> + <literal>withCommunityModules</literal> now passes through the modules to + <option>services.prosody.extraModules</option>. Use + <literal>withOnlyInstalledCommunityModules</literal> for modules that + should not be enabled directly, e.g <literal>lib_ldap</literal>. + </para> + </listitem> + <listitem> + <para> + All prometheus exporter modules are now defined as submodules. The + exporters are configured using + <literal>services.prometheus.exporters</literal>. + </para> + </listitem> + </itemizedlist> + </section> + + <section xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-release-18.03-notable-changes"> + <title>Other Notable Changes</title> + + <itemizedlist> + <listitem> + <para> + ZNC option <option>services.znc.mutable</option> now defaults to + <literal>true</literal>. That means that old configuration is not + overwritten by default when update to the znc options are made. + </para> + </listitem> + <listitem> + <para> + The option <option>networking.wireless.networks.<name>.auth</option> + has been added for wireless networks with WPA-Enterprise authentication. + There is also a new <option>extraConfig</option> option to directly + configure <literal>wpa_supplicant</literal> and <option>hidden</option> to + connect to hidden networks. + </para> + </listitem> + <listitem> + <para> + In the module <option>networking.interfaces.<name></option> the + following options have been removed: + <itemizedlist> + <listitem> + <para> + <option>ipAddress</option> + </para> + </listitem> + <listitem> + <para> + <option>ipv6Address</option> + </para> + </listitem> + <listitem> + <para> + <option>prefixLength</option> + </para> + </listitem> + <listitem> + <para> + <option>ipv6PrefixLength</option> + </para> + </listitem> + <listitem> + <para> + <option>subnetMask</option> + </para> + </listitem> + </itemizedlist> + To assign static addresses to an interface the options + <option>ipv4.addresses</option> and <option>ipv6.addresses</option> should + be used instead. The options <option>ip4</option> and <option>ip6</option> + have been renamed to <option>ipv4.addresses</option> + <option>ipv6.addresses</option> respectively. The new options + <option>ipv4.routes</option> and <option>ipv6.routes</option> have been + added to set up static routing. + </para> + </listitem> + <listitem> + <para> + The option <option>services.logstash.listenAddress</option> is now + <literal>127.0.0.1</literal> by default. Previously the default behaviour + was to listen on all interfaces. + </para> + </listitem> + <listitem> + <para> + <literal>services.btrfs.autoScrub</literal> has been added, to + periodically check btrfs filesystems for data corruption. If there's a + correct copy available, it will automatically repair corrupted blocks. + </para> + </listitem> + <listitem> + <para> + <literal>displayManager.lightdm.greeters.gtk.clock-format.</literal> has + been added, the clock format string (as expected by strftime, e.g. + <literal>%H:%M</literal>) to use with the lightdm gtk greeter panel. + </para> + <para> + If set to null the default clock format is used. + </para> + </listitem> + <listitem> + <para> + <literal>displayManager.lightdm.greeters.gtk.indicators</literal> has been + added, a list of allowed indicator modules to use with the lightdm gtk + greeter panel. + </para> + <para> + Built-in indicators include <literal>~a11y</literal>, + <literal>~language</literal>, <literal>~session</literal>, + <literal>~power</literal>, <literal>~clock</literal>, + <literal>~host</literal>, <literal>~spacer</literal>. Unity indicators can + be represented by short name (e.g. <literal>sound</literal>, + <literal>power</literal>), service file name, or absolute path. + </para> + <para> + If set to <literal>null</literal> the default indicators are used. + </para> + <para> + In order to have the previous default configuration add +<programlisting> + services.xserver.displayManager.lightdm.greeters.gtk.indicators = [ + "~host" "~spacer" + "~clock" "~spacer" + "~session" + "~language" + "~a11y" + "~power" + ]; +</programlisting> + to your <literal>configuration.nix</literal>. + </para> + </listitem> + <listitem> + <para> + The NixOS test driver supports user services declared by + <literal>systemd.user.services</literal>. The methods + <literal>waitForUnit</literal>, <literal>getUnitInfo</literal>, + <literal>startJob</literal> and <literal>stopJob</literal> provide an + optional <literal>$user</literal> argument for that purpose. + </para> + </listitem> + <listitem> + <para> + Enabling bash completion on NixOS, + <literal>programs.bash.enableCompletion</literal>, will now also enable + completion for the Nix command line tools by installing the + <link xlink:href="https://github.com/hedning/nix-bash-completions">nix-bash-completions</link> + package. + </para> + </listitem> + </itemizedlist> + </section> +</section> diff --git a/nixos/doc/manual/release-notes/rl-1809.xml b/nixos/doc/manual/release-notes/rl-1809.xml new file mode 100644 index 000000000000..f57fd75c782d --- /dev/null +++ b/nixos/doc/manual/release-notes/rl-1809.xml @@ -0,0 +1,311 @@ +<section xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-release-18.09"> + <title>Release 18.09 (“Jellyfish”, 2018/09/??)</title> + + <section xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-release-18.09-highlights"> + <title>Highlights</title> + + <para> + In addition to numerous new and upgraded packages, this release has the + following highlights: + </para> + + <itemizedlist> + <listitem> + <para> + User channels are now in the default <literal>NIX_PATH</literal>, allowing + users to use their personal <command>nix-channel</command> defined + channels in <command>nix-build</command> and <command>nix-shell</command> + commands, as well as in imports like <code>import + <mychannel></code>. + </para> + <para> + For example + </para> +<programlisting> +$ nix-channel --add https://nixos.org/channels/nixpkgs-unstable nixpkgsunstable +$ nix-channel --update +$ nix-build '<nixpkgsunstable>' -A gitFull +$ nix run -f '<nixpkgsunstable>' gitFull +$ nix-instantiate -E '(import <nixpkgsunstable> {}).gitFull' +</programlisting> + </listitem> + </itemizedlist> + </section> + + <section xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-release-18.09-new-services"> + <title>New Services</title> + + <para> + The following new services were added since the last release: + </para> + + <itemizedlist> + <listitem> + <para> + When enabled the <literal>iproute2</literal> will copy the files expected + by ip route (e.g., <filename>rt_tables</filename>) in + <filename>/run/iproute2</filename>. This allows to write aliases for + routing tables for instance. + </para> + </listitem> + </itemizedlist> + </section> + + <section xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-release-18.09-incompatibilities"> + <title>Backward Incompatibilities</title> + + <para> + When upgrading from a previous release, please be aware of the following + incompatible changes: + </para> + + <itemizedlist> + <listitem> + <para> + <literal>lib.strict</literal> is removed. Use + <literal>builtins.seq</literal> instead. + </para> + </listitem> + <listitem> + <para> + The <literal>clementine</literal> package points now to the free + derivation. <literal>clementineFree</literal> is removed now and + <literal>clementineUnfree</literal> points to the package which is bundled + with the unfree <literal>libspotify</literal> package. + </para> + </listitem> + <listitem> + <para> + The <literal>netcat</literal> package is now taken directly from OpenBSD's + <literal>libressl</literal>, instead of relying on Debian's fork. The new + version should be very close to the old version, but there are some minor + differences. Importantly, flags like -b, -q, -C, and -Z are no longer + accepted by the nc command. + </para> + </listitem> + <listitem> + <para> + The <varname>services.docker-registry.extraConfig</varname> object doesn't + contain environment variables anymore. Instead it needs to provide an + object structure that can be mapped onto the YAML configuration defined in + <link xlink:href="https://github.com/docker/distribution/blob/v2.6.2/docs/configuration.md">the + <varname>docker/distribution</varname> docs</link>. + </para> + </listitem> + <listitem> + <para> + <literal>gnucash</literal> has changed from version 2.4 to 3.x. If you've + been using <literal>gnucash</literal> (version 2.4) instead of + <literal>gnucash26</literal> (version 2.6) you must open your Gnucash data + file(s) with <literal>gnucash26</literal> and then save them to upgrade + the file format. Then you may use your data file(s) with Gnucash 3.x. See + the upgrade + <link xlink:href="https://wiki.gnucash.org/wiki/FAQ#Using_Different_Versions.2C_Up_And_Downgrade">documentation</link>. + Gnucash 2.4 is still available under the attribute + <literal>gnucash24</literal>. + </para> + </listitem> + <listitem> + <para> + <varname>services.munge</varname> now runs as user (and group) <literal>munge</literal> instead of root. + Make sure the key file is accessible to the daemon. + </para> + </listitem> + </itemizedlist> + </section> + + <section xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-release-18.09-notable-changes"> + <title>Other Notable Changes</title> + + <itemizedlist> + <listitem> + <para> + <literal>dockerTools.pullImage</literal> relies on image digest instead of + image tag to download the image. The <literal>sha256</literal> of a pulled + image has to be updated. + </para> + </listitem> + <listitem> + <para> + <literal>lib.attrNamesToStr</literal> has been deprecated. Use more + specific concatenation (<literal>lib.concat(Map)StringsSep</literal>) + instead. + </para> + </listitem> + <listitem> + <para> + <literal>lib.addErrorContextToAttrs</literal> has been deprecated. Use + <literal>builtins.addErrorContext</literal> directly. + </para> + </listitem> + <listitem> + <para> + <literal>lib.showVal</literal> has been deprecated. Use + <literal>lib.traceSeqN</literal> instead. + </para> + </listitem> + <listitem> + <para> + <literal>lib.traceXMLVal</literal> has been deprecated. Use + <literal>lib.traceValFn builtins.toXml</literal> instead. + </para> + </listitem> + <listitem> + <para> + <literal>lib.traceXMLValMarked</literal> has been deprecated. Use + <literal>lib.traceValFn (x: str + builtins.toXML x)</literal> instead. + </para> + </listitem> + <listitem> + <para> + The <literal>pkgs</literal> argument to NixOS modules can now be set directly using <literal>nixpkgs.pkgs</literal>. Previously, only the <literal>system</literal>, <literal>config</literal> and <literal>overlays</literal> arguments could be used to influence <literal>pkgs</literal>. + </para> + </listitem> + <listitem> + <para> + A NixOS system can now be constructed more easily based on a preexisting invocation of Nixpkgs. For example: + <programlisting> +inherit (pkgs.nixos { + boot.loader.grub.enable = false; + fileSystems."/".device = "/dev/xvda1"; +}) toplevel kernel initialRamdisk manual; + </programlisting> + + This benefits evaluation performance, lets you write Nixpkgs packages that depend on NixOS images and is consistent with a deployment architecture that would be centered around Nixpkgs overlays. + </para> + </listitem> + <listitem> + <para> + <literal>lib.traceValIfNot</literal> has been deprecated. Use + <literal>if/then/else</literal> and <literal>lib.traceValSeq</literal> instead. + </para> + </listitem> + <listitem> + <para> + <literal>lib.traceCallXml</literal> has been deprecated. Please complain + if you use the function regularly. + </para> + <para> + The attribute <literal>lib.nixpkgsVersion</literal> has been deprecated in + favor of <literal>lib.version</literal>. Please refer to the discussion in + <link xlink:href="https://github.com/NixOS/nixpkgs/pull/39416#discussion_r183845745">NixOS/nixpkgs#39416</link> + for further reference. + </para> + </listitem> + <listitem> + <para> + The module for <option>security.dhparams</option> has two new options now: + </para> + <variablelist> + <varlistentry> + <term> + <option>security.dhparams.stateless</option> + </term> + <listitem> + <para> + Puts the generated Diffie-Hellman parameters into the Nix store instead + of managing them in a stateful manner in + <filename class="directory">/var/lib/dhparams</filename>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <option>security.dhparams.defaultBitSize</option> + </term> + <listitem> + <para> + The default bit size to use for the generated Diffie-Hellman + parameters. + </para> + </listitem> + </varlistentry> + </variablelist> + <note> + <para> + The path to the actual generated parameter files should now be queried + using + <literal>config.security.dhparams.params.<replaceable>name</replaceable>.path</literal> + because it might be either in the Nix store or in a directory configured + by <option>security.dhparams.path</option>. + </para> + </note> + <note> + <title>For developers:</title> + <para> + Module implementers should not set a specific bit size in order to let + users configure it by themselves if they want to have a different bit + size than the default (2048). + </para> + <para> + An example usage of this would be: +<programlisting> +{ config, ... }: + +{ + security.dhparams.params.myservice = {}; + environment.etc."myservice.conf".text = '' + dhparams = ${config.security.dhparams.params.myservice.path} + ''; +} +</programlisting> + </para> + </note> + </listitem> + <listitem> + <para> + <literal>networking.networkmanager.useDnsmasq</literal> has been + deprecated. Use <literal>networking.networkmanager.dns</literal> instead. + </para> + </listitem> + <listitem> + <para> + The option + <varname>services.kubernetes.apiserver.admissionControl</varname> was + renamed to + <varname>services.kubernetes.apiserver.enableAdmissionPlugins</varname>. + </para> + </listitem> + <listitem> + <para> + Recommended way to access the Kubernetes Dashboard is via HTTPS (TLS) + Therefore; public service port for the dashboard has changed to 443 + (container port 8443) and scheme to https. + </para> + </listitem> + <listitem> + <para> + The option <varname>services.kubernetes.apiserver.address</varname> + was renamed to <varname>services.kubernetes.apiserver.bindAddress</varname>. + Note that the default value has changed from 127.0.0.1 to 0.0.0.0. + </para> + </listitem> + <listitem> + <para> + The option <varname>services.kubernetes.apiserver.publicAddress</varname> + was not used and thus has been removed. + </para> + </listitem> + </itemizedlist> + </section> +</section> diff --git a/nixos/doc/manual/release-notes/rl-unstable.xml b/nixos/doc/manual/release-notes/rl-unstable.xml deleted file mode 100644 index 2745fb2cbe42..000000000000 --- a/nixos/doc/manual/release-notes/rl-unstable.xml +++ /dev/null @@ -1,45 +0,0 @@ -<section xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="sec-release-unstable"> - -<title>Unstable</title> - -<para>When upgrading from a previous release, please be aware of the -following incompatible changes:</para> - -<itemizedlist> - <listitem> - <para><command>wmiiSnap</command> has been replaced with - <command>wmii_hg</command>, but - <command>services.xserver.windowManager.wmii.enable</command> has - been updated respectively so this only affects you if you have - explicitly installed <command>wmiiSnap</command>. - </para> - </listitem> - - <listitem> - <para><command>wmiimenu</command> is removed, as it has been - removed by the developers upstream. Use <command>wimenu</command> - from the <command>wmii-hg</command> package.</para> - </listitem> - - <listitem> - <para>Gitit is no longer automatically added to the module list in - NixOS and as such there will not be any manual entries for it. You - will need to add an import statement to your NixOS configuration - in order to use it, e.g. - -<programlisting><![CDATA[ -{ - imports = [ <nixos/modules/services/misc/gitit.nix> ]; -} -]]></programlisting> - - will include the Gitit service configuration options.</para> - </listitem> - -</itemizedlist> - -</section> diff --git a/nixos/doc/manual/shell.nix b/nixos/doc/manual/shell.nix new file mode 100644 index 000000000000..cc3609d750e0 --- /dev/null +++ b/nixos/doc/manual/shell.nix @@ -0,0 +1,8 @@ +let + pkgs = import ../../.. { }; +in +pkgs.mkShell { + name = "nixos-manual"; + + buildInputs = with pkgs; [ xmlformat jing xmloscopy ruby ]; +} diff --git a/nixos/doc/manual/style.css b/nixos/doc/manual/style.css deleted file mode 100644 index 3118b37ead1f..000000000000 --- a/nixos/doc/manual/style.css +++ /dev/null @@ -1,267 +0,0 @@ -/* Copied from http://bakefile.sourceforge.net/, which appears - licensed under the GNU GPL. */ - - -/*************************************************************************** - Basic headers and text: - ***************************************************************************/ - -body -{ - font-family: "Nimbus Sans L", sans-serif; - background: white; - margin: 2em 1em 2em 1em; -} - -h1, h2, h3, h4 -{ - color: #005aa0; -} - -h1 /* title */ -{ - font-size: 200%; -} - -h2 /* chapters, appendices, subtitle */ -{ - font-size: 180%; -} - -/* Extra space between chapters, appendices. */ -div.chapter > div.titlepage h2, div.appendix > div.titlepage h2 -{ - margin-top: 1.5em; -} - -div.section > div.titlepage h2 /* sections */ -{ - font-size: 150%; - margin-top: 1.5em; -} - -h3 /* subsections */ -{ - font-size: 125%; -} - -div.simplesect h2 -{ - font-size: 110%; -} - -div.appendix h3 -{ - font-size: 150%; - margin-top: 1.5em; -} - -div.refnamediv h2, div.refsynopsisdiv h2, div.refsection h2 /* refentry parts */ -{ - margin-top: 1.4em; - font-size: 125%; -} - -div.refsection h3 -{ - font-size: 110%; -} - - -/*************************************************************************** - Examples: - ***************************************************************************/ - -div.example -{ - border: 1px solid #b0b0b0; - padding: 6px 6px; - margin-left: 1.5em; - margin-right: 1.5em; - background: #f4f4f8; - border-radius: 0.4em; - box-shadow: 0.4em 0.4em 0.5em #e0e0e0; -} - -div.example p.title -{ - margin-top: 0em; -} - -div.example pre -{ - box-shadow: none; -} - - -/*************************************************************************** - Screen dumps: - ***************************************************************************/ - -pre.screen, pre.programlisting -{ - border: 1px solid #b0b0b0; - padding: 3px 3px; - margin-left: 1.5em; - margin-right: 1.5em; - color: #600000; - background: #f4f4f8; - font-family: monospace; - border-radius: 0.4em; - box-shadow: 0.4em 0.4em 0.5em #e0e0e0; -} - -div.example pre.programlisting -{ - border: 0px; - padding: 0 0; - margin: 0 0 0 0; -} - - -/*************************************************************************** - Notes, warnings etc: - ***************************************************************************/ - -.note, .warning -{ - border: 1px solid #b0b0b0; - padding: 3px 3px; - margin-left: 1.5em; - margin-right: 1.5em; - margin-bottom: 1em; - padding: 0.3em 0.3em 0.3em 0.3em; - background: #fffff5; - border-radius: 0.4em; - box-shadow: 0.4em 0.4em 0.5em #e0e0e0; -} - -div.note, div.warning -{ - font-style: italic; -} - -div.note h3, div.warning h3 -{ - color: red; - font-size: 100%; - padding-right: 0.5em; - display: inline; -} - -div.note p, div.warning p -{ - margin-bottom: 0em; -} - -div.note h3 + p, div.warning h3 + p -{ - display: inline; -} - -div.note h3 -{ - color: blue; - font-size: 100%; -} - -div.navfooter * -{ - font-size: 90%; -} - - -/*************************************************************************** - Links colors and highlighting: - ***************************************************************************/ - -a { text-decoration: none; } -a:hover { text-decoration: underline; } -a:link { color: #0048b3; } -a:visited { color: #002a6a; } - - -/*************************************************************************** - Table of contents: - ***************************************************************************/ - -div.toc -{ - font-size: 90%; -} - -div.toc dl -{ - margin-top: 0em; - margin-bottom: 0em; -} - - -/*************************************************************************** - Special elements: - ***************************************************************************/ - -tt, code -{ - color: #400000; -} - -.term -{ - font-weight: bold; - -} - -div.variablelist dd p, div.glosslist dd p -{ - margin-top: 0em; -} - -div.variablelist dd, div.glosslist dd -{ - margin-left: 1.5em; -} - -div.glosslist dt -{ - font-style: italic; -} - -.varname -{ - color: #400000; -} - -span.command strong -{ - font-weight: normal; - color: #400000; -} - -div.calloutlist table -{ - box-shadow: none; -} - -table -{ - border-collapse: collapse; - box-shadow: 0.4em 0.4em 0.5em #e0e0e0; -} - -table.simplelist -{ - text-align: left; - color: #005aa0; - border: 0; - padding: 5px; - background: #fffff5; - font-weight: normal; - font-style: italic; - box-shadow: none; - margin-bottom: 1em; -} - -div.navheader table, div.navfooter table { - box-shadow: none; -} diff --git a/nixos/doc/varlistentry-fixer.rb b/nixos/doc/varlistentry-fixer.rb new file mode 100755 index 000000000000..6c7cc1e6439b --- /dev/null +++ b/nixos/doc/varlistentry-fixer.rb @@ -0,0 +1,124 @@ +#!/usr/bin/env ruby + +# This script is written intended as a living, evolving tooling +# to fix oopsies within the docbook documentation. +# +# This is *not* a formatter. It, instead, handles some known cases +# where something bad happened, and fixing it manually is tedious. +# +# Read the code to see the different cases it handles. +# +# ALWAYS `make format` after fixing with this! +# ALWAYS read the changes, this tool isn't yet proven to be always right. + +require "rexml/document" +include REXML + +if ARGV.length < 1 then + $stderr.puts "Needs a filename." + exit 1 +end + +filename = ARGV.shift +doc = Document.new(File.open(filename)) + +$touched = false + +# Fixing varnames having a sibling element without spacing. +# This is to fix an initial `xmlformat` issue where `term` +# would mangle as spaces. +# +# <varlistentry> +# <term><varname>types.separatedString</varname><replaceable>sep</replaceable> <---- +# </term> +# ... +# +# Generates: types.separatedStringsep +# ^^^^ +# +# <varlistentry xml:id='fun-makeWrapper'> +# <term> +# <function>makeWrapper</function><replaceable>executable</replaceable><replaceable>wrapperfile</replaceable><replaceable>args</replaceable> <---- +# </term> +# +# Generates: makeWrapperexecutablewrapperfileargs +# ^^^^ ^^^^ ^^ ^^ +# +# <term> +# <option>--option</option><replaceable>name</replaceable><replaceable>value</replaceable> <----- +# </term> +# +# Generates: --optionnamevalue +# ^^ ^^ +doc.elements.each("//varlistentry/term") do |term| + ["varname", "function", "option", "replaceable"].each do |prev_name| + term.elements.each(prev_name) do |el| + if el.next_element and + el.next_element.name == "replaceable" and + el.next_sibling_node.class == Element + then + $touched = true + term.insert_after(el, Text.new(" ")) + end + end + end +end + + + +# <cmdsynopsis> +# <command>nixos-option</command> +# <arg> +# <option>-I</option><replaceable>path</replaceable> <------ +# </arg> +# +# Generates: -Ipath +# ^^ +doc.elements.each("//cmdsynopsis/arg") do |term| + ["option", "replaceable"].each do |prev_name| + term.elements.each(prev_name) do |el| + if el.next_element and + el.next_element.name == "replaceable" and + el.next_sibling_node.class == Element + then + $touched = true + term.insert_after(el, Text.new(" ")) + end + end + end +end + +# <cmdsynopsis> +# <arg> +# <group choice='req'> +# <arg choice='plain'> +# <option>--profile-name</option> +# </arg> +# +# <arg choice='plain'> +# <option>-p</option> +# </arg> +# </group><replaceable>name</replaceable> <---- +# </arg> +# +# Generates: [{--profile-name | -p }name] +# ^^^^ +doc.elements.each("//cmdsynopsis/arg") do |term| + ["group"].each do |prev_name| + term.elements.each(prev_name) do |el| + if el.next_element and + el.next_element.name == "replaceable" and + el.next_sibling_node.class == Element + then + $touched = true + term.insert_after(el, Text.new(" ")) + end + end + end +end + + +if $touched then + doc.context[:attribute_quote] = :quote + doc.write(output: File.open(filename, "w")) +end diff --git a/nixos/doc/xmlformat.conf b/nixos/doc/xmlformat.conf new file mode 100644 index 000000000000..4a565c8465bc --- /dev/null +++ b/nixos/doc/xmlformat.conf @@ -0,0 +1,73 @@ +# +# DocBook Configuration file for "xmlformat" +# see http://www.kitebird.com/software/xmlformat/ +# 10 Sept. 2004 +# + +# Only block elements +ackno address appendix article biblioentry bibliography bibliomixed \ +biblioset blockquote book bridgehead callout calloutlist caption caution \ +chapter chapterinfo classsynopsis cmdsynopsis colophon constraintdef \ +constructorsynopsis dedication destructorsynopsis entry epigraph equation example \ +figure formalpara funcsynopsis glossary glossdef glossdiv glossentry glosslist \ +glosssee glossseealso graphic graphicco highlights imageobjectco important \ +index indexdiv indexentry indexinfo info informalequation informalexample \ +informalfigure informaltable legalnotice literallayout lot lotentry mediaobject \ +mediaobjectco msgmain msgset note orderedlist para part preface primaryie \ +procedure qandadiv qandaentry qandaset refentry refentrytitle reference \ +refnamediv refsect1 refsect2 refsect3 refsection revhistory screenshot sect1 \ +sect2 sect3 sect4 sect5 section seglistitem set setindex sidebar simpara \ +simplesect step substeps synopfragment synopsis table term title \ +toc variablelist varlistentry warning itemizedlist listitem \ +footnote colspec partintro row simplelist subtitle tbody tgroup thead tip + format block + normalize no + + +#appendix bibliography chapter glossary preface reference +# element-break 3 + +sect1 section + element-break 2 + + +# +para abstract + format block + entry-break 1 + exit-break 1 + normalize yes + wrap-length 79 + +title + format block + normalize = yes + entry-break = 0 + exit-break = 0 + +# Inline elements +abbrev accel acronym action application citation citebiblioid citerefentry citetitle \ +classname co code command computeroutput constant country database date email emphasis \ +envar errorcode errorname errortext errortype exceptionname fax filename \ +firstname firstterm footnoteref foreignphrase funcdef funcparams function \ +glossterm group guibutton guiicon guilabel guimenu guimenuitem guisubmenu \ +hardware holder honorific indexterm inlineequation inlinegraphic inlinemediaobject \ +interface interfacename \ +keycap keycode keycombo keysym lineage link literal manvolnum markup medialabel \ +menuchoice methodname methodparam modifier mousebutton olink ooclass ooexception \ +oointerface option optional otheraddr othername package paramdef parameter personname \ +phrase pob postcode productname prompt property quote refpurpose replaceable \ +returnvalue revnumber sgmltag state street structfield structname subscript \ +superscript surname symbol systemitem token trademark type ulink userinput \ +uri varargs varname void wordasword xref year mathphrase member tag + format inline + +programlisting screen + format verbatim + entry-break = 0 + exit-break = 0 + +# This is needed so that the spacing inside those tags is kept. +term cmdsynopsis arg + normalize yes + format block |