diff options
Diffstat (limited to 'nixpkgs/nixos/doc/manual')
113 files changed, 16677 insertions, 0 deletions
diff --git a/nixpkgs/nixos/doc/manual/.gitignore b/nixpkgs/nixos/doc/manual/.gitignore new file mode 100644 index 000000000000..879282624217 --- /dev/null +++ b/nixpkgs/nixos/doc/manual/.gitignore @@ -0,0 +1,2 @@ +generated +manual-combined.xml diff --git a/nixpkgs/nixos/doc/manual/Makefile b/nixpkgs/nixos/doc/manual/Makefile new file mode 100644 index 000000000000..9ff599a0090f --- /dev/null +++ b/nixpkgs/nixos/doc/manual/Makefile @@ -0,0 +1,30 @@ +.PHONY: all +all: manual-combined.xml format + +.PHONY: debug +debug: generated manual-combined.xml + +manual-combined.xml: generated *.xml **/*.xml + rm -f ./manual-combined.xml + nix-shell --pure -Q --packages xmloscopy \ + --run "xmloscopy --docbook5 ./manual.xml ./manual-combined.xml" + +.PHONY: format +format: + nix-shell --pure -Q --packages xmlformat \ + --run "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/nixpkgs/nixos/doc/manual/README b/nixpkgs/nixos/doc/manual/README new file mode 100644 index 000000000000..587f6275197a --- /dev/null +++ b/nixpkgs/nixos/doc/manual/README @@ -0,0 +1,12 @@ +To build the manual, you need Nix installed on your system (no need +for NixOS). To install Nix, follow the instructions at + + https://nixos.org/nix/download.html + +When you have Nix on your system, in the root directory of the project +(i.e., `nixpkgs`), run: + + nix-build nixos/release.nix -A manual.x86_64-linux + +When this command successfully finishes, it will tell you where the +manual got generated. diff --git a/nixpkgs/nixos/doc/manual/administration/boot-problems.xml b/nixpkgs/nixos/doc/manual/administration/boot-problems.xml new file mode 100644 index 000000000000..de3d8ac21aeb --- /dev/null +++ b/nixpkgs/nixos/doc/manual/administration/boot-problems.xml @@ -0,0 +1,90 @@ +<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-boot-problems"> + <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 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/nixpkgs/nixos/doc/manual/administration/cleaning-store.xml b/nixpkgs/nixos/doc/manual/administration/cleaning-store.xml new file mode 100644 index 000000000000..526803e429ba --- /dev/null +++ b/nixpkgs/nixos/doc/manual/administration/cleaning-store.xml @@ -0,0 +1,63 @@ +<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-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: +<screen> +<prompt>$ </prompt>nix-collect-garbage +</screen> + Alternatively, you can use a systemd unit that does the same in the + background: +<screen> +<prompt># </prompt>systemctl start nix-gc.service +</screen> + You can tell NixOS in <filename>configuration.nix</filename> to run this unit + automatically at certain points in time, for instance, every night at 03:15: +<programlisting> +<xref linkend="opt-nix.gc.automatic"/> = true; +<xref linkend="opt-nix.gc.dates"/> = "03:15"; +</programlisting> + </para> + <para> + The commands above do not remove garbage collector roots, such as old system + configurations. Thus they do not remove the ability to roll back to previous + configurations. The following command deletes old roots, removing the ability + to roll back to them: +<screen> +<prompt>$ </prompt>nix-collect-garbage -d +</screen> + You can also do this for specific profiles, e.g. +<screen> +<prompt>$ </prompt>nix-env -p /nix/var/nix/profiles/per-user/eelco/profile --delete-generations old +</screen> + Note that NixOS system configurations are stored in the profile + <filename>/nix/var/nix/profiles/system</filename>. + </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> +<prompt>$ </prompt>nix-store --optimise +</screen> + Since this command needs to read the entire Nix store, it can take quite a + while to finish. + </para> + <section xml:id="sect-nixos-gc-boot-entries"> + <title>NixOS Boot Entries</title> + + <para> + If your <filename>/boot</filename> partition runs out of space, after + clearing old profiles you must rebuild your system with + <literal>nixos-rebuild</literal> to update the <filename>/boot</filename> + partition and clear space. + </para> + </section> +</chapter> diff --git a/nixpkgs/nixos/doc/manual/administration/container-networking.xml b/nixpkgs/nixos/doc/manual/administration/container-networking.xml new file mode 100644 index 000000000000..42486f01fe8c --- /dev/null +++ b/nixpkgs/nixos/doc/manual/administration/container-networking.xml @@ -0,0 +1,59 @@ +<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-container-networking"> + <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: +<screen> +<prompt># </prompt>nixos-container show-ip foo +10.233.4.2 + +<prompt>$ </prompt>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: +<programlisting> +<xref linkend="opt-networking.nat.enable"/> = true; +<xref linkend="opt-networking.nat.internalInterfaces"/> = ["ve-+"]; +<xref linkend="opt-networking.nat.externalInterface"/> = "eth0"; +</programlisting> + where <literal>eth0</literal> should be replaced with the desired external + interface. Note that <literal>ve-+</literal> is a wildcard that matches all + container interfaces. + </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> + + <para> + You may need to restart your system for the changes to take effect. + </para> +</section> diff --git a/nixpkgs/nixos/doc/manual/administration/containers.xml b/nixpkgs/nixos/doc/manual/administration/containers.xml new file mode 100644 index 000000000000..0d3355e56a58 --- /dev/null +++ b/nixpkgs/nixos/doc/manual/administration/containers.xml @@ -0,0 +1,34 @@ +<chapter xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="ch-containers"> + <title>Container Management</title> + <para> + NixOS allows you to easily run other NixOS instances as + <emphasis>containers</emphasis>. Containers are a light-weight approach to + virtualisation that runs software in the container at the same speed as in + the host system. NixOS containers share the Nix store of the host, making + container creation very efficient. + </para> + <warning> + <para> + Currently, NixOS containers are not perfectly isolated from the host system. + This means that a user with root access to the container can do things that + affect the host. So you should not give container root access to untrusted + users. + </para> + </warning> + <para> + NixOS containers can be created in two ways: imperatively, using the command + <command>nixos-container</command>, and declaratively, by specifying them in + your <filename>configuration.nix</filename>. The declarative approach implies + that containers get upgraded along with your host system when you run + <command>nixos-rebuild</command>, which is often not what you want. By + contrast, in the imperative approach, containers are configured and updated + independently from the host system. + </para> + <xi:include href="imperative-containers.xml" /> + <xi:include href="declarative-containers.xml" /> + <xi:include href="container-networking.xml" /> +</chapter> diff --git a/nixpkgs/nixos/doc/manual/administration/control-groups.xml b/nixpkgs/nixos/doc/manual/administration/control-groups.xml new file mode 100644 index 000000000000..16d03cc0d1ab --- /dev/null +++ b/nixpkgs/nixos/doc/manual/administration/control-groups.xml @@ -0,0 +1,65 @@ +<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-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: +<screen> +<prompt>$ </prompt>systemd-cgls +├─user +│ └─eelco +│ └─c1 +│ ├─ 2567 -:0 +│ ├─ 2682 kdeinit4: kdeinit4 Running... +│ ├─ <replaceable>...</replaceable> +│ └─10851 sh -c less -R +└─system + ├─httpd.service + │ ├─2444 httpd -f /nix/store/3pyacby5cpr55a03qwbnndizpciwq161-httpd.conf -DNO_DETACH + │ └─<replaceable>...</replaceable> + ├─dhcpcd.service + │ └─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>: +<programlisting> +<link linkend="opt-systemd.services._name_.serviceConfig">systemd.services.httpd.serviceConfig</link>.CPUShares = 512; +</programlisting> + By default, every cgroup has 1024 CPU shares, so this will halve the CPU + allocation of the <literal>httpd.service</literal> cgroup. + </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> +<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> +</chapter> diff --git a/nixpkgs/nixos/doc/manual/administration/declarative-containers.xml b/nixpkgs/nixos/doc/manual/administration/declarative-containers.xml new file mode 100644 index 000000000000..d03dbc4d7055 --- /dev/null +++ b/nixpkgs/nixos/doc/manual/administration/declarative-containers.xml @@ -0,0 +1,60 @@ +<section xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-declarative-containers"> + <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: +<programlisting> +containers.database = + { config = + { config, pkgs, ... }: + { <xref linkend="opt-services.postgresql.enable"/> = true; + <xref linkend="opt-services.postgresql.package"/> = pkgs.postgresql_9_6; + }; + }; +</programlisting> + If you run <literal>nixos-rebuild switch</literal>, the container will be + built. If the container was already running, it will be updated in place, + without rebooting. The container can be configured to start automatically by + setting <literal>containers.database.autoStart = true</literal> in its + configuration. + </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 = { + <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>. 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/nixpkgs/nixos/doc/manual/administration/imperative-containers.xml b/nixpkgs/nixos/doc/manual/administration/imperative-containers.xml new file mode 100644 index 000000000000..7ded0c11786e --- /dev/null +++ b/nixpkgs/nixos/doc/manual/administration/imperative-containers.xml @@ -0,0 +1,123 @@ +<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-imperative-containers"> + <title>Imperative Container Management</title> + + <para> + We’ll cover imperative container management using + <command>nixos-container</command> first. Be aware that container management + is currently only possible as <literal>root</literal>. + </para> + + <para> + You create a container with identifier <literal>foo</literal> as follows: +<screen> +# nixos-container create foo +</screen> + This creates the container’s root directory in + <filename>/var/lib/containers/foo</filename> and a small configuration file + in <filename>/etc/containers/foo.conf</filename>. It also builds the + container’s initial system configuration and stores it in + <filename>/nix/var/nix/profiles/per-container/foo/system</filename>. You can + modify the initial configuration of the container on the command line. For + instance, to create a container that has <command>sshd</command> running, + with the given public key for <literal>root</literal>: +<screen> +# nixos-container create foo --config ' + <xref linkend="opt-services.openssh.enable"/> = true; + <link linkend="opt-users.users._name__.openssh.authorizedKeys.keys">users.users.root.openssh.authorizedKeys.keys</link> = ["ssh-dss AAAAB3N…"]; +' +</screen> + By default the next free address in the <literal>10.233.0.0/16</literal> subnet will be chosen + as container IP. This behavior can be altered by setting <literal>--host-address</literal> and + <literal>--local-address</literal>: +<screen> +# nixos-container create test --config-file test-container.nix \ + --local-address 10.235.1.2 --host-address 10.235.1.1 +</screen> + </para> + + <para> + Creating a container does not start it. To start the container, run: +<screen> +# nixos-container start foo +</screen> + This command will return as soon as the container has booted and has reached + <literal>multi-user.target</literal>. On the host, the container runs within + a systemd unit called + <literal>container@<replaceable>container-name</replaceable>.service</literal>. + Thus, if something went wrong, you can get status info using + <command>systemctl</command>: +<screen> +# systemctl status container@foo +</screen> + </para> + + <para> + If the container has started successfully, you can log in as root using the + <command>root-login</command> operation: +<screen> +# nixos-container root-login foo +[root@foo:~]# +</screen> + Note that only root on the host can do this (since there is no + authentication). You can also get a regular login prompt using the + <command>login</command> operation, which is available to all users on the + host: +<screen> +# nixos-container login foo +foo login: alice +Password: *** +</screen> + With <command>nixos-container run</command>, you can execute arbitrary + commands in the container: +<screen> +# nixos-container run foo -- uname -a +Linux foo 3.4.82 #1-NixOS SMP Thu Mar 20 14:44:05 UTC 2014 x86_64 GNU/Linux +</screen> + </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 +<screen> +# nixos-container update foo +</screen> + This will build and activate the new configuration. You can also specify a + new configuration on the command line: +<screen> +# 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)/ +<!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 +<screen> +# nixos-container destroy foo +</screen> + </para> +</section> diff --git a/nixpkgs/nixos/doc/manual/administration/logging.xml b/nixpkgs/nixos/doc/manual/administration/logging.xml new file mode 100644 index 000000000000..da4877fcdf08 --- /dev/null +++ b/nixpkgs/nixos/doc/manual/administration/logging.xml @@ -0,0 +1,43 @@ +<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-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, +<screen> +<prompt>$ </prompt>journalctl -b +</screen> + shows all journal entries since the last reboot. (The output of + <command>journalctl</command> is piped into <command>less</command> by + default.) You can use various options and match operators to restrict output + to messages of interest. For instance, to get all messages from PostgreSQL: +<screen> +<prompt>$ </prompt>journalctl -u postgresql.service +-- Logs begin at Mon, 2013-01-07 13:28:01 CET, end at Tue, 2013-01-08 01:09:57 CET. -- +... +Jan 07 15:44:14 hagbard postgres[2681]: [2-1] LOG: database system is shut down +-- Reboot -- +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: +<screen> +<prompt>$ </prompt>journalctl -b -p crit +Dec 17 21:08:06 mandark sudo[3673]: pam_unix(sudo:auth): auth could not identify password for [alice] +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> diff --git a/nixpkgs/nixos/doc/manual/administration/maintenance-mode.xml b/nixpkgs/nixos/doc/manual/administration/maintenance-mode.xml new file mode 100644 index 000000000000..71e3f9ea665d --- /dev/null +++ b/nixpkgs/nixos/doc/manual/administration/maintenance-mode.xml @@ -0,0 +1,16 @@ +<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-maintenance-mode"> + <title>Maintenance Mode</title> + + <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> diff --git a/nixpkgs/nixos/doc/manual/administration/network-problems.xml b/nixpkgs/nixos/doc/manual/administration/network-problems.xml new file mode 100644 index 000000000000..570f58358845 --- /dev/null +++ b/nixpkgs/nixos/doc/manual/administration/network-problems.xml @@ -0,0 +1,27 @@ +<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-nix-network-issues"> + <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. +<screen> +# nixos-rebuild switch --option use-binary-caches false +</screen> + If you have an alternative binary cache at your disposal, you can use it + instead: +<screen> +# nixos-rebuild switch --option binary-caches http://my-cache.example.org/ +</screen> + </para> +</section> diff --git a/nixpkgs/nixos/doc/manual/administration/rebooting.xml b/nixpkgs/nixos/doc/manual/administration/rebooting.xml new file mode 100644 index 000000000000..a5abd6f02588 --- /dev/null +++ b/nixpkgs/nixos/doc/manual/administration/rebooting.xml @@ -0,0 +1,35 @@ +<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-rebooting"> + <title>Rebooting and Shutting Down</title> + <para> + The system can be shut down (and automatically powered off) by doing: +<screen> +# shutdown +</screen> + This is equivalent to running <command>systemctl poweroff</command>. + </para> + <para> + To reboot the system, run +<screen> +# reboot +</screen> + which is equivalent to <command>systemctl reboot</command>. Alternatively, + you can quickly reboot the system using <literal>kexec</literal>, which + bypasses the BIOS by directly loading the new kernel into memory: +<screen> +# systemctl kexec +</screen> + </para> + <para> + The machine can be suspended to RAM (if supported) using <command>systemctl + suspend</command>, and suspended to disk using <command>systemctl + hibernate</command>. + </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/nixpkgs/nixos/doc/manual/administration/rollback.xml b/nixpkgs/nixos/doc/manual/administration/rollback.xml new file mode 100644 index 000000000000..fb87810ba461 --- /dev/null +++ b/nixpkgs/nixos/doc/manual/administration/rollback.xml @@ -0,0 +1,41 @@ +<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-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: +<screen> +# /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: +<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: +<screen> +<prompt>$ </prompt>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> diff --git a/nixpkgs/nixos/doc/manual/administration/running.xml b/nixpkgs/nixos/doc/manual/administration/running.xml new file mode 100644 index 000000000000..19bec1f7794d --- /dev/null +++ b/nixpkgs/nixos/doc/manual/administration/running.xml @@ -0,0 +1,21 @@ +<part 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-running"> + <title>Administration</title> + <partintro xml:id="ch-running-intro"> + <para> + This chapter describes various aspects of managing a running NixOS system, + such as how to use the <command>systemd</command> service manager. + </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/nixpkgs/nixos/doc/manual/administration/service-mgmt.xml b/nixpkgs/nixos/doc/manual/administration/service-mgmt.xml new file mode 100644 index 000000000000..1b9c745eb59f --- /dev/null +++ b/nixpkgs/nixos/doc/manual/administration/service-mgmt.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-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: +<screen> +<prompt>$ </prompt>systemctl +-.mount loaded active mounted / +swapfile.swap loaded active active /swapfile +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: +<screen> +<prompt>$ </prompt>systemctl status postgresql.service +postgresql.service - PostgreSQL Server + Loaded: loaded (/nix/store/pn3q73mvh75gsrl8w7fdlfk3fq5qm5mw-unit/postgresql.service) + Active: active (running) since Mon, 2013-01-07 15:55:57 CET; 9h ago + Main PID: 2390 (postgres) + CGroup: name=systemd:/system/postgresql.service + ├─2390 postgres + ├─2418 postgres: writer process + ├─2419 postgres: wal writer process + ├─2420 postgres: autovacuum launcher process + ├─2421 postgres: stats collector process + └─2498 postgres: zabbix zabbix [local] idle + +Jan 07 15:55:55 hagbard postgres[2394]: [1-1] LOG: database system was shut down at 2013-01-07 15:55:05 CET +Jan 07 15:55:57 hagbard postgres[2390]: [1-1] LOG: database system is ready to accept connections +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: +<screen> +# 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> +<!-- - cgroups: each service and user session is a cgroup + +- cgroup resource management --> +</chapter> diff --git a/nixpkgs/nixos/doc/manual/administration/store-corruption.xml b/nixpkgs/nixos/doc/manual/administration/store-corruption.xml new file mode 100644 index 000000000000..b9d11152d5e1 --- /dev/null +++ b/nixpkgs/nixos/doc/manual/administration/store-corruption.xml @@ -0,0 +1,36 @@ +<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-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 +<screen> +<prompt># </prompt>nixos-rebuild switch --repair +</screen> + This will cause Nix to check every path in the closure, and if its + cryptographic hash differs from the hash recorded in Nix’s database, the + path is rebuilt or redownloaded. + </para> + + <para> + You can also scan the entire Nix store for corrupt paths: +<screen> +<prompt># </prompt>nix-store --verify --check-contents --repair +</screen> + Any corrupt paths will be redownloaded if they’re available in a binary + cache; otherwise, they cannot be repaired. + </para> +</section> diff --git a/nixpkgs/nixos/doc/manual/administration/troubleshooting.xml b/nixpkgs/nixos/doc/manual/administration/troubleshooting.xml new file mode 100644 index 000000000000..6496e7bde387 --- /dev/null +++ b/nixpkgs/nixos/doc/manual/administration/troubleshooting.xml @@ -0,0 +1,16 @@ +<chapter xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="ch-troubleshooting"> + <title>Troubleshooting</title> + <para> + This chapter describes solutions to common problems you might encounter when + you manage your NixOS system. + </para> + <xi:include href="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/nixpkgs/nixos/doc/manual/administration/user-sessions.xml b/nixpkgs/nixos/doc/manual/administration/user-sessions.xml new file mode 100644 index 000000000000..80daf6bdbff0 --- /dev/null +++ b/nixpkgs/nixos/doc/manual/administration/user-sessions.xml @@ -0,0 +1,45 @@ +<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-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> +<prompt>$ </prompt>loginctl + SESSION UID USER SEAT + c1 500 eelco seat0 + 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: +<screen> +<prompt>$ </prompt>loginctl session-status c3 +c3 - root (0) + Since: Tue, 2013-01-08 01:17:56 CET; 4min 42s ago + Leader: 2536 (login) + Seat: seat0; vc3 + TTY: /dev/tty3 + Service: login; type tty; class user + State: online + CGroup: name=systemd:/user/root/c3 + ├─ 2536 /nix/store/10mn4xip9n7y9bxqwnsx7xwx2v2g34xn-shadow-4.1.5.1/bin/login -- + ├─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: +<screen> +# loginctl terminate-session c3 +</screen> + </para> +</chapter> diff --git a/nixpkgs/nixos/doc/manual/configuration/abstractions.xml b/nixpkgs/nixos/doc/manual/configuration/abstractions.xml new file mode 100644 index 000000000000..5bf0635cc1aa --- /dev/null +++ b/nixpkgs/nixos/doc/manual/configuration/abstractions.xml @@ -0,0 +1,156 @@ +<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-module-abstractions"> + <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: +<programlisting> +{ + <xref linkend="opt-services.httpd.virtualHosts"/> = + [ { hostName = "example.org"; + documentRoot = "/webroot"; + adminAddr = "alice@example.org"; + enableUserDir = true; + } + { hostName = "example.org"; + documentRoot = "/webroot"; + adminAddr = "alice@example.org"; + enableUserDir = true; + enableSSL = true; + sslServerCert = "/root/ssl-example-org.crt"; + sslServerKey = "/root/ssl-example-org.key"; + } + ]; +} +</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>: +<programlisting> +let + exampleOrgCommon = + { hostName = "example.org"; + documentRoot = "/webroot"; + adminAddr = "alice@example.org"; + enableUserDir = true; + }; +in +{ + <xref linkend="opt-services.httpd.virtualHosts"/> = + [ exampleOrgCommon + (exampleOrgCommon // { + enableSSL = true; + sslServerCert = "/root/ssl-example-org.crt"; + sslServerKey = "/root/ssl-example-org.key"; + }) + ]; +} +</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: +<programlisting> +{ + <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: +<programlisting> +{ + <xref linkend="opt-services.httpd.virtualHosts"/> = + let + makeVirtualHost = name: + { hostName = name; + documentRoot = "/webroot"; + adminAddr = "alice@example.org"; + }; + in + [ (makeVirtualHost "example.org") + (makeVirtualHost "example.com") + (makeVirtualHost "example.gov") + (makeVirtualHost "example.nl") + ]; +} +</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: +<programlisting> +{ + <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: +<programlisting> +{ + <xref linkend="opt-services.httpd.virtualHosts"/> = + let + makeVirtualHost = { name, root }: + { hostName = name; + documentRoot = root; + adminAddr = "alice@example.org"; + }; + in map makeVirtualHost + [ { name = "example.org"; root = "/sites/example.org"; } + { name = "example.com"; root = "/sites/example.com"; } + { name = "example.gov"; root = "/sites/example.gov"; } + { name = "example.nl"; root = "/sites/example.nl"; } + ]; +} +</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 +<programlisting> +makeVirtualHost = name: + { hostName = name; + documentRoot = "/sites/${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> +</section> diff --git a/nixpkgs/nixos/doc/manual/configuration/ad-hoc-network-config.xml b/nixpkgs/nixos/doc/manual/configuration/ad-hoc-network-config.xml new file mode 100644 index 000000000000..00e595c7cb7f --- /dev/null +++ b/nixpkgs/nixos/doc/manual/configuration/ad-hoc-network-config.xml @@ -0,0 +1,20 @@ +<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="ad-hoc-network-config"> + <title>Ad-Hoc Configuration</title> + + <para> + You can use <xref linkend="opt-networking.localCommands"/> to specify shell + commands to be run at the end of <literal>network-setup.service</literal>. + This is useful for doing network configuration not covered by the existing + NixOS modules. For instance, to statically configure an IPv6 address: +<programlisting> +<xref linkend="opt-networking.localCommands"/> = + '' + ip -6 addr add 2001:610:685:1::1/64 dev eth0 + ''; +</programlisting> + </para> +</section> diff --git a/nixpkgs/nixos/doc/manual/configuration/ad-hoc-packages.xml b/nixpkgs/nixos/doc/manual/configuration/ad-hoc-packages.xml new file mode 100644 index 000000000000..c7e882d846fa --- /dev/null +++ b/nixpkgs/nixos/doc/manual/configuration/ad-hoc-packages.xml @@ -0,0 +1,61 @@ +<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-ad-hoc-packages"> + <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: +<screen> +<prompt>$ </prompt>nix-env -iA nixos.thunderbird</screen> + If you invoke this as root, the package is installed in the Nix profile + <filename>/nix/var/nix/profiles/default</filename> and visible to all users + of the system; otherwise, the package ends up in + <filename>/nix/var/nix/profiles/per-user/<replaceable>username</replaceable>/profile</filename> + and is not visible to other users. The <option>-A</option> flag specifies the + package by its attribute name; without it, the package is installed by + matching against its package name (e.g. <literal>thunderbird</literal>). The + latter is slower because it requires matching against all available Nix + packages, and is ambiguous if there are multiple matching packages. + </para> + + <para> + Packages come from the NixOS channel. You typically upgrade a package by + updating to the latest version of the NixOS channel: +<screen> +<prompt>$ </prompt>nix-channel --update nixos +</screen> + and then running <literal>nix-env -i</literal> again. Other packages in the + profile are <emphasis>not</emphasis> affected; this is the crucial difference + with the declarative style of package management, where running + <command>nixos-rebuild switch</command> causes all packages to be updated to + their current versions in the NixOS channel. You can however upgrade all + packages for which there is a newer version by doing: +<screen> +<prompt>$ </prompt>nix-env -u '*' +</screen> + </para> + + <para> + A package can be uninstalled using the <option>-e</option> flag: +<screen> +<prompt>$ </prompt>nix-env -e thunderbird +</screen> + </para> + + <para> + Finally, you can roll back an undesirable <command>nix-env</command> action: +<screen> +<prompt>$ </prompt>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> +</section> diff --git a/nixpkgs/nixos/doc/manual/configuration/adding-custom-packages.xml b/nixpkgs/nixos/doc/manual/configuration/adding-custom-packages.xml new file mode 100644 index 000000000000..182641055e4d --- /dev/null +++ b/nixpkgs/nixos/doc/manual/configuration/adding-custom-packages.xml @@ -0,0 +1,73 @@ +<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-custom-packages"> + <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: +<screen> +<prompt>$ </prompt>git clone https://github.com/NixOS/nixpkgs +<prompt>$ </prompt>cd nixpkgs +</screen> + Then you write and test the package as described in the Nixpkgs manual. + Finally, you add it to <literal>environment.systemPackages</literal>, e.g. +<programlisting> +<xref linkend="opt-environment.systemPackages"/> = [ pkgs.my-package ]; +</programlisting> + and you run <command>nixos-rebuild</command>, specifying your own Nixpkgs + tree: +<screen> +# nixos-rebuild switch -I nixpkgs=/path/to/my/nixpkgs</screen> + </para> + + <para> + The second possibility is to add the package outside of the Nixpkgs tree. For + instance, here is how you specify a build of the + <link xlink:href="https://www.gnu.org/software/hello/">GNU Hello</link> + package directly in <filename>configuration.nix</filename>: +<programlisting> +<xref linkend="opt-environment.systemPackages"/> = + let + my-hello = with pkgs; stdenv.mkDerivation rec { + name = "hello-2.8"; + src = fetchurl { + url = "mirror://gnu/hello/${name}.tar.gz"; + sha256 = "0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6"; + }; + }; + in + [ my-hello ]; +</programlisting> + Of course, you can also move the definition of <literal>my-hello</literal> + into a separate Nix expression, e.g. +<programlisting> +<xref linkend="opt-environment.systemPackages"/> = [ (import ./my-hello.nix) ]; +</programlisting> + where <filename>my-hello.nix</filename> contains: +<programlisting> +with import <nixpkgs> {}; # bring all of Nixpkgs into scope + +stdenv.mkDerivation rec { + name = "hello-2.8"; + src = fetchurl { + url = "mirror://gnu/hello/${name}.tar.gz"; + sha256 = "0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6"; + }; +} +</programlisting> + This allows testing the package easily: +<screen> +<prompt>$ </prompt>nix-build my-hello.nix +<prompt>$ </prompt>./result/bin/hello +Hello, world! +</screen> + </para> +</section> diff --git a/nixpkgs/nixos/doc/manual/configuration/config-file.xml b/nixpkgs/nixos/doc/manual/configuration/config-file.xml new file mode 100644 index 000000000000..eadafb94b8f6 --- /dev/null +++ b/nixpkgs/nixos/doc/manual/configuration/config-file.xml @@ -0,0 +1,211 @@ +<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-configuration-file"> + <title>NixOS Configuration File</title> + + <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, +<programlisting> +{ config, pkgs, ... }: + +{ <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, + <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, ... }: + +{ services = { + httpd = { + enable = true; + adminAddr = "alice@example.org"; + documentRoot = "/webroot"; + }; + }; +} +</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: +<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: +<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> + <listitem> + <para> + Strings are enclosed in double quotes, e.g. +<programlisting> +<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. +<programlisting> +<xref linkend="opt-networking.extraHosts"/> = + '' + 127.0.0.2 other-localhost + 10.0.0.1 server + ''; +</programlisting> + The main difference is that it strips from each line a number of spaces + equal to the minimal indentation of the string as a whole (disregarding + the indentation of empty lines), and that characters like + <literal>"</literal> and <literal>\</literal> are not special (making it + more convenient for including things like shell code). See more info + about this in the Nix manual + <link + xlink:href="https://nixos.org/nix/manual/#ssec-values">here</link>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + Booleans + </term> + <listitem> + <para> + These can be <literal>true</literal> or <literal>false</literal>, e.g. +<programlisting> +<xref linkend="opt-networking.firewall.enable"/> = true; +<xref linkend="opt-networking.firewall.allowPing"/> = false; +</programlisting> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + Integers + </term> + <listitem> + <para> + For example, +<programlisting> +<xref linkend="opt-boot.kernel.sysctl"/>."net.ipv4.tcp_keepalive_time" = 60; +</programlisting> + (Note that here the attribute name + <literal>net.ipv4.tcp_keepalive_time</literal> is enclosed in quotes to + prevent it from being interpreted as a set named <literal>net</literal> + containing a set named <literal>ipv4</literal>, and so on. This is + because it’s not a NixOS option but the literal name of a Linux kernel + setting.) + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + Sets + </term> + <listitem> + <para> + Sets were introduced above. They are name/value pairs enclosed in braces, + as in the option definition +<programlisting> +<xref linkend="opt-fileSystems"/>."/boot" = + { device = "/dev/sda1"; + fsType = "ext4"; + options = [ "rw" "data=ordered" "relatime" ]; + }; +</programlisting> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + Lists + </term> + <listitem> + <para> + The important thing to note about lists is that list elements are + separated by whitespace, like this: +<programlisting> +<xref linkend="opt-boot.kernelModules"/> = [ "fuse" "kvm-intel" "coretemp" ]; +</programlisting> + List elements can be any other type, e.g. sets: +<programlisting> +swapDevices = [ { device = "/dev/disk/by-label/swap"; } ]; +</programlisting> + </para> + </listitem> + </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: +<programlisting> +<xref linkend="opt-environment.systemPackages"/> = + [ pkgs.thunderbird + pkgs.emacs + ]; + +<xref linkend="opt-services.postgresql.package"/> = pkgs.postgresql_10; +</programlisting> + The latter option definition changes the default PostgreSQL package used + by NixOS’s PostgreSQL service to 10.x. For more information on + packages, including how to add new ones, see + <xref linkend="sec-custom-packages"/>. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> +</section> diff --git a/nixpkgs/nixos/doc/manual/configuration/config-syntax.xml b/nixpkgs/nixos/doc/manual/configuration/config-syntax.xml new file mode 100644 index 000000000000..5ef498cf9ae3 --- /dev/null +++ b/nixpkgs/nixos/doc/manual/configuration/config-syntax.xml @@ -0,0 +1,25 @@ +<chapter xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-configuration-syntax"> + <title>Configuration Syntax</title> + <para> + The NixOS configuration file + <filename>/etc/nixos/configuration.nix</filename> is actually a <emphasis>Nix + expression</emphasis>, which is the Nix package manager’s purely functional + language for describing how to build packages and configurations. This means + you have all the expressive power of that language at your disposal, + including the ability to abstract over common patterns, which is very useful + when managing complex systems. The syntax and semantics of the Nix language + are fully described in the + <link +xlink:href="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" /> +</chapter> diff --git a/nixpkgs/nixos/doc/manual/configuration/configuration.xml b/nixpkgs/nixos/doc/manual/configuration/configuration.xml new file mode 100644 index 000000000000..5961209bc13a --- /dev/null +++ b/nixpkgs/nixos/doc/manual/configuration/configuration.xml @@ -0,0 +1,29 @@ +<part 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-configuration"> + <title>Configuration</title> + <partintro xml:id="ch-configuration-intro"> + <para> + This chapter describes how to configure various aspects of a NixOS machine + through the configuration file + <filename>/etc/nixos/configuration.nix</filename>. As described in + <xref linkend="sec-changing-config" />, changes to this file only take + effect after you run <command>nixos-rebuild</command>. + </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="matrix.xml" /> + <xi:include href="../generated/modules.xml" xpointer="xpointer(//section[@id='modules']/*)" /> + <xi:include href="profiles.xml" /> + <xi:include href="kubernetes.xml" /> +<!-- Apache; libvirtd virtualisation --> +</part> diff --git a/nixpkgs/nixos/doc/manual/configuration/customizing-packages.xml b/nixpkgs/nixos/doc/manual/configuration/customizing-packages.xml new file mode 100644 index 000000000000..03b5bb53197b --- /dev/null +++ b/nixpkgs/nixos/doc/manual/configuration/customizing-packages.xml @@ -0,0 +1,86 @@ +<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-customising-packages"> + <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> + + <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> +<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> + + <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> +<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> + + <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> +</section> diff --git a/nixpkgs/nixos/doc/manual/configuration/declarative-packages.xml b/nixpkgs/nixos/doc/manual/configuration/declarative-packages.xml new file mode 100644 index 000000000000..5fb3bcb9f8f5 --- /dev/null +++ b/nixpkgs/nixos/doc/manual/configuration/declarative-packages.xml @@ -0,0 +1,48 @@ +<section xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-declarative-package-mgmt"> + <title>Declarative Package Management</title> + + <para> + With declarative package management, you specify which packages you want on + your system by setting the option + <xref linkend="opt-environment.systemPackages"/>. For instance, adding the + following line to <filename>configuration.nix</filename> enables the Mozilla + Thunderbird email application: +<programlisting> +<xref linkend="opt-environment.systemPackages"/> = [ pkgs.thunderbird ]; +</programlisting> + The effect of this specification is that the Thunderbird package from Nixpkgs + will be built or downloaded as part of the system when you run + <command>nixos-rebuild switch</command>. + </para> + + <para> + You can get a list of the available packages as follows: +<screen> +<prompt>$ </prompt>nix-env -qaP '*' --description +nixos.firefox firefox-23.0 Mozilla Firefox - the browser, reloaded +<replaceable>...</replaceable> +</screen> + The first column in the output is the <emphasis>attribute name</emphasis>, + such as <literal>nixos.thunderbird</literal>. + </para> + <para> + Note: the <literal>nixos</literal> prefix tells us that we want to get the + package from the <literal>nixos</literal> channel and works only in CLI tools. + + In declarative configuration use <literal>pkgs</literal> prefix (variable). + </para> + + <para> + To “uninstall” a package, simply remove it from + <xref linkend="opt-environment.systemPackages"/> and run + <command>nixos-rebuild switch</command>. + </para> + + <xi:include href="customizing-packages.xml" /> + + <xi:include href="adding-custom-packages.xml" /> +</section> diff --git a/nixpkgs/nixos/doc/manual/configuration/file-systems.xml b/nixpkgs/nixos/doc/manual/configuration/file-systems.xml new file mode 100644 index 000000000000..e4c03de71b72 --- /dev/null +++ b/nixpkgs/nixos/doc/manual/configuration/file-systems.xml @@ -0,0 +1,46 @@ +<chapter xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="ch-file-systems"> + <title>File Systems</title> + <para> + You can define file systems using the <option>fileSystems</option> + configuration option. For instance, the following definition causes NixOS to + mount the Ext4 file system on device + <filename>/dev/disk/by-label/data</filename> onto the mount point + <filename>/data</filename>: +<programlisting> +<xref linkend="opt-fileSystems"/>."/data" = + { device = "/dev/disk/by-label/data"; + fsType = "ext4"; + }; +</programlisting> + 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/nixpkgs/nixos/doc/manual/configuration/firewall.xml b/nixpkgs/nixos/doc/manual/configuration/firewall.xml new file mode 100644 index 000000000000..47a19ac82c0f --- /dev/null +++ b/nixpkgs/nixos/doc/manual/configuration/firewall.xml @@ -0,0 +1,37 @@ +<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-firewall"> + <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: +<programlisting> +<xref linkend="opt-networking.firewall.enable"/> = false; +</programlisting> + If the firewall is enabled, you can open specific TCP ports to the outside + world: +<programlisting> +<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><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> +<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> +</section> diff --git a/nixpkgs/nixos/doc/manual/configuration/ipv4-config.xml b/nixpkgs/nixos/doc/manual/configuration/ipv4-config.xml new file mode 100644 index 000000000000..71ddf41491ba --- /dev/null +++ b/nixpkgs/nixos/doc/manual/configuration/ipv4-config.xml @@ -0,0 +1,43 @@ +<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-ipv4"> + <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: +<programlisting> +<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: +<programlisting> +<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 <xref linkend="opt-networking.hostName"/>: +<programlisting> +<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> +</section> diff --git a/nixpkgs/nixos/doc/manual/configuration/ipv6-config.xml b/nixpkgs/nixos/doc/manual/configuration/ipv6-config.xml new file mode 100644 index 000000000000..675a5d9a260d --- /dev/null +++ b/nixpkgs/nixos/doc/manual/configuration/ipv6-config.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-ipv6"> + <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> + 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> +<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> + 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/nixpkgs/nixos/doc/manual/configuration/kubernetes.xml b/nixpkgs/nixos/doc/manual/configuration/kubernetes.xml new file mode 100644 index 000000000000..54a100e44795 --- /dev/null +++ b/nixpkgs/nixos/doc/manual/configuration/kubernetes.xml @@ -0,0 +1,112 @@ +<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-kubernetes"> + <title>Kubernetes</title> + <para> + The NixOS Kubernetes module is a collective term for a handful of individual + submodules implementing the Kubernetes cluster components. + </para> + <para> + There are generally two ways of enabling Kubernetes on NixOS. One way is to + enable and configure cluster components appropriately by hand: +<programlisting> +services.kubernetes = { + apiserver.enable = true; + controllerManager.enable = true; + scheduler.enable = true; + addonManager.enable = true; + proxy.enable = true; + flannel.enable = true; +}; +</programlisting> + Another way is to assign cluster roles ("master" and/or "node") to the host. + This enables apiserver, controllerManager, scheduler, addonManager, + kube-proxy and etcd: +<programlisting> +<xref linkend="opt-services.kubernetes.roles"/> = [ "master" ]; +</programlisting> + While this will enable the kubelet and kube-proxy only: +<programlisting> +<xref linkend="opt-services.kubernetes.roles"/> = [ "node" ]; +</programlisting> + Assigning both the master and node roles is usable if you want a single node + Kubernetes cluster for dev or testing purposes: +<programlisting> +<xref linkend="opt-services.kubernetes.roles"/> = [ "master" "node" ]; +</programlisting> + Note: Assigning either role will also default both + <xref linkend="opt-services.kubernetes.flannel.enable"/> and + <xref linkend="opt-services.kubernetes.easyCerts"/> to true. This sets up + flannel as CNI and activates automatic PKI bootstrapping. + </para> + <para> + As of kubernetes 1.10.X it has been deprecated to open non-tls-enabled ports + on kubernetes components. Thus, from NixOS 19.03 all plain HTTP ports have + been disabled by default. While opening insecure ports is still possible, it + is recommended not to bind these to other interfaces than loopback. To + re-enable the insecure port on the apiserver, see options: + <xref linkend="opt-services.kubernetes.apiserver.insecurePort"/> and + <xref linkend="opt-services.kubernetes.apiserver.insecureBindAddress"/> + </para> + <note> + <para> + As of NixOS 19.03, it is mandatory to configure: + <xref linkend="opt-services.kubernetes.masterAddress"/>. The masterAddress + must be resolveable and routeable by all cluster nodes. In single node + clusters, this can be set to <literal>localhost</literal>. + </para> + </note> + <para> + Role-based access control (RBAC) authorization mode is enabled by default. + This means that anonymous requests to the apiserver secure port will + expectedly cause a permission denied error. All cluster components must + therefore be configured with x509 certificates for two-way tls communication. + The x509 certificate subject section determines the roles and permissions + granted by the apiserver to perform clusterwide or namespaced operations. See + also: + <link + xlink:href="https://kubernetes.io/docs/reference/access-authn-authz/rbac/"> + Using RBAC Authorization</link>. + </para> + <para> + The NixOS kubernetes module provides an option for automatic certificate + bootstrapping and configuration, + <xref linkend="opt-services.kubernetes.easyCerts"/>. The PKI bootstrapping + process involves setting up a certificate authority (CA) daemon (cfssl) on + the kubernetes master node. cfssl generates a CA-cert for the cluster, and + uses the CA-cert for signing subordinate certs issued to each of the cluster + components. Subsequently, the certmgr daemon monitors active certificates and + renews them when needed. For single node Kubernetes clusters, setting + <xref linkend="opt-services.kubernetes.easyCerts"/> = true is sufficient and + no further action is required. For joining extra node machines to an existing + cluster on the other hand, establishing initial trust is mandatory. + </para> + <para> + To add new nodes to the cluster: On any (non-master) cluster node where + <xref linkend="opt-services.kubernetes.easyCerts"/> is enabled, the helper + script <literal>nixos-kubernetes-node-join</literal> is available on PATH. + Given a token on stdin, it will copy the token to the kubernetes secrets + directory and restart the certmgr service. As requested certificates are + issued, the script will restart kubernetes cluster components as needed for + them to pick up new keypairs. + </para> + <note> + <para> + Multi-master (HA) clusters are not supported by the easyCerts module. + </para> + </note> + <para> + In order to interact with an RBAC-enabled cluster as an administrator, one + needs to have cluster-admin privileges. By default, when easyCerts is + enabled, a cluster-admin kubeconfig file is generated and linked into + <literal>/etc/kubernetes/cluster-admin.kubeconfig</literal> as determined by + <xref linkend="opt-services.kubernetes.pki.etcClusterAdminKubeconfig"/>. + <literal>export KUBECONFIG=/etc/kubernetes/cluster-admin.kubeconfig</literal> + will make kubectl use this kubeconfig to access and authenticate the cluster. + The cluster-admin kubeconfig references an auto-generated keypair owned by + root. Thus, only root on the kubernetes master may obtain cluster-admin + rights by means of this file. + </para> +</chapter> diff --git a/nixpkgs/nixos/doc/manual/configuration/linux-kernel.xml b/nixpkgs/nixos/doc/manual/configuration/linux-kernel.xml new file mode 100644 index 000000000000..644d3a33ffd2 --- /dev/null +++ b/nixpkgs/nixos/doc/manual/configuration/linux-kernel.xml @@ -0,0 +1,138 @@ +<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-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: +<programlisting> +<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: +<programlisting> +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: +<programlisting> +nixpkgs.config.packageOverrides = pkgs: + { linux_3_4 = pkgs.linux_3_4.override { + extraConfig = + '' + KGDB y + ''; + }; + }; +</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 + <xref linkend="opt-boot.kernelModules"/>, e.g. +<programlisting> +<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 <xref linkend="opt-boot.initrd.kernelModules"/>: +<programlisting> +<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 + <xref linkend="opt-boot.kernel.sysctl"/>, e.g. +<programlisting> +<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> + <section xml:id="sec-linux-config-customizing"> + <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 xml:id="sec-linux-config-developing-modules"> + <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/nixpkgs/nixos/doc/manual/configuration/luks-file-systems.xml b/nixpkgs/nixos/doc/manual/configuration/luks-file-systems.xml new file mode 100644 index 000000000000..8a2b107e0ee8 --- /dev/null +++ b/nixpkgs/nixos/doc/manual/configuration/luks-file-systems.xml @@ -0,0 +1,40 @@ +<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-luks-file-systems"> + <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/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d</filename>: +<screen> +# cryptsetup luksFormat /dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d + +WARNING! +======== +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/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 +</screen> + To ensure that this file system is automatically mounted at boot time as + <filename>/</filename>, add the following to + <filename>configuration.nix</filename>: +<programlisting> +<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> + 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/nixpkgs/nixos/doc/manual/configuration/matrix.xml b/nixpkgs/nixos/doc/manual/configuration/matrix.xml new file mode 100644 index 000000000000..ef8d5cbda889 --- /dev/null +++ b/nixpkgs/nixos/doc/manual/configuration/matrix.xml @@ -0,0 +1,203 @@ +<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="module-services-matrix"> + <title>Matrix</title> + <para> + <link xlink:href="https://matrix.org/">Matrix</link> is an open standard for + interoperable, decentralised, real-time communication over IP. It can be used + to power Instant Messaging, VoIP/WebRTC signalling, Internet of Things + communication - or anywhere you need a standard HTTP API for publishing and + subscribing to data whilst tracking the conversation history. + </para> + <para> + This chapter will show you how to set up your own, self-hosted Matrix + homeserver using the Synapse reference homeserver, and how to serve your own + copy of the Riot web client. See the + <link xlink:href="https://matrix.org/docs/projects/try-matrix-now.html">Try + Matrix Now!</link> overview page for links to Riot Apps for Android and iOS, + desktop clients, as well as bridges to other networks and other projects + around Matrix. + </para> + <section xml:id="module-services-matrix-synapse"> + <title>Synapse Homeserver</title> + + <para> + <link xlink:href="https://github.com/matrix-org/synapse">Synapse</link> is + the reference homeserver implementation of Matrix from the core development + team at matrix.org. The following configuration example will set up a + synapse server for the <literal>example.org</literal> domain, served from + the host <literal>myhostname.example.org</literal>. For more information, + please refer to the + <link xlink:href="https://github.com/matrix-org/synapse#synapse-installation"> + installation instructions of Synapse </link>. +<programlisting> +let + fqdn = + let + join = hostName: domain: hostName + optionalString (domain != null) ".${domain}"; + in join config.networking.hostName config.networking.domain; +in { + networking = { + hostName = "myhostname"; + domain = "example.org"; + }; + networking.firewall.allowedTCPPorts = [ 80 443 ]; + + services.nginx = { + enable = true; + # only recommendedProxySettings and recommendedGzipSettings are strictly required, + # but the rest make sense as well + recommendedTlsSettings = true; + recommendedOptimisation = true; + recommendedGzipSettings = true; + recommendedProxySettings = true; + + virtualHosts = { + # This host section can be placed on a different host than the rest, + # i.e. to delegate from the host being accessible as ${config.networking.domain} + # to another host actually running the Matrix homeserver. + "${config.networking.domain}" = { + locations."= /.well-known/matrix/server".extraConfig = + let + # use 443 instead of the default 8448 port to unite + # the client-server and server-server port for simplicity + server = { "m.server" = "${fqdn}:443"; }; + in '' + add_header Content-Type application/json; + return 200 '${builtins.toJSON server}'; + ''; + locations."= /.well-known/matrix/client".extraConfig = + let + client = { + "m.homeserver" = { "base_url" = "https://${fqdn}"; }; + "m.identity_server" = { "base_url" = "https://vector.im"; }; + }; + # ACAO required to allow riot-web on any URL to request this json file + in '' + add_header Content-Type application/json; + add_header Access-Control-Allow-Origin *; + return 200 '${builtins.toJSON client}'; + ''; + }; + + # Reverse proxy for Matrix client-server and server-server communication + ${fqdn} = { + enableACME = true; + forceSSL = true; + + # Or do a redirect instead of the 404, or whatever is appropriate for you. + # But do not put a Matrix Web client here! See the Riot Web section below. + locations."/".extraConfig = '' + return 404; + ''; + + # forward all Matrix API calls to the synapse Matrix homeserver + locations."/_matrix" = { + proxyPass = "http://[::1]:8008"; # without a trailing / + }; + }; + }; + }; + services.matrix-synapse = { + enable = true; + server_name = config.networking.domain; + listeners = [ + { + port = 8008; + bind_address = "::1"; + type = "http"; + tls = false; + x_forwarded = true; + resources = [ + { names = [ "client" "federation" ]; compress = false; } + ]; + } + ]; + }; +}; +</programlisting> + </para> + + <para> + If the <code>A</code> and <code>AAAA</code> DNS records on + <literal>example.org</literal> do not point on the same host as the records + for <code>myhostname.example.org</code>, you can easily move the + <code>/.well-known</code> virtualHost section of the code to the host that + is serving <literal>example.org</literal>, while the rest stays on + <literal>myhostname.example.org</literal> with no other changes required. + This pattern also allows to seamlessly move the homeserver from + <literal>myhostname.example.org</literal> to + <literal>myotherhost.example.org</literal> by only changing the + <code>/.well-known</code> redirection target. + </para> + + <para> + If you want to run a server with public registration by anybody, you can + then enable <option>services.matrix-synapse.enable_registration = + true;</option>. Otherwise, or you can generate a registration secret with + <command>pwgen -s 64 1</command> and set it with + <option>services.matrix-synapse.registration_shared_secret</option>. To + create a new user or admin, run the following after you have set the secret + and have rebuilt NixOS: +<screen> +<prompt>$ </prompt>nix run nixpkgs.matrix-synapse +<prompt>$ </prompt>register_new_matrix_user -k <replaceable>your-registration-shared-secret</replaceable> http://localhost:8008 +<prompt>New user localpart: </prompt><replaceable>your-username</replaceable> +<prompt>Password:</prompt> +<prompt>Confirm password:</prompt> +<prompt>Make admin [no]:</prompt> +Success! +</screen> + In the example, this would create a user with the Matrix Identifier + <literal>@your-username:example.org</literal>. Note that the registration + secret ends up in the nix store and therefore is world-readable by any user + on your machine, so it makes sense to only temporarily activate the + <option>registration_shared_secret</option> option until a better solution + for NixOS is in place. + </para> + </section> + <section xml:id="module-services-matrix-riot-web"> + <title>Riot Web Client</title> + + <para> + <link xlink:href="https://github.com/vector-im/riot-web/">Riot Web</link> is + the reference web client for Matrix and developed by the core team at + matrix.org. The following snippet can be optionally added to the code before + to complete the synapse installation with a web client served at + <code>https://riot.myhostname.example.org</code> and + <code>https://riot.example.org</code>. Alternatively, you can use the hosted + copy at <link xlink:href="https://riot.im/app">https://riot.im/app</link>, + or use other web clients or native client applications. Due to the + <literal>/.well-known</literal> urls set up done above, many clients should + fill in the required connection details automatically when you enter your + Matrix Identifier. See + <link xlink:href="https://matrix.org/docs/projects/try-matrix-now.html">Try + Matrix Now!</link> for a list of existing clients and their supported + featureset. +<programlisting> +services.nginx.virtualHosts."riot.${fqdn}" = { + enableACME = true; + forceSSL = true; + serverAliases = [ + "riot.${config.networking.domain}" + ]; + + root = pkgs.riot-web; +}; +</programlisting> + </para> + + <para> + Note that the Riot developers do not recommend running Riot and your Matrix + homeserver on the same fully-qualified domain name for security reasons. In + the example, this means that you should not reuse the + <literal>myhostname.example.org</literal> virtualHost to also serve Riot, + but instead serve it on a different subdomain, like + <literal>riot.example.org</literal> in the example. See the + <link xlink:href="https://github.com/vector-im/riot-web#important-security-note">Riot + Important Security Notes</link> for more information on this subject. + </para> + </section> +</chapter> diff --git a/nixpkgs/nixos/doc/manual/configuration/modularity.xml b/nixpkgs/nixos/doc/manual/configuration/modularity.xml new file mode 100644 index 000000000000..7ad0ae80a48a --- /dev/null +++ b/nixpkgs/nixos/doc/manual/configuration/modularity.xml @@ -0,0 +1,145 @@ +<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-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.: +<programlisting> +{ config, pkgs, ... }: + +{ imports = [ ./vpn.nix ./kde.nix ]; + <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: +<programlisting> +{ config, pkgs, ... }: + +{ <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 + <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> +<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 <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: +<programlisting> +<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 xml:id="footnote-nix-is-lazy"> + <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, ... }: + +{ <xref linkend="opt-environment.systemPackages"/> = + if config.<xref linkend="opt-services.xserver.enable"/> then + [ pkgs.firefox + pkgs.thunderbird + ] + else + [ ]; +} +</programlisting> + </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: +<screen> +<prompt>$ </prompt>nixos-option <xref linkend="opt-services.xserver.enable"/> +true + +<prompt>$ </prompt>nixos-option <xref linkend="opt-boot.kernelModules"/> +[ "tun" "ipv6" "loop" <replaceable>...</replaceable> ] +</screen> + Interactive exploration of the configuration is possible using <command>nix + repl</command>, a read-eval-print loop for Nix expressions. A typical use: +<screen> +<prompt>$ </prompt>nix repl '<nixpkgs/nixos>' + +<prompt>nix-repl> </prompt>config.<xref linkend="opt-networking.hostName"/> +"mandark" + +<prompt>nix-repl> </prompt>map (x: x.hostName) config.<xref linkend="opt-services.httpd.virtualHosts"/> +[ "example.org" "example.gov" ] +</screen> + </para> + + <para> + While abstracting your configuration, you may find it useful to generate + modules using code, instead of writing files. The example below would have + the same effect as importing a file which sets those options. +<programlisting> +{ config, pkgs, ... }: + +let netConfig = { hostName }: { + networking.hostName = hostName; + networking.useDHCP = false; +}; + +in + +{ imports = [ (netConfig "nixos.localdomain") ]; } +</programlisting> + </para> +</section> diff --git a/nixpkgs/nixos/doc/manual/configuration/network-manager.xml b/nixpkgs/nixos/doc/manual/configuration/network-manager.xml new file mode 100644 index 000000000000..d103ee249783 --- /dev/null +++ b/nixpkgs/nixos/doc/manual/configuration/network-manager.xml @@ -0,0 +1,44 @@ +<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-networkmanager"> + <title>NetworkManager</title> + + <para> + To facilitate network configuration, some desktop environments use + NetworkManager. You can enable NetworkManager by setting: +<programlisting> +<xref linkend="opt-networking.networkmanager.enable"/> = true; +</programlisting> + 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: +<programlisting> +<link linkend="opt-users.users._name__.extraGroups">users.users.alice.extraGroups</link> = [ "networkmanager" ]; +</programlisting> + </para> + + <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/nixpkgs/nixos/doc/manual/configuration/networking.xml b/nixpkgs/nixos/doc/manual/configuration/networking.xml new file mode 100644 index 000000000000..02cf811e0bd3 --- /dev/null +++ b/nixpkgs/nixos/doc/manual/configuration/networking.xml @@ -0,0 +1,19 @@ +<chapter xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-networking"> + <title>Networking</title> + <para> + This section describes how to configure networking components on your NixOS + machine. + </para> + <xi:include href="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/nixpkgs/nixos/doc/manual/configuration/package-mgmt.xml b/nixpkgs/nixos/doc/manual/configuration/package-mgmt.xml new file mode 100644 index 000000000000..e8ac5d0681a9 --- /dev/null +++ b/nixpkgs/nixos/doc/manual/configuration/package-mgmt.xml @@ -0,0 +1,31 @@ +<chapter xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + 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" /> +</chapter> diff --git a/nixpkgs/nixos/doc/manual/configuration/profiles.xml b/nixpkgs/nixos/doc/manual/configuration/profiles.xml new file mode 100644 index 000000000000..9d08f7f7bed2 --- /dev/null +++ b/nixpkgs/nixos/doc/manual/configuration/profiles.xml @@ -0,0 +1,39 @@ +<chapter xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="ch-profiles"> + <title>Profiles</title> + <para> + In some cases, it may be desirable to take advantage of commonly-used, + predefined configurations provided by nixpkgs, but different from those that + come as default. This is a role fulfilled by NixOS's Profiles, which come as + files living in <filename><nixpkgs/nixos/modules/profiles></filename>. + That is to say, expected usage is to add them to the imports list of your + <filename>/etc/configuration.nix</filename> as such: + </para> +<programlisting> + imports = [ + <nixpkgs/nixos/modules/profiles/profile-name.nix> + ]; +</programlisting> + <para> + Even if some of these profiles seem only useful in the context of install + media, many are actually intended to be used in real installs. + </para> + <para> + What follows is a brief explanation on the purpose and use-case for each + profile. Detailing each option configured by each one is out of scope. + </para> + <xi:include href="profiles/all-hardware.xml" /> + <xi:include href="profiles/base.xml" /> + <xi:include href="profiles/clone-config.xml" /> + <xi:include href="profiles/demo.xml" /> + <xi:include href="profiles/docker-container.xml" /> + <xi:include href="profiles/graphical.xml" /> + <xi:include href="profiles/hardened.xml" /> + <xi:include href="profiles/headless.xml" /> + <xi:include href="profiles/installation-device.xml" /> + <xi:include href="profiles/minimal.xml" /> + <xi:include href="profiles/qemu-guest.xml" /> +</chapter> diff --git a/nixpkgs/nixos/doc/manual/configuration/profiles/all-hardware.xml b/nixpkgs/nixos/doc/manual/configuration/profiles/all-hardware.xml new file mode 100644 index 000000000000..2936f71069d5 --- /dev/null +++ b/nixpkgs/nixos/doc/manual/configuration/profiles/all-hardware.xml @@ -0,0 +1,21 @@ +<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-profile-all-hardware"> + <title>All Hardware</title> + + <para> + Enables all hardware supported by NixOS: i.e., all firmware is included, and + all devices from which one may boot are enabled in the initrd. Its primary + use is in the NixOS installation CDs. + </para> + + <para> + The enabled kernel modules include support for SATA and PATA, SCSI + (partially), USB, Firewire (untested), Virtio (QEMU, KVM, etc.), VMware, and + Hyper-V. Additionally, <xref linkend="opt-hardware.enableAllFirmware"/> is + enabled, and the firmware for the ZyDAS ZD1211 chipset is specifically + installed. + </para> +</section> diff --git a/nixpkgs/nixos/doc/manual/configuration/profiles/base.xml b/nixpkgs/nixos/doc/manual/configuration/profiles/base.xml new file mode 100644 index 000000000000..b75f6ba25b4f --- /dev/null +++ b/nixpkgs/nixos/doc/manual/configuration/profiles/base.xml @@ -0,0 +1,15 @@ +<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-profile-base"> + <title>Base</title> + + <para> + Defines the software packages included in the "minimal" installation CD. It + installs several utilities useful in a simple recovery or install media, such + as a text-mode web browser, and tools for manipulating block devices, + networking, hardware diagnostics, and filesystems (with their respective + kernel modules). + </para> +</section> diff --git a/nixpkgs/nixos/doc/manual/configuration/profiles/clone-config.xml b/nixpkgs/nixos/doc/manual/configuration/profiles/clone-config.xml new file mode 100644 index 000000000000..234835845e2d --- /dev/null +++ b/nixpkgs/nixos/doc/manual/configuration/profiles/clone-config.xml @@ -0,0 +1,14 @@ +<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-profile-clone-config"> + <title>Clone Config</title> + + <para> + This profile is used in installer images. It provides an editable + configuration.nix that imports all the modules that were also used when + creating the image in the first place. As a result it allows users to edit + and rebuild the live-system. + </para> +</section> diff --git a/nixpkgs/nixos/doc/manual/configuration/profiles/demo.xml b/nixpkgs/nixos/doc/manual/configuration/profiles/demo.xml new file mode 100644 index 000000000000..395a5ec357c9 --- /dev/null +++ b/nixpkgs/nixos/doc/manual/configuration/profiles/demo.xml @@ -0,0 +1,15 @@ +<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-profile-demo"> + <title>Demo</title> + + <para> + This profile just enables a <systemitem class="username">demo</systemitem> + user, with password <literal>demo</literal>, uid <literal>1000</literal>, + <systemitem class="groupname">wheel</systemitem> group and + <link linkend="opt-services.xserver.displayManager.sddm.autoLogin"> autologin + in the SDDM display manager</link>. + </para> +</section> diff --git a/nixpkgs/nixos/doc/manual/configuration/profiles/docker-container.xml b/nixpkgs/nixos/doc/manual/configuration/profiles/docker-container.xml new file mode 100644 index 000000000000..efa7b8f24c43 --- /dev/null +++ b/nixpkgs/nixos/doc/manual/configuration/profiles/docker-container.xml @@ -0,0 +1,16 @@ +<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-profile-docker-container"> + <title>Docker Container</title> + + <para> + This is the profile from which the Docker images are generated. It prepares a + working system by importing the + <link linkend="sec-profile-minimal">Minimal</link> and + <link linkend="sec-profile-clone-config">Clone Config</link> profiles, and + setting appropriate configuration options that are useful inside a container + context, like <xref linkend="opt-boot.isContainer"/>. + </para> +</section> diff --git a/nixpkgs/nixos/doc/manual/configuration/profiles/graphical.xml b/nixpkgs/nixos/doc/manual/configuration/profiles/graphical.xml new file mode 100644 index 000000000000..73e3abc59d0c --- /dev/null +++ b/nixpkgs/nixos/doc/manual/configuration/profiles/graphical.xml @@ -0,0 +1,22 @@ +<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-profile-graphical"> + <title>Graphical</title> + + <para> + Defines a NixOS configuration with the Plasma 5 desktop. It's used by the + graphical installation CD. + </para> + + <para> + It sets <xref linkend="opt-services.xserver.enable"/>, + <xref linkend="opt-services.xserver.displayManager.sddm.enable"/>, + <xref linkend="opt-services.xserver.desktopManager.plasma5.enable"/> ( + <link linkend="opt-services.xserver.desktopManager.plasma5.enableQt4Support"> + without Qt4 Support</link>), and + <xref linkend="opt-services.xserver.libinput.enable"/> to true. It also + includes glxinfo and firefox in the system packages list. + </para> +</section> diff --git a/nixpkgs/nixos/doc/manual/configuration/profiles/hardened.xml b/nixpkgs/nixos/doc/manual/configuration/profiles/hardened.xml new file mode 100644 index 000000000000..dc83fc837e2a --- /dev/null +++ b/nixpkgs/nixos/doc/manual/configuration/profiles/hardened.xml @@ -0,0 +1,24 @@ +<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-profile-hardened"> + <title>Hardened</title> + + <para> + A profile with most (vanilla) hardening options enabled by default, + potentially at the cost of features and performance. + </para> + + <para> + This includes a hardened kernel, and limiting the system information + available to processes through the <filename>/sys</filename> and + <filename>/proc</filename> filesystems. It also disables the User Namespaces + feature of the kernel, which stops Nix from being able to build anything + (this particular setting can be overriden via + <xref linkend="opt-security.allowUserNamespaces"/>). See the + <literal + xlink:href="https://github.com/nixos/nixpkgs/tree/master/nixos/modules/profiles/hardened.nix"> + profile source</literal> for further detail on which settings are altered. + </para> +</section> diff --git a/nixpkgs/nixos/doc/manual/configuration/profiles/headless.xml b/nixpkgs/nixos/doc/manual/configuration/profiles/headless.xml new file mode 100644 index 000000000000..1b64497ebf7f --- /dev/null +++ b/nixpkgs/nixos/doc/manual/configuration/profiles/headless.xml @@ -0,0 +1,19 @@ +<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-profile-headless"> + <title>Headless</title> + + <para> + Common configuration for headless machines (e.g., Amazon EC2 instances). + </para> + + <para> + Disables <link linkend="opt-sound.enable">sound</link>, + <link linkend="opt-boot.vesa">vesa</link>, serial consoles, + <link linkend="opt-systemd.enableEmergencyMode">emergency mode</link>, + <link linkend="opt-boot.loader.grub.splashImage">grub splash images</link> + and configures the kernel to reboot automatically on panic. + </para> +</section> diff --git a/nixpkgs/nixos/doc/manual/configuration/profiles/installation-device.xml b/nixpkgs/nixos/doc/manual/configuration/profiles/installation-device.xml new file mode 100644 index 000000000000..3dcdf403d89d --- /dev/null +++ b/nixpkgs/nixos/doc/manual/configuration/profiles/installation-device.xml @@ -0,0 +1,38 @@ +<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-profile-installation-device"> + <title>Installation Device</title> + + <para> + Provides a basic configuration for installation devices like CDs. This means + enabling hardware scans, using the <link linkend="sec-profile-clone-config"> + Clone Config profile</link> to guarantee + <filename>/etc/nixos/configuration.nix</filename> exists (for + <command>nixos-rebuild</command> to work), a copy of the Nixpkgs channel + snapshot used to create the install media. + </para> + + <para> + Additionally, documentation for <link linkend="opt-documentation.enable"> + Nixpkgs</link> and <link linkend="opt-documentation.nixos.enable">NixOS + </link> are forcefully enabled (to override the + <link linkend="sec-profile-minimal">Minimal profile</link> preference); the + NixOS manual is shown automatically on TTY 8, sudo and udisks are disabled. + Autologin is enabled as root. + </para> + + <para> + A message is shown to the user to start a display manager if needed, ssh with + <xref linkend="opt-services.openssh.permitRootLogin"/> are enabled (but + doesn't autostart). WPA Supplicant is also enabled without autostart. + </para> + + <para> + Finally, vim is installed, root is set to not have a password, the kernel is + made more silent for remote public IP installs, and several settings are + tweaked so that the installer has a better chance of succeeding under + low-memory environments. + </para> +</section> diff --git a/nixpkgs/nixos/doc/manual/configuration/profiles/minimal.xml b/nixpkgs/nixos/doc/manual/configuration/profiles/minimal.xml new file mode 100644 index 000000000000..179f2d0be64b --- /dev/null +++ b/nixpkgs/nixos/doc/manual/configuration/profiles/minimal.xml @@ -0,0 +1,17 @@ +<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-profile-minimal"> + <title>Minimal</title> + + <para> + This profile defines a small NixOS configuration. It does not contain any + graphical stuff. It's a very short file that enables + <link linkend="opt-environment.noXlibs">noXlibs</link>, sets + <link linkend="opt-i18n.supportedLocales">i18n.supportedLocales</link> to + only support the user-selected locale, + <link linkend="opt-documentation.enable">disables packages' documentation + </link>, and <link linkend="opt-sound.enable">disables sound</link>. + </para> +</section> diff --git a/nixpkgs/nixos/doc/manual/configuration/profiles/qemu-guest.xml b/nixpkgs/nixos/doc/manual/configuration/profiles/qemu-guest.xml new file mode 100644 index 000000000000..5d055c45d2d8 --- /dev/null +++ b/nixpkgs/nixos/doc/manual/configuration/profiles/qemu-guest.xml @@ -0,0 +1,18 @@ +<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-profile-qemu-guest"> + <title>QEMU Guest</title> + + <para> + This profile contains common configuration for virtual machines running under + QEMU (using virtio). + </para> + + <para> + It makes virtio modules available on the initrd, sets the system time from + the hardware clock to work around a bug in qemu-kvm, and + <link linkend="opt-security.rngd.enable">enables rngd</link>. + </para> +</section> diff --git a/nixpkgs/nixos/doc/manual/configuration/ssh.xml b/nixpkgs/nixos/doc/manual/configuration/ssh.xml new file mode 100644 index 000000000000..a4af1b96583d --- /dev/null +++ b/nixpkgs/nixos/doc/manual/configuration/ssh.xml @@ -0,0 +1,27 @@ +<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-ssh"> + <title>Secure Shell Access</title> + + <para> + Secure shell (SSH) access to your machine can be enabled by setting: +<programlisting> +<xref linkend="opt-services.openssh.enable"/> = true; +</programlisting> + 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> +<link linkend="opt-users.users._name__.openssh.authorizedKeys.keys">users.users.alice.openssh.authorizedKeys.keys</link> = + [ "ssh-dss AAAAB3NzaC1kc3MAAACBAPIkGWVEt4..." ]; +</programlisting> + </para> +</section> diff --git a/nixpkgs/nixos/doc/manual/configuration/summary.xml b/nixpkgs/nixos/doc/manual/configuration/summary.xml new file mode 100644 index 000000000000..ea980254a8fc --- /dev/null +++ b/nixpkgs/nixos/doc/manual/configuration/summary.xml @@ -0,0 +1,227 @@ +<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-nix-syntax-summary"> + <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 +xlink:href="http://nixos.org/nix/manual/#chap-writing-nix-expressions">Nix + manual</link> for the rest. + </para> + + <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>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 + <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 + <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>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 + <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> +<!-- + <row> + <entry><literal>throw "Urgh"</literal></entry> + <entry>Raise an error condition</entry> + </row> + --> + </tbody> + </tgroup> + </informaltable> +</section> diff --git a/nixpkgs/nixos/doc/manual/configuration/user-mgmt.xml b/nixpkgs/nixos/doc/manual/configuration/user-mgmt.xml new file mode 100644 index 000000000000..4b1710f3a2b1 --- /dev/null +++ b/nixpkgs/nixos/doc/manual/configuration/user-mgmt.xml @@ -0,0 +1,88 @@ +<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-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: +<programlisting> +<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 <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: +<programlisting> +<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>: +<screen> +# 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> +# 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>: +<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> +</chapter> diff --git a/nixpkgs/nixos/doc/manual/configuration/wireless.xml b/nixpkgs/nixos/doc/manual/configuration/wireless.xml new file mode 100644 index 000000000000..9c0e3a8d7aa4 --- /dev/null +++ b/nixpkgs/nixos/doc/manual/configuration/wireless.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-wireless"> + <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: +<programlisting> +<xref linkend="opt-networking.wireless.enable"/> = true; +</programlisting> + 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 <citerefentry> + <refentrytitle>wpa_supplicant.conf</refentrytitle> + <manvolnum>5</manvolnum> </citerefentry>). + </para> + + <para> + If you are using WPA2 you can generate pskRaw key using + <command>wpa_passphrase</command>: +<screen> +<prompt>$ </prompt>wpa_passphrase ESSID PSK +network={ + ssid="echelon" + #psk="abcdefgh" + psk=dca6d6ed41f4ab5a984c9f55f6f66d4efdc720ebf66959810f4329bb391c5435 +} +</screen> +<programlisting> +<xref linkend="opt-networking.wireless.networks"/> = { + echelon = { + pskRaw = "dca6d6ed41f4ab5a984c9f55f6f66d4efdc720ebf66959810f4329bb391c5435"; + }; +} +</programlisting> + or you can use it to directly generate the + <literal>wpa_supplicant.conf</literal>: +<screen> +<prompt># </prompt>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> +<prompt># </prompt>systemctl restart wpa_supplicant.service</screen> + </para> +</section> diff --git a/nixpkgs/nixos/doc/manual/configuration/x-windows.xml b/nixpkgs/nixos/doc/manual/configuration/x-windows.xml new file mode 100644 index 000000000000..7cdc5196e0d2 --- /dev/null +++ b/nixpkgs/nixos/doc/manual/configuration/x-windows.xml @@ -0,0 +1,292 @@ +<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-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: +<programlisting> +<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. +<programlisting> +<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: +<programlisting> +<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.desktopManager.mate.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 LightDM. You + can select an alternative one by picking one of the following lines: +<programlisting> +<xref linkend="opt-services.xserver.displayManager.sddm.enable"/> = true; +<xref linkend="opt-services.xserver.displayManager.slim.enable"/> = true; +</programlisting> + </para> + <para> + You can set the keyboard layout (and optionally the layout variant): +<programlisting> +<xref linkend="opt-services.xserver.layout"/> = "de"; +<xref linkend="opt-services.xserver.xkbVariant"/> = "neo"; +</programlisting> + </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 +</screen> + </para> + <para> + On 64-bit systems, if you want OpenGL for 32-bit programs such as in Wine, + you should also set the following: +<programlisting> +<xref linkend="opt-hardware.opengl.driSupport32Bit"/> = true; +</programlisting> + </para> + <simplesect xml:id="sec-x11-auto-login"> + <title>Auto-login</title> + <para> + The x11 login screen can be skipped entirely, automatically logging you into + your window manager and desktop environment when you boot your computer. + </para> + <para> + This is especially helpful if you have disk encryption enabled. Since you + already have to provide a password to decrypt your disk, entering a second + password to login can be redundant. + </para> + <para> + To enable auto-login, you need to define your default window manager and + desktop environment. If you wanted no desktop environment and i3 as your your + window manager, you'd define: +<programlisting> +<xref linkend="opt-services.xserver.desktopManager.default"/> = "none"; +<xref linkend="opt-services.xserver.windowManager.default"/> = "i3"; +</programlisting> + And, finally, to enable auto-login for a user <literal>johndoe</literal>: +<programlisting> +<xref linkend="opt-services.xserver.displayManager.auto.enable"/> = true; +<xref linkend="opt-services.xserver.displayManager.auto.user"/> = "johndoe"; +</programlisting> + </para> + </simplesect> + <simplesect xml:id="sec-x11-graphics-cards-nvidia"> + <title>Proprietary NVIDIA drivers</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> +<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: +<programlisting> +<xref linkend="opt-services.xserver.videoDrivers"/> = [ "nvidiaLegacy390" ]; +<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> + </simplesect> + <simplesect xml:id="sec-x11--graphics-cards-amd"> + <title>Proprietary AMD drivers</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> +<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> + <note> + <para> + For recent AMD GPUs you most likely want to keep either the defaults + or <literal>"amdgpu"</literal> (both free). + </para> + </note> + </simplesect> + <simplesect xml:id="sec-x11-touchpads"> + <title>Touchpads</title> + <para> + Support for Synaptics touchpads (found in many laptops such as the Dell + Latitude series) can be enabled as follows: +<programlisting> +<xref linkend="opt-services.xserver.libinput.enable"/> = true; +</programlisting> + The driver has many options (see <xref linkend="ch-options"/>). For + instance, the following disables tap-to-click behavior: +<programlisting> +<xref linkend="opt-services.xserver.libinput.tapping"/> = false; +</programlisting> + Note: the use of <literal>services.xserver.synaptics</literal> is deprecated + since NixOS 17.09. + </para> + </simplesect> + <simplesect xml:id="sec-x11-gtk-and-qt-themes"> + <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> + <simplesect xml:id="custom-xkb-layouts"> + <title>Custom XKB layouts</title> + <para> + It is possible to install custom + <link xlink:href="https://en.wikipedia.org/wiki/X_keyboard_extension"> + XKB + </link> + keyboard layouts using the option + <option> + <link linkend="opt-services.xserver.extraLayouts"> + services.xserver.extraLayouts + </link> + </option>. + As a first example, we are going to create a layout based on the basic US + layout, with an additional layer to type some greek symbols by pressing the + right-alt key. + </para> + <para> + To do this we are going to create a <literal>us-greek</literal> file + with a <literal>xkb_symbols</literal> section. + </para> +<programlisting> +xkb_symbols "us-greek" +{ + include "us(basic)" // includes the base US keys + include "level3(ralt_switch)" // configures right alt as a third level switch + + key <LatA> { [ a, A, Greek_alpha ] }; + key <LatB> { [ b, B, Greek_beta ] }; + key <LatG> { [ g, G, Greek_gamma ] }; + key <LatD> { [ d, D, Greek_delta ] }; + key <LatZ> { [ z, Z, Greek_zeta ] }; +}; +</programlisting> + <para> + To install the layout, the filepath, a description and the list of + languages must be given: + </para> +<programlisting> +<xref linkend="opt-services.xserver.extraLayouts"/>.us-greek = { + description = "US layout with alt-gr greek"; + languages = [ "eng" ]; + symbolsFile = /path/to/us-greek; +} +</programlisting> + <note> + <para> + The name should match the one given to the + <literal>xkb_symbols</literal> block. + </para> + </note> + <para> + The layout should now be installed and ready to use: try it by + running <literal>setxkbmap us-greek</literal> and type + <literal><alt>+a</literal>. To change the default the usual + <option> + <link linkend="opt-services.xserver.layout"> + services.xserver.layout + </link> + </option> + option can still be used. + </para> + <para> + A layout can have several other components besides + <literal>xkb_symbols</literal>, for example we will define new + keycodes for some multimedia key and bind these to some symbol. + </para> + <para> + Use the <emphasis>xev</emphasis> utility from + <literal>pkgs.xorg.xev</literal> to find the codes of the keys of + interest, then create a <literal>media-key</literal> file to hold + the keycodes definitions + </para> +<programlisting> +xkb_keycodes "media" +{ + <volUp> = 123; + <volDown> = 456; +} +</programlisting> + <para> + Now use the newly define keycodes in <literal>media-sym</literal>: + </para> +<programlisting> +xkb_symbols "media" +{ + key.type = "ONE_LEVEL"; + key <volUp> { [ XF86AudioLowerVolume ] }; + key <volDown> { [ XF86AudioRaiseVolume ] }; +} +</programlisting> + <para> + As before, to install the layout do + </para> +<programlisting> +<xref linkend="opt-services.xserver.extraLayouts"/>.media = { + description = "Multimedia keys remapping"; + languages = [ "eng" ]; + symbolsFile = /path/to/media-key; + keycodesFile = /path/to/media-sym; +}; +</programlisting> + <note> + <para> + The function <literal>pkgs.writeText <filename> <content> + </literal> can be useful if you prefer to keep the layout definitions + inside the NixOS configuration. + </para> + </note> + <para> + Unfortunately, the Xorg server does not (currently) support setting a + keymap directly but relies instead on XKB rules to select the matching + components (keycodes, types, ...) of a layout. This means that components + other than symbols won't be loaded by default. As a workaround, you + can set the keymap using <literal>setxkbmap</literal> at the start of the + session with: + </para> +<programlisting> +<xref linkend="opt-services.xserver.displayManager.sessionCommands"/> = "setxkbmap -keycodes media"; +</programlisting> + <para> + To learn how to write layouts take a look at the XKB + <link xlink:href="https://www.x.org/releases/current/doc/xorg-docs/input/XKB-Enhancing.html#Defining_New_Layouts"> + documentation + </link>. More example layouts can also be found + <link xlink:href="https://wiki.archlinux.org/index.php/X_KeyBoard_extension#Basic_examples"> + here + </link>. + </para> +</simplesect> +</chapter> diff --git a/nixpkgs/nixos/doc/manual/configuration/xfce.xml b/nixpkgs/nixos/doc/manual/configuration/xfce.xml new file mode 100644 index 000000000000..6ac99c6b2bee --- /dev/null +++ b/nixpkgs/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 xml:id="sec-xfce-thunar-volumes"> + <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 xml:id="sec-xfce-polkit"> + <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 xml:id="sec-xfce-troubleshooting"> + <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> +<prompt>$ </prompt>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/nixpkgs/nixos/doc/manual/default.nix b/nixpkgs/nixos/doc/manual/default.nix new file mode 100644 index 000000000000..f9de2db1a084 --- /dev/null +++ b/nixpkgs/nixos/doc/manual/default.nix @@ -0,0 +1,255 @@ +{ pkgs, options, config, version, revision, extraSources ? [] }: + +with pkgs; + +let + lib = pkgs.lib; + + # 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; + + optionsDoc = buildPackages.nixosOptionsDoc { + inherit options revision; + transformOptions = opt: opt // { + # Clean up declaration sites to not refer to the NixOS source tree. + declarations = map stripAnyPrefixes opt.declarations; + }; + }; + + 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 ${optionsDoc.optionsDocBook} $out/options-db.xml + printf "%s" "${version}" > $out/version + ''; + + copySources = + '' + cp -prd $sources/* . # */ + ln -s ${generatedSources} ./generated + chmod -R u+w . + ''; + + toc = builtins.toFile "toc.xml" + '' + <toc role="chunk-toc"> + <d:tocentry xmlns:d="http://docbook.org/ns/docbook" linkend="book-nixos-manual"><?dbhtml filename="index.html"?> + <d:tocentry linkend="ch-options"><?dbhtml filename="options.html"?></d:tocentry> + <d:tocentry linkend="ch-release-notes"><?dbhtml filename="release-notes.html"?></d:tocentry> + </d:tocentry> + </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 \ + ${docbook_xsl_ns}/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://${docbook_xsl_ns}/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; + + inherit (optionsDoc) optionsJSON optionsXML optionsDocBook; + + # Generate the NixOS manual. + manualHTML = runCommand "nixos-manual-html" + { 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 \ + ${manualXsltprocOptions} \ + --stringparam target.database.document "${olinkDB}/olinkdb.xml" \ + --stringparam id.warnings "1" \ + --nonet --output $dst/ \ + ${docbook_xsl_ns}/xml/xsl/docbook/xhtml/chunktoc.xsl \ + ${manual-combined}/manual-combined.xml \ + |& tee xsltproc.out + grep "^ID recommended on" xsltproc.out &>/dev/null && echo "error: some IDs are missing" && false + rm xsltproc.out + + mkdir -p $dst/images/callouts + cp ${docbook_xsl_ns}/xml/xsl/docbook/images/callouts/*.svg $dst/images/callouts/ + + 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 + ''; # */ + + # Alias for backward compatibility. TODO(@oxij): remove eventually. + manual = manualHTML; + + # Index page of the NixOS manual. + manualHTMLIndex = "${manualHTML}/share/doc/nixos/index.html"; + + manualEpub = runCommand "nixos-manual-epub" + { inherit sources; + buildInputs = [ libxml2.bin libxslt.bin zip ]; + } + '' + # Generate the epub manual. + dst=$out/share/doc/nixos + + xsltproc \ + ${manualXsltprocOptions} \ + --stringparam target.database.document "${olinkDB}/olinkdb.xml" \ + --nonet --xinclude --output $dst/epub/ \ + ${docbook_xsl_ns}/xml/xsl/docbook/epub/docbook.xsl \ + ${manual-combined}/manual-combined.xml + + mkdir -p $dst/epub/OEBPS/images/callouts + cp -r ${docbook_xsl_ns}/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" * + + rm -rf $dst/epub + + mkdir -p $out/nix-support + echo "doc-epub manual $manual" >> $out/nix-support/hydra-build-products + ''; + + + # 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 \ + --maxdepth 6000 \ + --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" \ + ${docbook_xsl_ns}/xml/xsl/docbook/manpages/docbook.xsl \ + ${manual-combined}/man-pages-combined.xml + ''; + +} diff --git a/nixpkgs/nixos/doc/manual/development/assertions.xml b/nixpkgs/nixos/doc/manual/development/assertions.xml new file mode 100644 index 000000000000..32f90cf2e7c4 --- /dev/null +++ b/nixpkgs/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 xml:id="sec-assertions-warnings"> + <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 xml:id="sec-assertions-assertions"> + <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/nixpkgs/nixos/doc/manual/development/building-nixos.xml b/nixpkgs/nixos/doc/manual/development/building-nixos.xml new file mode 100644 index 000000000000..56a596baed00 --- /dev/null +++ b/nixpkgs/nixos/doc/manual/development/building-nixos.xml @@ -0,0 +1,27 @@ +<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-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>. +<screen> +<prompt>$ </prompt>git clone https://github.com/NixOS/nixpkgs.git +<prompt>$ </prompt>cd nixpkgs/nixos +<prompt>$ </prompt>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> +<prompt># </prompt>mount -o loop -t iso9660 ./result/iso/cd.iso /mnt/iso</screen> + </para> +</chapter> diff --git a/nixpkgs/nixos/doc/manual/development/building-parts.xml b/nixpkgs/nixos/doc/manual/development/building-parts.xml new file mode 100644 index 000000000000..88369fb891b3 --- /dev/null +++ b/nixpkgs/nixos/doc/manual/development/building-parts.xml @@ -0,0 +1,121 @@ +<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-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: +<screen> +<prompt>$ </prompt>cd <replaceable>/path/to/nixpkgs/nixos</replaceable> +<prompt>$ </prompt>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> + <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: +<screen> +<prompt>$ </prompt>nix-build -A system</screen> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>system.build.manual.manualHTML</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> + <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> +<prompt>$ </prompt>nix-build -A config.system.build.initialRamdisk -o initrd +<prompt>$ </prompt>nix-build -A config.system.build.kernel -o kernel +<prompt>$ </prompt>qemu-system-x86_64 -kernel ./kernel/bzImage -initrd ./initrd/initrd -hda /dev/null +</screen> + </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> + <listitem> + <para> + These build the corresponding NixOS commands. + </para> + </listitem> + </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: +<screen> +<prompt>$ </prompt>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>: +<screen> +<prompt>$ </prompt>cp $(nix-build -A 'config.systemd.units."httpd.service".unit')/httpd.service \ + /run/systemd/system/tmp-httpd.service +<prompt># </prompt>systemctl daemon-reload +<prompt># </prompt>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> + </listitem> + </varlistentry> + </variablelist> + </para> +</chapter> diff --git a/nixpkgs/nixos/doc/manual/development/development.xml b/nixpkgs/nixos/doc/manual/development/development.xml new file mode 100644 index 000000000000..43f511b3e96b --- /dev/null +++ b/nixpkgs/nixos/doc/manual/development/development.xml @@ -0,0 +1,20 @@ +<part 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-development"> + <title>Development</title> + <partintro xml:id="ch-development-intro"> + <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/nixpkgs/nixos/doc/manual/development/importing-modules.xml b/nixpkgs/nixos/doc/manual/development/importing-modules.xml new file mode 100644 index 000000000000..1c6a5671eda8 --- /dev/null +++ b/nixpkgs/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/nixpkgs/nixos/doc/manual/development/meta-attributes.xml b/nixpkgs/nixos/doc/manual/development/meta-attributes.xml new file mode 100644 index 000000000000..3d019a4987e1 --- /dev/null +++ b/nixpkgs/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/nixpkgs/nixos/doc/manual/development/nixos-tests.xml b/nixpkgs/nixos/doc/manual/development/nixos-tests.xml new file mode 100644 index 000000000000..2695082e3867 --- /dev/null +++ b/nixpkgs/nixos/doc/manual/development/nixos-tests.xml @@ -0,0 +1,19 @@ +<chapter xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-nixos-tests"> + <title>NixOS Tests</title> + <para> + When you add some feature to NixOS, you should write a test for it. NixOS + tests are kept in the directory + <filename +xlink:href="https://github.com/NixOS/nixpkgs/tree/master/nixos/tests">nixos/tests</filename>, + and are executed (using Nix) by a testing framework that automatically starts + one or more virtual machines containing the NixOS system(s) required for the + test. + </para> + <xi:include href="writing-nixos-tests.xml" /> + <xi:include href="running-nixos-tests.xml" /> + <xi:include href="running-nixos-tests-interactively.xml" /> +</chapter> diff --git a/nixpkgs/nixos/doc/manual/development/option-declarations.xml b/nixpkgs/nixos/doc/manual/development/option-declarations.xml new file mode 100644 index 000000000000..eee81bf64263 --- /dev/null +++ b/nixpkgs/nixos/doc/manual/development/option-declarations.xml @@ -0,0 +1,199 @@ +<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-declarations"> + <title>Option Declarations</title> + + <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 { + type = <replaceable>type specification</replaceable>; + default = <replaceable>default value</replaceable>; + example = <replaceable>example value</replaceable>; + description = "<replaceable>Description for use in the NixOS manual.</replaceable>"; + }; +}; +</programlisting> + 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 <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; 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>example</varname> + </term> + <listitem> + <para> + An example value that will be shown in the NixOS manual. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>description</varname> + </term> + <listitem> + <para> + A textual description of the option, in DocBook format, that will be + included in the NixOS manual. + </para> + </listitem> + </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> + Managing the display managers independently by adding an enable option to + every display manager module backend. (NixOS) + </para> + </listitem> + <listitem> + <para> + Managing the display managers in the central module by adding an option + to select which display manager backend to use. + </para> + </listitem> + </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/nixpkgs/nixos/doc/manual/development/option-def.xml b/nixpkgs/nixos/doc/manual/development/option-def.xml new file mode 100644 index 000000000000..50a705d0cb8e --- /dev/null +++ b/nixpkgs/nixos/doc/manual/development/option-def.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-option-definitions"> + <title>Option Definitions</title> + + <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 xml:id="sec-option-definitions-delaying-conditionals"> + <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: +<programlisting> +config = if config.services.httpd.enable then { + services.httpd.enable = false; +} else { + services.httpd.enable = true; +}; +</programlisting> + 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: +<programlisting> +config = { + environment.systemPackages = if config.services.httpd.enable then [ <replaceable>...</replaceable> ] else []; + <replaceable>...</replaceable> +}; +</programlisting> + </para> + </simplesect> + + <simplesect xml:id="sec-option-definitions-setting-priorities"> + <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 xml:id="sec-option-definitions-merging"> + <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. + { environment.systemPackages = [ <replaceable>...</replaceable> ]; + } + # Conditional stuff. + (mkIf config.services.bla.enable { + environment.systemPackages = [ <replaceable>...</replaceable> ]; + }) + ]; +</programlisting> + </para> + </simplesect> +</section> diff --git a/nixpkgs/nixos/doc/manual/development/option-types.xml b/nixpkgs/nixos/doc/manual/development/option-types.xml new file mode 100644 index 000000000000..069cc36573d8 --- /dev/null +++ b/nixpkgs/nixos/doc/manual/development/option-types.xml @@ -0,0 +1,781 @@ +<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 xml:id="sec-option-types-basic"> + <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 xml:id='types.ints.ux'> + <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> + <varlistentry> + <term> + <varname>types.port</varname> + </term> + <listitem> + <para> + A port number. This type is an alias to + <link linkend='types.ints.ux'><varname>types.ints.u16</varname></link>. + </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 xml:id="sec-option-types-value"> + <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 xml:id="sec-option-types-composed"> + <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 xml:id="sec-option-types-extending"> + <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 = types.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 xml:id="sec-option-types-custom"> + <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/nixpkgs/nixos/doc/manual/development/releases.xml b/nixpkgs/nixos/doc/manual/development/releases.xml new file mode 100755 index 000000000000..3cb16d33cd48 --- /dev/null +++ b/nixpkgs/nixos/doc/manual/development/releases.xml @@ -0,0 +1,269 @@ +<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/compare/bdf161ed8d21...6b63c4616790"> + Bump the <literal>system.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> + Remove attributes that we know we will not be able to support, + especially if there is a stable alternative. E.g. Check that our + Linux kernels' + <link xlink:href="https://www.kernel.org/category/releases.html"> + projected end-of-life</link> are after our release projected + end-of-life + </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 "Chapter 4. Upgrading NixOS" section of the manual to match + new stable release version. + </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/nixpkgs/nixos/doc/manual/development/replace-modules.xml b/nixpkgs/nixos/doc/manual/development/replace-modules.xml new file mode 100644 index 000000000000..7b103c36d907 --- /dev/null +++ b/nixpkgs/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/nixpkgs/nixos/doc/manual/development/running-nixos-tests-interactively.xml b/nixpkgs/nixos/doc/manual/development/running-nixos-tests-interactively.xml new file mode 100644 index 000000000000..e390d62fde2f --- /dev/null +++ b/nixpkgs/nixos/doc/manual/development/running-nixos-tests-interactively.xml @@ -0,0 +1,44 @@ +<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-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: +<screen> +<prompt>$ </prompt>nix-build nixos/tests/login.nix -A driver +<prompt>$ </prompt>./result/bin/nixos-test-driver +starting VDE switch for network 1 +<prompt>></prompt> +</screen> + You can then take any Perl statement, e.g. +<screen> +<prompt>></prompt> startAll +<prompt>></prompt> testScript +<prompt>></prompt> $machine->succeed("touch /tmp/foo") +<prompt>></prompt> print($machine->succeed("pwd")) # Show stdout of command +</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: +<screen> +<prompt>$ </prompt>nix-build nixos/tests/login.nix -A driver +<prompt>$ </prompt>./result/bin/nixos-run-vms +</screen> + The script <command>nixos-run-vms</command> starts the virtual machines + defined by test. + </para> + + <para> + The machine state is kept across VM restarts in + <filename>/tmp/vm-state-</filename><varname>machinename</varname>. + </para> +</section> diff --git a/nixpkgs/nixos/doc/manual/development/running-nixos-tests.xml b/nixpkgs/nixos/doc/manual/development/running-nixos-tests.xml new file mode 100644 index 000000000000..13ae1ed93699 --- /dev/null +++ b/nixpkgs/nixos/doc/manual/development/running-nixos-tests.xml @@ -0,0 +1,36 @@ +<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-running-nixos-tests-interactively"> + <title>Running Tests</title> + + <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: +<screen> +<prompt>$ </prompt>nix-build '<nixpkgs/nixos/tests/login.nix>' +</screen> + or, if you don’t want to rely on <envar>NIX_PATH</envar>: +<screen> +<prompt>$ </prompt>cd /my/nixpkgs/nixos/tests +<prompt>$ </prompt>nix-build login.nix +… +running the VM test script +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: +<screen> +<prompt>$ </prompt>firefox result/log.html +</screen> + </para> +</section> diff --git a/nixpkgs/nixos/doc/manual/development/sources.xml b/nixpkgs/nixos/doc/manual/development/sources.xml new file mode 100644 index 000000000000..3c30c782746d --- /dev/null +++ b/nixpkgs/nixos/doc/manual/development/sources.xml @@ -0,0 +1,86 @@ +<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-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</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> +<prompt>$ </prompt>git clone https://github.com/NixOS/nixpkgs +<prompt>$ </prompt>cd nixpkgs +<prompt>$ </prompt>git remote add channels https://github.com/NixOS/nixpkgs-channels +<prompt>$ </prompt>git remote update channels +</screen> + 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> +<prompt>$ </prompt>nixos-version +17.09pre104379.6e0b727 (Hummingbird) + +<prompt>$ </prompt>git checkout -b local 6e0b727 +</screen> + Or, to base your local branch on the latest version available in a NixOS + channel: +<screen> +<prompt>$ </prompt>git remote update channels +<prompt>$ </prompt>git checkout -b local channels/nixos-17.03 +</screen> + (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> +<prompt>$ </prompt>git remote update channels +<prompt>$ </prompt>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: +<screen> +<prompt># </prompt>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>: +<screen> +<prompt>$ </prompt>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 (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/nixpkgs/nixos/doc/manual/development/testing-installer.xml b/nixpkgs/nixos/doc/manual/development/testing-installer.xml new file mode 100644 index 000000000000..902f995fbc1b --- /dev/null +++ b/nixpkgs/nixos/doc/manual/development/testing-installer.xml @@ -0,0 +1,22 @@ +<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-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: +<screen> +<prompt># </prompt>mount -t tmpfs none /mnt +<prompt># </prompt>nixos-generate-config --root /mnt +<prompt>$ </prompt>nix-build '<nixpkgs/nixos>' -A config.system.build.nixos-install +<prompt># </prompt>./result/bin/nixos-install</screen> + To start a login shell in the new NixOS installation in + <filename>/mnt</filename>: +<screen> +<prompt>$ </prompt>nix-build '<nixpkgs/nixos>' -A config.system.build.nixos-enter +<prompt># </prompt>./result/bin/nixos-enter +</screen> + </para> +</chapter> diff --git a/nixpkgs/nixos/doc/manual/development/writing-documentation.xml b/nixpkgs/nixos/doc/manual/development/writing-documentation.xml new file mode 100644 index 000000000000..2183937ad0da --- /dev/null +++ b/nixpkgs/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 xml:id="sec-writing-docs-building-the-manual"> + <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 xml:id="sec-writing-docs-editing-docbook-xml"> + <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 xml:id="sec-writing-docs-creating-a-topic"> + <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 xml:id="sec-writing-docs-adding-a-topic"> + <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/nixpkgs/nixos/doc/manual/development/writing-modules.xml b/nixpkgs/nixos/doc/manual/development/writing-modules.xml new file mode 100644 index 000000000000..bbf793bb0be9 --- /dev/null +++ b/nixpkgs/nixos/doc/manual/development/writing-modules.xml @@ -0,0 +1,186 @@ +<chapter xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-writing-modules"> + <title>Writing NixOS Modules</title> + <para> + NixOS has a modular system for declarative configuration. This system + combines multiple <emphasis>modules</emphasis> to produce the full system + configuration. One of the modules that constitute the configuration is + <filename>/etc/nixos/configuration.nix</filename>. Most of the others live in + the + <link +xlink:href="https://github.com/NixOS/nixpkgs/tree/master/nixos/modules"><filename>nixos/modules</filename></link> + subdirectory of the Nixpkgs tree. + </para> + <para> + Each NixOS module is a file that handles one logical aspect of the + configuration, such as a specific kind of hardware, a service, or network + settings. A module configuration does not have to handle everything from + scratch; it can use the functionality provided by other modules for its + implementation. Thus a module can <emphasis>declare</emphasis> options that + can be used by other modules, and conversely can <emphasis>define</emphasis> + options provided by other modules in its own implementation. For example, the + module + <link +xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/security/pam.nix"><filename>pam.nix</filename></link> + declares the option <option>security.pam.services</option> that allows other + modules (e.g. + <link +xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/services/networking/ssh/sshd.nix"><filename>sshd.nix</filename></link>) + to define PAM services; and it defines the option + <option>environment.etc</option> (declared by + <link +xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/system/etc/etc.nix"><filename>etc.nix</filename></link>) + to cause files to be created in <filename>/etc/pam.d</filename>. + </para> + <para xml:id="para-module-syn"> + In <xref +linkend="sec-configuration-syntax"/>, we saw the following structure + of NixOS modules: +<programlisting> +{ config, pkgs, ... }: + +{ <replaceable>option definitions</replaceable> +} +</programlisting> + This is actually an <emphasis>abbreviated</emphasis> form of module that only + defines options, but does not declare any. The structure of full NixOS + modules is shown in <xref linkend='ex-module-syntax' />. + </para> + <example xml:id='ex-module-syntax'> + <title>Structure of NixOS Modules</title> +<programlisting> +{ config, pkgs, ... }: <co xml:id='module-syntax-1' /> + +{ + imports = + [ <replaceable>paths of other modules</replaceable> <co xml:id='module-syntax-2' /> + ]; + + options = { + <replaceable>option declarations</replaceable> <co xml:id='module-syntax-3' /> + }; + + config = { + <replaceable>option definitions</replaceable> <co xml:id='module-syntax-4' /> + }; +}</programlisting> + </example> + <para> + The meaning of each part is as follows. + <calloutlist> + <callout arearefs='module-syntax-1'> + <para> + This line makes the current Nix expression a function. The variable + <varname>pkgs</varname> contains Nixpkgs, while <varname>config</varname> + contains the full system configuration. This line can be omitted if there + is no reference to <varname>pkgs</varname> and <varname>config</varname> + inside the module. + </para> + </callout> + <callout arearefs='module-syntax-2'> + <para> + This list enumerates the paths to other NixOS modules that should be + included in the evaluation of the system configuration. A default set of + modules is defined in the file + <filename>modules/module-list.nix</filename>. These don't need to be added + in the import list. + </para> + </callout> + <callout arearefs='module-syntax-3'> + <para> + The attribute <varname>options</varname> is a nested set of + <emphasis>option declarations</emphasis> (described below). + </para> + </callout> + <callout arearefs='module-syntax-4'> + <para> + The attribute <varname>config</varname> is a nested set of + <emphasis>option definitions</emphasis> (also described below). + </para> + </callout> + </calloutlist> + </para> + <para> + <xref linkend='locate-example' /> shows a module that handles the regular + update of the “locate” database, an index of all files in the file + system. This module declares two options that can be defined by other modules + (typically the user’s <filename>configuration.nix</filename>): + <option>services.locate.enable</option> (whether the database should be + updated) and <option>services.locate.interval</option> (when the update + should be done). It implements its functionality by defining two options + declared by other modules: <option>systemd.services</option> (the set of all + systemd services) and <option>systemd.timers</option> (the list of commands + to be executed periodically by <command>systemd</command>). + </para> + <example xml:id='locate-example'> + <title>NixOS Module for the “locate” Service</title> +<programlisting> +{ config, lib, pkgs, ... }: + +with lib; + +let + cfg = config.services.locate; +in { + options.services.locate = { + enable = mkOption { + type = types.bool; + default = false; + description = '' + If enabled, NixOS will periodically update the database of + files used by the <command>locate</command> command. + ''; + }; + + interval = mkOption { + type = types.str; + default = "02:15"; + example = "hourly"; + description = '' + Update the locate database at this interval. Updates by + default at 2:15 AM every day. + + The format is described in + <citerefentry><refentrytitle>systemd.time</refentrytitle> + <manvolnum>7</manvolnum></citerefentry>. + ''; + }; + + # Other options omitted for documentation + }; + + config = { + systemd.services.update-locatedb = + { description = "Update Locate Database"; + path = [ pkgs.su ]; + script = + '' + mkdir -m 0755 -p $(dirname ${toString cfg.output}) + exec updatedb \ + --localuser=${cfg.localuser} \ + ${optionalString (!cfg.includeStore) "--prunepaths='/nix/store'"} \ + --output=${toString cfg.output} ${concatStringsSep " " cfg.extraFlags} + ''; + }; + + systemd.timers.update-locatedb = mkIf cfg.enable + { description = "Update timer for locate database"; + partOf = [ "update-locatedb.service" ]; + wantedBy = [ "timers.target" ]; + timerConfig.OnCalendar = cfg.interval; + }; + }; +} +</programlisting> + </example> + <xi:include href="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/nixpkgs/nixos/doc/manual/development/writing-nixos-tests.xml b/nixpkgs/nixos/doc/manual/development/writing-nixos-tests.xml new file mode 100644 index 000000000000..6be2d0a4d231 --- /dev/null +++ b/nixpkgs/nixos/doc/manual/development/writing-nixos-tests.xml @@ -0,0 +1,421 @@ +<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-writing-nixos-tests"> + <title>Writing Tests</title> + + <para> + A NixOS test is a Nix expression that has the following structure: +<programlisting> +import ./make-test.nix { + + # Either the configuration of a single machine: + machine = + { config, pkgs, ... }: + { <replaceable>configuration…</replaceable> + }; + + # Or a set of machines: + nodes = + { <replaceable>machine1</replaceable> = + { config, pkgs, ... }: { <replaceable>…</replaceable> }; + <replaceable>machine2</replaceable> = + { config, pkgs, ... }: { <replaceable>…</replaceable> }; + … + }; + + testScript = + '' + <replaceable>Perl code…</replaceable> + ''; +} +</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 +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 +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: +<!-- 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 + 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: +<programlisting> +$machine->start; +$machine->waitForUnit("default.target"); +$machine->succeed("uname") =~ /Linux/ or die; +</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: +<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> + <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/nixpkgs/nixos/doc/manual/installation/changing-config.xml b/nixpkgs/nixos/doc/manual/installation/changing-config.xml new file mode 100644 index 000000000000..b77d71389a9d --- /dev/null +++ b/nixpkgs/nixos/doc/manual/installation/changing-config.xml @@ -0,0 +1,90 @@ +<chapter xmlns="http://docbook.org/ns/docbook" + 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 + <link linkend="ch-configuration">changed something</link> in that file, you + should do +<screen> +<prompt># </prompt>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> +<prompt># </prompt>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> +<prompt># </prompt>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> +<prompt># </prompt>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> +<prompt>$ </prompt>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 +<screen> +<prompt>$ </prompt>nixos-rebuild build-vm +<prompt>$ </prompt>./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 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.users.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> +<prompt>$ </prompt>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): +<screen> +<prompt>$ </prompt>ssh -p 2222 localhost +</screen> + </para> +</chapter> diff --git a/nixpkgs/nixos/doc/manual/installation/installation.xml b/nixpkgs/nixos/doc/manual/installation/installation.xml new file mode 100644 index 000000000000..2901f462dee0 --- /dev/null +++ b/nixpkgs/nixos/doc/manual/installation/installation.xml @@ -0,0 +1,17 @@ +<part 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-installation"> + <title>Installation</title> + <partintro xml:id="ch-installation-intro"> + <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/nixpkgs/nixos/doc/manual/installation/installing-behind-a-proxy.xml b/nixpkgs/nixos/doc/manual/installation/installing-behind-a-proxy.xml new file mode 100644 index 000000000000..8f9baff44b51 --- /dev/null +++ b/nixpkgs/nixos/doc/manual/installation/installing-behind-a-proxy.xml @@ -0,0 +1,48 @@ +<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-behind-proxy"> + <title>Installing behind a proxy</title> + + <para> + To install NixOS behind a proxy, do the following before running + <literal>nixos-install</literal>. + </para> + + <orderedlist numeration="arabic"> + <listitem> + <para> + Update proxy configuration in + <literal>/mnt/etc/nixos/configuration.nix</literal> to keep the internet + accessible after reboot. + </para> +<programlisting> +networking.proxy.default = "http://user:password@proxy:port/"; +networking.proxy.noProxy = "127.0.0.1,localhost,internal.domain"; +</programlisting> + </listitem> + <listitem> + <para> + Setup the proxy environment variables in the shell where you are running + <literal>nixos-install</literal>. + </para> +<programlisting> +# proxy_url="http://user:password@proxy:port/" +# export http_proxy="$proxy_url" +# export HTTP_PROXY="$proxy_url" +# export https_proxy="$proxy_url" +# export HTTPS_PROXY="$proxy_url" +</programlisting> + </listitem> + </orderedlist> + + <note> + <para> + If you are switching networks with different proxy configurations, use the + <literal>nesting.clone</literal> option in + <literal>configuration.nix</literal> to switch proxies at runtime. Refer to + <xref linkend="ch-options" /> for more information. + </para> + </note> +</section> diff --git a/nixpkgs/nixos/doc/manual/installation/installing-from-other-distro.xml b/nixpkgs/nixos/doc/manual/installation/installing-from-other-distro.xml new file mode 100644 index 000000000000..8ed45899fd7f --- /dev/null +++ b/nixpkgs/nixos/doc/manual/installation/installing-from-other-distro.xml @@ -0,0 +1,357 @@ +<!-- 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> +<prompt>$ </prompt>curl https://nixos.org/nix/install | sh +<prompt>$ </prompt>. $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> +<prompt>$ </prompt>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> +<prompt>$ </prompt>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><prompt>$ </prompt>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><prompt>$ </prompt>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> +<prompt>$ </prompt>sudo groupadd -g 30000 nixbld +<prompt>$ </prompt>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><prompt>$ </prompt>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> +<prompt>$ </prompt>sudo userdel nixbld +<prompt>$ </prompt>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><prompt>$ </prompt>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.users.root.initialHashedPassword</link> = ""; +</programlisting> + </listitem> + <listitem> + <para> + Build the NixOS closure and install it in the <literal>system</literal> + profile: + </para> +<screen><prompt>$ </prompt>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><prompt>$ </prompt>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> +<prompt>$ </prompt>sudo touch /etc/NIXOS +<prompt>$ </prompt>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> +<prompt>$ </prompt>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> +<prompt>$ </prompt>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/nixpkgs/nixos/doc/manual/installation/installing-pxe.xml b/nixpkgs/nixos/doc/manual/installation/installing-pxe.xml new file mode 100644 index 000000000000..94199e5e028d --- /dev/null +++ b/nixpkgs/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/nixpkgs/nixos/doc/manual/installation/installing-usb.xml b/nixpkgs/nixos/doc/manual/installation/installing-usb.xml new file mode 100644 index 000000000000..83598635acca --- /dev/null +++ b/nixpkgs/nixos/doc/manual/installation/installing-usb.xml @@ -0,0 +1,40 @@ +<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-usb"> + <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/sdX</replaceable></command>. Be careful about specifying + the correct drive; you can use the <command>lsblk</command> command to get a + list of block devices. + <note> + <title>On macOS</title> + <para> +<screen> +<prompt>$ </prompt>diskutil list +[..] +/dev/diskN (external, physical): + #: TYPE NAME SIZE IDENTIFIER +[..] +<prompt>$ </prompt>diskutil unmountDisk diskN +Unmount of all volumes on diskN was successful +<prompt>$ </prompt>sudo dd if=nix.iso of=/dev/rdiskN +</screen> + 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> + </note> + </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. + </para> +</section> diff --git a/nixpkgs/nixos/doc/manual/installation/installing-virtualbox-guest.xml b/nixpkgs/nixos/doc/manual/installation/installing-virtualbox-guest.xml new file mode 100644 index 000000000000..5c86eacfbf45 --- /dev/null +++ b/nixpkgs/nixos/doc/manual/installation/installing-virtualbox-guest.xml @@ -0,0 +1,103 @@ +<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. If you do + not add <literal>"nofail"</literal>, the system will no boot properly. The + same goes for disabling <literal>rngd</literal> which is normally used to get + randomness but this does not work in virtual machines. + </para> + +<programlisting> +{ config, pkgs, ...} : +{ + security.rngd.enable = false; // otherwise vm will not boot + ... + + fileSystems."/virtualboxshare" = { + fsType = "vboxsf"; + device = "nameofthesharedfolder"; + options = [ "rw" "nofail" ]; + }; +} +</programlisting> + + <para> + The folder will be available directly under the root directory. + </para> +</section> diff --git a/nixpkgs/nixos/doc/manual/installation/installing.xml b/nixpkgs/nixos/doc/manual/installation/installing.xml new file mode 100644 index 000000000000..742376378dea --- /dev/null +++ b/nixpkgs/nixos/doc/manual/installation/installing.xml @@ -0,0 +1,562 @@ +<chapter xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-installation"> + <title>Installing NixOS</title> + <section xml:id="sec-installation-booting"> + <title>Booting the system</title> + + <para> + NixOS can be installed on BIOS or UEFI systems. The procedure for a UEFI + installation is by and large the same as a BIOS installation. The + differences are mentioned in the steps that follow. + </para> + + <para> + The installation media can be burned to a CD, or now more commonly, "burned" + to a USB drive (see <xref linkend="sec-booting-from-usb"/>). + </para> + + <para> + The installation media contains a basic NixOS installation. When it’s + finished booting, it should have detected most of your hardware. + </para> + + <para> + The NixOS manual is available on virtual console 8 (press Alt+F8 to access) + or by running <command>nixos-help</command>. + </para> + + <para> + You are logged-in automatically as <literal>root</literal>. (The + <literal>root</literal> user account has an empty password.) + </para> + + <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> + + <section xml:id="sec-installation-booting-networking"> + <title>Networking in the installer</title> + + <para> + The boot process should have brought up networking (check <command>ip + a</command>). Networking is necessary for the installer, since it will + download lots of stuff (such as source tarballs or Nixpkgs channel + binaries). It’s best if you have a DHCP server on your network. Otherwise + configure networking manually using <command>ifconfig</command>. + </para> + + <para> + To manually configure the network on the graphical installer, first disable + network-manager with <command>systemctl stop NetworkManager</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> + + <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> + </section> + </section> + <section xml:id="sec-installation-partitioning"> + <title>Partitioning and formatting</title> + + <para> + The NixOS installer doesn’t do any partitioning or formatting, so you need + to do that yourself. + </para> + + <para> + The NixOS installer ships with multiple partitioning tools. The examples + below use <command>parted</command>, but also provides + <command>fdisk</command>, <command>gdisk</command>, + <command>cfdisk</command>, and <command>cgdisk</command>. + </para> + + <para> + The recommended partition scheme differs depending if the computer uses + <emphasis>Legacy Boot</emphasis> or <emphasis>UEFI</emphasis>. + </para> + + <section xml:id="sec-installation-partitioning-UEFI"> + <title>UEFI (GPT)</title> + + <para> + Here's an example partition scheme for UEFI, using + <filename>/dev/sda</filename> as the device. + <note> + <para> + You can safely ignore <command>parted</command>'s informational message + about needing to update /etc/fstab. + </para> + </note> + </para> + + <para> + <orderedlist> + <listitem> + <para> + Create a <emphasis>GPT</emphasis> partition table. +<screen language="commands"><prompt># </prompt>parted /dev/sda -- mklabel gpt</screen> + </para> + </listitem> + <listitem> + <para> + Add the <emphasis>root</emphasis> partition. This will fill the disk + except for the end part, where the swap will live, and the space left in + front (512MiB) which will be used by the boot partition. +<screen language="commands"><prompt># </prompt>parted /dev/sda -- mkpart primary 512MiB -8GiB</screen> + </para> + </listitem> + <listitem> + <para> + Next, add a <emphasis>swap</emphasis> partition. The size required will + vary according to needs, here a 8GiB one is created. +<screen language="commands"><prompt># </prompt>parted /dev/sda -- mkpart primary linux-swap -8GiB 100%</screen> + <note> + <para> + The swap partition size rules are no different than for other Linux + distributions. + </para> + </note> + </para> + </listitem> + <listitem> + <para> + Finally, the <emphasis>boot</emphasis> partition. NixOS by default uses + the ESP (EFI system partition) as its <emphasis>/boot</emphasis> + partition. It uses the initially reserved 512MiB at the start of the + disk. +<screen language="commands"><prompt># </prompt>parted /dev/sda -- mkpart ESP fat32 1MiB 512MiB +<prompt># </prompt>parted /dev/sda -- set 3 boot on</screen> + </para> + </listitem> + </orderedlist> + </para> + + <para> + Once complete, you can follow with + <xref linkend="sec-installation-partitioning-formatting"/>. + </para> + </section> + + <section xml:id="sec-installation-partitioning-MBR"> + <title>Legacy Boot (MBR)</title> + + <para> + Here's an example partition scheme for Legacy Boot, using + <filename>/dev/sda</filename> as the device. + <note> + <para> + You can safely ignore <command>parted</command>'s informational message + about needing to update /etc/fstab. + </para> + </note> + </para> + + <para> + <orderedlist> + <listitem> + <para> + Create a <emphasis>MBR</emphasis> partition table. +<screen language="commands"><prompt># </prompt>parted /dev/sda -- mklabel msdos</screen> + </para> + </listitem> + <listitem> + <para> + Add the <emphasis>root</emphasis> partition. This will fill the the disk + except for the end part, where the swap will live. +<screen language="commands"><prompt># </prompt>parted /dev/sda -- mkpart primary 1MiB -8GiB</screen> + </para> + </listitem> + <listitem> + <para> + Finally, add a <emphasis>swap</emphasis> partition. The size required + will vary according to needs, here a 8GiB one is created. +<screen language="commands"><prompt># </prompt>parted /dev/sda -- mkpart primary linux-swap -8GiB 100%</screen> + <note> + <para> + The swap partition size rules are no different than for other Linux + distributions. + </para> + </note> + </para> + </listitem> + </orderedlist> + </para> + + <para> + Once complete, you can follow with + <xref linkend="sec-installation-partitioning-formatting"/>. + </para> + </section> + + <section xml:id="sec-installation-partitioning-formatting"> + <title>Formatting</title> + + <para> + Use the following commands: + <itemizedlist> + <listitem> + <para> + For initialising Ext4 partitions: <command>mkfs.ext4</command>. It is + recommended that you assign a unique symbolic label to the file system + using the option <option>-L <replaceable>label</replaceable></option>, + since this makes the file system configuration independent from device + changes. For example: +<screen> +<prompt># </prompt>mkfs.ext4 -L nixos /dev/sda1</screen> + </para> + </listitem> + <listitem> + <para> + For creating swap partitions: <command>mkswap</command>. Again it’s + recommended to assign a label to the swap partition: <option>-L + <replaceable>label</replaceable></option>. For example: +<screen> +<prompt># </prompt>mkswap -L swap /dev/sda2</screen> + </para> + </listitem> + <listitem> + <variablelist> + <varlistentry> + <term> + UEFI systems + </term> + <listitem> + <para> + For creating boot partitions: <command>mkfs.fat</command>. Again + it’s recommended to assign a label to the boot partition: + <option>-n <replaceable>label</replaceable></option>. For example: +<screen> +<prompt># </prompt>mkfs.fat -F 32 -n boot /dev/sda3</screen> + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + <listitem> + <para> + For creating LVM volumes, the LVM commands, e.g., + <command>pvcreate</command>, <command>vgcreate</command>, and + <command>lvcreate</command>. + </para> + </listitem> + <listitem> + <para> + For creating software RAID devices, use <command>mdadm</command>. + </para> + </listitem> + </itemizedlist> + </para> + </section> + </section> + <section xml:id="sec-installation-installing"> + <title>Installing</title> + + <orderedlist> + <listitem> + <para> + Mount the target file system on which NixOS should be installed on + <filename>/mnt</filename>, e.g. +<screen> +<prompt># </prompt>mount /dev/disk/by-label/nixos /mnt +</screen> + </para> + </listitem> + <listitem> + <variablelist> + <varlistentry> + <term> + UEFI systems + </term> + <listitem> + <para> + Mount the boot file system on <filename>/mnt/boot</filename>, e.g. +<screen> +<prompt># </prompt>mkdir -p /mnt/boot +<prompt># </prompt>mount /dev/disk/by-label/boot /mnt/boot +</screen> + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + <listitem> + <para> + If your machine has a limited amount of memory, you may want to activate + swap devices now (<command>swapon + <replaceable>device</replaceable></command>). The installer (or rather, + the build actions that it may spawn) may need quite a bit of RAM, + depending on your configuration. +<screen> +<prompt># </prompt>swapon /dev/sda2</screen> + </para> + </listitem> + <listitem> + <para> + You now need to create a file + <filename>/mnt/etc/nixos/configuration.nix</filename> that specifies the + intended configuration of the system. This is because NixOS has a + <emphasis>declarative</emphasis> configuration model: you create or edit a + description of the desired configuration of your system, and then NixOS + takes care of making it happen. The syntax of the NixOS configuration file + is described in <xref linkend="sec-configuration-syntax"/>, while a list + of available configuration options appears in + <xref + linkend="ch-options"/>. A minimal example is shown in + <xref + linkend="ex-config"/>. + </para> + <para> + The command <command>nixos-generate-config</command> can generate an + initial configuration file for you: +<screen> +<prompt># </prompt>nixos-generate-config --root /mnt</screen> + You should then edit <filename>/mnt/etc/nixos/configuration.nix</filename> + to suit your needs: +<screen> +<prompt># </prompt>nano /mnt/etc/nixos/configuration.nix +</screen> + If you’re using the graphical ISO image, other editors may be available + (such as <command>vim</command>). If you have network access, you can also + install other editors — for instance, you can install Emacs by running + <literal>nix-env -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> + If you need to configure networking for your machine the configuration + options are described in <xref linkend="sec-networking"/>. + </para> + <para> + Another critical option is <option>fileSystems</option>, specifying the + file systems that need to be mounted by NixOS. However, you typically + don’t need to set it yourself, because + <command>nixos-generate-config</command> sets it automatically in + <filename>/mnt/etc/nixos/hardware-configuration.nix</filename> from your + currently mounted file systems. (The configuration file + <filename>hardware-configuration.nix</filename> is included from + <filename>configuration.nix</filename> and will be overwritten by future + invocations of <command>nixos-generate-config</command>; thus, you + generally should not modify it.) + </para> + <note> + <para> + Depending on your hardware configuration or type of file system, you may + need to set the option <option>boot.initrd.kernelModules</option> to + include the kernel modules that are necessary for mounting the root file + system, otherwise the installed system will not be able to boot. (If this + happens, boot from the installation media again, mount the target file + system on <filename>/mnt</filename>, fix + <filename>/mnt/etc/nixos/configuration.nix</filename> and rerun + <filename>nixos-install</filename>.) In most cases, + <command>nixos-generate-config</command> will figure out the required + modules. + </para> + </note> + </listitem> + <listitem> + <para> + Do the installation: +<screen> +<prompt># </prompt>nixos-install</screen> + 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> + <note> + <para> + For unattended installations, it is possible to use + <command>nixos-install --no-root-passwd</command> in order to disable + the password prompt entirely. + </para> + </note> + </para> + </listitem> + <listitem> + <para> + If everything went well: +<screen> +<prompt># </prompt>reboot</screen> + </para> + </listitem> + <listitem> + <para> + You should now be able to boot into the installed NixOS. The GRUB boot + menu shows a list of <emphasis>available configurations</emphasis> + (initially just one). Every time you change the NixOS configuration (see + <link + linkend="sec-changing-config">Changing Configuration</link> + ), a new item is added to the menu. This allows you to easily roll back to + a previous configuration if something goes wrong. + </para> + <para> + You should log in and change the <literal>root</literal> password with + <command>passwd</command>. + </para> + <para> + You’ll probably want to create some user accounts as well, which can be + done with <command>useradd</command>: +<screen> +<prompt>$ </prompt>useradd -c 'Eelco Dolstra' -m eelco +<prompt>$ </prompt>passwd eelco</screen> + </para> + <para> + You may also want to install some software. For instance, +<screen> +<prompt>$ </prompt>nix-env -qa \*</screen> + shows what packages are available, and +<screen> +<prompt>$ </prompt>nix-env -i w3m</screen> + install the <literal>w3m</literal> browser. + </para> + </listitem> + </orderedlist> + </section> + <section xml:id="sec-installation-summary"> + <title>Installation summary</title> + + <para> + To summarise, <xref linkend="ex-install-sequence" /> shows a typical + sequence of commands for installing NixOS on an empty hard drive (here + <filename>/dev/sda</filename>). <xref linkend="ex-config" +/> shows a + corresponding configuration Nix expression. + </para> + + <example xml:id="ex-partition-scheme-MBR"> + <title>Example partition schemes for NixOS on <filename>/dev/sda</filename> (MBR)</title> +<screen language="commands"> +<prompt># </prompt>parted /dev/sda -- mklabel msdos +<prompt># </prompt>parted /dev/sda -- mkpart primary 1MiB -8GiB +<prompt># </prompt>parted /dev/sda -- mkpart primary linux-swap -8GiB 100%</screen> + </example> + + <example xml:id="ex-partition-scheme-UEFI"> + <title>Example partition schemes for NixOS on <filename>/dev/sda</filename> (UEFI)</title> +<screen language="commands"> +<prompt># </prompt>parted /dev/sda -- mklabel gpt +<prompt># </prompt>parted /dev/sda -- mkpart primary 512MiB -8GiB +<prompt># </prompt>parted /dev/sda -- mkpart primary linux-swap -8GiB 100% +<prompt># </prompt>parted /dev/sda -- mkpart ESP fat32 1MiB 512MiB +<prompt># </prompt>parted /dev/sda -- set 3 boot on</screen> + </example> + + <example xml:id="ex-install-sequence"> + <title>Commands for Installing NixOS on <filename>/dev/sda</filename></title> + <para> + With a partitioned disk. +<screen language="commands"> +<prompt># </prompt>mkfs.ext4 -L nixos /dev/sda1 +<prompt># </prompt>mkswap -L swap /dev/sda2 +<prompt># </prompt>swapon /dev/sda2 +<prompt># </prompt>mkfs.fat -F 32 -n boot /dev/sda3 # <lineannotation>(for UEFI systems only)</lineannotation> +<prompt># </prompt>mount /dev/disk/by-label/nixos /mnt +<prompt># </prompt>mkdir -p /mnt/boot # <lineannotation>(for UEFI systems only)</lineannotation> +<prompt># </prompt>mount /dev/disk/by-label/boot /mnt/boot # <lineannotation>(for UEFI systems only)</lineannotation> +<prompt># </prompt>nixos-generate-config --root /mnt +<prompt># </prompt>nano /mnt/etc/nixos/configuration.nix +<prompt># </prompt>nixos-install +<prompt># </prompt>reboot</screen> + </para> + </example> + + <example xml:id='ex-config'> + <title>NixOS Configuration</title> +<programlisting> +{ config, pkgs, ... }: { + imports = [ + # Include the results of the hardware scan. + ./hardware-configuration.nix + ]; + + <xref linkend="opt-boot.loader.grub.device"/> = "/dev/sda"; # <lineannotation>(for BIOS systems only)</lineannotation> + <xref linkend="opt-boot.loader.systemd-boot.enable"/> = true; # <lineannotation>(for UEFI systems only)</lineannotation> + + # Note: setting fileSystems is generally not + # necessary, since nixos-generate-config figures them out + # automatically in hardware-configuration.nix. + #<link linkend="opt-fileSystems._name__.device">fileSystems."/".device</link> = "/dev/disk/by-label/nixos"; + + # Enable the OpenSSH server. + services.sshd.enable = true; +} +</programlisting> + </example> + </section> + <section xml:id="sec-installation-additional-notes"> + <title>Additional installation notes</title> + + <xi:include href="installing-usb.xml" /> + + <xi:include href="installing-pxe.xml" /> + + <xi:include href="installing-virtualbox-guest.xml" /> + + <xi:include href="installing-from-other-distro.xml" /> + + <xi:include href="installing-behind-a-proxy.xml" /> + </section> +</chapter> diff --git a/nixpkgs/nixos/doc/manual/installation/obtaining.xml b/nixpkgs/nixos/doc/manual/installation/obtaining.xml new file mode 100644 index 000000000000..56af5c0e25a0 --- /dev/null +++ b/nixpkgs/nixos/doc/manual/installation/obtaining.xml @@ -0,0 +1,54 @@ +<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-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. <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/nixpkgs/nixos/doc/manual/installation/upgrading.xml b/nixpkgs/nixos/doc/manual/installation/upgrading.xml new file mode 100644 index 000000000000..35b4d266e12e --- /dev/null +++ b/nixpkgs/nixos/doc/manual/installation/upgrading.xml @@ -0,0 +1,134 @@ +<chapter xmlns="http://docbook.org/ns/docbook" + 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-19.03">nixos-19.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.19.34 to 4.19.38 (a minor bug fix), but not from + 4.19.<replaceable>x</replaceable> to 4.20.<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 + 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-19.03-small">nixos-19.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.) Please note that + during the release process, channels that are not yet released will be + present here as well. See the Getting NixOS page + <link xlink:href="https://nixos.org/nixos/download.html"/> to find the newest + supported stable release. + </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 19.03 ISO, you will be subscribed to the + <literal>nixos-19.03</literal> channel. To see which NixOS channel you’re + subscribed to, run the following as root: +<screen> +# nix-channel --list | grep nixos +nixos https://nixos.org/channels/nixos-unstable +</screen> + To switch to a different NixOS channel, do +<screen> +# 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 19.03 stable channel: +<screen> +# nix-channel --add https://nixos.org/channels/nixos-19.03 nixos +</screen> + If you have a server, you may want to use the “small” channel instead: +<screen> +# nix-channel --add https://nixos.org/channels/nixos-19.03-small nixos +</screen> + And if you want to live on the bleeding edge: +<screen> +# 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 +<screen> +# nixos-rebuild switch --upgrade +</screen> + 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 xml:id="sec-upgrading-automatic"> + <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> +<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. +<programlisting> +<xref linkend="opt-system.autoUpgrade.channel"/> = https://nixos.org/channels/nixos-19.03; +</programlisting> + </para> + </section> +</chapter> diff --git a/nixpkgs/nixos/doc/manual/man-configuration.xml b/nixpkgs/nixos/doc/manual/man-configuration.xml new file mode 100644 index 000000000000..9f30b7925101 --- /dev/null +++ b/nixpkgs/nixos/doc/manual/man-configuration.xml @@ -0,0 +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> + <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="./generated/options-db.xml" + xpointer="configuration-variable-list" /> + </refsection> +</refentry> diff --git a/nixpkgs/nixos/doc/manual/man-nixos-build-vms.xml b/nixpkgs/nixos/doc/manual/man-nixos-build-vms.xml new file mode 100644 index 000000000000..7d6e04e0dd90 --- /dev/null +++ b/nixpkgs/nixos/doc/manual/man-nixos-build-vms.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-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> + <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> + <option>--option</option> + <replaceable>name</replaceable> + <replaceable>value</replaceable> + </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: +<screen> +{ + test1 = {pkgs, config, ...}: + { + services.openssh.enable = true; + 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.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.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> + </listitem> + </varlistentry> + <varlistentry> + <term> + <option>--no-out-link</option> + </term> + <listitem> + <para> + Do not create a 'result' symlink. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <option>-h</option>, <option>--help</option> + </term> + <listitem> + <para> + Shows the usage of this command to the user. + </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>. + This overrides settings in the Nix configuration file (see + <citerefentry><refentrytitle>nix.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>). + </para> + </listitem> + </varlistentry> + </variablelist> + </refsection> +</refentry> diff --git a/nixpkgs/nixos/doc/manual/man-nixos-enter.xml b/nixpkgs/nixos/doc/manual/man-nixos-enter.xml new file mode 100644 index 000000000000..42edaa1ae5b6 --- /dev/null +++ b/nixpkgs/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/nixpkgs/nixos/doc/manual/man-nixos-generate-config.xml b/nixpkgs/nixos/doc/manual/man-nixos-generate-config.xml new file mode 100644 index 000000000000..61531a8f01ca --- /dev/null +++ b/nixpkgs/nixos/doc/manual/man-nixos-generate-config.xml @@ -0,0 +1,214 @@ +<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> + <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> + <cmdsynopsis> + <command>nixos-generate-config</command> + <arg> + <option>--force</option> + </arg> + + <arg> + <arg choice='plain'> + <option>--root</option> + </arg> + <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> + <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> + 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>--dir</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> + </listitem> + </varlistentry> + <varlistentry> + <term> + <option>--force</option> + </term> + <listitem> + <para> + Overwrite <filename>/etc/nixos/configuration.nix</filename> if it already + exists. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <option>--no-filesystems</option> + </term> + <listitem> + <para> + Omit everything concerning file systems and 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: +<screen> +<prompt>$ </prompt>nixos-generate-config --root /mnt +</screen> + 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 +# to /etc/nixos/configuration.nix instead. +{ config, pkgs, ... }: + +{ + imports = + [ <nixos/modules/installer/scan/not-detected.nix> + ]; + + boot.initrd.availableKernelModules = [ "ehci_hcd" "ahci" ]; + boot.kernelModules = [ "kvm-intel" ]; + boot.extraModulePackages = [ ]; + + fileSystems."/" = + { device = "/dev/disk/by-label/nixos"; + fsType = "ext3"; + options = [ "rw" "data=ordered" "relatime" ]; + }; + + fileSystems."/boot" = + { device = "/dev/sda1"; + fsType = "ext3"; + options = [ "rw" "errors=continue" "user_xattr" "acl" "barrier=1" "data=writeback" "relatime" ]; + }; + + swapDevices = + [ { device = "/dev/sda2"; } + ]; + + 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: +<programlisting> + imports = [ ./hardware-configuration.nix ]; +</programlisting> + </para> + <para> + After installation, if your hardware configuration changes, you can run: +<screen> +<prompt>$ </prompt>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> +</refentry> diff --git a/nixpkgs/nixos/doc/manual/man-nixos-install.xml b/nixpkgs/nixos/doc/manual/man-nixos-install.xml new file mode 100644 index 000000000000..4fb94ee7494c --- /dev/null +++ b/nixpkgs/nixos/doc/manual/man-nixos-install.xml @@ -0,0 +1,267 @@ +<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> + <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> + <cmdsynopsis> + <command>nixos-install</command> + <arg> + <arg choice='plain'> + <option>-I</option> + </arg> + <replaceable>path</replaceable> + </arg> + + <arg> + <arg choice='plain'> + <option>--root</option> + </arg> + <replaceable>root</replaceable> + </arg> + + <arg> + <arg choice='plain'> + <option>--system</option> + </arg> + <replaceable>path</replaceable> + </arg> + + <arg> + <arg choice='plain'> + <option>--no-channel-copy</option> + </arg> + </arg> + + <arg> + <arg choice='plain'> + <option>--no-root-passwd</option> + </arg> + </arg> + + <arg> + <arg choice='plain'> + <option>--no-bootloader</option> + </arg> + </arg> + + <arg> + <group choice='req'> + <arg choice='plain'> + <option>--max-jobs</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> (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> + 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> + <listitem> + <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> + <listitem> + <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>: +<screen> +<prompt>$ </prompt>mkfs.ext4 /dev/sda1 +<prompt>$ </prompt>mount /dev/sda1 /mnt +<prompt>$ </prompt>nixos-generate-config --root /mnt +<prompt>$ </prompt># edit /mnt/etc/nixos/configuration.nix +<prompt>$ </prompt>nixos-install +<prompt>$ </prompt>reboot +</screen> + </para> + </refsection> +</refentry> diff --git a/nixpkgs/nixos/doc/manual/man-nixos-option.xml b/nixpkgs/nixos/doc/manual/man-nixos-option.xml new file mode 100644 index 000000000000..3e316e10d4eb --- /dev/null +++ b/nixpkgs/nixos/doc/manual/man-nixos-option.xml @@ -0,0 +1,137 @@ +<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> + <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> + <cmdsynopsis> + <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>Options</title> + <para> + This command accepts the following options: + </para> + <variablelist> + <varlistentry> + <term> + <option>-I</option> <replaceable>path</replaceable> + </term> + <listitem> + <para> + This option is passed to the underlying + <command>nix-instantiate</command> invocation. + </para> + </listitem> + </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><prompt>$ </prompt>nixos-option boot.loader +This attribute set contains: +generationsDir +grub +initScript + +<prompt>$ </prompt>nixos-option boot.loader.grub.enable +Value: +true + +Default: +true + +Description: +Whether to enable the GNU GRUB boot loader. + +Declared by: + "/nix/var/nix/profiles/per-user/root/channels/nixos/nixpkgs/nixos/modules/system/boot/loader/grub/grub.nix" + +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> +</refentry> diff --git a/nixpkgs/nixos/doc/manual/man-nixos-rebuild.xml b/nixpkgs/nixos/doc/manual/man-nixos-rebuild.xml new file mode 100644 index 000000000000..9cec83f1e28b --- /dev/null +++ b/nixpkgs/nixos/doc/manual/man-nixos-rebuild.xml @@ -0,0 +1,505 @@ +<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> + <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> + <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>edit</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-bootloader</option> + </arg> + + <arg> + <option>--no-build-nix</option> + </arg> + + <arg> + <option>--fast</option> + </arg> + + <arg> + <option>--rollback</option> + </arg> + + <arg> + <option>--builders</option> <replaceable>builder-spec</replaceable> + </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> + </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 + 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> +<prompt>$ </prompt>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>edit</option> + </term> + <listitem> + <para> + Opens <filename>configuration.nix</filename> in the default editor. + </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> +<prompt>$ </prompt>nixos-rebuild build-vm +<prompt>$ </prompt>./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. + </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> + </listitem> + </varlistentry> + <varlistentry> + <term> + <option>--install-bootloader</option> + </term> + <listitem> + <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> + <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> + </listitem> + </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> + </listitem> + </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> + </listitem> + </varlistentry> + <varlistentry> + <term> + <option>--builders</option> <replaceable>builder-spec</replaceable> + </term> + <listitem> + <para> + Allow ad-hoc remote builders for building the new system. This requires + the user executing <command>nixos-rebuild</command> (usually root) to be + configured as a trusted user in the Nix daemon. This can be achieved by + using the <literal>nix.trustedUsers</literal> NixOS option. Examples + values for that option are described in the <literal>Remote builds + chapter</literal> in the Nix manual, (i.e. <command>--builders + "ssh://bigbrother x86_64-linux"</command>). By specifying an empty string + existing builders specified in <filename>/etc/nix/machines</filename> can + be ignored: <command>--builders ""</command> for example when they are + not reachable due to network connectivity. + </para> + </listitem> + </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 + <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: +<screen> +<prompt>$ </prompt>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> + </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> + <varlistentry> + <term> + <envar>NIX_SSHOPTS</envar> + </term> + <listitem> + <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> + <listitem> + <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> + <listitem> + <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> +</refentry> diff --git a/nixpkgs/nixos/doc/manual/man-nixos-version.xml b/nixpkgs/nixos/doc/manual/man-nixos-version.xml new file mode 100644 index 000000000000..931c4a5ad029 --- /dev/null +++ b/nixpkgs/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/nixpkgs/nixos/doc/manual/man-pages.xml b/nixpkgs/nixos/doc/manual/man-pages.xml new file mode 100644 index 000000000000..f5a1dd2d69f4 --- /dev/null +++ b/nixpkgs/nixos/doc/manual/man-pages.xml @@ -0,0 +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-2019</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/nixpkgs/nixos/doc/manual/manual.xml b/nixpkgs/nixos/doc/manual/manual.xml new file mode 100644 index 000000000000..12f52e1997c8 --- /dev/null +++ b/nixpkgs/nixos/doc/manual/manual.xml @@ -0,0 +1,48 @@ +<book 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="book-nixos-manual"> + <info> + <title>NixOS Manual</title> + <subtitle>Version <xi:include href="./generated/version" parse="text" /> + </subtitle> + </info> + <preface xml:id="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://discourse.nixos.org">Discourse</literal> 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> + <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/nixpkgs/nixos/doc/manual/release-notes/release-notes.xml b/nixpkgs/nixos/doc/manual/release-notes/release-notes.xml new file mode 100644 index 000000000000..02b591477214 --- /dev/null +++ b/nixpkgs/nixos/doc/manual/release-notes/release-notes.xml @@ -0,0 +1,23 @@ +<appendix 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-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-1909.xml" /> + <xi:include href="rl-1903.xml" /> + <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/nixpkgs/nixos/doc/manual/release-notes/rl-1310.xml b/nixpkgs/nixos/doc/manual/release-notes/rl-1310.xml new file mode 100644 index 000000000000..248bab70c36b --- /dev/null +++ b/nixpkgs/nixos/doc/manual/release-notes/rl-1310.xml @@ -0,0 +1,11 @@ +<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-13.10"> + <title>Release 13.10 (“Aardvark”, 2013/10/31)</title> + + <para> + This is the first stable release branch of NixOS. + </para> +</section> diff --git a/nixpkgs/nixos/doc/manual/release-notes/rl-1404.xml b/nixpkgs/nixos/doc/manual/release-notes/rl-1404.xml new file mode 100644 index 000000000000..8d8cea4303a3 --- /dev/null +++ b/nixpkgs/nixos/doc/manual/release-notes/rl-1404.xml @@ -0,0 +1,179 @@ +<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-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-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: +<programlisting> +systemd.packages = [ pkgs.foo ]; +</programlisting> + 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: +<programlisting> +nixpkgs.config.allowUnfree = true; +</programlisting> + 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: +<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: +<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> +</section> diff --git a/nixpkgs/nixos/doc/manual/release-notes/rl-1412.xml b/nixpkgs/nixos/doc/manual/release-notes/rl-1412.xml new file mode 100644 index 000000000000..139f61c2a550 --- /dev/null +++ b/nixpkgs/nixos/doc/manual/release-notes/rl-1412.xml @@ -0,0 +1,467 @@ +<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-14.12"> + <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="https://www.mail-archive.com/nix-dev@lists.science.uu.nl/msg13957.html"> + 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 +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: +<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> +</section> diff --git a/nixpkgs/nixos/doc/manual/release-notes/rl-1509.xml b/nixpkgs/nixos/doc/manual/release-notes/rl-1509.xml new file mode 100644 index 000000000000..5c4d99701785 --- /dev/null +++ b/nixpkgs/nixos/doc/manual/release-notes/rl-1509.xml @@ -0,0 +1,750 @@ +<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-15.09"> + <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> + <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 + 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 + xlink:href="http://www.stackage.org/">LTS Haskell</link> release + 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="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> + </listitem> + <listitem> + <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> + </listitem> + <listitem> + <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> + </listitem> + <listitem> + <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> + </listitem> + <listitem> + <para> + E19 has been upgraded to 0.16.8.15. + </para> + </listitem> + </itemizedlist> + + <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> + </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 +<programlisting> +system.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: +<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> +nix-env -f "<nixpkgs>" -qaP -A haskellPackages +</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 + 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 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> +<prompt>$ </prompt>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 +<programlisting> +{ config, pkgs, ... }: + +with pkgs.lib; + +{ + options = { + foo = mkOption { … }; + }; + config = mkIf config.foo { … }; +} +</programlisting> + should be modified to look like: +<programlisting> +{ config, pkgs, lib, ... }: + +with lib; + +{ + options = { + foo = mkOption { <replaceable>option declaration</replaceable> }; + }; + 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 +<programlisting> +{ config, pkgs, ... }: + +let + myProject = pkgs.fetchurl { + src = <replaceable>url</replaceable>; + sha256 = <replaceable>hash</replaceable>; + }; +in + +{ + imports = [ "${myProject}/module.nix" ]; +} +</programlisting> + should be modified to look like: +<programlisting> +{ config, pkgs, ... }: + +let + myProject = (import <nixpkgs> {}).fetchurl { + src = <replaceable>url</replaceable>; + sha256 = <replaceable>hash</replaceable>; + }; +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> + <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/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/nixpkgs/nixos/doc/manual/release-notes/rl-1603.xml b/nixpkgs/nixos/doc/manual/release-notes/rl-1603.xml new file mode 100644 index 000000000000..9b512c4b1e58 --- /dev/null +++ b/nixpkgs/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/nixpkgs/nixos/doc/manual/release-notes/rl-1609.xml b/nixpkgs/nixos/doc/manual/release-notes/rl-1609.xml new file mode 100644 index 000000000000..4a2343edc970 --- /dev/null +++ b/nixpkgs/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/nixpkgs/nixos/doc/manual/release-notes/rl-1703.xml b/nixpkgs/nixos/doc/manual/release-notes/rl-1703.xml new file mode 100644 index 000000000000..86f4a1ccfb78 --- /dev/null +++ b/nixpkgs/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/nixpkgs/nixos/doc/manual/release-notes/rl-1709.xml b/nixpkgs/nixos/doc/manual/release-notes/rl-1709.xml new file mode 100644 index 000000000000..795c51d2923d --- /dev/null +++ b/nixpkgs/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/nixpkgs/nixos/doc/manual/release-notes/rl-1803.xml b/nixpkgs/nixos/doc/manual/release-notes/rl-1803.xml new file mode 100644 index 000000000000..c14679eea071 --- /dev/null +++ b/nixpkgs/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/nixpkgs/nixos/doc/manual/release-notes/rl-1809.xml b/nixpkgs/nixos/doc/manual/release-notes/rl-1809.xml new file mode 100644 index 000000000000..3f10b26223dd --- /dev/null +++ b/nixpkgs/nixos/doc/manual/release-notes/rl-1809.xml @@ -0,0 +1,933 @@ +<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/10/05)</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 notable updates: + </para> + + <itemizedlist> + <listitem> + <para> + End of support is planned for end of April 2019, handing over to 19.03. + </para> + </listitem> + <listitem> + <para> + Platform support: x86_64-linux and x86_64-darwin as always. Support for + aarch64-linux is as with the previous releases, not equivalent to the + x86-64-linux release, but with efforts to reach parity. + </para> + </listitem> + <listitem> + <para> + Nix has been updated to 2.1; see its + <link xlink:href="https://nixos.org/nix/manual/#ssec-relnotes-2.1">release + notes</link>. + </para> + </listitem> + <listitem> + <para> + Core versions: linux: 4.14 LTS (unchanged), glibc: 2.26 → 2.27, gcc: 7 + (unchanged), systemd: 237 → 239. + </para> + </listitem> + <listitem> + <para> + Desktop version changes: gnome: 3.26 → 3.28, (KDE) plasma-desktop: 5.12 + → 5.13. + </para> + </listitem> + </itemizedlist> + + <para> + Notable changes and additions for 18.09 include: + </para> + + <itemizedlist> + <listitem> + <para> + Support for wrapping binaries using <literal>firejail</literal> has been + added through <varname>programs.firejail.wrappedBinaries</varname>. + </para> + <para> + For example + </para> +<programlisting> +programs.firejail = { + enable = true; + wrappedBinaries = { + firefox = "${lib.getBin pkgs.firefox}/bin/firefox"; + mpv = "${lib.getBin pkgs.mpv}/bin/mpv"; + }; +}; +</programlisting> + <para> + This will place <literal>firefox</literal> and <literal>mpv</literal> + binaries in the global path wrapped by firejail. + </para> + </listitem> + <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> + A curated selection of new services that were added since the last release: + </para> + + <itemizedlist> + <listitem> + <para> + The <varname>services.cassandra</varname> module has been reworked and was + rewritten from scratch. The service has succeeding tests for the versions + 2.1, 2.2, 3.0 and 3.11 of + <link + xlink:href="https://cassandra.apache.org/">Apache + Cassandra</link>. + </para> + </listitem> + <listitem> + <para> + There is a new <varname>services.foundationdb</varname> module for + deploying + <link xlink:href="https://www.foundationdb.org">FoundationDB</link> + clusters. + </para> + </listitem> + <listitem> + <para> + When enabled the <literal>iproute2</literal> will copy the files expected + by ip route (e.g., <filename>rt_tables</filename>) in + <filename>/etc/iproute2</filename>. This allows to write aliases for + routing tables for instance. + </para> + </listitem> + <listitem> + <para> + <varname>services.strongswan-swanctl</varname> is a modern replacement for + <varname>services.strongswan</varname>. You can use either one of them to + setup IPsec VPNs but not both at the same time. + </para> + <para> + <varname>services.strongswan-swanctl</varname> uses the + <link xlink:href="https://wiki.strongswan.org/projects/strongswan/wiki/swanctl">swanctl</link> + command which uses the modern + <link xlink:href="https://github.com/strongswan/strongswan/blob/master/src/libcharon/plugins/vici/README.md">vici</link> + <emphasis>Versatile IKE Configuration Interface</emphasis>. The deprecated + <literal>ipsec</literal> command used in + <varname>services.strongswan</varname> is using the legacy + <link xlink:href="https://github.com/strongswan/strongswan/blob/master/README_LEGACY.md">stroke + configuration interface</link>. + </para> + </listitem> + <listitem> + <para> + The new <varname>services.elasticsearch-curator</varname> service + periodically curates or manages, your Elasticsearch indices and snapshots. + </para> + </listitem> + </itemizedlist> + + <para> + Every new services: + </para> + + <itemizedlist> + <listitem> + <para> + <literal>./config/xdg/autostart.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./config/xdg/icons.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./config/xdg/menus.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./config/xdg/mime.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./hardware/brightnessctl.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./hardware/onlykey.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./hardware/video/uvcvideo/default.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./misc/documentation.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./programs/firejail.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./programs/iftop.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./programs/sedutil.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./programs/singularity.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./programs/xss-lock.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./programs/zsh/zsh-autosuggestions.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/admin/oxidized.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/backup/duplicati.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/backup/restic.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/backup/restic-rest-server.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/cluster/hadoop/default.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/databases/aerospike.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/databases/monetdb.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/desktops/bamf.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/desktops/flatpak.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/desktops/zeitgeist.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/development/bloop.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/development/jupyter/default.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/hardware/lcd.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/hardware/undervolt.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/misc/clipmenu.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/misc/gitweb.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/misc/serviio.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/misc/safeeyes.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/misc/sysprof.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/misc/weechat.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/monitoring/datadog-agent.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/monitoring/incron.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/networking/dnsdist.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/networking/freeradius.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/networking/hans.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/networking/morty.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/networking/ndppd.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/networking/ocserv.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/networking/owamp.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/networking/quagga.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/networking/shadowsocks.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/networking/stubby.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/networking/zeronet.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/security/certmgr.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/security/cfssl.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/security/oauth2_proxy_nginx.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/web-apps/virtlyst.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/web-apps/youtrack.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/web-servers/hitch/default.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/web-servers/hydron.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/web-servers/meguca.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./services/web-servers/nginx/gitweb.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./virtualisation/kvmgt.nix</literal> + </para> + </listitem> + <listitem> + <para> + <literal>./virtualisation/qemu-guest-agent.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.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> + Some licenses that were incorrectly not marked as unfree now are. This is + the case for: + <itemizedlist> + <listitem> + <para> + cc-by-nc-sa-20: Creative Commons Attribution Non Commercial Share Alike + 2.0 + </para> + </listitem> + <listitem> + <para> + cc-by-nc-sa-25: Creative Commons Attribution Non Commercial Share Alike + 2.5 + </para> + </listitem> + <listitem> + <para> + cc-by-nc-sa-30: Creative Commons Attribution Non Commercial Share Alike + 3.0 + </para> + </listitem> + <listitem> + <para> + cc-by-nc-sa-40: Creative Commons Attribution Non Commercial Share Alike + 4.0 + </para> + </listitem> + <listitem> + <para> + cc-by-nd-30: Creative Commons Attribution-No Derivative Works v3.00 + </para> + </listitem> + <listitem> + <para> + msrla: Microsoft Research License Agreement + </para> + </listitem> + </itemizedlist> + </para> + </listitem> + <listitem> + <para> + The deprecated <varname>services.cassandra</varname> module has seen a + complete rewrite. (See above.) + </para> + </listitem> + <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> + <listitem> + <para> + <varname>dockerTools.buildImage</varname> now uses <literal>null</literal> + as default value for <varname>tag</varname>, which indicates that the nix + output hash will be used as tag. + </para> + </listitem> + <listitem> + <para> + The ELK stack: <varname>elasticsearch</varname>, + <varname>logstash</varname> and <varname>kibana</varname> has been + upgraded from 2.* to 6.3.*. The 2.* versions have been + <link xlink:href="https://www.elastic.co/support/eol">unsupported since + last year</link> so they have been removed. You can still use the 5.* + versions under the names <varname>elasticsearch5</varname>, + <varname>logstash5</varname> and <varname>kibana5</varname>. + </para> + <para> + The elastic beats: <varname>filebeat</varname>, + <varname>heartbeat</varname>, <varname>metricbeat</varname> and + <varname>packetbeat</varname> have had the same treatment: they now target + 6.3.* as well. The 5.* versions are available under the names: + <varname>filebeat5</varname>, <varname>heartbeat5</varname>, + <varname>metricbeat5</varname> and <varname>packetbeat5</varname> + </para> + <para> + The ELK-6.3 stack now comes with + <link xlink:href="https://www.elastic.co/products/x-pack/open">X-Pack by + default</link>. Since X-Pack is licensed under the + <link xlink:href="https://github.com/elastic/elasticsearch/blob/master/licenses/ELASTIC-LICENSE.txt">Elastic + License</link> the ELK packages now have an unfree license. To use them + you need to specify <literal>allowUnfree = true;</literal> in your nixpkgs + configuration. + </para> + <para> + Fortunately there is also a free variant of the ELK stack without X-Pack. + The packages are available under the names: + <varname>elasticsearch-oss</varname>, <varname>logstash-oss</varname> and + <varname>kibana-oss</varname>. + </para> + </listitem> + <listitem> + <para> + Options + <literal>boot.initrd.luks.devices.<replaceable>name</replaceable>.yubikey.ramfsMountPoint</literal> + <literal>boot.initrd.luks.devices.<replaceable>name</replaceable>.yubikey.storage.mountPoint</literal> + were removed. <literal>luksroot.nix</literal> module never supported more + than one YubiKey at a time anyway, hence those options never had any + effect. You should be able to remove them from your config without any + issues. + </para> + </listitem> + <listitem> + <para> + <literal>stdenv.system</literal> and <literal>system</literal> in nixpkgs + now refer to the host platform instead of the build platform. For native + builds this is not change, let alone a breaking one. For cross builds, it + is a breaking change, and <literal>stdenv.buildPlatform.system</literal> + can be used instead for the old behavior. They should be using that + anyways for clarity. + </para> + </listitem> + <listitem> + <para> + Groups <literal>kvm</literal> and <literal>render</literal> are introduced + now, as systemd requires them. + </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> + </listitem> + <listitem> + <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> + <literal>lib.recursiveUpdateUntil</literal> was not acting according to + its specification. It has been fixed to act according to the docstring, + and a test has been added. + </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 Kubernetes package has been bumped to major version 1.11. Please + consult the + <link xlink:href="https://github.com/kubernetes/kubernetes/blob/release-1.11/CHANGELOG-1.11.md">release + notes</link> for details on new features and api changes. + </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> + <listitem> + <para> + The option + <varname>services.kubernetes.addons.dashboard.enableRBAC</varname> was + renamed to + <varname>services.kubernetes.addons.dashboard.rbac.enable</varname>. + </para> + </listitem> + <listitem> + <para> + The Kubernetes Dashboard now has only minimal RBAC permissions by default. + If dashboard cluster-admin rights are desired, set + <varname>services.kubernetes.addons.dashboard.rbac.clusterAdmin</varname> + to true. On existing clusters, in order for the revocation of privileges + to take effect, the current ClusterRoleBinding for kubernetes-dashboard + must be manually removed: <literal>kubectl delete clusterrolebinding + kubernetes-dashboard</literal> + </para> + </listitem> + <listitem> + <para> + The <varname>programs.screen</varname> module provides allows to configure + <literal>/etc/screenrc</literal>, however the module behaved fairly + counterintuitive as the config exists, but the package wasn't available. + Since 18.09 <literal>pkgs.screen</literal> will be added to + <literal>environment.systemPackages</literal>. + </para> + </listitem> + <listitem> + <para> + The module <option>services.networking.hostapd</option> now uses WPA2 by + default. + </para> + </listitem> + <listitem> + <para> + <varname>s6Dns</varname>, <varname>s6Networking</varname>, + <varname>s6LinuxUtils</varname> and <varname>s6PortableUtils</varname> + renamed to <varname>s6-dns</varname>, <varname>s6-networking</varname>, + <varname>s6-linux-utils</varname> and <varname>s6-portable-utils</varname> + respectively. + </para> + </listitem> + <listitem> + <para> + The module option <option>nix.useSandbox</option> is now defaulted to + <literal>true</literal>. + </para> + </listitem> + <listitem> + <para> + The config activation script of <literal>nixos-rebuild</literal> now + <link xlink:href="https://www.freedesktop.org/software/systemd/man/systemctl.html#Manager%20Lifecycle%20Commands">reloads</link> + all user units for each authenticated user. + </para> + </listitem> + <listitem> + <para> + The default display manager is now LightDM. To use SLiM set + <literal>services.xserver.displayManager.slim.enable</literal> to + <literal>true</literal>. + </para> + </listitem> + <listitem> + <para> + NixOS option descriptions are now automatically broken up into individual + paragraphs if the text contains two consecutive newlines, so it's no + longer necessary to use <code></para><para></code> to start a + new paragraph. + </para> + </listitem> + <listitem> + <para> + Top-level <literal>buildPlatform</literal>, + <literal>hostPlatform</literal>, and <literal>targetPlatform</literal> in + Nixpkgs are deprecated. Please use their equivalents in + <literal>stdenv</literal> instead: + <literal>stdenv.buildPlatform</literal>, + <literal>stdenv.hostPlatform</literal>, and + <literal>stdenv.targetPlatform</literal>. + </para> + </listitem> + </itemizedlist> + </section> +</section> diff --git a/nixpkgs/nixos/doc/manual/release-notes/rl-1903.xml b/nixpkgs/nixos/doc/manual/release-notes/rl-1903.xml new file mode 100644 index 000000000000..8ff1681d3b4a --- /dev/null +++ b/nixpkgs/nixos/doc/manual/release-notes/rl-1903.xml @@ -0,0 +1,768 @@ +<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-19.03"> + <title>Release 19.03 (“Koi”, 2019/04/11)</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-19.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 2019, handing over to 19.09. + </para> + </listitem> + <listitem> + <para> + The default Python 3 interpreter is now CPython 3.7 instead of CPython + 3.6. + </para> + </listitem> + <listitem> + <para> + Added the Pantheon desktop environment. It can be enabled through + <varname>services.xserver.desktopManager.pantheon.enable</varname>. + </para> + <note> + <para> + By default, <varname>services.xserver.desktopManager.pantheon</varname> + enables LightDM as a display manager, as pantheon's screen locking + implementation relies on it. + </para> + <para> + Because of that it is recommended to leave LightDM enabled. If you'd like + to disable it anyway, set + <option>services.xserver.displayManager.lightdm.enable</option> to + <literal>false</literal> and enable your preferred display manager. + </para> + </note> + <para> + Also note that Pantheon's LightDM greeter is not enabled by default, + because it has numerous issues in NixOS and isn't optimal for use here + yet. + </para> + </listitem> + <listitem> + <para> + A major refactoring of the Kubernetes module has been completed. + Refactorings primarily focus on decoupling components and enhancing + security. Two-way TLS and RBAC has been enabled by default for all + components, which slightly changes the way the module is configured. See: + <xref linkend="sec-kubernetes"/> for details. + </para> + </listitem> + <listitem> + <para> + There is now a set of <option>confinement</option> options for + <option>systemd.services</option>, which allows to restrict services + into a <citerefentry> + <refentrytitle>chroot</refentrytitle> + <manvolnum>2</manvolnum> + </citerefentry>ed environment that only contains the store paths from + the runtime closure of the service. + </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-19.03-new-services"> + <title>New Services</title> + + <para> + The following new services were added since the last release: + </para> + + <itemizedlist> + <listitem> + <para> + <literal>./programs/nm-applet.nix</literal> + </para> + </listitem> + <listitem> + <para> + There is a new <varname>security.googleOsLogin</varname> module for using + <link xlink:href="https://cloud.google.com/compute/docs/instances/managing-instance-access">OS + Login</link> to manage SSH access to Google Compute Engine instances, + which supersedes the imperative and broken + <literal>google-accounts-daemon</literal> used in + <literal>nixos/modules/virtualisation/google-compute-config.nix</literal>. + </para> + </listitem> + <listitem> + <para> + <literal>./services/misc/beanstalkd.nix</literal> + </para> + </listitem> + <listitem> + <para> + There is a new <varname>services.cockroachdb</varname> module for running + CockroachDB databases. NixOS now ships with CockroachDB 2.1.x as well, + available on <literal>x86_64-linux</literal> and + <literal>aarch64-linux</literal>. + </para> + </listitem> + </itemizedlist> + + <itemizedlist> + <listitem> + <para> + <literal>./security/duosec.nix</literal> + </para> + </listitem> + <listitem> + <para> + The <link xlink:href="https://duo.com/docs/duounix">PAM module for Duo + Security</link> has been enabled for use. One can configure it using the + <option>security.duosec</option> options along with the corresponding PAM + option in + <option>security.pam.services.<name?>.duoSecurity.enable</option>. + </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-19.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> + The minimum version of Nix required to evaluate Nixpkgs is now 2.0. + </para> + <itemizedlist> + <listitem> + <para> + For users of NixOS 18.03 and 19.03, NixOS defaults to Nix 2.0, but + supports using Nix 1.11 by setting <literal>nix.package = + pkgs.nix1;</literal>. If this option is set to a Nix 1.11 package, you + will need to either unset the option or upgrade it to Nix 2.0. + </para> + </listitem> + <listitem> + <para> + For users of NixOS 17.09, you will first need to upgrade Nix by setting + <literal>nix.package = pkgs.nixStable2;</literal> and run + <command>nixos-rebuild switch</command> as the <literal>root</literal> + user. + </para> + </listitem> + <listitem> + <para> + For users of a daemon-less Nix installation on Linux or macOS, you can + upgrade Nix by running <command>curl https://nixos.org/nix/install | + sh</command>, or prior to doing a channel update, running + <command>nix-env -iA nix</command>. + </para> + <para> + If you have already run a channel update and Nix is no longer able to + evaluate Nixpkgs, the error message printed should provide adequate + directions for upgrading Nix. + </para> + </listitem> + <listitem> + <para> + For users of the Nix daemon on macOS, you can upgrade Nix by running + <command>sudo -i sh -c 'nix-channel --update && nix-env -iA + nixpkgs.nix'; sudo launchctl stop org.nixos.nix-daemon; sudo launchctl + start org.nixos.nix-daemon</command>. + </para> + </listitem> + </itemizedlist> + </listitem> + <listitem> + <para> + The <varname>buildPythonPackage</varname> function now sets + <varname>strictDeps = true</varname> to help distinguish between native + and non-native dependencies in order to improve cross-compilation + compatibility. Note however that this may break user expressions. + </para> + </listitem> + <listitem> + <para> + The <varname>buildPythonPackage</varname> function now sets <varname>LANG + = C.UTF-8</varname> to enable Unicode support. The + <varname>glibcLocales</varname> package is no longer needed as a build + input. + </para> + </listitem> + <listitem> + <para> + The Syncthing state and configuration data has been moved from + <varname>services.syncthing.dataDir</varname> to the newly defined + <varname>services.syncthing.configDir</varname>, which default to + <literal>/var/lib/syncthing/.config/syncthing</literal>. This change makes + possible to share synced directories using ACLs without Syncthing + resetting the permission on every start. + </para> + </listitem> + <listitem> + <para> + The <literal>ntp</literal> module now has sane default restrictions. If + you're relying on the previous defaults, which permitted all queries and + commands from all firewall-permitted sources, you can set + <varname>services.ntp.restrictDefault</varname> and + <varname>services.ntp.restrictSource</varname> to <literal>[]</literal>. + </para> + </listitem> + <listitem> + <para> + Package <varname>rabbitmq_server</varname> is renamed to + <varname>rabbitmq-server</varname>. + </para> + </listitem> + <listitem> + <para> + The <literal>light</literal> module no longer uses setuid binaries, but + udev rules. As a consequence users of that module have to belong to the + <literal>video</literal> group in order to use the executable (i.e. + <literal>users.users.yourusername.extraGroups = ["video"];</literal>). + </para> + </listitem> + <listitem> + <para> + Buildbot now supports Python 3 and its packages have been moved to + <literal>pythonPackages</literal>. The options + <option>services.buildbot-master.package</option> and + <option>services.buildbot-worker.package</option> can be used to select + the Python 2 or 3 version of the package. + </para> + </listitem> + <listitem> + <para> + Options + <literal>services.znc.confOptions.networks.<replaceable>name</replaceable>.userName</literal> + and + <literal>services.znc.confOptions.networks.<replaceable>name</replaceable>.modulePackages</literal> + were removed. They were never used for anything and can therefore safely + be removed. + </para> + </listitem> + <listitem> + <para> + Package <literal>wasm</literal> has been renamed + <literal>proglodyte-wasm</literal>. The package <literal>wasm</literal> + will be pointed to <literal>ocamlPackages.wasm</literal> in 19.09, so make + sure to update your configuration if you want to keep + <literal>proglodyte-wasm</literal> + </para> + </listitem> + <listitem> + <para> + When the <literal>nixpkgs.pkgs</literal> option is set, NixOS will no + longer ignore the <literal>nixpkgs.overlays</literal> option. The old + behavior can be recovered by setting <literal>nixpkgs.overlays = + lib.mkForce [];</literal>. + </para> + </listitem> + <listitem> + <para> + OpenSMTPD has been upgraded to version 6.4.0p1. This release makes + backwards-incompatible changes to the configuration file format. See + <command>man smtpd.conf</command> for more information on the new file + format. + </para> + </listitem> + <listitem> + <para> + The versioned <varname>postgresql</varname> have been renamed to use + underscore number seperators. For example, <varname>postgresql96</varname> + has been renamed to <varname>postgresql_9_6</varname>. + </para> + </listitem> + <listitem> + <para> + Package <literal>consul-ui</literal> and passthrough + <literal>consul.ui</literal> have been removed. The package + <literal>consul</literal> now uses upstream releases that vendor the UI + into the binary. See + <link xlink:href="https://github.com/NixOS/nixpkgs/pull/48714#issuecomment-433454834">#48714</link> + for details. + </para> + </listitem> + <listitem> + <para> + Slurm introduces the new option + <literal>services.slurm.stateSaveLocation</literal>, which is now set to + <literal>/var/spool/slurm</literal> by default (instead of + <literal>/var/spool</literal>). Make sure to move all files to the new + directory or to set the option accordingly. + </para> + <para> + The slurmctld now runs as user <literal>slurm</literal> instead of + <literal>root</literal>. If you want to keep slurmctld running as + <literal>root</literal>, set <literal>services.slurm.user = + root</literal>. + </para> + <para> + The options <literal>services.slurm.nodeName</literal> and + <literal>services.slurm.partitionName</literal> are now sets of strings to + correctly reflect that fact that each of these options can occour more + than once in the configuration. + </para> + </listitem> + <listitem> + <para> + The <literal>solr</literal> package has been upgraded from 4.10.3 to 7.5.0 + and has undergone some major changes. The <literal>services.solr</literal> + module has been updated to reflect these changes. Please review + http://lucene.apache.org/solr/ carefully before upgrading. + </para> + </listitem> + <listitem> + <para> + Package <literal>ckb</literal> is renamed to <literal>ckb-next</literal>, + and options <literal>hardware.ckb.*</literal> are renamed to + <literal>hardware.ckb-next.*</literal>. + </para> + </listitem> + <listitem> + <para> + The option + <literal>services.xserver.displayManager.job.logToFile</literal> which was + previously set to <literal>true</literal> when using the display managers + <literal>lightdm</literal>, <literal>sddm</literal> or + <literal>xpra</literal> has been reset to the default value + (<literal>false</literal>). + </para> + </listitem> + <listitem> + <para> + Network interface indiscriminate NixOS firewall options + (<literal>networking.firewall.allow*</literal>) are now preserved when + also setting interface specific rules such as + <literal>networking.firewall.interfaces.en0.allow*</literal>. These rules + continue to use the pseudo device "default" + (<literal>networking.firewall.interfaces.default.*</literal>), and + assigning to this pseudo device will override the + (<literal>networking.firewall.allow*</literal>) options. + </para> + </listitem> + <listitem> + <para> + The <literal>nscd</literal> service now disables all caching of + <literal>passwd</literal> and <literal>group</literal> databases by + default. This was interferring with the correct functioning of the + <literal>libnss_systemd.so</literal> module which is used by + <literal>systemd</literal> to manage uids and usernames in the presence of + <literal>DynamicUser=</literal> in systemd services. This was already the + default behaviour in presence of <literal>services.sssd.enable = + true</literal> because nscd caching would interfere with + <literal>sssd</literal> in unpredictable ways as well. Because we're using + nscd not for caching, but for convincing glibc to find NSS modules in the + nix store instead of an absolute path, we have decided to disable caching + globally now, as it's usually not the behaviour the user wants and can + lead to surprising behaviour. Furthermore, negative caching of host + lookups is also disabled now by default. This should fix the issue of dns + lookups failing in the presence of an unreliable network. + </para> + <para> + If the old behaviour is desired, this can be restored by setting the + <literal>services.nscd.config</literal> option with the desired caching + parameters. +<programlisting> + services.nscd.config = + '' + server-user nscd + threads 1 + paranoia no + debug-level 0 + + enable-cache passwd yes + positive-time-to-live passwd 600 + negative-time-to-live passwd 20 + suggested-size passwd 211 + check-files passwd yes + persistent passwd no + shared passwd yes + + enable-cache group yes + positive-time-to-live group 3600 + negative-time-to-live group 60 + suggested-size group 211 + check-files group yes + persistent group no + shared group yes + + enable-cache hosts yes + positive-time-to-live hosts 600 + negative-time-to-live hosts 5 + suggested-size hosts 211 + check-files hosts yes + persistent hosts no + shared hosts yes + ''; + </programlisting> + See + <link xlink:href="https://github.com/NixOS/nixpkgs/pull/50316">#50316</link> + for details. + </para> + </listitem> + <listitem> + <para> + GitLab Shell previously used the nix store paths for the + <literal>gitlab-shell</literal> command in its + <literal>authorized_keys</literal> file, which might stop working after + garbage collection. To circumvent that, we regenerated that file on each + startup. As <literal>gitlab-shell</literal> has now been changed to use + <literal>/var/run/current-system/sw/bin/gitlab-shell</literal>, this is + not necessary anymore, but there might be leftover lines with a nix store + path. Regenerate the <literal>authorized_keys</literal> file via + <command>sudo -u git -H gitlab-rake gitlab:shell:setup</command> in that + case. + </para> + </listitem> + <listitem> + <para> + The <literal>pam_unix</literal> account module is now loaded with its + control field set to <literal>required</literal> instead of + <literal>sufficient</literal>, so that later PAM account modules that + might do more extensive checks are being executed. Previously, the whole + account module verification was exited prematurely in case a nss module + provided the account name to <literal>pam_unix</literal>. The LDAP and + SSSD NixOS modules already add their NSS modules when enabled. In case + your setup breaks due to some later PAM account module previosuly + shadowed, or failing NSS lookups, please file a bug. You can get back the + old behaviour by manually setting <literal> +<![CDATA[security.pam.services.<name?>.text]]> + </literal>. + </para> + </listitem> + <listitem> + <para> + The <literal>pam_unix</literal> password module is now loaded with its + control field set to <literal>sufficient</literal> instead of + <literal>required</literal>, so that password managed only by later PAM + password modules are being executed. Previously, for example, changing an + LDAP account's password through PAM was not possible: the whole password + module verification was exited prematurely by <literal>pam_unix</literal>, + preventing <literal>pam_ldap</literal> to manage the password as it + should. + </para> + </listitem> + <listitem> + <para> + <literal>fish</literal> has been upgraded to 3.0. It comes with a number + of improvements and backwards incompatible changes. See the + <literal>fish</literal> + <link xlink:href="https://github.com/fish-shell/fish-shell/releases/tag/3.0.0">release + notes</link> for more information. + </para> + </listitem> + <listitem> + <para> + The ibus-table input method has had a change in config format, which + causes all previous settings to be lost. See + <link xlink:href="https://github.com/mike-fabian/ibus-table/commit/f9195f877c5212fef0dfa446acb328c45ba5852b">this + commit message</link> for details. + </para> + </listitem> + <listitem> + <para> + NixOS module system type <literal>types.optionSet</literal> and + <literal>lib.mkOption</literal> argument <literal>options</literal> are + deprecated. Use <literal>types.submodule</literal> instead. + (<link xlink:href="https://github.com/NixOS/nixpkgs/pull/54637">#54637</link>) + </para> + </listitem> + <listitem> + <para> + <literal>matrix-synapse</literal> has been updated to version 0.99. It + will <link xlink:href="https://github.com/matrix-org/synapse/pull/4509">no + longer generate a self-signed certificate on first launch</link> and will + be + <link xlink:href="https://matrix.org/blog/2019/02/05/synapse-0-99-0/">the + last version to accept self-signed certificates</link>. As such, it is now + recommended to use a proper certificate verified by a root CA (for example + Let's Encrypt). The new <link linkend="module-services-matrix">manual + chapter on Matrix</link> contains a working example of using nginx as a + reverse proxy in front of <literal>matrix-synapse</literal>, using Let's + Encrypt certificates. + </para> + </listitem> + <listitem> + <para> + <literal>mailutils</literal> now works by default when + <literal>sendmail</literal> is not in a setuid wrapper. As a consequence, + the <literal>sendmailPath</literal> argument, having lost its main use, + has been removed. + </para> + </listitem> + <listitem> + <para> + <literal>graylog</literal> has been upgraded from version 2.* to 3.*. Some + setups making use of extraConfig (especially those exposing Graylog via + reverse proxies) need to be updated as upstream removed/replaced some + settings. See + <link xlink:href="http://docs.graylog.org/en/3.0/pages/upgrade/graylog-3.0.html#simplified-http-interface-configuration">Upgrading + Graylog</link> for details. + </para> + </listitem> + <listitem> + <para> + The option <literal>users.ldap.bind.password</literal> was renamed to <literal>users.ldap.bind.passwordFile</literal>, + and needs to be readable by the <literal>nslcd</literal> user. + Same applies to the new <literal>users.ldap.daemon.rootpwmodpwFile</literal> option. + </para> + </listitem> + <listitem> + <para> + <literal>nodejs-6_x</literal> is end-of-life. + <literal>nodejs-6_x</literal>, <literal>nodejs-slim-6_x</literal> and + <literal>nodePackages_6_x</literal> are 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-19.03-notable-changes"> + <title>Other Notable Changes</title> + + <itemizedlist> + <listitem> + <para> + The <option>services.matomo</option> module gained the option + <option>services.matomo.package</option> which determines the used Matomo + version. + </para> + <para> + The Matomo module now also comes with the systemd service + <literal>matomo-archive-processing.service</literal> and a timer that + automatically triggers archive processing every hour. This means that you + can safely + <link xlink:href="https://matomo.org/docs/setup-auto-archiving/#disable-browser-triggers-for-matomo-archiving-and-limit-matomo-reports-to-updating-every-hour"> + disable browser triggers for Matomo archiving </link> at + <literal>Administration > System > General Settings</literal>. + </para> + <para> + Additionally, you can enable to + <link xlink:href="https://matomo.org/docs/privacy/#step-2-delete-old-visitors-logs"> + delete old visitor logs </link> at <literal>Administration > System > + Privacy</literal>, but make sure that you run <literal>systemctl start + matomo-archive-processing.service</literal> at least once without errors + if you have already collected data before, so that the reports get + archived before the source data gets deleted. + </para> + </listitem> + <listitem> + <para> + <literal>composableDerivation</literal> along with supporting library + functions has been removed. + </para> + </listitem> + <listitem> + <para> + The deprecated <literal>truecrypt</literal> package has been removed and + <literal>truecrypt</literal> attribute is now an alias for + <literal>veracrypt</literal>. VeraCrypt is backward-compatible with + TrueCrypt volumes. Note that <literal>cryptsetup</literal> also supports + loading TrueCrypt volumes. + </para> + </listitem> + <listitem> + <para> + The Kubernetes DNS addons, kube-dns, has been replaced with CoreDNS. This + change is made in accordance with Kubernetes making CoreDNS the official + default starting from + <link xlink:href="https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG-1.11.md#sig-cluster-lifecycle">Kubernetes + v1.11</link>. Please beware that upgrading DNS-addon on existing clusters + might induce minor downtime while the DNS-addon terminates and + re-initializes. Also note that the DNS-service now runs with 2 pod + replicas by default. The desired number of replicas can be configured + using: <option>services.kubernetes.addons.dns.replicas</option>. + </para> + </listitem> + <listitem> + <para> + The quassel-webserver package and module was removed from nixpkgs due to + the lack of maintainers. + </para> + </listitem> + <listitem> + <para> + The manual gained a <link linkend="module-services-matrix"> new chapter on + self-hosting <literal>matrix-synapse</literal> and + <literal>riot-web</literal> </link>, the most prevalent server and client + implementations for the + <link xlink:href="https://matrix.org/">Matrix</link> federated + communication network. + </para> + </listitem> + <listitem> + <para> + The astah-community package was removed from nixpkgs due to it being + discontinued and the downloads not being available anymore. + </para> + </listitem> + <listitem> + <para> + The httpd service now saves log files with a .log file extension by + default for easier integration with the logrotate service. + </para> + </listitem> + <listitem> + <para> + The owncloud server packages and httpd subservice module were removed from + nixpkgs due to the lack of maintainers. + </para> + </listitem> + <listitem> + <para> + It is possible now to uze ZRAM devices as general purpose ephemeral block + devices, not only as swap. Using more than 1 device as ZRAM swap is no + longer recommended, but is still possible by setting + <literal>zramSwap.swapDevices</literal> explicitly. + </para> + <para> + ZRAM algorithm can be changed now. + </para> + <para> + Changes to ZRAM algorithm are applied during <literal>nixos-rebuild + switch</literal>, so make sure you have enough swap space on disk to + survive ZRAM device rebuild. Alternatively, use <literal>nixos-rebuild + boot; reboot</literal>. + </para> + </listitem> + <listitem> + <para> + Flat volumes are now disabled by default in + <literal>hardware.pulseaudio</literal>. This has been done to prevent + applications, which are unaware of this feature, setting their volumes to + 100% on startup causing harm to your audio hardware and potentially your + ears. + </para> + <note> + <para> + With this change application specific volumes are relative to the master + volume which can be adjusted independently, whereas before they were + absolute; meaning that in effect, it scaled the device-volume with the + volume of the loudest application. + </para> + </note> + </listitem> + <listitem> + <para> + The + <link xlink:href="https://github.com/DanielAdolfsson/ndppd"><literal>ndppd</literal></link> + module now supports <link linkend="opt-services.ndppd.enable">all config + options</link> provided by the current upstream version as service + options. Additionally the <literal>ndppd</literal> package doesn't contain + the systemd unit configuration from upstream anymore, the unit is + completely configured by the NixOS module now. + </para> + </listitem> + <listitem> + <para> + New installs of NixOS will default to the Redmine 4.x series unless + otherwise specified in <literal>services.redmine.package</literal> while + existing installs of NixOS will default to the Redmine 3.x series. + </para> + </listitem> + <listitem> + <para> + The <link linkend="opt-services.grafana.enable">Grafana module</link> now + supports declarative + <link xlink:href="http://docs.grafana.org/administration/provisioning/">datasource + and dashboard</link> provisioning. + </para> + </listitem> + <listitem> + <para> + The use of insecure ports on kubernetes has been deprecated. Thus options: + <varname>services.kubernetes.apiserver.port</varname> and + <varname>services.kubernetes.controllerManager.port</varname> has been + renamed to <varname>.insecurePort</varname>, and default of both options + has changed to 0 (disabled). + </para> + </listitem> + <listitem> + <para> + Note that the default value of + <varname>services.kubernetes.apiserver.bindAddress</varname> has changed + from 127.0.0.1 to 0.0.0.0, allowing the apiserver to be accessible from + outside the master node itself. If the apiserver insecurePort is enabled, + it is strongly recommended to only bind on the loopback interface. See: + <varname>services.kubernetes.apiserver.insecurebindAddress</varname>. + </para> + </listitem> + <listitem> + <para> + The option + <varname>services.kubernetes.apiserver.allowPrivileged</varname> and + <varname>services.kubernetes.kubelet.allowPrivileged</varname> now + defaults to false. Disallowing privileged containers on the cluster. + </para> + </listitem> + <listitem> + <para> + The kubernetes module does no longer add the kubernetes package to + <varname>environment.systemPackages</varname> implicitly. + </para> + </listitem> + <listitem> + <para> + The <literal>intel</literal> driver has been removed from the default list + of <link linkend="opt-services.xserver.videoDrivers">X.org video + drivers</link>. The <literal>modesetting</literal> driver should take over + automatically, it is better maintained upstream and has less problems with + advanced X11 features. This can lead to a change in the output names used + by <literal>xrandr</literal>. Some performance regressions on some GPU + models might happen. Some OpenCL and VA-API applications might also break + (Beignet seems to provide OpenCL support with + <literal>modesetting</literal> driver, too). Kernel mode setting API does + not support backlight control, so <literal>xbacklight</literal> tool will + not work; backlight level can be controlled directly via + <literal>/sys/</literal> or with <literal>brightnessctl</literal>. Users + who need this functionality more than multi-output XRandR are advised to + add `intel` to `videoDrivers` and report an issue (or provide additional + details in an existing one) + </para> + </listitem> + <listitem> + <para> + Openmpi has been updated to version 4.0.0, which removes some deprecated + MPI-1 symbols. This may break some older applications that still rely on + those symbols. An upgrade guide can be found + <link xlink:href="https://www.open-mpi.org/faq/?category=mpi-removed">here</link>. + </para> + <para> + The nginx package now relies on OpenSSL 1.1 and supports TLS 1.3 by + default. You can set the protocols used by the nginx service using + <xref linkend="opt-services.nginx.sslProtocols"/>. + </para> + </listitem> + <listitem> + <para> + A new subcommand <command>nixos-rebuild edit</command> was added. + </para> + </listitem> + </itemizedlist> + </section> +</section> diff --git a/nixpkgs/nixos/doc/manual/release-notes/rl-1909.xml b/nixpkgs/nixos/doc/manual/release-notes/rl-1909.xml new file mode 100644 index 000000000000..b12858cfc963 --- /dev/null +++ b/nixpkgs/nixos/doc/manual/release-notes/rl-1909.xml @@ -0,0 +1,414 @@ +<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-19.09"> + <title>Release 19.09 (“Loris”, 2019/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-19.09-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 April 2020, handing over to 20.03. + </para> + </listitem> + <listitem> + <para> + PHP now defaults to PHP 7.3, updated from 7.2. + </para> + </listitem> + <listitem> + <para> + PHP 7.1 is no longer supported due to upstream not supporting this version for the entire lifecycle of the 19.09 release. + </para> + </listitem> + <listitem> + <para> + The binfmt module is now easier to use. Additional systems can + be added through <option>boot.binfmt.emulatedSystems</option>. + For instance, <literal>boot.binfmt.emulatedSystems = [ + "wasm32-wasi" "x86_64-windows" "aarch64-linux" ];</literal> will + set up binfmt interpreters for each of those listed systems. + </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-19.09-new-services"> + <title>New Services</title> + + <para> + The following new services were added since the last release: + </para> + + <itemizedlist> + <listitem> + <para> + <literal>./programs/dwm-status.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-19.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> + Buildbot no longer supports Python 2, as support was dropped upstream in + version 2.0.0. Configurations may need to be modified to make them + compatible with Python 3. + </para> + </listitem> + <listitem> + <para> + PostgreSQL now uses + <filename class="directory">/run/postgresql</filename> as its socket + directory instead of <filename class="directory">/tmp</filename>. So + if you run an application like eg. Nextcloud, where you need to use + the Unix socket path as the database host name, you need to change it + accordingly. + </para> + </listitem> + <listitem> + <para> + The options <option>services.prometheus.alertmanager.user</option> and + <option>services.prometheus.alertmanager.group</option> have been removed + because the alertmanager service is now using systemd's <link + xlink:href="http://0pointer.net/blog/dynamic-users-with-systemd.html"> + DynamicUser mechanism</link> which obviates these options. + </para> + </listitem> + <listitem> + <para> + The NetworkManager systemd unit was renamed back from network-manager.service to + NetworkManager.service for better compatibility with other applications expecting this name. + The same applies to ModemManager where modem-manager.service is now called ModemManager.service again. + </para> + </listitem> + <listitem> + <para> + The <option>services.nzbget.configFile</option> and <option>services.nzbget.openFirewall</option> + options were removed as they are managed internally by the nzbget. The + <option>services.nzbget.dataDir</option> option hadn't actually been used by + the module for some time and so was removed as cleanup. + </para> + </listitem> + <listitem> + <para> + The <option>services.mysql.pidDir</option> option was removed, as it was only used by the wordpress + apache-httpd service to wait for mysql to have started up. + This can be accomplished by either describing a dependency on mysql.service (preferred) + or waiting for the (hardcoded) <filename>/run/mysqld/mysql.sock</filename> file to appear. + </para> + </listitem> + <listitem> + <para> + The <option>services.emby.enable</option> module has been removed, see + <option>services.jellyfin.enable</option> instead for a free software fork of Emby. + + See the Jellyfin documentation: + <link xlink:href="https://jellyfin.readthedocs.io/en/latest/administrator-docs/migrate-from-emby/"> + Migrating from Emby to Jellyfin + </link> + </para> + </listitem> + <listitem> + <para> + IPv6 Privacy Extensions are now enabled by default for undeclared + interfaces. The previous behaviour was quite misleading — even though + the default value for + <option>networking.interfaces.*.preferTempAddress</option> was + <literal>true</literal>, undeclared interfaces would not prefer temporary + addresses. Now, interfaces not mentioned in the config will prefer + temporary addresses. EUI64 addresses can still be set as preferred by + explicitly setting the option to <literal>false</literal> for the + interface in question. + </para> + </listitem> + <listitem> + <para> + Since Bittorrent Sync was superseded by Resilio Sync in 2016, the + <literal>bittorrentSync</literal>, <literal>bittorrentSync14</literal>, + and <literal>bittorrentSync16</literal> packages have been removed in + favor of <literal>resilio-sync</literal>. + </para> + <para> + The corresponding module, <option>services.btsync</option> has been + replaced by the <option>services.resilio</option> module. + </para> + </listitem> + <listitem> + <para> + The httpd service no longer attempts to start the postgresql service. If you have come to depend + on this behaviour then you can preserve the behavior with the following configuration: + <literal>systemd.services.httpd.after = [ "postgresql.service" ];</literal> + </para> + <para> + The option <option>services.httpd.extraSubservices</option> has been + marked as deprecated. You may still use this feature, but it will be + removed in a future release of NixOS. You are encouraged to convert any + httpd subservices you may have written to a full NixOS module. + </para> + <para> + Most of the httpd subservices packaged with NixOS have been replaced with + full NixOS modules including LimeSurvey, WordPress, and Zabbix. These + modules can be enabled using the <option>services.limesurvey.enable</option>, + <option>services.mediawiki.enable</option>, <option>services.wordpress.enable</option>, + and <option>services.zabbixWeb.enable</option> options. + </para> + </listitem> + <listitem> + <para> + The option <option>systemd.network.networks.<name>.routes.*.routeConfig.GatewayOnlink</option> + was renamed to <option>systemd.network.networks.<name>.routes.*.routeConfig.GatewayOnLink</option> + (capital <literal>L</literal>). This follows + <link xlink:href="https://github.com/systemd/systemd/commit/9cb8c5593443d24c19e40bfd4fc06d672f8c554c"> + upstreams renaming + </link> of the setting. + </para> + </listitem> + <listitem> + <para> + As of this release the NixOps feature <literal>autoLuks</literal> is deprecated. It no longer works + with our systemd version without manual intervention. + </para> + <para> + Whenever the usage of the module is detected the evaluation will fail with a message + explaining why and how to deal with the situation. + </para> + <para> + A new knob named <literal>nixops.enableDeprecatedAutoLuks</literal> + has been introduced to disable the eval failure and to acknowledge the notice was received and read. + If you plan on using the feature please note that it might break with subsequent updates. + </para> + <para> + Make sure you set the <literal>_netdev</literal> option for each of the file systems referring to block + devices provided by the autoLuks module. Not doing this might render the system in a + state where it doesn't boot anymore. + </para> + <para> + If you are actively using the <literal>autoLuks</literal> module please let us know in + <link xlink:href="https://github.com/NixOS/nixpkgs/issues/62211">issue #62211</link>. + </para> + </listitem> + <listitem> + <para> + The setopt declarations will be evaluated at the end of <literal>/etc/zshrc</literal>, so any code in <xref linkend="opt-programs.zsh.interactiveShellInit" />, + <xref linkend="opt-programs.zsh.loginShellInit" /> and <xref linkend="opt-programs.zsh.promptInit" /> may break if it relies on those options being set. + </para> + </listitem> + <listitem> + <para> + The <literal>prometheus-nginx-exporter</literal> package now uses the offical exporter provided by NGINX Inc. + Its metrics are differently structured and are incompatible to the old ones. For information about the metrics, + have a look at the <link xlink:href="https://github.com/nginxinc/nginx-prometheus-exporter">official repo</link>. + </para> + </listitem> + <listitem> + <para> + Nodejs 8 is scheduled EOL under the lifetime of 19.09 and has been dropped. + </para> + </listitem> + <listitem> + <para> + By default, prometheus exporters are now run with <literal>DynamicUser</literal> enabled. + Exporters that need a real user, now run under a seperate user and group which follow the pattern <literal><exporter-name>-exporter</literal>, instead of the previous default <literal>nobody</literal> and <literal>nogroup</literal>. + Only some exporters are affected by the latter, namely the exporters <literal>dovecot</literal>, <literal>node</literal>, <literal>postfix</literal> and <literal>varnish</literal>. + </para> + </listitem> + <listitem> + <para> + The <literal>ibus-qt</literal> package is not installed by default anymore when <xref linkend="opt-i18n.inputMethod.enabled" /> is set to <literal>ibus</literal>. + If IBus support in Qt 4.x applications is required, add the <literal>ibus-qt</literal> package to your <xref linkend="opt-environment.systemPackages" /> manually. + </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-19.09-notable-changes"> + <title>Other Notable Changes</title> + + <itemizedlist> + <listitem> + <para> + The <option>documentation</option> module gained an option named + <option>documentation.nixos.includeAllModules</option> which makes the + generated <citerefentry> + <refentrytitle>configuration.nix</refentrytitle> + <manvolnum>5</manvolnum></citerefentry> manual page include all options + from all NixOS modules included in a given + <literal>configuration.nix</literal> configuration file. Currently, it is + set to <literal>false</literal> by default as enabling it frequently + prevents evaluation. But the plan is to eventually have it set to + <literal>true</literal> by default. Please set it to + <literal>true</literal> now in your <literal>configuration.nix</literal> + and fix all the bugs it uncovers. + </para> + </listitem> + <listitem> + <para> + The <literal>vlc</literal> package gained support for Chromecast + streaming, enabled by default. TCP port 8010 must be open for it to work, + so something like <literal>networking.firewall.allowedTCPPorts = [ 8010 + ];</literal> may be required in your configuration. Also consider enabling + <link xlink:href="https://nixos.wiki/wiki/Accelerated_Video_Playback"> + Accelerated Video Playback</link> for better transcoding performance. + </para> + </listitem> + <listitem> + <para> + The following changes apply if the <literal>stateVersion</literal> is + changed to 19.09 or higher. For <literal>stateVersion = "19.03"</literal> + or lower the old behavior is preserved. + </para> + <itemizedlist> + <listitem> + <para> + <literal>solr.package</literal> defaults to + <literal>pkgs.solr_8</literal>. + </para> + </listitem> + </itemizedlist> + </listitem> + <listitem> + <para> + The <literal>hunspellDicts.fr-any</literal> dictionary now ships with <literal>fr_FR.{aff,dic}</literal> + which is linked to <literal>fr-toutesvariantes.{aff,dic}</literal>. + </para> + </listitem> + <listitem> + <para> + The <literal>mysql</literal> service now runs as <literal>mysql</literal> + user. Previously, systemd did execute it as root, and mysql dropped privileges + itself. + This includes <literal>ExecStartPre=</literal> and + <literal>ExecStartPost=</literal> phases. + To accomplish that, runtime and data directory setup was delegated to + RuntimeDirectory and tmpfiles. + </para> + </listitem> + <listitem> + <para> + With the upgrade to systemd version 242 the <literal>systemd-timesyncd</literal> + service is no longer using <literal>DynamicUser=yes</literal>. In order for the + upgrade to work we rely on an activation script to move the state from the old + to the new directory. The older directory (prior <literal>19.09</literal>) was + <literal>/var/lib/private/systemd/timesync</literal>. + </para> + <para> + As long as the <literal>system.config.stateVersion</literal> is below + <literal>19.09</literal> the state folder will migrated to its proper location + (<literal>/var/lib/systemd/timesync</literal>), if required. + </para> + </listitem> + <listitem> + <para> + The package <literal>avahi</literal> is now built to look up service + definitions from <literal>/etc/avahi/services</literal> instead of its + output directory in the nix store. Accordingly the module + <option>avahi</option> now supports custom service definitions via + <option>services.avahi.extraServiceFiles</option>, which are then placed + in the aforementioned directory. See <citerefentry> + <refentrytitle>avahi.service</refentrytitle><manvolnum>5</manvolnum> + </citerefentry> for more information on custom service definitions. + </para> + </listitem> + <listitem> + <para> + Since version 0.1.19, <literal>cargo-vendor</literal> honors package + includes that are specified in the <filename>Cargo.toml</filename> + file of Rust crates. <literal>rustPlatform.buildRustPackage</literal> uses + <literal>cargo-vendor</literal> to collect and build dependent crates. + Since this change in <literal>cargo-vendor</literal> changes the set of + vendored files for most Rust packages, the hash that use used to verify + the dependencies, <literal>cargoSha256</literal>, also changes. + </para> + <para> + The <literal>cargoSha256</literal> hashes of all in-tree derivations that + use <literal>buildRustPackage</literal> have been updated to reflect this + change. However, third-party derivations that use + <literal>buildRustPackage</literal> may have to be updated as well. + </para> + </listitem> + <listitem> + <para> + The <literal>consul</literal> package was upgraded past version <literal>1.5</literal>, + so its deprecated legacy UI is no longer available. + </para> + </listitem> + <listitem> + <para> + The default resample-method for PulseAudio has been changed from the upstream default <literal>speex-float-1</literal> + to <literal>speex-float-5</literal>. Be aware that low-powered ARM-based and MIPS-based boards will struggle with this + so you'll need to set <option>hardware.pulseaudio.daemon.config.resample-method</option> back to <literal>speex-float-1</literal>. + </para> + </listitem> + <listitem> + <para> + The <literal>phabricator</literal> package and associated <literal>httpd.extraSubservice</literal>, as well as the + <literal>phd</literal> service have been removed from nixpkgs due to lack of maintainer. + </para> + </listitem> + <listitem> + <para> + The <literal>mercurial</literal> <literal>httpd.extraSubservice</literal> has been removed from nixpkgs due to lack of maintainer. + </para> + </listitem> + <listitem> + <para> + The <literal>trac</literal> <literal>httpd.extraSubservice</literal> has been removed from nixpkgs because it was unmaintained. + </para> + </listitem> + <listitem> + <para> + The <literal>foswiki</literal> package and associated <literal>httpd.extraSubservice</literal> have been removed + from nixpkgs due to lack of maintainer. + </para> + </listitem> + <listitem> + <para> + The <literal>tomcat-connector</literal> <literal>httpd.extraSubservice</literal> has been removed from nixpkgs. + </para> + </listitem> + <listitem> + <para> + It's now possible to change configuration in + <link linkend="opt-services.nextcloud.enable">services.nextcloud</link> after the initial deploy + since all config parameters are persisted in an additional config file generated by the module. + Previously core configuration like database parameters were set using their imperative + installer after creating <literal>/var/lib/nextcloud</literal>. + </para> + </listitem> + </itemizedlist> + </section> +</section> diff --git a/nixpkgs/nixos/doc/manual/shell.nix b/nixpkgs/nixos/doc/manual/shell.nix new file mode 100644 index 000000000000..cc3609d750e0 --- /dev/null +++ b/nixpkgs/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 ]; +} |