diff --git a/nixos/COPYING b/nixos/COPYING new file mode 100644 index 0000000..c9b44cb --- /dev/null +++ b/nixos/COPYING @@ -0,0 +1,18 @@ +Permission is hereby granted, free of charge, to any person obtaining +a copy of this software and associated documentation files (the +"Software"), to deal in the Software without restriction, including +without limitation the rights to use, copy, modify, merge, publish, +distribute, sublicense, and/or sell copies of the Software, and to +permit persons to whom the Software is furnished to do so, subject to +the following conditions: + +The above copyright notice and this permission notice shall be +included in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE +LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION +OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION +WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. diff --git a/nixos/README b/nixos/README new file mode 100644 index 0000000..4ecf648 --- /dev/null +++ b/nixos/README @@ -0,0 +1,5 @@ +*** NixOS *** + +NixOS is a Linux distribution based on the purely functional package +management system Nix. More information can be found at +http://nixos.org/nixos and in the manual in doc/manual. diff --git a/nixos/default.nix b/nixos/default.nix new file mode 100644 index 0000000..45da78e --- /dev/null +++ b/nixos/default.nix @@ -0,0 +1,38 @@ +{ configuration ? import ./lib/from-env.nix "NIXOS_CONFIG" +, system ? builtins.currentSystem +}: + +let + + eval = import ./lib/eval-config.nix { + inherit system; + modules = [ configuration ]; + }; + + # This is for `nixos-rebuild build-vm'. + vmConfig = (import ./lib/eval-config.nix { + inherit system; + modules = [ configuration ./modules/virtualisation/qemu-vm.nix ]; + }).config; + + # This is for `nixos-rebuild build-vm-with-bootloader'. + vmWithBootLoaderConfig = (import ./lib/eval-config.nix { + inherit system; + modules = + [ configuration + ./modules/virtualisation/qemu-vm.nix + { virtualisation.useBootLoader = true; } + ]; + }).config; + +in + +{ + inherit (eval) pkgs config options; + + system = eval.config.system.build.toplevel; + + vm = vmConfig.system.build.vm; + + vmWithBootLoader = vmWithBootLoaderConfig.system.build.vm; +} diff --git a/nixos/doc/manual/.gitignore b/nixos/doc/manual/.gitignore new file mode 100644 index 0000000..8792826 --- /dev/null +++ b/nixos/doc/manual/.gitignore @@ -0,0 +1,2 @@ +generated +manual-combined.xml diff --git a/nixos/doc/manual/Makefile b/nixos/doc/manual/Makefile new file mode 100644 index 0000000..b251a1f --- /dev/null +++ b/nixos/doc/manual/Makefile @@ -0,0 +1,29 @@ +.PHONY: all +all: manual-combined.xml format + +.PHONY: debug +debug: generated manual-combined.xml + +manual-combined.xml: generated *.xml **/*.xml + rm -f ./manual-combined.xml + nix-shell --packages xmloscopy \ + --run "xmloscopy --docbook5 ./manual.xml ./manual-combined.xml" + +.PHONY: format +format: + find ../../ -iname '*.xml' -type f -print0 | xargs -0 -I{} -n1 \ + xmlformat --config-file "../xmlformat.conf" -i {} + +.PHONY: fix-misc-xml +fix-misc-xml: + find . -iname '*.xml' -type f \ + -exec ../varlistentry-fixer.rb {} ';' + +.PHONY: clean +clean: + rm -f manual-combined.xml generated + +generated: ./options-to-docbook.xsl + nix-build ../../release.nix \ + --attr manualGeneratedSources.x86_64-linux \ + --out-link ./generated diff --git a/nixos/doc/manual/README b/nixos/doc/manual/README new file mode 100644 index 0000000..587f627 --- /dev/null +++ b/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/nixos/doc/manual/administration/boot-problems.xml b/nixos/doc/manual/administration/boot-problems.xml new file mode 100644 index 0000000..de3d8ac --- /dev/null +++ b/nixos/doc/manual/administration/boot-problems.xml @@ -0,0 +1,90 @@ +
+ Boot Problems + + + 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 linux. The following + are some useful kernel command line parameters that are recognised by the + NixOS boot scripts or by systemd: + + + + boot.shell_on_fail + + + + 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. + + + + + + boot.debug1 + + + + 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 /proc and + /sys. + + + + + + boot.trace + + + + Print every shell command executed by the stage 1 and 2 boot scripts. + + + + + + single + + + + Boot into rescue mode (a.k.a. single user mode). This will cause systemd + to start nothing but the unit rescue.target, which + runs sulogin 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. + + + + + + systemd.log_level=debug systemd.log_target=console + + + + Make systemd very verbose and send log messages to the console instead of + the journal. + + + + + For more parameters recognised by systemd, see + systemd + 1. + + + + 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 + agetty login prompts should appear eventually unless + something is very wrong.) + +
diff --git a/nixos/doc/manual/administration/cleaning-store.xml b/nixos/doc/manual/administration/cleaning-store.xml new file mode 100644 index 0000000..f078b8c --- /dev/null +++ b/nixos/doc/manual/administration/cleaning-store.xml @@ -0,0 +1,63 @@ + + Cleaning the Nix Store + + 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 (/nix/store). You should periodically run + Nix’s garbage collector to remove old, unreferenced + packages. This is easy: + +$ nix-collect-garbage + + Alternatively, you can use a systemd unit that does the same in the + background: + +# systemctl start nix-gc.service + + You can tell NixOS in configuration.nix to run this unit + automatically at certain points in time, for instance, every night at 03:15: + + = true; + = "03:15"; + + + + 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: + +$ nix-collect-garbage -d + + You can also do this for specific profiles, e.g. + +$ nix-env -p /nix/var/nix/profiles/per-user/eelco/profile --delete-generations old + + Note that NixOS system configurations are stored in the profile + /nix/var/nix/profiles/system. + + + 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. + +$ nix-store --optimise + + Since this command needs to read the entire Nix store, it can take quite a + while to finish. + +
+ NixOS Boot Entries + + + If your /boot partition runs out of space, after + clearing old profiles you must rebuild your system with + nixos-rebuild to update the /boot + partition and clear space. + +
+ diff --git a/nixos/doc/manual/administration/container-networking.xml b/nixos/doc/manual/administration/container-networking.xml new file mode 100644 index 0000000..2ee8bfd --- /dev/null +++ b/nixos/doc/manual/administration/container-networking.xml @@ -0,0 +1,59 @@ +
+ Container Networking + + + When you create a container using nixos-container create, + it gets it own private IPv4 address in the range + 10.233.0.0/16. You can get the container’s IPv4 address + as follows: + +# nixos-container show-ip foo +10.233.4.2 + +$ ping -c1 10.233.4.2 +64 bytes from 10.233.4.2: icmp_seq=1 ttl=64 time=0.106 ms + + + + + Networking is implemented using a pair of virtual Ethernet devices. The + network interface in the container is called eth0, while + the matching interface in the host is called + ve-container-name (e.g., + ve-foo). The container has its own network namespace and + the CAP_NET_ADMIN capability, so it can perform arbitrary + network configuration such as setting up firewall rules, without affecting or + having access to the host’s network. + + + + 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: + + = true; + = ["ve-+"]; + = "eth0"; + + where eth0 should be replaced with the desired external + interface. Note that ve-+ is a wildcard that matches all + container interfaces. + + + + If you are using Network Manager, you need to explicitly prevent it from + managing container interfaces: + +networking.networkmanager.unmanaged = [ "interface-name:ve-*" ]; + + + + + You may need to restart your system for the changes to take effect. + +
diff --git a/nixos/doc/manual/administration/containers.xml b/nixos/doc/manual/administration/containers.xml new file mode 100644 index 0000000..0d3355e --- /dev/null +++ b/nixos/doc/manual/administration/containers.xml @@ -0,0 +1,34 @@ + + Container Management + + NixOS allows you to easily run other NixOS instances as + containers. Containers are a light-weight approach to + virtualisation that runs software in the container at the same speed as in + the host system. NixOS containers share the Nix store of the host, making + container creation very efficient. + + + + Currently, NixOS containers are not perfectly isolated from the host system. + This means that a user with root access to the container can do things that + affect the host. So you should not give container root access to untrusted + users. + + + + NixOS containers can be created in two ways: imperatively, using the command + nixos-container, and declaratively, by specifying them in + your configuration.nix. The declarative approach implies + that containers get upgraded along with your host system when you run + nixos-rebuild, which is often not what you want. By + contrast, in the imperative approach, containers are configured and updated + independently from the host system. + + + + + diff --git a/nixos/doc/manual/administration/control-groups.xml b/nixos/doc/manual/administration/control-groups.xml new file mode 100644 index 0000000..bb8b7f8 --- /dev/null +++ b/nixos/doc/manual/administration/control-groups.xml @@ -0,0 +1,65 @@ + + Control Groups + + To keep track of the processes in a running system, systemd uses + control groups (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. + + + The command systemd-cgls lists all control groups in the + systemd hierarchy, which is what systemd uses to keep + track of the processes belonging to each service or user session: + +$ systemd-cgls +├─user +│ └─eelco +│ └─c1 +│ ├─ 2567 -:0 +│ ├─ 2682 kdeinit4: kdeinit4 Running... +│ ├─ ... +│ └─10851 sh -c less -R +└─system + ├─httpd.service + │ ├─2444 httpd -f /nix/store/3pyacby5cpr55a03qwbnndizpciwq161-httpd.conf -DNO_DETACH + │ └─... + ├─dhcpcd.service + │ └─2376 dhcpcd --config /nix/store/f8dif8dsi2yaa70n03xir8r653776ka6-dhcpcd.conf + └─ ... + + Similarly, systemd-cgls cpu 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 httpd.service cgroup cannot + starve the CPU for one process in the postgresql.service + 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 configuration.nix: + +systemd.services.httpd.serviceConfig.CPUShares = 512; + + By default, every cgroup has 1024 CPU shares, so this will halve the CPU + allocation of the httpd.service cgroup. + + + There also is a memory 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 configuration.nix; for + instance, to limit httpd.service to 512 MiB of RAM + (excluding swap): + +systemd.services.httpd.serviceConfig.MemoryLimit = "512M"; + + + + The command systemd-cgtop shows a continuously updated + list of all cgroups with their CPU and memory usage. + + diff --git a/nixos/doc/manual/administration/declarative-containers.xml b/nixos/doc/manual/administration/declarative-containers.xml new file mode 100644 index 0000000..d03dbc4 --- /dev/null +++ b/nixos/doc/manual/administration/declarative-containers.xml @@ -0,0 +1,60 @@ +
+ Declarative Container Specification + + + You can also specify containers and their configuration in the host’s + configuration.nix. For example, the following specifies + that there shall be a container named database running + PostgreSQL: + +containers.database = + { config = + { config, pkgs, ... }: + { = true; + = pkgs.postgresql_9_6; + }; + }; + + If you run nixos-rebuild switch, 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 containers.database.autoStart = true in its + configuration. + + + + 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: + +containers.database = { + privateNetwork = true; + hostAddress = "192.168.100.10"; + localAddress = "192.168.100.11"; +}; + + This gives the container a private virtual Ethernet interface with IP address + 192.168.100.11, which is hooked up to a virtual Ethernet + interface on the host with IP address 192.168.100.10. (See + the next section for details on container networking.) + + + + To disable the container, just remove it from + configuration.nix and run nixos-rebuild + switch. Note that this will not delete the root directory of the + container in /var/lib/containers. Containers can be + destroyed using the imperative method: nixos-container destroy + foo. + + + + Declarative containers can be started and stopped using the corresponding + systemd service, e.g. systemctl start container@database. + +
diff --git a/nixos/doc/manual/administration/imperative-containers.xml b/nixos/doc/manual/administration/imperative-containers.xml new file mode 100644 index 0000000..9bb62bc --- /dev/null +++ b/nixos/doc/manual/administration/imperative-containers.xml @@ -0,0 +1,116 @@ +
+ Imperative Container Management + + + We’ll cover imperative container management using + nixos-container first. Be aware that container management + is currently only possible as root. + + + + You create a container with identifier foo as follows: + +# nixos-container create foo + + This creates the container’s root directory in + /var/lib/containers/foo and a small configuration file + in /etc/containers/foo.conf. It also builds the + container’s initial system configuration and stores it in + /nix/var/nix/profiles/per-container/foo/system. You can + modify the initial configuration of the container on the command line. For + instance, to create a container that has sshd running, + with the given public key for root: + +# nixos-container create foo --config ' + = true; + users.users.root.openssh.authorizedKeys.keys = ["ssh-dss AAAAB3N…"]; +' + + + + + Creating a container does not start it. To start the container, run: + +# nixos-container start foo + + This command will return as soon as the container has booted and has reached + multi-user.target. On the host, the container runs within + a systemd unit called + container@container-name.service. + Thus, if something went wrong, you can get status info using + systemctl: + +# systemctl status container@foo + + + + + If the container has started successfully, you can log in as root using the + root-login operation: + +# nixos-container root-login foo +[root@foo:~]# + + 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 + login operation, which is available to all users on the + host: + +# nixos-container login foo +foo login: alice +Password: *** + + With nixos-container run, you can execute arbitrary + commands in the container: + +# 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 + + + + + There are several ways to change the configuration of the container. First, + on the host, you can edit + /var/lib/container/name/etc/nixos/configuration.nix, + and run + +# nixos-container update foo + + This will build and activate the new configuration. You can also specify a + new configuration on the command line: + +# nixos-container update foo --config ' + = true; + = "foo@example.org"; + = [ 80 ]; +' + +# curl http://$(nixos-container show-ip foo)/ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">… + + However, note that this will overwrite the container’s + /etc/nixos/configuration.nix. + + + + Alternatively, you can change the configuration from within the container + itself by running nixos-rebuild switch inside the + container. Note that the container by default does not have a copy of the + NixOS channel, so you should run nix-channel --update + first. + + + + Containers can be stopped and started using nixos-container + stop and nixos-container start, respectively, or + by using systemctl on the container’s service unit. To + destroy a container, including its file system, do + +# nixos-container destroy foo + + +
diff --git a/nixos/doc/manual/administration/logging.xml b/nixos/doc/manual/administration/logging.xml new file mode 100644 index 0000000..a41936b --- /dev/null +++ b/nixos/doc/manual/administration/logging.xml @@ -0,0 +1,43 @@ + + Logging + + System-wide logging is provided by systemd’s journal, + which subsumes traditional logging daemons such as syslogd and klogd. Log + entries are kept in binary files in /var/log/journal/. + The command journalctl allows you to see the contents of + the journal. For example, + +$ journalctl -b + + shows all journal entries since the last reboot. (The output of + journalctl is piped into less 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: + +$ 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 + + Or to get all messages since the last reboot that have at least a + “critical” severity level: + +$ 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) + + + + The system journal is readable by root and by users in the + wheel and systemd-journal groups. All + users have a private journal that can be read using + journalctl. + + diff --git a/nixos/doc/manual/administration/maintenance-mode.xml b/nixos/doc/manual/administration/maintenance-mode.xml new file mode 100644 index 0000000..71e3f9e --- /dev/null +++ b/nixos/doc/manual/administration/maintenance-mode.xml @@ -0,0 +1,16 @@ +
+ Maintenance Mode + + + You can enter rescue mode by running: + +# systemctl rescue + 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. + +
diff --git a/nixos/doc/manual/administration/network-problems.xml b/nixos/doc/manual/administration/network-problems.xml new file mode 100644 index 0000000..570f583 --- /dev/null +++ b/nixos/doc/manual/administration/network-problems.xml @@ -0,0 +1,27 @@ +
+ Network Problems + + + Nix uses a so-called binary cache to optimise building a + package from source into downloading it as a pre-built binary. That is, + whenever a command like nixos-rebuild 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 + https://cache.nixos.org/. 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 , e.g. + +# nixos-rebuild switch --option use-binary-caches false + + If you have an alternative binary cache at your disposal, you can use it + instead: + +# nixos-rebuild switch --option binary-caches http://my-cache.example.org/ + + +
diff --git a/nixos/doc/manual/administration/rebooting.xml b/nixos/doc/manual/administration/rebooting.xml new file mode 100644 index 0000000..a5abd6f --- /dev/null +++ b/nixos/doc/manual/administration/rebooting.xml @@ -0,0 +1,35 @@ + + Rebooting and Shutting Down + + The system can be shut down (and automatically powered off) by doing: + +# shutdown + + This is equivalent to running systemctl poweroff. + + + To reboot the system, run + +# reboot + + which is equivalent to systemctl reboot. Alternatively, + you can quickly reboot the system using kexec, which + bypasses the BIOS by directly loading the new kernel into memory: + +# systemctl kexec + + + + The machine can be suspended to RAM (if supported) using systemctl + suspend, and suspended to disk using systemctl + hibernate. + + + 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. + + diff --git a/nixos/doc/manual/administration/rollback.xml b/nixos/doc/manual/administration/rollback.xml new file mode 100644 index 0000000..07c6aca --- /dev/null +++ b/nixos/doc/manual/administration/rollback.xml @@ -0,0 +1,41 @@ +
+ Rolling Back Configuration Changes + + + After running nixos-rebuild 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. + + + + 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: + +# /run/current-system/bin/switch-to-configuration boot + + + + Second, you can switch to the previous configuration in a running system: + +# nixos-rebuild switch --rollback + This is equivalent to running: + +# /nix/var/nix/profiles/system-N-link/bin/switch-to-configuration switch + where N is the number of the NixOS system + configuration. To get a list of the available configurations, do: + +$ ls -l /nix/var/nix/profiles/system-*-link +... +lrwxrwxrwx 1 root root 78 Aug 12 13:54 /nix/var/nix/profiles/system-268-link -> /nix/store/202b...-nixos-13.07pre4932_5a676e4-4be1055 + + +
diff --git a/nixos/doc/manual/administration/running.xml b/nixos/doc/manual/administration/running.xml new file mode 100644 index 0000000..786dd5e --- /dev/null +++ b/nixos/doc/manual/administration/running.xml @@ -0,0 +1,21 @@ + + Administration + + + This chapter describes various aspects of managing a running NixOS system, + such as how to use the systemd service manager. + + + + + + + + + + + diff --git a/nixos/doc/manual/administration/service-mgmt.xml b/nixos/doc/manual/administration/service-mgmt.xml new file mode 100644 index 0000000..0c2085c --- /dev/null +++ b/nixos/doc/manual/administration/service-mgmt.xml @@ -0,0 +1,72 @@ + + Service Management + + 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 default.target; 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. + + + The command systemctl is the main way to interact with + systemd. Without any arguments, it shows the status of + active units: + +$ 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 +... + + + + You can ask for detailed status information about a unit, for instance, the + PostgreSQL database service: + +$ 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. + + 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. + + + Units can be stopped, started or restarted: + +# systemctl stop postgresql.service +# systemctl start postgresql.service +# systemctl restart postgresql.service + + 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). + + + diff --git a/nixos/doc/manual/administration/store-corruption.xml b/nixos/doc/manual/administration/store-corruption.xml new file mode 100644 index 0000000..a4ca3b6 --- /dev/null +++ b/nixos/doc/manual/administration/store-corruption.xml @@ -0,0 +1,36 @@ +
+ Nix Store Corruption + + + 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 sync 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. + + + + If the corruption is in a path in the closure of the NixOS system + configuration, you can fix it by doing + +# nixos-rebuild switch --repair + + 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. + + + + You can also scan the entire Nix store for corrupt paths: + +# nix-store --verify --check-contents --repair + + Any corrupt paths will be redownloaded if they’re available in a binary + cache; otherwise, they cannot be repaired. + +
diff --git a/nixos/doc/manual/administration/troubleshooting.xml b/nixos/doc/manual/administration/troubleshooting.xml new file mode 100644 index 0000000..6496e7b --- /dev/null +++ b/nixos/doc/manual/administration/troubleshooting.xml @@ -0,0 +1,16 @@ + + Troubleshooting + + This chapter describes solutions to common problems you might encounter when + you manage your NixOS system. + + + + + + + diff --git a/nixos/doc/manual/administration/user-sessions.xml b/nixos/doc/manual/administration/user-sessions.xml new file mode 100644 index 0000000..1d95cfb --- /dev/null +++ b/nixos/doc/manual/administration/user-sessions.xml @@ -0,0 +1,45 @@ + + User Sessions + + Systemd keeps track of all users who are logged into the system (e.g. on a + virtual console or remotely via SSH). The command loginctl + allows querying and manipulating user sessions. For instance, to list all + user sessions: + +$ loginctl + SESSION UID USER SEAT + c1 500 eelco seat0 + c3 0 root seat0 + c4 500 alice + + 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: + +$ 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 + + 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: + +# loginctl terminate-session c3 + + + diff --git a/nixos/doc/manual/configuration/abstractions.xml b/nixos/doc/manual/configuration/abstractions.xml new file mode 100644 index 0000000..5bf0635 --- /dev/null +++ b/nixos/doc/manual/configuration/abstractions.xml @@ -0,0 +1,156 @@ +
+ Abstractions + + + If you find yourself repeating yourself over and over, it’s time to + abstract. Take, for instance, this Apache HTTP Server configuration: + +{ + = + [ { 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"; + } + ]; +} + + 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 let: + +let + exampleOrgCommon = + { hostName = "example.org"; + documentRoot = "/webroot"; + adminAddr = "alice@example.org"; + enableUserDir = true; + }; +in +{ + = + [ exampleOrgCommon + (exampleOrgCommon // { + enableSSL = true; + sslServerCert = "/root/ssl-example-org.crt"; + sslServerKey = "/root/ssl-example-org.key"; + }) + ]; +} + + The let exampleOrgCommon = ... + defines a variable named exampleOrgCommon. The + // operator merges two attribute sets, so the + configuration of the second virtual host is the set + exampleOrgCommon extended with the SSL options. + + + + You can write a let wherever an expression is allowed. + Thus, you also could have written: + +{ + = + let exampleOrgCommon = ...; in + [ exampleOrgCommon + (exampleOrgCommon // { ... }) + ]; +} + + but not { let exampleOrgCommon = ...; in + ...; } since attributes (as opposed to + attribute values) are not expressions. + + + + Functions 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: + +{ + = + let + makeVirtualHost = name: + { hostName = name; + documentRoot = "/webroot"; + adminAddr = "alice@example.org"; + }; + in + [ (makeVirtualHost "example.org") + (makeVirtualHost "example.com") + (makeVirtualHost "example.gov") + (makeVirtualHost "example.nl") + ]; +} + + Here, makeVirtualHost is a function that takes a single + argument name and returns the configuration for a virtual + host. That function is then called for several names to produce the list of + virtual host configurations. + + + + We can further improve on this by using the function map, + which applies another function to every element in a list: + +{ + = + let + makeVirtualHost = ...; + in map makeVirtualHost + [ "example.org" "example.com" "example.gov" "example.nl" ]; +} + + (The function map is called a higher-order + function because it takes another function as an argument.) + + + + What if you need more than one argument, for instance, if we want to use a + different documentRoot for each virtual host? Then we can + make makeVirtualHost a function that takes a + set as its argument, like this: + +{ + = + 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"; } + ]; +} + + But in this case (where every root is a subdirectory of + /sites named after the virtual host), it would have been + shorter to define makeVirtualHost as + +makeVirtualHost = name: + { hostName = name; + documentRoot = "/sites/${name}"; + adminAddr = "alice@example.org"; + }; + + Here, the construct ${...} + allows the result of an expression to be spliced into a string. + +
diff --git a/nixos/doc/manual/configuration/ad-hoc-network-config.xml b/nixos/doc/manual/configuration/ad-hoc-network-config.xml new file mode 100644 index 0000000..00e595c --- /dev/null +++ b/nixos/doc/manual/configuration/ad-hoc-network-config.xml @@ -0,0 +1,20 @@ +
+ Ad-Hoc Configuration + + + You can use to specify shell + commands to be run at the end of network-setup.service. + This is useful for doing network configuration not covered by the existing + NixOS modules. For instance, to statically configure an IPv6 address: + + = + '' + ip -6 addr add 2001:610:685:1::1/64 dev eth0 + ''; + + +
diff --git a/nixos/doc/manual/configuration/ad-hoc-packages.xml b/nixos/doc/manual/configuration/ad-hoc-packages.xml new file mode 100644 index 0000000..19159d8 --- /dev/null +++ b/nixos/doc/manual/configuration/ad-hoc-packages.xml @@ -0,0 +1,61 @@ +
+ Ad-Hoc Package Management + + + With the command nix-env, you can install and uninstall + packages from the command line. For instance, to install Mozilla Thunderbird: + +$ nix-env -iA nixos.thunderbird + If you invoke this as root, the package is installed in the Nix profile + /nix/var/nix/profiles/default and visible to all users + of the system; otherwise, the package ends up in + /nix/var/nix/profiles/per-user/username/profile + and is not visible to other users. The flag specifies the + package by its attribute name; without it, the package is installed by + matching against its package name (e.g. thunderbird). The + latter is slower because it requires matching against all available Nix + packages, and is ambiguous if there are multiple matching packages. + + + + Packages come from the NixOS channel. You typically upgrade a package by + updating to the latest version of the NixOS channel: + +$ nix-channel --update nixos + + and then running nix-env -i again. Other packages in the + profile are not affected; this is the crucial difference + with the declarative style of package management, where running + nixos-rebuild switch 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: + +$ nix-env -u '*' + + + + + A package can be uninstalled using the flag: + +$ nix-env -e thunderbird + + + + + Finally, you can roll back an undesirable nix-env action: + +$ nix-env --rollback + + + + + nix-env has many more flags. For details, see the + + nix-env + 1 manpage or the Nix manual. + +
diff --git a/nixos/doc/manual/configuration/adding-custom-packages.xml b/nixos/doc/manual/configuration/adding-custom-packages.xml new file mode 100644 index 0000000..cdcfa10 --- /dev/null +++ b/nixos/doc/manual/configuration/adding-custom-packages.xml @@ -0,0 +1,73 @@ +
+ Adding Custom Packages + + + 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 Nixpkgs + manual. In short, you clone Nixpkgs: + +$ git clone https://github.com/NixOS/nixpkgs +$ cd nixpkgs + + Then you write and test the package as described in the Nixpkgs manual. + Finally, you add it to environment.systemPackages, e.g. + + = [ pkgs.my-package ]; + + and you run nixos-rebuild, specifying your own Nixpkgs + tree: + +# nixos-rebuild switch -I nixpkgs=/path/to/my/nixpkgs + + + + The second possibility is to add the package outside of the Nixpkgs tree. For + instance, here is how you specify a build of the + GNU Hello + package directly in configuration.nix: + + = + 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 ]; + + Of course, you can also move the definition of my-hello + into a separate Nix expression, e.g. + + = [ (import ./my-hello.nix) ]; + + where my-hello.nix contains: + +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"; + }; +} + + This allows testing the package easily: + +$ nix-build my-hello.nix +$ ./result/bin/hello +Hello, world! + + +
diff --git a/nixos/doc/manual/configuration/config-file.xml b/nixos/doc/manual/configuration/config-file.xml new file mode 100644 index 0000000..c77cfe1 --- /dev/null +++ b/nixos/doc/manual/configuration/config-file.xml @@ -0,0 +1,210 @@ +
+ NixOS Configuration File + + + The NixOS configuration file generally looks like this: + +{ config, pkgs, ... }: + +{ option definitions +} + + The first line ({ config, pkgs, ... }:) denotes that this + is actually a function that takes at least the two arguments + config and pkgs. (These are explained + later.) The function returns a set of option definitions + ({ ... }). These definitions + have the form name = + value, where + name is the name of an option and + value is its value. For example, + +{ config, pkgs, ... }: + +{ = true; + = "alice@example.org"; + = "/webroot"; +} + + defines a configuration with three option definitions that together enable + the Apache HTTP Server with /webroot as the document + root. + + + + Sets can be nested, and in fact dots in option names are shorthand for + defining a set containing another set. For instance, + defines a set named + services that contains a set named + httpd, which in turn contains an option definition named + enable with value true. This means that + the example above can also be written as: + +{ config, pkgs, ... }: + +{ services = { + httpd = { + enable = true; + adminAddr = "alice@example.org"; + documentRoot = "/webroot"; + }; + }; +} + + which may be more convenient if you have lots of option definitions that + share the same prefix (such as services.httpd). + + + + 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 option declaration), + nixos-rebuild will give an error like: + +The option `services.httpd.enable' defined in `/etc/nixos/configuration.nix' does not exist. + + Likewise, values in option definitions must have a correct type. For + instance, must be a Boolean + (true or false). Trying to give it a + value of another type, such as a string, will cause an error: + +The option value `services.httpd.enable' in `/etc/nixos/configuration.nix' is not a boolean. + + + + + Options have various types of values. The most important are: + + + + Strings + + + + Strings are enclosed in double quotes, e.g. + + = "dexter"; + + Special characters can be escaped by prefixing them with a backslash + (e.g. \"). + + + Multi-line strings can be enclosed in double single + quotes, e.g. + + = + '' + 127.0.0.2 other-localhost + 10.0.0.1 server + ''; + + 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 + " and \ are not special (making it + more convenient for including things like shell code). See more info + about this in the Nix manual + here. + + + + + + Booleans + + + + These can be true or false, e.g. + + = true; + = false; + + + + + + + Integers + + + + For example, + +."net.ipv4.tcp_keepalive_time" = 60; + + (Note that here the attribute name + net.ipv4.tcp_keepalive_time is enclosed in quotes to + prevent it from being interpreted as a set named net + containing a set named ipv4, and so on. This is + because it’s not a NixOS option but the literal name of a Linux kernel + setting.) + + + + + + Sets + + + + Sets were introduced above. They are name/value pairs enclosed in braces, + as in the option definition + +."/boot" = + { device = "/dev/sda1"; + fsType = "ext4"; + options = [ "rw" "data=ordered" "relatime" ]; + }; + + + + + + + Lists + + + + The important thing to note about lists is that list elements are + separated by whitespace, like this: + + = [ "fuse" "kvm-intel" "coretemp" ]; + + List elements can be any other type, e.g. sets: + +swapDevices = [ { device = "/dev/disk/by-label/swap"; } ]; + + + + + + + Packages + + + + 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 pkgs. Typical uses: + + = + [ pkgs.thunderbird + pkgs.emacs + ]; + + = pkgs.postgresql_10; + + 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 . + + + + + +
diff --git a/nixos/doc/manual/configuration/config-syntax.xml b/nixos/doc/manual/configuration/config-syntax.xml new file mode 100644 index 0000000..5ef498c --- /dev/null +++ b/nixos/doc/manual/configuration/config-syntax.xml @@ -0,0 +1,25 @@ + + Configuration Syntax + + The NixOS configuration file + /etc/nixos/configuration.nix is actually a Nix + expression, which is the Nix package manager’s purely functional + language for describing how to build packages and configurations. This means + you have all the expressive power of that language at your disposal, + including the ability to abstract over common patterns, which is very useful + when managing complex systems. The syntax and semantics of the Nix language + are fully described in the + Nix + manual, but here we give a short overview of the most important + constructs useful in NixOS configuration files. + + + + + + diff --git a/nixos/doc/manual/configuration/configuration.xml b/nixos/doc/manual/configuration/configuration.xml new file mode 100644 index 0000000..cebc412 --- /dev/null +++ b/nixos/doc/manual/configuration/configuration.xml @@ -0,0 +1,27 @@ + + Configuration + + + This chapter describes how to configure various aspects of a NixOS machine + through the configuration file + /etc/nixos/configuration.nix. As described in + , changes to this file only take + effect after you run nixos-rebuild. + + + + + + + + + + + + + + diff --git a/nixos/doc/manual/configuration/customizing-packages.xml b/nixos/doc/manual/configuration/customizing-packages.xml new file mode 100644 index 0000000..03b5bb5 --- /dev/null +++ b/nixos/doc/manual/configuration/customizing-packages.xml @@ -0,0 +1,86 @@ +
+ Customising Packages + + + 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 configuration.nix as follows: + nixpkgs.config.firefox.enableGoogleTalkPlugin = true; + + + + + Unfortunately, Nixpkgs currently lacks a way to query available + configuration options. + + + + + 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: + + = [ (pkgs.emacs.override { gtk = pkgs.gtk3; }) ]; + + The function override 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 + gtk gets the value pkgs.gtk3, 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, would be a list with + two elements.) + + + + Even greater customisation is possible using the function + overrideAttrs. While the override + mechanism above overrides the arguments of a package function, + overrideAttrs allows changing the + attributes passed to mkDerivation. + 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: + + = [ + (pkgs.emacs.overrideAttrs (oldAttrs: { + name = "emacs-25.0-pre"; + src = /path/to/my/emacs/tree; + })) +]; + + Here, overrideAttrs takes the Nix derivation specified by + pkgs.emacs and produces a new derivation in which the + original’s name and src attribute + have been replaced by the given values by re-calling + stdenv.mkDerivation. The original attributes are + accessible via the function argument, which is conventionally named + oldAttrs. + + + + 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 global override as follows: + +nixpkgs.config.packageOverrides = pkgs: + { emacs = pkgs.emacs.override { gtk = pkgs.gtk3; }; + }; + + The effect of this definition is essentially equivalent to modifying the + emacs attribute in the Nixpkgs source tree. Any package in + Nixpkgs that depends on emacs will be passed your + customised instance. (However, the value pkgs.emacs in + nixpkgs.config.packageOverrides refers to the original + rather than overridden instance, to prevent an infinite recursion.) + +
diff --git a/nixos/doc/manual/configuration/declarative-packages.xml b/nixos/doc/manual/configuration/declarative-packages.xml new file mode 100644 index 0000000..be9884f --- /dev/null +++ b/nixos/doc/manual/configuration/declarative-packages.xml @@ -0,0 +1,43 @@ +
+ Declarative Package Management + + + With declarative package management, you specify which packages you want on + your system by setting the option + . For instance, adding the + following line to configuration.nix enables the Mozilla + Thunderbird email application: + + = [ pkgs.thunderbird ]; + + The effect of this specification is that the Thunderbird package from Nixpkgs + will be built or downloaded as part of the system when you run + nixos-rebuild switch. + + + + You can get a list of the available packages as follows: + +$ nix-env -qaP '*' --description +nixos.firefox firefox-23.0 Mozilla Firefox - the browser, reloaded +... + + The first column in the output is the attribute name, + such as nixos.thunderbird. (The nixos + prefix allows distinguishing between different channels that you might have.) + + + + To “uninstall” a package, simply remove it from + and run + nixos-rebuild switch. + + + + + +
diff --git a/nixos/doc/manual/configuration/file-systems.xml b/nixos/doc/manual/configuration/file-systems.xml new file mode 100644 index 0000000..e4c03de --- /dev/null +++ b/nixos/doc/manual/configuration/file-systems.xml @@ -0,0 +1,46 @@ + + File Systems + + You can define file systems using the + configuration option. For instance, the following definition causes NixOS to + mount the Ext4 file system on device + /dev/disk/by-label/data onto the mount point + /data: + +."/data" = + { device = "/dev/disk/by-label/data"; + fsType = "ext4"; + }; + + Mount points are created automatically if they don’t already exist. For + , + it’s best to use the topology-independent device aliases in + /dev/disk/by-label and + /dev/disk/by-uuid, as these don’t change if the + topology changes (e.g. if a disk is moved to another IDE controller). + + + You can usually omit the file system type + (), + since mount can usually detect the type and load the + necessary kernel module automatically. However, if the file system is needed + at early boot (in the initial ramdisk) and is not ext2, + ext3 or ext4, then it’s best to + specify to ensure that the kernel module is + available. + + + + System startup will fail if any of the filesystems fails to mount, dropping + you to the emergency shell. You can make a mount asynchronous and + non-critical by adding + options = [ + "nofail" ];. + + + + diff --git a/nixos/doc/manual/configuration/firewall.xml b/nixos/doc/manual/configuration/firewall.xml new file mode 100644 index 0000000..47a19ac --- /dev/null +++ b/nixos/doc/manual/configuration/firewall.xml @@ -0,0 +1,37 @@ +
+ Firewall + + + 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: + + = false; + + If the firewall is enabled, you can open specific TCP ports to the outside + world: + + = [ 80 443 ]; + + Note that TCP port 22 (ssh) is opened automatically if the SSH daemon is + enabled (). UDP ports can be opened through + . + + + + To open ranges of TCP ports: + + = [ + { from = 4000; to = 4007; } + { from = 8000; to = 8010; } +]; + + Similarly, UDP port ranges can be opened through + . + +
diff --git a/nixos/doc/manual/configuration/ipv4-config.xml b/nixos/doc/manual/configuration/ipv4-config.xml new file mode 100644 index 0000000..71ddf41 --- /dev/null +++ b/nixos/doc/manual/configuration/ipv4-config.xml @@ -0,0 +1,43 @@ +
+ IPv4 Configuration + + + By default, NixOS uses DHCP (specifically, dhcpcd) to + automatically configure network interfaces. However, you can configure an + interface manually as follows: + +networking.interfaces.eth0.ipv4.addresses = [ { + address = "192.168.1.2"; + prefixLength = 24; +} ]; + + Typically you’ll also want to set a default gateway and set of name + servers: + + = "192.168.1.1"; + = [ "8.8.8.8" ]; + + + + + + Statically configured interfaces are set up by the systemd service + interface-name-cfg.service. + The default gateway and name server configuration is performed by + network-setup.service. + + + + + The host name is set using : + + = "cartman"; + + The default host name is nixos. Set it to the empty string + ("") to allow the DHCP server to provide the host name. + +
diff --git a/nixos/doc/manual/configuration/ipv6-config.xml b/nixos/doc/manual/configuration/ipv6-config.xml new file mode 100644 index 0000000..e9ab7cc --- /dev/null +++ b/nixos/doc/manual/configuration/ipv6-config.xml @@ -0,0 +1,50 @@ +
+ IPv6 Configuration + + + 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: + + = false; + + + + + You can disable IPv6 on a single interface using a normal sysctl (in this + example, we use interface eth0): + +."net.ipv6.conf.eth0.disable_ipv6" = true; + + + + + As with IPv4 networking interfaces are automatically configured via DHCPv6. + You can configure an interface manually: + +networking.interfaces.eth0.ipv6.addresses = [ { + address = "fe00:aa:bb:cc::2"; + prefixLength = 64; +} ]; + + + + + For configuring a gateway, optionally with explicitly specified interface: + + = { + address = "fe00::1"; + interface = "enp0s3"; +} + + + + + See for similar examples and additional + information. + +
diff --git a/nixos/doc/manual/configuration/linux-kernel.xml b/nixos/doc/manual/configuration/linux-kernel.xml new file mode 100644 index 0000000..644d3a3 --- /dev/null +++ b/nixos/doc/manual/configuration/linux-kernel.xml @@ -0,0 +1,138 @@ + + Linux Kernel + + You can override the Linux kernel and associated packages using the option + . For instance, this selects the Linux + 3.10 kernel: + + = pkgs.linuxPackages_3_10; + + 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. + + + The default Linux kernel configuration should be fine for most users. You can + see the configuration of your current kernel with the following command: + +zcat /proc/config.gz + + If you want to change the kernel configuration, you can use the + feature (see + ). For instance, to enable support + for the kernel debugger KGDB: + +nixpkgs.config.packageOverrides = pkgs: + { linux_3_4 = pkgs.linux_3_4.override { + extraConfig = + '' + KGDB y + ''; + }; + }; + + extraConfig takes a list of Linux kernel configuration + options, one per line. The name of the option should not include the prefix + CONFIG_. The option value is typically + y, n or m (to build + something as a kernel module). + + + Kernel modules for hardware devices are generally loaded automatically by + udev. You can force a module to be loaded via + , e.g. + + = [ "fuse" "kvm-intel" "coretemp" ]; + + If the module is required early during the boot (e.g. to mount the root file + system), you can use : + + = [ "cifs" ]; + + This causes the specified modules and their dependencies to be added to the + initial ramdisk. + + + Kernel runtime parameters can be set through + , e.g. + +."net.ipv4.tcp_keepalive_time" = 120; + + sets the kernel’s TCP keepalive time to 120 seconds. To see the available + parameters, run sysctl -a. + +
+ Customize your kernel + + + The first step before compiling the kernel is to generate an appropriate + .config configuration. Either you pass your own config + via the configfile setting of + linuxManualConfig: + + You can edit the config with this snippet (by default make + menuconfig won't work out of the box on nixos): + {}; kernelToOverride.overrideAttrs (o: {nativeBuildInputs=o.nativeBuildInputs ++ [ pkgconfig ncurses ];})' + ]]> + or you can let nixpkgs generate the configuration. Nixpkgs generates it via + answering the interactive kernel utility make config. The + answers depend on parameters passed to + pkgs/os-specific/linux/kernel/generic.nix (which you + can influence by overriding extraConfig, autoModules, + modDirVersion, preferBuiltin, extraConfig). + + +
+
+ Developing kernel modules + + + 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 + mellanox drivers. + + +' -A linuxPackages.kernel.dev +$ nix-shell '' -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 +]]> +
+ diff --git a/nixos/doc/manual/configuration/luks-file-systems.xml b/nixos/doc/manual/configuration/luks-file-systems.xml new file mode 100644 index 0000000..8a2b107 --- /dev/null +++ b/nixos/doc/manual/configuration/luks-file-systems.xml @@ -0,0 +1,40 @@ +
+ LUKS-Encrypted File Systems + + + NixOS supports file systems that are encrypted using + LUKS (Linux Unified Key Setup). For example, here is how + you create an encrypted Ext4 file system on the device + /dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d: + +# 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 + + To ensure that this file system is automatically mounted at boot time as + /, add the following to + configuration.nix: + +boot.initrd.luks.devices.crypted.device = "/dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d"; +."/".device = "/dev/mapper/crypted"; + + Should grub be used as bootloader, and /boot is located + on an encrypted partition, it is necessary to add the following grub option: + = true; + +
diff --git a/nixos/doc/manual/configuration/modularity.xml b/nixos/doc/manual/configuration/modularity.xml new file mode 100644 index 0000000..5ff5bc2 --- /dev/null +++ b/nixos/doc/manual/configuration/modularity.xml @@ -0,0 +1,147 @@ +
+ Modularity + + + The NixOS configuration mechanism is modular. If your + configuration.nix 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. + + + + Modules have exactly the same syntax as + configuration.nix. In fact, + configuration.nix is itself a module. You can use other + modules by including them from configuration.nix, e.g.: + +{ config, pkgs, ... }: + +{ imports = [ ./vpn.nix ./kde.nix ]; + = true; + = [ pkgs.emacs ]; + ... +} + + Here, we include two modules from the same directory, + vpn.nix and kde.nix. The latter + might look like this: + +{ config, pkgs, ... }: + +{ = true; + = true; + = true; +} + + Note that both configuration.nix and + kde.nix define the option + . When multiple modules + define an option, NixOS will try to merge the + definitions. In the case of , + that’s easy: the lists of packages can simply be concatenated. The value in + configuration.nix 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 mkBefore: + + = mkBefore [ "kvm-intel" ]; + + This causes the kvm-intel kernel module to be loaded + before any other kernel modules. + + + + For other types of options, a merge may not be possible. For instance, if two + modules define , + nixos-rebuild will give an error: + +The unique option `services.httpd.adminAddr' is defined multiple times, in `/etc/nixos/httpd.nix' and `/etc/nixos/configuration.nix'. + + When that happens, it’s possible to force one definition take precedence + over the others: + + = pkgs.lib.mkForce "bob@example.org"; + + + + + When using multiple modules, you may need to access configuration values + defined in other modules. This is what the config function + argument is for: it contains the complete, merged system configuration. That + is, config is the result of combining the configurations + returned by every module + + + If you’re wondering how it’s possible that the (indirect) + result of a function is passed as an + input 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. + + + . For example, here is a module that adds some packages to + only if + is set to + true somewhere else: + +{ config, pkgs, ... }: + +{ = + if config. then + [ pkgs.firefox + pkgs.thunderbird + ] + else + [ ]; +} + + + + + With multiple modules, it may not be obvious what the final value of a + configuration option is. The command allows you + to find out: + +$ nixos-option +true + +$ nixos-option +[ "tun" "ipv6" "loop" ... ] + + Interactive exploration of the configuration is possible using + nix repl, a read-eval-print loop for Nix expressions. + A typical use: + +$ nix repl '<nixpkgs/nixos>' + +nix-repl> config. +"mandark" + +nix-repl> map (x: x.hostName) config. +[ "example.org" "example.gov" ] + + + + + 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. + + { config, pkgs, ... }: + + let netConfig = { hostName }: { + networking.hostName = hostName; + networking.useDHCP = false; + }; + + in + + { imports = [ (netConfig "nixos.localdomain") ]; } + + +
diff --git a/nixos/doc/manual/configuration/network-manager.xml b/nixos/doc/manual/configuration/network-manager.xml new file mode 100644 index 0000000..d103ee2 --- /dev/null +++ b/nixos/doc/manual/configuration/network-manager.xml @@ -0,0 +1,44 @@ +
+ NetworkManager + + + To facilitate network configuration, some desktop environments use + NetworkManager. You can enable NetworkManager by setting: + + = true; + + some desktop managers (e.g., GNOME) enable NetworkManager automatically for + you. + + + + All users that should have permission to change network settings must belong + to the networkmanager group: + +users.users.alice.extraGroups = [ "networkmanager" ]; + + + + + NetworkManager is controlled using either nmcli or + nmtui (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 + networkmanagerapplet 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). + + + + + networking.networkmanager and networking.wireless + (WPA Supplicant) cannot be enabled at the same time: you can still connect + to the wireless networks using NetworkManager. + + +
diff --git a/nixos/doc/manual/configuration/networking.xml b/nixos/doc/manual/configuration/networking.xml new file mode 100644 index 0000000..02cf811 --- /dev/null +++ b/nixos/doc/manual/configuration/networking.xml @@ -0,0 +1,19 @@ + + Networking + + This section describes how to configure networking components on your NixOS + machine. + + + + + + + + + + diff --git a/nixos/doc/manual/configuration/package-mgmt.xml b/nixos/doc/manual/configuration/package-mgmt.xml new file mode 100644 index 0000000..e8ac5d0 --- /dev/null +++ b/nixos/doc/manual/configuration/package-mgmt.xml @@ -0,0 +1,31 @@ + + Package Management + + This section describes how to add additional packages to your system. NixOS + has two distinct styles of package management: + + + + Declarative, where you declare what packages you want + in your configuration.nix. Every time you run + nixos-rebuild, NixOS will ensure that you get a + consistent set of binaries corresponding to your specification. + + + + + Ad hoc, where you install, upgrade and uninstall + packages via the nix-env command. This style allows + mixing packages from different Nixpkgs versions. It’s the only choice + for non-root users. + + + + + + + diff --git a/nixos/doc/manual/configuration/profiles.xml b/nixos/doc/manual/configuration/profiles.xml new file mode 100644 index 0000000..92c0f62 --- /dev/null +++ b/nixos/doc/manual/configuration/profiles.xml @@ -0,0 +1,39 @@ + + Profiles + + In some cases, it may be desirable to take advantage of commonly-used, + predefined configurations provided by nixpkgs, but different from those that + come as default. This is a role fulfilled by NixOS's Profiles, which come as + files living in <nixpkgs/nixos/modules/profiles>. + That is to say, expected usage is to add them to the imports list of your + /etc/configuration.nix as such: + + + imports = [ + <nixpkgs/nixos/modules/profiles/profile-name.nix> + ]; + + + Even if some of these profiles seem only useful in the context of + install media, many are actually intended to be used in real installs. + + + What follows is a brief explanation on the purpose and use-case for each + profile. Detailing each option configured by each one is out of scope. + + + + + + + + + + + + + diff --git a/nixos/doc/manual/configuration/profiles/all-hardware.xml b/nixos/doc/manual/configuration/profiles/all-hardware.xml new file mode 100644 index 0000000..1729751 --- /dev/null +++ b/nixos/doc/manual/configuration/profiles/all-hardware.xml @@ -0,0 +1,20 @@ + +
+ All Hardware + + 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. + + + The enabled kernel modules include support for SATA and PATA, SCSI + (partially), USB, Firewire (untested), Virtio (QEMU, KVM, etc.), VMware, and + Hyper-V. Additionally, is + enabled, and the firmware for the ZyDAS ZD1211 chipset is specifically + installed. + +
diff --git a/nixos/doc/manual/configuration/profiles/base.xml b/nixos/doc/manual/configuration/profiles/base.xml new file mode 100644 index 0000000..f58a35d --- /dev/null +++ b/nixos/doc/manual/configuration/profiles/base.xml @@ -0,0 +1,15 @@ + +
+ Base + + 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). + +
diff --git a/nixos/doc/manual/configuration/profiles/clone-config.xml b/nixos/doc/manual/configuration/profiles/clone-config.xml new file mode 100644 index 0000000..87c8b9e --- /dev/null +++ b/nixos/doc/manual/configuration/profiles/clone-config.xml @@ -0,0 +1,14 @@ + +
+ Clone Config + + 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. + +
diff --git a/nixos/doc/manual/configuration/profiles/demo.xml b/nixos/doc/manual/configuration/profiles/demo.xml new file mode 100644 index 0000000..98829e4 --- /dev/null +++ b/nixos/doc/manual/configuration/profiles/demo.xml @@ -0,0 +1,13 @@ + +
+ Demo + + This profile just enables a demo user, with password demo, uid 1000, wheel + group and + autologin in the SDDM display manager. + +
diff --git a/nixos/doc/manual/configuration/profiles/docker-container.xml b/nixos/doc/manual/configuration/profiles/docker-container.xml new file mode 100644 index 0000000..bf96244 --- /dev/null +++ b/nixos/doc/manual/configuration/profiles/docker-container.xml @@ -0,0 +1,15 @@ + +
+ Docker Container + + This is the profile from which the Docker images are generated. It prepares a + working system by importing the Minimal and + Clone Config profiles, and setting appropriate + configuration options that are useful inside a container context, like + . + +
diff --git a/nixos/doc/manual/configuration/profiles/graphical.xml b/nixos/doc/manual/configuration/profiles/graphical.xml new file mode 100644 index 0000000..5ded61d --- /dev/null +++ b/nixos/doc/manual/configuration/profiles/graphical.xml @@ -0,0 +1,21 @@ + +
+ Graphical + + Defines a NixOS configuration with the Plasma 5 desktop. It's used by the + graphical installation CD. + + + It sets , + , + ( + + without Qt4 Support), and + to true. It also + includes glxinfo and firefox in the system packages list. + +
diff --git a/nixos/doc/manual/configuration/profiles/hardened.xml b/nixos/doc/manual/configuration/profiles/hardened.xml new file mode 100644 index 0000000..b3b4337 --- /dev/null +++ b/nixos/doc/manual/configuration/profiles/hardened.xml @@ -0,0 +1,22 @@ + +
+ Hardened + + A profile with most (vanilla) hardening options enabled by default, + potentially at the cost of features and performance. + + + This includes a hardened kernel, and limiting the system information + available to processes through the /sys and + /proc 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 + ). See the + profile source for further detail on which settings are altered. + +
diff --git a/nixos/doc/manual/configuration/profiles/headless.xml b/nixos/doc/manual/configuration/profiles/headless.xml new file mode 100644 index 0000000..54dc61f --- /dev/null +++ b/nixos/doc/manual/configuration/profiles/headless.xml @@ -0,0 +1,18 @@ + +
+ Headless + + Common configuration for headless machines (e.g., Amazon EC2 instances). + + + Disables sound, + vesa, serial consoles, + emergency mode, + grub splash images and + configures the kernel to reboot automatically on panic. + +
diff --git a/nixos/doc/manual/configuration/profiles/installation-device.xml b/nixos/doc/manual/configuration/profiles/installation-device.xml new file mode 100644 index 0000000..44ccfc5 --- /dev/null +++ b/nixos/doc/manual/configuration/profiles/installation-device.xml @@ -0,0 +1,35 @@ + +
+ Installation Device + + Provides a basic configuration for installation devices like CDs. This means + enabling hardware scans, using the + Clone Config profile to guarantee + /etc/nixos/configuration.nix exists (for + nixos-rebuild to work), a copy of the Nixpkgs channel + snapshot used to create the install media. + + + Additionally, documentation for + Nixpkgs and NixOS + are forcefully enabled (to override the + Minimal profile preference); the + NixOS manual is shown automatically on TTY 8, sudo and udisks are disabled. + Autologin is enabled as root. + + + A message is shown to the user to start a display manager if needed, + ssh with are enabled (but + doesn't autostart). WPA Supplicant is also enabled without autostart. + + + 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. + +
diff --git a/nixos/doc/manual/configuration/profiles/minimal.xml b/nixos/doc/manual/configuration/profiles/minimal.xml new file mode 100644 index 0000000..a24af21 --- /dev/null +++ b/nixos/doc/manual/configuration/profiles/minimal.xml @@ -0,0 +1,17 @@ + +
+ Minimal + + This profile defines a small NixOS configuration. It does not contain any + graphical stuff. It's a very short file that enables + noXlibs, sets + i18n.supportedLocales + to only support the user-selected locale, + disables packages' documentation + , and disables sound. + +
diff --git a/nixos/doc/manual/configuration/profiles/qemu-guest.xml b/nixos/doc/manual/configuration/profiles/qemu-guest.xml new file mode 100644 index 0000000..d080686 --- /dev/null +++ b/nixos/doc/manual/configuration/profiles/qemu-guest.xml @@ -0,0 +1,16 @@ +
+ QEMU Guest + + This profile contains common configuration for virtual machines running under + QEMU (using virtio). + + + 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 + enables rngd. + +
diff --git a/nixos/doc/manual/configuration/ssh.xml b/nixos/doc/manual/configuration/ssh.xml new file mode 100644 index 0000000..a4af1b9 --- /dev/null +++ b/nixos/doc/manual/configuration/ssh.xml @@ -0,0 +1,27 @@ +
+ Secure Shell Access + + + Secure shell (SSH) access to your machine can be enabled by setting: + + = true; + + By default, root logins using a password are disallowed. They can be disabled + entirely by setting to + "no". + + + + You can declaratively specify authorised RSA/DSA public keys for a user as + follows: + + +users.users.alice.openssh.authorizedKeys.keys = + [ "ssh-dss AAAAB3NzaC1kc3MAAACBAPIkGWVEt4..." ]; + + +
diff --git a/nixos/doc/manual/configuration/summary.xml b/nixos/doc/manual/configuration/summary.xml new file mode 100644 index 0000000..ea98025 --- /dev/null +++ b/nixos/doc/manual/configuration/summary.xml @@ -0,0 +1,227 @@ +
+ Syntax Summary + + + 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 + Nix + manual for the rest. + + + + + + + + + Example + Description + + + + + Basic values + + + + "Hello world" + + A string + + + "${pkgs.bash}/bin/sh" + + A string containing an expression (expands to "/nix/store/hash-bash-version/bin/sh") + + + true, false + + Booleans + + + 123 + + An integer + + + ./foo.png + + A path (relative to the containing Nix expression) + + + Compound values + + + + { x = 1; y = 2; } + + A set with attributes named x and y + + + + { foo.bar = 1; } + + A nested set, equivalent to { foo = { bar = 1; }; } + + + + rec { x = "foo"; y = x + "bar"; } + + A recursive set, equivalent to { x = "foo"; y = "foobar"; } + + + + [ "foo" "bar" ] + + A list with two elements + + + Operators + + + + "foo" + "bar" + + String concatenation + + + 1 + 2 + + Integer addition + + + "foo" == "f" + "oo" + + Equality test (evaluates to true) + + + "foo" != "bar" + + Inequality test (evaluates to true) + + + !true + + Boolean negation + + + { x = 1; y = 2; }.x + + Attribute selection (evaluates to 1) + + + { x = 1; y = 2; }.z or 3 + + Attribute selection with default (evaluates to 3) + + + { x = 1; y = 2; } // { z = 3; } + + Merge two sets (attributes in the right-hand set taking precedence) + + + Control structures + + + + if 1 + 1 == 2 then "yes!" else "no!" + + Conditional expression + + + assert 1 + 1 == 2; "yes!" + + Assertion check (evaluates to "yes!"). See for using assertions in modules + + + let x = "foo"; y = "bar"; in x + y + + Variable definition + + + with pkgs.lib; head [ 1 2 3 ] + + Add all attributes from the given set to the scope + (evaluates to 1) + + + Functions (lambdas) + + + + x: x + 1 + + A function that expects an integer and returns it increased by 1 + + + (x: x + 1) 100 + + A function call (evaluates to 101) + + + let inc = x: x + 1; in inc (inc (inc 100)) + + A function bound to a variable and subsequently called by name (evaluates to 103) + + + { x, y }: x + y + + A function that expects a set with required attributes + x and y and concatenates + them + + + { x, y ? "bar" }: x + y + + A function that expects a set with required attribute + x and optional y, using + "bar" as default value for + y + + + + { x, y, ... }: x + y + + A function that expects a set with required attributes + x and y and ignores any + other attributes + + + { x, y } @ args: x + y + + A function that expects a set with required attributes + x and y, and binds the + whole set to args + + + + Built-in functions + + + + import ./foo.nix + + Load and return Nix expression in given file + + + map (x: x + x) [ 1 2 3 ] + + Apply a function to every element of a list (evaluates to [ 2 4 6 ]) + + + + + +
diff --git a/nixos/doc/manual/configuration/user-mgmt.xml b/nixos/doc/manual/configuration/user-mgmt.xml new file mode 100644 index 0000000..66c1c6e --- /dev/null +++ b/nixos/doc/manual/configuration/user-mgmt.xml @@ -0,0 +1,88 @@ + + User Management + + NixOS supports both declarative and imperative styles of user management. In + the declarative style, users are specified in + configuration.nix. For instance, the following states + that a user account named alice shall exist: + +.alice = { + isNormalUser = true; + home = "/home/alice"; + description = "Alice Foobar"; + extraGroups = [ "wheel" "networkmanager" ]; + openssh.authorizedKeys.keys = [ "ssh-dss AAAAB3Nza... alice@foobar" ]; +}; + + Note that alice is a member of the + wheel and networkmanager groups, which + allows her to use sudo to execute commands as + root 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 passwd program to set a password, which is retained + across invocations of nixos-rebuild. + + + If you set to false, then the + contents of /etc/passwd and /etc/group + will be congruent to your NixOS configuration. For instance, if you remove a + user from 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 + hashedPassword + option. A hashed password can be generated using mkpasswd -m + sha-512 after installing the mkpasswd package. + + + A user ID (uid) is assigned automatically. You can also specify a uid + manually by adding + + uid = 1000; + + to the user specification. + + + Groups can be specified similarly. The following states that a group named + students shall exist: + +.students.gid = 1000; + + As with users, the group ID (gid) is optional and will be assigned + automatically if it’s missing. + + + In the imperative style, users and groups are managed by commands such as + useradd, groupmod and so on. For + instance, to create a user account named alice: + +# useradd -m alice + 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: + +# su - alice -c "true" + The flag 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 + passwd utility: + +# passwd alice +Enter new UNIX password: *** +Retype new UNIX password: *** + + A user can be deleted using userdel: + +# userdel -r alice + The flag deletes the user’s home directory. Accounts + can be modified using usermod. Unix groups can be managed + using groupadd, groupmod and + groupdel. + + diff --git a/nixos/doc/manual/configuration/wireless.xml b/nixos/doc/manual/configuration/wireless.xml new file mode 100644 index 0000000..9994472 --- /dev/null +++ b/nixos/doc/manual/configuration/wireless.xml @@ -0,0 +1,45 @@ +
+ Wireless Networks + + + For a desktop installation using NetworkManager (e.g., GNOME), you just have + to make sure the user is in the networkmanager group and you can + skip the rest of this section on wireless networks. + + + + NixOS will start wpa_supplicant for you if you enable this setting: + + = true; + + NixOS lets you specify networks for wpa_supplicant declaratively: + + = { + echelon = { + psk = "abcdefgh"; + }; + "free.wifi" = {}; +} + + 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 + /etc/wpa_supplicant.conf. You should edit this file + yourself to define wireless networks, WPA keys and so on (see + wpa_supplicant.conf(5)). + + + + If you are using WPA2 the wpa_passphrase tool might be + useful to generate the wpa_supplicant.conf. + +# wpa_passphrase ESSID PSK > /etc/wpa_supplicant.conf + After you have edited the wpa_supplicant.conf, you need to + restart the wpa_supplicant service. + +# systemctl restart wpa_supplicant.service + +
diff --git a/nixos/doc/manual/configuration/x-windows.xml b/nixos/doc/manual/configuration/x-windows.xml new file mode 100644 index 0000000..703a1b8 --- /dev/null +++ b/nixos/doc/manual/configuration/x-windows.xml @@ -0,0 +1,136 @@ + + X Window System + + The X Window System (X11) provides the basis of NixOS’ graphical user + interface. It can be enabled as follows: + + = true; + + The X server will automatically detect and use the appropriate video driver + from a set of X.org drivers (such as vesa and + intel). You can also specify a driver manually, e.g. + + = [ "r128" ]; + + to enable X.org’s xf86-video-r128 driver. + + + You also need to enable at least one desktop or window manager. Otherwise, + you can only log into a plain undecorated xterm window. + Thus you should pick one or more of the following lines: + + = true; + = true; + = true; + = true; + = true; + = true; + = true; + = true; + + + + NixOS’s default display manager (the program that + provides a graphical login prompt and manages the X server) is SLiM. You can + select an alternative one by picking one of the following lines: + + = true; + = true; + + + + You can set the keyboard layout (and optionally the layout variant): + + = "de"; + = "neo"; + + + + The X server is started automatically at boot time. If you don’t want this + to happen, you can set: + + = false; + + The X server can then be started manually: + +# systemctl start display-manager.service + + + + NVIDIA Graphics Cards + + 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: + + = [ "nvidia" ]; + + Or if you have an older card, you may have to use one of the legacy drivers: + + = [ "nvidiaLegacy340" ]; + = [ "nvidiaLegacy304" ]; + = [ "nvidiaLegacy173" ]; + + You may need to reboot after enabling this driver to prevent a clash with + other kernel modules. + + + On 64-bit systems, if you want full acceleration for 32-bit programs such as + Wine, you should also set the following: + + = true; + + + + + AMD Graphics Cards + + 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: + + = [ "ati_unfree" ]; + + You will need to reboot after enabling this driver to prevent a clash with + other kernel modules. + + + On 64-bit systems, if you want full acceleration for 32-bit programs such as + Wine, you should also set the following: + + = true; + + + + + Touchpads + + Support for Synaptics touchpads (found in many laptops such as the Dell + Latitude series) can be enabled as follows: + + = true; + + The driver has many options (see ). For + instance, the following disables tap-to-click behavior: + + = false; + + Note: the use of services.xserver.synaptics is deprecated + since NixOS 17.09. + + + + GTK/Qt themes + + GTK themes can be installed either to user profile or system-wide (via + environment.systemPackages). To make Qt 5 applications + look similar to GTK2 ones, you can install qt5.qtbase.gtk + package into your system environment. It should work for all Qt 5 library + versions. + + + diff --git a/nixos/doc/manual/configuration/xfce.xml b/nixos/doc/manual/configuration/xfce.xml new file mode 100644 index 0000000..77d5d96 --- /dev/null +++ b/nixos/doc/manual/configuration/xfce.xml @@ -0,0 +1,72 @@ + + Xfce Desktop Environment + + To enable the Xfce Desktop Environment, set + +services.xserver.desktopManager = { + xfce.enable = true; + default = "xfce"; +}; + + + + Optionally, compton can be enabled for nice graphical + effects, some example settings: + +services.compton = { + enable = true; + fade = true; + inactiveOpacity = "0.9"; + shadow = true; + fadeDelta = 4; +}; + + + + Some Xfce programs are not installed automatically. To install them manually + (system wide), put them into your + . + + + Thunar Volume Support + + To enable Thunar volume support, put + + = true; + + into your configuration.nix. + + + + Polkit Authentication Agent + + There is no authentication agent automatically installed alongside Xfce. To + allow mounting of local (non-removable) filesystems, you will need to + install one. Installing polkit_gnome, a rebuild, logout + and login did the trick. + + + + Troubleshooting + + 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 journalctl --user -b). + +Thunar:2410): GVFS-RemoteVolumeMonitor-WARNING **: remote volume monitor with dbus name org.gtk.Private.UDisks2VolumeMonitor is not supported + + 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. + +$ xfconf-query -c xfce4-session -p /compat/LaunchGNOME -s true + + A log-out and re-log will be needed for this to take effect. + + + diff --git a/nixos/doc/manual/default.nix b/nixos/doc/manual/default.nix new file mode 100644 index 0000000..faae4f2 --- /dev/null +++ b/nixos/doc/manual/default.nix @@ -0,0 +1,338 @@ +{ pkgs, options, config, version, revision, extraSources ? [] }: + +with pkgs; + +let + lib = pkgs.lib; + + # Remove invisible and internal options. + optionsListVisible = lib.filter (opt: opt.visible && !opt.internal) (lib.optionAttrSetToDocList options); + + # Replace functions by the string + substFunction = x: + if builtins.isAttrs x then lib.mapAttrs (name: substFunction) x + else if builtins.isList x then map substFunction x + else if lib.isFunction x then "" + else x; + + # Generate DocBook documentation for a list of packages. This is + # what `relatedPackages` option of `mkOption` from + # ../../../lib/options.nix influences. + # + # Each element of `relatedPackages` can be either + # - a string: that will be interpreted as an attribute name from `pkgs`, + # - a list: that will be interpreted as an attribute path from `pkgs`, + # - an attrset: that can specify `name`, `path`, `package`, `comment` + # (either of `name`, `path` is required, the rest are optional). + genRelatedPackages = packages: + let + unpack = p: if lib.isString p then { name = p; } + else if lib.isList p then { path = p; } + else p; + describe = args: + let + title = args.title or null; + name = args.name or (lib.concatStringsSep "." args.path); + path = args.path or [ args.name ]; + package = args.package or (lib.attrByPath path (throw "Invalid package attribute path `${toString path}'") pkgs); + in "" + + "${lib.optionalString (title != null) "${title} aka "}pkgs.${name} (${package.meta.name})" + + lib.optionalString (!package.meta.available) " [UNAVAILABLE]" + + ": ${package.meta.description or "???"}." + + lib.optionalString (args ? comment) "\n${args.comment}" + # Lots of `longDescription's break DocBook, so we just wrap them into + + lib.optionalString (package.meta ? longDescription) "\n${package.meta.longDescription}" + + ""; + in "${lib.concatStringsSep "\n" (map (p: describe (unpack p)) packages)}"; + + optionsListDesc = lib.flip map optionsListVisible (opt: opt // { + # Clean up declaration sites to not refer to the NixOS source tree. + declarations = map stripAnyPrefixes opt.declarations; + } + // lib.optionalAttrs (opt ? example) { example = substFunction opt.example; } + // lib.optionalAttrs (opt ? default) { default = substFunction opt.default; } + // lib.optionalAttrs (opt ? type) { type = substFunction opt.type; } + // lib.optionalAttrs (opt ? relatedPackages && opt.relatedPackages != []) { relatedPackages = genRelatedPackages opt.relatedPackages; }); + + # We need to strip references to /nix/store/* from options, + # including any `extraSources` if some modules came from elsewhere, + # or else the build will fail. + # + # E.g. if some `options` came from modules in ${pkgs.customModules}/nix, + # you'd need to include `extraSources = [ pkgs.customModules ]` + prefixesToStrip = map (p: "${toString p}/") ([ ../../.. ] ++ extraSources); + stripAnyPrefixes = lib.flip (lib.fold lib.removePrefix) prefixesToStrip; + + # Custom "less" that pushes up all the things ending in ".enable*" + # and ".package*" + optionLess = a: b: + let + ise = lib.hasPrefix "enable"; + isp = lib.hasPrefix "package"; + cmp = lib.splitByAndCompare ise lib.compare + (lib.splitByAndCompare isp lib.compare lib.compare); + in lib.compareLists cmp a.loc b.loc < 0; + + # Customly sort option list for the man page. + optionsList = lib.sort optionLess optionsListDesc; + + # Convert the list of options into an XML file. + optionsXML = builtins.toFile "options.xml" (builtins.toXML optionsList); + + optionsDocBook = runCommand "options-db.xml" {} '' + optionsXML=${optionsXML} + if grep /nixpkgs/nixos/modules $optionsXML; then + echo "The manual appears to depend on the location of Nixpkgs, which is bad" + echo "since this prevents sharing via the NixOS channel. This is typically" + echo "caused by an option default that refers to a relative path (see above" + echo "for hints about the offending path)." + exit 1 + fi + ${buildPackages.libxslt.bin}/bin/xsltproc \ + --stringparam revision '${revision}' \ + -o intermediate.xml ${./options-to-docbook.xsl} $optionsXML + ${buildPackages.libxslt.bin}/bin/xsltproc \ + -o "$out" ${./postprocess-option-descriptions.xsl} intermediate.xml + ''; + + sources = lib.sourceFilesBySuffices ./. [".xml"]; + + modulesDoc = builtins.toFile "modules.xml" '' +
+ ${(lib.concatMapStrings (path: '' + + '') (lib.catAttrs "value" config.meta.doc))} +
+ ''; + + generatedSources = runCommand "generated-docbook" {} '' + mkdir $out + ln -s ${modulesDoc} $out/modules.xml + ln -s ${optionsDocBook} $out/options-db.xml + printf "%s" "${version}" > $out/version + ''; + + copySources = + '' + cp -prd $sources/* . # */ + ln -s ${generatedSources} ./generated + chmod -R u+w . + ''; + + toc = builtins.toFile "toc.xml" + '' + + + + + + + ''; + + 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" < + + ]> + + + Allows for cross-referencing olinks between the manpages + and manual. + + + &manualtargets; + + EOF + ''; + +in rec { + inherit generatedSources; + + # The NixOS options in JSON format. + optionsJSON = runCommand "options-json" + { meta.description = "List of NixOS options in JSON format"; + } + '' + # Export list of options in different format. + dst=$out/share/doc/nixos + mkdir -p $dst + + cp ${builtins.toFile "options.json" (builtins.unsafeDiscardStringContext (builtins.toJSON + (builtins.listToAttrs (map (o: { name = o.name; value = removeAttrs o ["name" "visible" "internal"]; }) optionsList)))) + } $dst/options.json + + mkdir -p $out/nix-support + echo "file json $dst/options.json" >> $out/nix-support/hydra-build-products + ''; # */ + + # 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" \ + --nonet --output $dst/ \ + ${docbook_xsl_ns}/xml/xsl/docbook/xhtml/chunktoc.xsl \ + ${manual-combined}/manual-combined.xml + + 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 \ + --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/nixos/doc/manual/development/assertions.xml b/nixos/doc/manual/development/assertions.xml new file mode 100644 index 0000000..32f90cf --- /dev/null +++ b/nixos/doc/manual/development/assertions.xml @@ -0,0 +1,74 @@ +
+ Warnings and Assertions + + + 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. + + + + Although Nix has the abort and + builtins.trace + functions + 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. + + +
+ Warnings + + + This is an example of using warnings. + + + + + +
+ +
+ Assertions + + + This example, extracted from the + + syslogd module shows how to use + assertions. 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. + + + + + +
+
diff --git a/nixos/doc/manual/development/building-nixos.xml b/nixos/doc/manual/development/building-nixos.xml new file mode 100644 index 0000000..23d9ddf --- /dev/null +++ b/nixos/doc/manual/development/building-nixos.xml @@ -0,0 +1,27 @@ + + Building Your Own NixOS CD + + Building a NixOS CD is as easy as configuring your own computer. The idea is + to use another module which will replace your + configuration.nix to configure the system that would be + installed on the CD. + + + Default CD/DVD configurations are available inside + nixos/modules/installer/cd-dvd. + +$ git clone https://github.com/NixOS/nixpkgs.git +$ cd nixpkgs/nixos +$ nix-build -A config.system.build.isoImage -I nixos-config=modules/installer/cd-dvd/installation-cd-minimal.nix default.nix + + + Before burning your CD/DVD, you can check the content of the image by + mounting anywhere like suggested by the following command: + +# mount -o loop -t iso9660 ./result/iso/cd.iso /mnt/iso + + diff --git a/nixos/doc/manual/development/building-parts.xml b/nixos/doc/manual/development/building-parts.xml new file mode 100644 index 0000000..b4791b7 --- /dev/null +++ b/nixos/doc/manual/development/building-parts.xml @@ -0,0 +1,121 @@ + + Building Specific Parts of NixOS + + With the command nix-build, you can build specific parts + of your NixOS configuration. This is done as follows: + +$ cd /path/to/nixpkgs/nixos +$ nix-build -A config.option + where option is a NixOS option with type + “derivation” (i.e. something that can be built). Attributes of interest + include: + + + + system.build.toplevel + + + + 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 nixos-rebuild builds and what + /run/current-system points to afterwards. + + + A shortcut to build this is: + +$ nix-build -A system + + + + + + system.build.manual.manualHTML + + + + The NixOS manual. + + + + + + system.build.etc + + + + A tree of symlinks that form the static parts of + /etc. + + + + + + system.build.initialRamdisk + + + system.build.kernel + + + + 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 and options: + +$ nix-build -A config.system.build.initialRamdisk -o initrd +$ nix-build -A config.system.build.kernel -o kernel +$ qemu-system-x86_64 -kernel ./kernel/bzImage -initrd ./initrd/initrd -hda /dev/null + + + + + + + system.build.nixos-rebuild + + + system.build.nixos-install + + + system.build.nixos-generate-config + + + + These build the corresponding NixOS commands. + + + + + + systemd.units.unit-name.unit + + + + This builds the unit with the specified name. Note that since unit names + contain dots (e.g. httpd.service), you need to put + them between quotes, like this: + +$ nix-build -A 'config.systemd.units."httpd.service".unit' + + You can also test individual units, without rebuilding the whole system, + by putting them in /run/systemd/system: + +$ cp $(nix-build -A 'config.systemd.units."httpd.service".unit')/httpd.service \ + /run/systemd/system/tmp-httpd.service +# systemctl daemon-reload +# systemctl start tmp-httpd.service + + Note that the unit must not have the same name as any unit in + /etc/systemd/system since those take precedence over + /run/systemd/system. That’s why the unit is + installed as tmp-httpd.service here. + + + + + + diff --git a/nixos/doc/manual/development/debugging-nixos-tests.xml b/nixos/doc/manual/development/debugging-nixos-tests.xml new file mode 100644 index 0000000..30e58e1 --- /dev/null +++ b/nixos/doc/manual/development/debugging-nixos-tests.xml @@ -0,0 +1,37 @@ +
+ Debugging NixOS tests + + + Tests may fail and infrastructure offers access to inspect machine state. + + + + To prevent test from stopping and cleaning up, insert a sleep command: + + + +$machine->succeed("sleep 84000"); + + + + As soon as machine starts run as root: + + + +nix-shell -p socat --run "socat STDIO,raw,echo=0,escape=0x11 UNIX:/tmp/nix-build-vm-test-run-*.drv-0/vm-state-machine/backdoor" + + + + You may need to find the correct path, replacing /tmp, + * or machine. + + + + Press "enter" to open up console and login as "root". After you're done, + press "ctrl-q" to exit the console. + +
diff --git a/nixos/doc/manual/development/development.xml b/nixos/doc/manual/development/development.xml new file mode 100644 index 0000000..03dee6f --- /dev/null +++ b/nixos/doc/manual/development/development.xml @@ -0,0 +1,20 @@ + + Development + + + This chapter describes how you can modify and extend NixOS. + + + + + + + + + + + diff --git a/nixos/doc/manual/development/importing-modules.xml b/nixos/doc/manual/development/importing-modules.xml new file mode 100644 index 0000000..1c6a567 --- /dev/null +++ b/nixos/doc/manual/development/importing-modules.xml @@ -0,0 +1,56 @@ +
+ Importing Modules + + + Sometimes NixOS modules need to be used in configuration but exist outside of + Nixpkgs. These modules can be imported: + + + +{ config, lib, pkgs, ... }: + +{ + imports = + [ # Use a locally-available module definition in + # ./example-module/default.nix + ./example-module + ]; + + services.exampleModule.enable = true; +} + + + + The environment variable NIXOS_EXTRA_MODULE_PATH 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: + + + +# ./module-list/default.nix +[ + ./example-module1 + ./example-module2 +] + + + +# ./extra-module/default.nix +{ imports = import ./module-list.nix; } + + + +# NIXOS_EXTRA_MODULE_PATH=/absolute/path/to/extra-module +{ config, lib, pkgs, ... }: + +{ + # No `imports` needed + + services.exampleModule1.enable = true; +} + +
diff --git a/nixos/doc/manual/development/meta-attributes.xml b/nixos/doc/manual/development/meta-attributes.xml new file mode 100644 index 0000000..3d019a4 --- /dev/null +++ b/nixos/doc/manual/development/meta-attributes.xml @@ -0,0 +1,63 @@ +
+ Meta Attributes + + + Like Nix packages, NixOS modules can declare meta-attributes to provide extra + information. Module meta attributes are defined in the + meta.nix + special module. + + + + meta is a top level attribute like + options and config. Available + meta-attributes are maintainers and + doc. + + + + Each of the meta-attributes must be defined at most once per module file. + + + +{ config, lib, pkgs, ... }: +{ + options = { + ... + }; + + config = { + ... + }; + + meta = { + maintainers = with lib.maintainers; [ ericsagnes ]; + doc = ./default.xml; + }; +} + + + + + + maintainers contains a list of the module maintainers. + + + + + doc points to a valid DocBook file containing the module + documentation. Its contents is automatically added to + . Changes to a module documentation + have to be checked to not break building the NixOS manual: + +$ nix-build nixos/release.nix -A manual + + +
diff --git a/nixos/doc/manual/development/nixos-tests.xml b/nixos/doc/manual/development/nixos-tests.xml new file mode 100644 index 0000000..d068887 --- /dev/null +++ b/nixos/doc/manual/development/nixos-tests.xml @@ -0,0 +1,20 @@ + + NixOS Tests + + When you add some feature to NixOS, you should write a test for it. NixOS + tests are kept in the directory + nixos/tests, + and are executed (using Nix) by a testing framework that automatically starts + one or more virtual machines containing the NixOS system(s) required for the + test. + + + + + + diff --git a/nixos/doc/manual/development/option-declarations.xml b/nixos/doc/manual/development/option-declarations.xml new file mode 100644 index 0000000..eee81bf --- /dev/null +++ b/nixos/doc/manual/development/option-declarations.xml @@ -0,0 +1,199 @@ +
+ Option Declarations + + + 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: + +options = { + name = mkOption { + type = type specification; + default = default value; + example = example value; + description = "Description for use in the NixOS manual."; + }; +}; + + The attribute names within the name attribute path + must be camel cased in general but should, as an exception, match the + + package attribute name when referencing a Nixpkgs package. For + example, the option services.nix-serve.bindAddress + references the nix-serve Nixpkgs package. + + + + The function mkOption accepts the following arguments. + + + + type + + + + The type of the option (see ). It may + be omitted, but that’s not advisable since it may lead to errors that + are hard to diagnose. + + + + + + default + + + + 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. + + + + + + example + + + + An example value that will be shown in the NixOS manual. + + + + + + description + + + + A textual description of the option, in DocBook format, that will be + included in the NixOS manual. + + + + + + +
+ Extensible Option Types + + + 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 enum and + submodules and any composed forms of them. + + + + Extensible option types can be used for enum options that + affects multiple modules, or as an alternative to related + enable options. + + + + 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 ...). + + + + There are two approach to this module structure: + + + + Managing the display managers independently by adding an enable option to + every display manager module backend. (NixOS) + + + + + Managing the display managers in the central module by adding an option + to select which display manager backend to use. + + + + + + + Both approaches have problems. + + + + 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 + enable option. As a result, this restriction has to be + done explicitely by adding assertions in each display manager backend + module. + + + + 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. + + + + By using extensible option types, it is possible to create a placeholder + option in the central module + (), and to extend + it in each backend module + (, + ). + + + + As a result, displayManager.enable 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. + + + + Extensible type placeholder in the service module + +services.xserver.displayManager.enable = mkOption { + description = "Display manager to use"; + type = with types; nullOr (enum [ ]); +}; + + + + Extending <literal>services.xserver.displayManager.enable</literal> in the <literal>slim</literal> module + +services.xserver.displayManager.enable = mkOption { + type = with types; nullOr (enum [ "slim" ]); +}; + + + + Extending <literal>services.xserver.displayManager.enable</literal> in the <literal>sddm</literal> module + +services.xserver.displayManager.enable = mkOption { + type = with types; nullOr (enum [ "sddm" ]); +}; + + + + The placeholder declaration is a standard mkOption + declaration, but it is important that extensible option declarations only + use the type argument. + + + + Extensible option types work with any of the composed variants of + enum such as with types; nullOr (enum [ "foo" + "bar" ]) or with types; listOf (enum [ "foo" "bar" + ]). + +
+
diff --git a/nixos/doc/manual/development/option-def.xml b/nixos/doc/manual/development/option-def.xml new file mode 100644 index 0000000..50a705d --- /dev/null +++ b/nixos/doc/manual/development/option-def.xml @@ -0,0 +1,99 @@ +
+ Option Definitions + + + Option definitions are generally straight-forward bindings of values to + option names, like + +config = { + services.httpd.enable = true; +}; + + However, sometimes you need to wrap an option definition or set of option + definitions in a property to achieve certain effects: + + + + Delaying Conditionals + + If a set of option definitions is conditional on the value of another + option, you may need to use mkIf. Consider, for instance: + +config = if config.services.httpd.enable then { + environment.systemPackages = [ ... ]; + ... +} else {}; + + This definition will cause Nix to fail with an “infinite recursion” + error. Why? Because the value of + depends on the value being + constructed here. After all, you could also write the clearly circular and + contradictory: + +config = if config.services.httpd.enable then { + services.httpd.enable = false; +} else { + services.httpd.enable = true; +}; + + The solution is to write: + +config = mkIf config.services.httpd.enable { + environment.systemPackages = [ ... ]; + ... +}; + + The special function mkIf causes the evaluation of the + conditional to be “pushed down” into the individual definitions, as if + you had written: + +config = { + environment.systemPackages = if config.services.httpd.enable then [ ... ] else []; + ... +}; + + + + + + Setting Priorities + + A module can override the definitions of an option in other modules by + setting a priority. 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 + mkOverride, e.g. + +services.openssh.enable = mkOverride 10 false; + + This definition causes all other definitions with priorities above 10 to be + discarded. The function mkForce is equal to + mkOverride 50. + + + + + Merging Configurations + + In conjunction with mkIf, 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 + mkMerge: + +config = mkMerge + [ # Unconditional stuff. + { environment.systemPackages = [ ... ]; + } + # Conditional stuff. + (mkIf config.services.bla.enable { + environment.systemPackages = [ ... ]; + }) + ]; + + + +
diff --git a/nixos/doc/manual/development/option-types.xml b/nixos/doc/manual/development/option-types.xml new file mode 100644 index 0000000..d993e47 --- /dev/null +++ b/nixos/doc/manual/development/option-types.xml @@ -0,0 +1,781 @@ +
+ Options Types + + + 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. + + +
+ Basic Types + + + 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. + + + + + + types.attrs + + + + A free-form attribute set. + + + + + + types.bool + + + + A boolean, its values can be true or + false. + + + + + + types.path + + + + 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 types.package should be preferred. + + + + + + types.package + + + + A derivation or a store path. + + + + + + + Integer-related types: + + + + + + types.int + + + + A signed integer. + + + + + + types.ints.{s8, s16, s32} + + + + Signed integers with a fixed length (8, 16 or 32 bits). They go from + −2n/2 + to + 2n/2−1 + respectively (e.g. −128 to + 127 for 8 bits). + + + + + + types.ints.unsigned + + + + An unsigned integer (that is >= 0). + + + + + + types.ints.{u8, u16, u32} + + + + Unsigned integers with a fixed length (8, 16 or 32 bits). They go from + 0 to + + 2n−1 + respectively (e.g. 0 to + 255 for 8 bits). + + + + + + types.ints.positive + + + + A positive integer (that is > 0). + + + + + + types.port + + + + A port number. This type is an alias to + types.ints.u16. + + + + + + + String-related types: + + + + + + types.str + + + + A string. Multiple definitions cannot be merged. + + + + + + types.lines + + + + A string. Multiple definitions are concatenated with a new line + "\n". + + + + + + types.commas + + + + A string. Multiple definitions are concatenated with a comma + ",". + + + + + + types.envVar + + + + A string. Multiple definitions are concatenated with a collon + ":". + + + + + + types.strMatching + + + + A string matching a specific regular expression. Multiple definitions + cannot be merged. The regular expression is processed using + builtins.match. + + + + +
+ +
+ Value Types + + + Value types are types that take a value parameter. + + + + + + types.enum l + + + + One element of the list l, e.g. + types.enum [ "left" "right" ]. Multiple definitions + cannot be merged. + + + + + + types.separatedString sep + + + + A string with a custom separator sep, e.g. + types.separatedString "|". + + + + + + types.ints.between lowest highest + + + + An integer between lowest and + highest (both inclusive). Useful for creating + types like types.port. + + + + + + types.submodule o + + + + A set of sub options o. + o 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 + . + + + + +
+ +
+ Composed Types + + + Composed types are types that take a type as parameter. listOf + int and either int str are examples of composed + types. + + + + + + types.listOf t + + + + A list of t type, e.g. types.listOf + int. Multiple definitions are merged with list concatenation. + + + + + + types.attrsOf t + + + + An attribute set of where all the values are of + t type. Multiple definitions result in the + joined attribute set. + + + + + + types.loaOf t + + + + An attribute set or a list of t type. Multiple + definitions are merged according to the value. + + + + + + types.nullOr t + + + + null or type t. Multiple + definitions are merged according to type t. + + + + + + types.uniq t + + + + Ensures that type t cannot be merged. It is + used to ensure option definitions are declared only once. + + + + + + types.either t1 t2 + + + + Type t1 or type t2, + e.g. with types; either int str. Multiple definitions + cannot be merged. + + + + + + types.coercedTo from f to + + + + Type to or type + from which will be coerced to type + to using function f + which takes an argument of type from and + return a value of type to. Can be used to + preserve backwards compatibility of an option if its type was changed. + + + + +
+ +
+ Submodule + + + submodule is a very powerful type that defines a set of + sub-options that are handled like a separate module. + + + + It takes a parameter o, that should be a set, or + a function returning a set with an options key defining + the sub-options. Submodule option definitions are type-checked accordingly + to the options declarations. Of course, you can nest + submodule option definitons for even higher modularity. + + + + The option set can be defined directly + () or as reference + (). + + + + Directly defined submodule + +options.mod = mkOption { + description = "submodule example"; + type = with types; submodule { + options = { + foo = mkOption { + type = int; + }; + bar = mkOption { + type = str; + }; + }; + }; +}; + + + + Submodule defined as a reference + +let + modOptions = { + options = { + foo = mkOption { + type = int; + }; + bar = mkOption { + type = int; + }; + }; + }; +in +options.mod = mkOption { + description = "submodule example"; + type = with types; submodule modOptions; +}; + + + + The submodule type is especially interesting when used + with composed types like attrsOf or + listOf. When composed with listOf + (), + submodule allows multiple definitions of the submodule + option set (). + + + + Declaration of a list of submodules + +options.mod = mkOption { + description = "submodule example"; + type = with types; listOf (submodule { + options = { + foo = mkOption { + type = int; + }; + bar = mkOption { + type = str; + }; + }; + }); +}; + + + + Definition of a list of submodules + +config.mod = [ + { foo = 1; bar = "one"; } + { foo = 2; bar = "two"; } +]; + + + + When composed with attrsOf + (), + submodule allows multiple named definitions of the + submodule option set (). + + + + Declaration of attribute sets of submodules + +options.mod = mkOption { + description = "submodule example"; + type = with types; attrsOf (submodule { + options = { + foo = mkOption { + type = int; + }; + bar = mkOption { + type = str; + }; + }; + }); +}; + + + + Declaration of attribute sets of submodules + +config.mod.one = { foo = 1; bar = "one"; }; +config.mod.two = { foo = 2; bar = "two"; }; + +
+ +
+ Extending types + + + Types are mainly characterized by their check and + merge functions. + + + + + + check + + + + 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 + addCheck function + (), or to fully + override the check function + (). + + + Adding a type check + +byte = mkOption { + description = "An integer between 0 and 255."; + type = addCheck types.int (x: x >= 0 && x <= 255); +}; + + + Overriding a type check + +nixThings = mkOption { + description = "words that start with 'nix'"; + type = types.str // { + check = (x: lib.hasPrefix "nix" x) + }; +}; + + + + + + merge + + + + Function to merge the options values when multiple values are set. The + function takes two parameters, loc the option path as + a list of strings, and defs the list of defined values + as a list. It is possible to override a type merge function for custom + needs. + + + + +
+ +
+ Custom Types + + + Custom types can be created with the mkOptionType + function. As type creation includes some more complex topics such as + submodule handling, it is recommended to get familiar with + types.nix + code before creating a new type. + + + + The only required parameter is name. + + + + + + name + + + + A string representation of the type function name. + + + + + + definition + + + + Description of the type used in documentation. Give information of the + type and any of its arguments. + + + + + + check + + + + A function to type check the definition value. Takes the definition value + as a parameter and returns a boolean indicating the type check result, + true for success and false for + failure. + + + + + + merge + + + + A function to merge multiple definitions values. Takes two parameters: + + + + + loc + + + + The option path as a list of strings, e.g. ["boot" "loader + "grub" "enable"]. + + + + + + defs + + + + The list of sets of defined value and + file where the value was defined, e.g. [ { + file = "/foo.nix"; value = 1; } { file = "/bar.nix"; value = 2 } + ]. The merge function should return the + merged value or throw an error in case the values are impossible or + not meant to be merged. + + + + + + + + + getSubOptions + + + + 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. prefix: + elemType.getSubOptions (prefix ++ + ["prefix"]) where + "prefix" is the newly added prefix. + + + + + + getSubModules + + + + 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 elemType, the function should just + recursively look into submodules by returning + elemType.getSubModules;. + + + + + + substSubModules + + + + 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 substSubModules, e.g for a type + composedType that take an elemtype + type parameter, this function should be defined as m: + composedType (elemType.substSubModules m). + + + + + + typeMerge + + + + A function to merge multiple type declarations. Takes the type to merge + functor as parameter. A null return + value means that type cannot be merged. + + + + + f + + + + The type to merge functor. + + + + + + Note: There is a generic defaultTypeMerge that work + with most of value and composed types. + + + + + + functor + + + + An attribute set representing the type. It is used for type operations + and has the following keys: + + + + + type + + + + The type function. + + + + + + wrapped + + + + Holds the type parameter for composed types. + + + + + + payload + + + + Holds the value parameter for value types. The types that have a + payload are the enum, + separatedString and submodule + types. + + + + + + binOp + + + + 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. + + + + + + + +
+
diff --git a/nixos/doc/manual/development/releases.xml b/nixos/doc/manual/development/releases.xml new file mode 100755 index 0000000..d4e5ff3 --- /dev/null +++ b/nixos/doc/manual/development/releases.xml @@ -0,0 +1,260 @@ + + Releases +
+ Release process + + + Going through an example of releasing NixOS 17.09: + + +
+ One month before the beta + + + + + Send an email to the nix-devel mailinglist as a warning about upcoming + beta "feature freeze" in a month. + + + + + 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. + + + +
+ +
+ At beta release time + + + + + Create + an issue for tracking Zero Hydra Failures progress. ZHF is an effort to + get build failures down to zero. + + + + + git tag -a -s -m "Release 17.09-beta" 17.09-beta + && git push --tags + + + + + From the master branch run git checkout -B + release-17.09. + + + + + + Make sure a channel is created at http://nixos.org/channels/. + + + + + + Let a GitHub nixpkgs admin lock the branch on github for you. (so + developers can’t force push) + + + + + + Bump the system.defaultChannel attribute in + nixos/modules/misc/version.nix + + + + + + Update versionSuffix in + nixos/release.nix, use git log + --format=%an|wc -l to get the commit count + + + + + echo -n "18.03" > .version on master. + + + + + + Pick a new name for the unstable branch. + + + + + Create a new release notes file for the upcoming release + 1, in this + case rl-1803.xml. + + + + + Create two Hydra jobsets: release-17.09 and release-17.09-small with + stableBranch set to false. + + + + + Edit changelog at + nixos/doc/manual/release-notes/rl-1709.xml (double + check desktop versions are noted) + + + + + Get all new NixOS modules git diff + release-17.03..release-17.09 nixos/modules/module-list.nix|grep + ^+ + + + + + Note systemd, kernel, glibc and Nix upgrades. + + + + + +
+ +
+ During Beta + + + + + Monitor the master branch for bugfixes and minor updates and cherry-pick + them to the release branch. + + + +
+ +
+ Before the final release + + + + + Re-check that the release notes are complete. + + + + + Release Nix (currently only Eelco Dolstra can do that). + + Make sure fallback is updated. + + + + + + Update README.md with new stable NixOS version information. + + + + + Change stableBranch to true and wait for channel to + update. + + + +
+ +
+ At final release time + + + + + git tag -s -a -m "Release 15.09" 15.09 + + + + + Update http://nixos.org/nixos/download.html and + http://nixos.org/nixos/manual in + https://github.com/NixOS/nixos-org-configurations + + + + + Get number of commits for the release: git log + release-14.04..release-14.12 --format=%an|wc -l + + + + + Commits by contributor: git log release-14.04..release-14.12 + --format=%an|sort|uniq -c|sort -rn + + + + + 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. + + + +
+
+
+ Release schedule + + + + + + + + + Date + + + Event + + + + + + + 2016-07-25 + + + Send email to nix-dev about upcoming branch-off + + + + + 2016-09-01 + + release-16.09 branch and corresponding jobsets are created, + change freeze + + + + + 2016-09-30 + + + NixOS 16.09 released + + + + + +
+ diff --git a/nixos/doc/manual/development/replace-modules.xml b/nixos/doc/manual/development/replace-modules.xml new file mode 100644 index 0000000..7b103c3 --- /dev/null +++ b/nixos/doc/manual/development/replace-modules.xml @@ -0,0 +1,79 @@ +
+ Replace Modules + + + 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. + + + + disabledModules is a top level attribute like + imports, options and + config. 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). + + + + 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. + + + +{ 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; +} + + + + 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. + + + +{ 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." ]; + }; +} + +
diff --git a/nixos/doc/manual/development/running-nixos-tests-interactively.xml b/nixos/doc/manual/development/running-nixos-tests-interactively.xml new file mode 100644 index 0000000..c15ad44 --- /dev/null +++ b/nixos/doc/manual/development/running-nixos-tests-interactively.xml @@ -0,0 +1,44 @@ +
+ Running Tests interactively + + + The test itself can be run interactively. This is particularly useful when + developing or debugging a test: + +$ nix-build nixos/tests/login.nix -A driver +$ ./result/bin/nixos-test-driver +starting VDE switch for network 1 +> + + You can then take any Perl statement, e.g. + +> startAll +> testScript +> $machine->succeed("touch /tmp/foo") +> print($machine->succeed("pwd")) # Show stdout of command + + The function testScript 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). + + + + To just start and experiment with the VMs, run: + +$ nix-build nixos/tests/login.nix -A driver +$ ./result/bin/nixos-run-vms + + The script nixos-run-vms starts the virtual machines + defined by test. + + + + The machine state is kept across VM restarts in + /tmp/vm-state-machinename. + +
diff --git a/nixos/doc/manual/development/running-nixos-tests.xml b/nixos/doc/manual/development/running-nixos-tests.xml new file mode 100644 index 0000000..eadbe1e --- /dev/null +++ b/nixos/doc/manual/development/running-nixos-tests.xml @@ -0,0 +1,36 @@ +
+ Running Tests + + + You can run tests using nix-build. For example, to run the + test + login.nix, + you just do: + +$ nix-build '<nixpkgs/nixos/tests/login.nix>' + + or, if you don’t want to rely on NIX_PATH: + +$ cd /my/nixpkgs/nixos/tests +$ nix-build login.nix +… +running the VM test script +machine: QEMU running (pid 8841) +… +6 out of 6 tests succeeded + + 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: + +$ firefox result/log.html + + +
diff --git a/nixos/doc/manual/development/sources.xml b/nixos/doc/manual/development/sources.xml new file mode 100644 index 0000000..eec9b56 --- /dev/null +++ b/nixos/doc/manual/development/sources.xml @@ -0,0 +1,86 @@ + + Getting the Sources + + By default, NixOS’s nixos-rebuild command uses the NixOS + and Nixpkgs sources provided by the nixos channel (kept in + /nix/var/nix/profiles/per-user/root/channels/nixos). To + modify NixOS, however, you should check out the latest sources from Git. This + is as follows: + +$ git clone https://github.com/NixOS/nixpkgs +$ cd nixpkgs +$ git remote add channels https://github.com/NixOS/nixpkgs-channels +$ git remote update channels + + This will check out the latest Nixpkgs sources to + ./nixpkgs the NixOS sources to + ./nixpkgs/nixos. (The NixOS source tree lives in a + subdirectory of the Nixpkgs repository.) The remote + channels refers to a read-only repository that tracks the + Nixpkgs/NixOS channels (see for more + information about channels). Thus, the Git branch + channels/nixos-17.03 will contain the latest built and + tested version available in the nixos-17.03 channel. + + + 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: + +$ nixos-version +17.09pre104379.6e0b727 (Hummingbird) + +$ git checkout -b local 6e0b727 + + Or, to base your local branch on the latest version available in a NixOS + channel: + +$ git remote update channels +$ git checkout -b local channels/nixos-17.03 + + (Replace nixos-17.03 with the name of the channel you want + to use.) You can use git merge or git + rebase to keep your local branch in sync with the channel, e.g. + +$ git remote update channels +$ git merge channels/nixos-17.03 + + You can use git cherry-pick to copy commits from your + local branch to the upstream branch. + + + If you want to rebuild your system using your (modified) sources, you need to + tell nixos-rebuild about them using the + flag: + +# nixos-rebuild switch -I nixpkgs=/my/sources/nixpkgs + + + + If you want nix-env to use the expressions in + /my/sources, use nix-env -f + /my/sources/nixpkgs, or change the + default by adding a symlink in ~/.nix-defexpr: + +$ ln -s /my/sources/nixpkgs ~/.nix-defexpr/nixpkgs + + You may want to delete the symlink + ~/.nix-defexpr/channels_root 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 ~/.nix-defexpr directory + completely, log out and log in again and it should have been recreated with a + link to the root channels. + + + diff --git a/nixos/doc/manual/development/testing-installer.xml b/nixos/doc/manual/development/testing-installer.xml new file mode 100644 index 0000000..63f5f3d --- /dev/null +++ b/nixos/doc/manual/development/testing-installer.xml @@ -0,0 +1,22 @@ + + Testing the Installer + + Building, burning, and booting from an installation CD is rather tedious, so + here is a quick way to see if the installer works properly: + +# mount -t tmpfs none /mnt +# nixos-generate-config --root /mnt +$ nix-build '<nixpkgs/nixos>' -A config.system.build.nixos-install +# ./result/bin/nixos-install + To start a login shell in the new NixOS installation in + /mnt: + +$ nix-build '<nixpkgs/nixos>' -A config.system.build.nixos-enter +# ./result/bin/nixos-enter + + + diff --git a/nixos/doc/manual/development/writing-documentation.xml b/nixos/doc/manual/development/writing-documentation.xml new file mode 100644 index 0000000..2183937 --- /dev/null +++ b/nixos/doc/manual/development/writing-documentation.xml @@ -0,0 +1,149 @@ + + Writing NixOS Documentation + + 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. + +
+ Building the Manual + + + The DocBook sources of the are in the + nixos/doc/manual + subdirectory of the Nixpkgs repository. + + + + You can quickly validate your edits with make: + + + + $ cd /path/to/nixpkgs/nixos/doc/manual + $ make + + + + Once you are done making modifications to the manual, it's important to + build it before committing. You can do that as follows: + + +nix-build nixos/release.nix -A manual.x86_64-linux + + + When this command successfully finishes, it will tell you where the manual + got generated. The HTML will be accessible through the + result symlink at + ./result/share/doc/nixos/index.html. + +
+
+ Editing DocBook XML + + + For general information on how to write in DocBook, see + DocBook + 5: The Definitive Guide. + + + + 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 + . + + + + Pandoc can generate DocBook XML + from a multitude of formats, which makes a good starting point. + + Pandoc invocation to convert GitHub-Flavoured MarkDown to DocBook 5 XML +pandoc -f markdown_github -t docbook5 docs.md -o my-section.md + + Pandoc can also quickly convert a single section.xml to + HTML, which is helpful when drafting. + + + + Sometimes writing valid DocBook is simply too difficult. In this case, + submit your documentation updates in a + GitHub + Issue and someone will handle the conversion to XML for you. + +
+
+ Creating a Topic + + + You can use an existing topic as a basis for the new topic or create a topic + from scratch. + + + + Keep the following guidelines in mind when you create and add a topic: + + + + The NixOS + book + element is in nixos/doc/manual/manual.xml. It + includes several + parts + which are in subdirectories. + + + + + Store the topic file in the same directory as the part to + which it belongs. If your topic is about configuring a NixOS module, then + the XML file can be stored alongside the module definition + nix file. + + + + + If you include multiple words in the file name, separate the words with a + dash. For example: ipv6-config.xml. + + + + + Make sure that the xml:id value is unique. You can use + abbreviations if the ID is too long. For example: + nixos-config. + + + + + 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. + + + + +
+
+ Adding a Topic to the Book + + + Open the parent XML file and add an xi:include element to + the list of chapters with the file name of the topic that you created. If + you created a section, you add the file to the chapter + file. If you created a chapter, you add the file to the + part file. + + + + If the topic is about configuring a NixOS module, it can be automatically + included in the manual by using the meta.doc attribute. + See for an explanation. + +
+ diff --git a/nixos/doc/manual/development/writing-modules.xml b/nixos/doc/manual/development/writing-modules.xml new file mode 100644 index 0000000..bbf793b --- /dev/null +++ b/nixos/doc/manual/development/writing-modules.xml @@ -0,0 +1,186 @@ + + Writing NixOS Modules + + NixOS has a modular system for declarative configuration. This system + combines multiple modules to produce the full system + configuration. One of the modules that constitute the configuration is + /etc/nixos/configuration.nix. Most of the others live in + the + nixos/modules + subdirectory of the Nixpkgs tree. + + + Each NixOS module is a file that handles one logical aspect of the + configuration, such as a specific kind of hardware, a service, or network + settings. A module configuration does not have to handle everything from + scratch; it can use the functionality provided by other modules for its + implementation. Thus a module can declare options that + can be used by other modules, and conversely can define + options provided by other modules in its own implementation. For example, the + module + pam.nix + declares the option that allows other + modules (e.g. + sshd.nix) + to define PAM services; and it defines the option + (declared by + etc.nix) + to cause files to be created in /etc/pam.d. + + + In , we saw the following structure + of NixOS modules: + +{ config, pkgs, ... }: + +{ option definitions +} + + This is actually an abbreviated form of module that only + defines options, but does not declare any. The structure of full NixOS + modules is shown in . + + + Structure of NixOS Modules + +{ config, pkgs, ... }: + +{ + imports = + [ paths of other modules + ]; + + options = { + option declarations + }; + + config = { + option definitions + }; +} + + + The meaning of each part is as follows. + + + + This line makes the current Nix expression a function. The variable + pkgs contains Nixpkgs, while config + contains the full system configuration. This line can be omitted if there + is no reference to pkgs and config + inside the module. + + + + + This list enumerates the paths to other NixOS modules that should be + included in the evaluation of the system configuration. A default set of + modules is defined in the file + modules/module-list.nix. These don't need to be added + in the import list. + + + + + The attribute options is a nested set of + option declarations (described below). + + + + + The attribute config is a nested set of + option definitions (also described below). + + + + + + shows a module that handles the regular + update of the “locate” database, an index of all files in the file + system. This module declares two options that can be defined by other modules + (typically the user’s configuration.nix): + (whether the database should be + updated) and (when the update + should be done). It implements its functionality by defining two options + declared by other modules: (the set of all + systemd services) and (the list of commands + to be executed periodically by systemd). + + + NixOS Module for the “locate” Service + +{ config, lib, pkgs, ... }: + +with lib; + +let + cfg = config.services.locate; +in { + options.services.locate = { + enable = mkOption { + type = types.bool; + default = false; + description = '' + If enabled, NixOS will periodically update the database of + files used by the locate command. + ''; + }; + + interval = mkOption { + type = types.str; + default = "02:15"; + example = "hourly"; + description = '' + Update the locate database at this interval. Updates by + default at 2:15 AM every day. + + The format is described in + systemd.time + 7. + ''; + }; + + # Other options omitted for documentation + }; + + config = { + systemd.services.update-locatedb = + { description = "Update Locate Database"; + path = [ pkgs.su ]; + script = + '' + mkdir -m 0755 -p $(dirname ${toString cfg.output}) + exec updatedb \ + --localuser=${cfg.localuser} \ + ${optionalString (!cfg.includeStore) "--prunepaths='/nix/store'"} \ + --output=${toString cfg.output} ${concatStringsSep " " cfg.extraFlags} + ''; + }; + + systemd.timers.update-locatedb = mkIf cfg.enable + { description = "Update timer for locate database"; + partOf = [ "update-locatedb.service" ]; + wantedBy = [ "timers.target" ]; + timerConfig.OnCalendar = cfg.interval; + }; + }; +} + + + + + + + + + + diff --git a/nixos/doc/manual/development/writing-nixos-tests.xml b/nixos/doc/manual/development/writing-nixos-tests.xml new file mode 100644 index 0000000..4a2615c --- /dev/null +++ b/nixos/doc/manual/development/writing-nixos-tests.xml @@ -0,0 +1,421 @@ +
+ Writing Tests + + + A NixOS test is a Nix expression that has the following structure: + +import ./make-test.nix { + + # Either the configuration of a single machine: + machine = + { config, pkgs, ... }: + { configuration… + }; + + # Or a set of machines: + nodes = + { machine1 = + { config, pkgs, ... }: { … }; + machine2 = + { config, pkgs, ... }: { … }; + … + }; + + testScript = + '' + Perl code… + ''; +} + + The attribute testScript 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 machine (if you need only one machine in your + test) or by the attribute nodes (if you need multiple + machines). For instance, + login.nix + 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, + nfs.nix, + 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. + + + + There are a few special NixOS configuration options for test VMs: + + + + + + + + + The memory of the VM in megabytes. + + + + + + + + + + The virtual networks to which the VM is connected. See + nat.nix + for an example. + + + + + + + + + + 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. + + + + + For more options, see the module + qemu-vm.nix. + + + + 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 + $name, where + name is the identifier of the machine (which is + just machine if you didn’t specify multiple machines + using the nodes 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: + +$machine->start; +$machine->waitForUnit("default.target"); +$machine->succeed("uname") =~ /Linux/ or die; + + The first line is actually unnecessary; machines are implicitly started when + you first execute an action on them (such as waitForUnit + or succeed). If you have multiple machines, you can speed + up the test by starting them in parallel: + +startAll; + + + + + The following methods are available on machine objects: + + + + start + + + + Start the virtual machine. This method is asynchronous — it does not + wait for the machine to finish booting. + + + + + + shutdown + + + + Shut down the machine, waiting for the VM to exit. + + + + + + crash + + + + Simulate a sudden power failure, by telling the VM to exit immediately. + + + + + + block + + + + Simulate unplugging the Ethernet cable that connects the machine to the + other machines. + + + + + + unblock + + + + Undo the effect of block. + + + + + + screenshot + + + + Take a picture of the display of the virtual machine, in PNG format. The + screenshot is linked from the HTML log. + + + + + + getScreenText + + + + Return a textual representation of what is currently visible on the + machine's screen using optical character recognition. + + + + This requires passing to the test attribute + set. + + + + + + + sendMonitorCommand + + + + 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. + + + + + + sendKeys + + + + Simulate pressing keys on the virtual keyboard, e.g., + sendKeys("ctrl-alt-delete"). + + + + + + sendChars + + + + Simulate typing a sequence of characters on the virtual keyboard, e.g., + sendKeys("foobar\n") will type the string + foobar followed by the Enter key. + + + + + + execute + + + + Execute a shell command, returning a list + (status, + stdout). + + + + + + succeed + + + + Execute a shell command, raising an exception if the exit status is not + zero, otherwise returning the standard output. + + + + + + fail + + + + Like succeed, but raising an exception if the + command returns a zero status. + + + + + + waitUntilSucceeds + + + + Repeat a shell command with 1-second intervals until it succeeds. + + + + + + waitUntilFails + + + + Repeat a shell command with 1-second intervals until it fails. + + + + + + waitForUnit + + + + Wait until the specified systemd unit has reached the “active” state. + + + + + + waitForFile + + + + Wait until the specified file exists. + + + + + + waitForOpenPort + + + + Wait until a process is listening on the given TCP port (on + localhost, at least). + + + + + + waitForClosedPort + + + + Wait until nobody is listening on the given TCP port. + + + + + + waitForX + + + + Wait until the X11 server is accepting connections. + + + + + + waitForText + + + + Wait until the supplied regular expressions matches the textual contents + of the screen by using optical character recognition (see + getScreenText). + + + + This requires passing to the test attribute + set. + + + + + + + waitForWindow + + + + Wait until an X11 window has appeared whose name matches the given + regular expression, e.g., waitForWindow(qr/Terminal/). + + + + + + copyFileFromHost + + + + Copies a file from host to machine, e.g., + copyFileFromHost("myfile", "/etc/my/important/file"). + + + 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. + + + + + + systemctl + + + + Runs systemctl commands with optional support for + systemctl --user + + + + $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` + + + + + + + + + To test user units declared by systemd.user.services the + optional $user argument can be used: + + $machine->start; + $machine->waitForX; + $machine->waitForUnit("xautolock.service", "x-session-user"); + + This applies to systemctl, getUnitInfo, + waitForUnit, startJob and + stopJob. + +
diff --git a/nixos/doc/manual/installation/changing-config.xml b/nixos/doc/manual/installation/changing-config.xml new file mode 100644 index 0000000..1a116ec --- /dev/null +++ b/nixos/doc/manual/installation/changing-config.xml @@ -0,0 +1,85 @@ + + Changing the Configuration + + The file /etc/nixos/configuration.nix contains the + current configuration of your machine. Whenever you’ve + changed something in that file, you + should do + +# nixos-rebuild switch + 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). + + + + These commands must be executed as root, so you should either run them from + a root shell or by prefixing them with sudo -i. + + + + You can also do + +# nixos-rebuild test + 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. + + + There is also + +# nixos-rebuild boot + 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). + + + You can make your configuration show up in a different submenu of the GRUB 2 + boot screen by giving it a different profile name, e.g. + +# nixos-rebuild switch -p test + which causes the new configuration (and previous ones created using + -p test) to show up in the GRUB submenu “NixOS - Profile + 'test'”. This can be useful to separate test configurations from + “stable” configurations. + + + Finally, you can do + +$ nixos-rebuild build + to build the configuration but nothing more. This is useful to see whether + everything compiles cleanly. + + + 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 + virtual machine that contains the desired configuration. + Just do + +$ nixos-rebuild build-vm +$ ./result/bin/run-*-vm + + 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 + mutableUsers = false. Another way is to temporarily add + the following to your configuration: + +users.users.your-user.initialHashedPassword = "test"; + + Important: 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): + +$ QEMU_NET_OPTS="hostfwd=tcp::2222-:22" ./result/bin/run-*-vm + + allowing you to log in via SSH (assuming you have set the appropriate + passwords or SSH authorized keys): + +$ ssh -p 2222 localhost + + + diff --git a/nixos/doc/manual/installation/installation.xml b/nixos/doc/manual/installation/installation.xml new file mode 100644 index 0000000..d4276be --- /dev/null +++ b/nixos/doc/manual/installation/installation.xml @@ -0,0 +1,17 @@ + + Installation + + + This section describes how to obtain, install, and configure NixOS for + first-time use. + + + + + + + diff --git a/nixos/doc/manual/installation/installing-behind-a-proxy.xml b/nixos/doc/manual/installation/installing-behind-a-proxy.xml new file mode 100644 index 0000000..8f9baff --- /dev/null +++ b/nixos/doc/manual/installation/installing-behind-a-proxy.xml @@ -0,0 +1,48 @@ +
+ Installing behind a proxy + + + To install NixOS behind a proxy, do the following before running + nixos-install. + + + + + + Update proxy configuration in + /mnt/etc/nixos/configuration.nix to keep the internet + accessible after reboot. + + +networking.proxy.default = "http://user:password@proxy:port/"; +networking.proxy.noProxy = "127.0.0.1,localhost,internal.domain"; + + + + + Setup the proxy environment variables in the shell where you are running + nixos-install. + + +# 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" + + + + + + + If you are switching networks with different proxy configurations, use the + nesting.clone option in + configuration.nix to switch proxies at runtime. Refer to + for more information. + + +
diff --git a/nixos/doc/manual/installation/installing-from-other-distro.xml b/nixos/doc/manual/installation/installing-from-other-distro.xml new file mode 100644 index 0000000..d1e49a2 --- /dev/null +++ b/nixos/doc/manual/installation/installing-from-other-distro.xml @@ -0,0 +1,356 @@ + +
+ Installing from another Linux distribution + + + 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: + + + + + + Install NixOS on another partition, from your existing Linux distribution + (without the use of a USB or optical device!) + + + + + Install NixOS on the same partition (in place!), from your existing + non-NixOS Linux distribution using NIXOS_LUSTRATE. + + + + + Install NixOS on your hard drive from the Live CD of any Linux + distribution. + + + + + + The first steps to all these are the same: + + + + + + Install the Nix package manager: + + + Short version: + + +$ curl https://nixos.org/nix/install | sh +$ . $HOME/.nix-profile/etc/profile.d/nix.sh # …or open a fresh shell + + More details in the + + Nix manual + + + + + Switch to the NixOS channel: + + + If you've just installed Nix on a non-NixOS distribution, you will be on + the nixpkgs channel by default. + + +$ nix-channel --list +nixpkgs https://nixos.org/channels/nixpkgs-unstable + + As that channel gets released without running the NixOS tests, it will be + safer to use the nixos-* channels instead: + + +$ nix-channel --add https://nixos.org/channels/nixos-version nixpkgs + + You may want to throw in a nix-channel --update for good + measure. + + + + + Install the NixOS installation tools: + + + You'll need nixos-generate-config and + nixos-install and we'll throw in some man pages and + nixos-enter 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.. + +$ nix-env -iE "_: with import <nixpkgs/nixos> { configuration = {}; }; with config.system.build; [ nixos-generate-config nixos-install nixos-enter manual.manpages ]" + + + + + The following 5 steps are only for installing NixOS to another partition. + For installing NixOS in place using NIXOS_LUSTRATE, + skip ahead. + + + + Prepare your target partition: + + + At this point it is time to prepare your target partition. Please refer to + the partitioning, file-system creation, and mounting steps of + + + + If you're about to install NixOS in place using + NIXOS_LUSTRATE there is nothing to do for this step. + + + + + Generate your NixOS configuration: + +$ sudo `which nixos-generate-config` --root /mnt + + You'll probably want to edit the configuration files. Refer to the + nixos-generate-config step in + for more + information. + + + 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 configuration.nix: + + + = '' + menuentry "Ubuntu" { + search --set=ubuntu --fs-uuid 3cc3e652-0c1f-4800-8451-033754f68e6e + configfile "($ubuntu)/boot/grub/grub.cfg" + } +''; + + (You can find the appropriate UUID for your partition in + /dev/disk/by-uuid) + + + + + Create the nixbld group and user on your original + distribution: + + +$ sudo groupadd -g 30000 nixbld +$ sudo useradd -u 30000 -g nixbld -G nixbld nixbld + + + + Download/build/install NixOS: + + + + 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. + + +$ sudo PATH="$PATH" NIX_PATH="$NIX_PATH" `which nixos-install` --root /mnt + + Again, please refer to the nixos-install step in + for more information. + + + That should be it for installation to another partition! + + + + + Optionally, you may want to clean up your non-NixOS distribution: + + +$ sudo userdel nixbld +$ sudo groupdel nixbld + + If you do not wish to keep the Nix package manager installed either, run + something like sudo rm -rv ~/.nix-* /nix and remove the + line that the Nix installer added to your ~/.profile. + + + + + + The following steps are only for installing NixOS in place using + NIXOS_LUSTRATE: + + + + Generate your NixOS configuration: + +$ sudo `which nixos-generate-config` --root / + + Note that this will place the generated configuration files in + /etc/nixos. You'll probably want to edit the + configuration files. Refer to the nixos-generate-config + step in for more + information. + + + 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 sudo passwd -l root if you + use sudo) + + +users.users.root.initialHashedPassword = ""; + + + + + Build the NixOS closure and install it in the system + profile: + +$ nix-env -p /nix/var/nix/profiles/system -f '<nixpkgs/nixos>' -I nixos-config=/etc/nixos/configuration.nix -iA system + + + + Change ownership of the /nix tree to root (since your + Nix install was probably single user): + +$ sudo chown -R 0.0 /nix + + + + Set up the /etc/NIXOS and + /etc/NIXOS_LUSTRATE files: + + + /etc/NIXOS officializes that this is now a NixOS + partition (the bootup scripts require its presence). + + + /etc/NIXOS_LUSTRATE tells the NixOS bootup scripts to + move everything that's in the root partition to + /old-root. 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: + + + + + The /nix directory + + + + + The /boot directory + + + + + Any file or directory listed in /etc/NIXOS_LUSTRATE + (one per line) + + + + + + Support for NIXOS_LUSTRATE was added in NixOS 16.09. + The act of "lustrating" refers to the wiping of the existing distribution. + Creating /etc/NIXOS_LUSTRATE can also be used on NixOS + to remove all mutable files from your root partition (anything that's not + in /nix or /boot gets "lustrated" on + the next boot. + + + lustrate /ˈlʌstreɪt/ verb. + + + purify by expiatory sacrifice, ceremonial washing, or some other ritual + action. + + + + Let's create the files: + + +$ sudo touch /etc/NIXOS +$ sudo touch /etc/NIXOS_LUSTRATE + + + Let's also make sure the NixOS configuration files are kept once we reboot + on NixOS: + + +$ echo etc/nixos | sudo tee -a /etc/NIXOS_LUSTRATE + + + + + Finally, move the /boot 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: + + + + 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. + + + +$ sudo mv -v /boot /boot.bak && + sudo /nix/var/nix/profiles/system/bin/switch-to-configuration boot + + Cross your fingers, reboot, hopefully you should get a NixOS prompt! + + + + + 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: + + +# 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 + + This may work as is or you might also need to reinstall the boot loader + + + And of course, if you're happy with NixOS and no longer need the old + distribution: + +sudo rm -rf /old-root + + + + 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, + nixos-infect + uses the lustrate process to convert Digital Ocean droplets to NixOS from + other distributions automatically. + + + +
diff --git a/nixos/doc/manual/installation/installing-pxe.xml b/nixos/doc/manual/installation/installing-pxe.xml new file mode 100644 index 0000000..94199e5 --- /dev/null +++ b/nixos/doc/manual/installation/installing-pxe.xml @@ -0,0 +1,50 @@ +
+ Booting from the <quote>netboot</quote> media (PXE) + + + Advanced users may wish to install NixOS using an existing PXE or iPXE setup. + + + + 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: + + + +nix-build -A netboot nixos/release.nix + + + + This will create a result directory containing: * + bzImage – the Linux kernel * initrd + – the initrd file * netboot.ipxe – an example ipxe + script demonstrating the appropriate kernel command line arguments for this + image + + + + If you’re using plain PXE, configure your boot loader to use the + bzImage and initrd files and have it + provide the same kernel command line arguments found in + netboot.ipxe. + + + + If you’re using iPXE, depending on how your HTTP/FTP/etc. server is + configured you may be able to use netboot.ipxe unmodified, + or you may need to update the paths to the files to match your server’s + directory layout + + + + 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. + +
diff --git a/nixos/doc/manual/installation/installing-usb.xml b/nixos/doc/manual/installation/installing-usb.xml new file mode 100644 index 0000000..0b31118 --- /dev/null +++ b/nixos/doc/manual/installation/installing-usb.xml @@ -0,0 +1,40 @@ +
+ Booting from a USB Drive + + + For systems without CD drive, the NixOS live CD can be booted from a USB + stick. You can use the dd utility to write the image: + dd if=path-to-image + of=/dev/sdX. Be careful about specifying + the correct drive; you can use the lsblk command to get a + list of block devices. + + On macOS + + +$ diskutil list +[..] +/dev/diskN (external, physical): + #: TYPE NAME SIZE IDENTIFIER +[..] +$ diskutil unmountDisk diskN +Unmount of all volumes on diskN was successful +$ sudo dd bs=1m if=nix.iso of=/dev/rdiskN + + Using the 'raw' rdiskN device instead of + diskN completes in minutes instead of hours. After + dd completes, a GUI dialog "The disk you inserted was + not readable by this computer" will pop up, which can be ignored. + + + + + + The dd utility will write the image verbatim to the drive, + making it the recommended option for both UEFI and non-UEFI installations. + +
diff --git a/nixos/doc/manual/installation/installing-virtualbox-guest.xml b/nixos/doc/manual/installation/installing-virtualbox-guest.xml new file mode 100644 index 0000000..da78b48 --- /dev/null +++ b/nixos/doc/manual/installation/installing-virtualbox-guest.xml @@ -0,0 +1,99 @@ +
+ Installing in a VirtualBox guest + + + 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 + the downloads + page. If you want to set up a VirtualBox guest manually, follow these + instructions: + + + + + + Add a New Machine in VirtualBox with OS Type "Linux / Other Linux" + + + + + Base Memory Size: 768 MB or higher. + + + + + New Hard Disk of 8 GB or higher. + + + + + Mount the CD-ROM with the NixOS ISO (by clicking on CD/DVD-ROM) + + + + + Click on Settings / System / Processor and enable PAE/NX + + + + + Click on Settings / System / Acceleration and enable "VT-x/AMD-V" + acceleration + + + + + Save the settings, start the virtual machine, and continue installation + like normal + + + + + + There are a few modifications you should make in configuration.nix. Enable + booting: + + + + = "/dev/sda"; + + + + Also remove the fsck that runs at startup. It will always fail to run, + stopping your boot until you press *. + + + + = false; + + + + 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 + /etc/nixos/configuration.nix to auto-mount them: + + + +{ config, pkgs, ...} : +{ + ... + + fileSystems."/virtualboxshare" = { + fsType = "vboxsf"; + device = "nameofthesharedfolder"; + options = [ "rw" ]; + }; +} + + + + The folder will be available directly under the root directory. + +
diff --git a/nixos/doc/manual/installation/installing.xml b/nixos/doc/manual/installation/installing.xml new file mode 100644 index 0000000..8e94f94 --- /dev/null +++ b/nixos/doc/manual/installation/installing.xml @@ -0,0 +1,558 @@ + + Installing NixOS +
+ Booting the system + + + NixOS can be installed on BIOS or UEFI systems. The procedure for a UEFI + installation is by and large the same as a BIOS installation. The + differences are mentioned in the steps that follow. + + + + The installation media can be burned to a CD, or now more commonly, "burned" + to a USB drive (see ). + + + + The installation media contains a basic NixOS installation. When it’s + finished booting, it should have detected most of your hardware. + + + + The NixOS manual is available on virtual console 8 (press Alt+F8 to access) + or by running nixos-help. + + + + You are logged-in automatically as root. (The + root user account has an empty password.) + + + + If you downloaded the graphical ISO image, you can run systemctl + start display-manager to start KDE. If you want to continue on the + terminal, you can use loadkeys to switch to your + preferred keyboard layout. (We even provide neo2 via loadkeys de + neo!) + + +
+ Networking in the installer + + + The boot process should have brought up networking (check ip + a). Networking is necessary for the installer, since it will + download lots of stuff (such as source tarballs or Nixpkgs channel + binaries). It’s best if you have a DHCP server on your network. Otherwise + configure networking manually using ifconfig. + + + + To manually configure the network on the graphical installer, first disable + network-manager with systemctl stop network-manager. + + + + To manually configure the wifi on the minimal installer, run + wpa_supplicant -B -i interface -c <(wpa_passphrase 'SSID' + 'key'). + + + + If you would like to continue the installation from a different machine you + need to activate the SSH daemon via systemctl start + sshd. In order to be able to login you also need to set a + password for root using passwd. + +
+
+
+ Partitioning and formatting + + + The NixOS installer doesn’t do any partitioning or formatting, so you need + to do that yourself. + + + + The NixOS installer ships with multiple partitioning tools. The examples + below use parted, but also provides + fdisk, gdisk, + cfdisk, and cgdisk. + + + + The recommended partition scheme differs depending if the computer uses + Legacy Boot or UEFI. + + +
+ UEFI (GPT) + + + Here's an example partition scheme for UEFI, using + /dev/sda as the device. + + + You can safely ignore parted's informational message + about needing to update /etc/fstab. + + + + + + + + + Create a GPT partition table. +# parted /dev/sda -- mklabel gpt + + + + + Add the root partition. This will fill the disk + except for the end part, where the swap will live, and the space left in + front (512MiB) which will be used by the boot partition. +# parted /dev/sda -- mkpart primary 512MiB -8GiB + + + + + Next, add a swap partition. The size required will + vary according to needs, here a 8GiB one is created. +# parted /dev/sda -- mkpart primary linux-swap -8GiB 100% + + + The swap partition size rules are no different than for other Linux + distributions. + + + + + + + Finally, the boot partition. NixOS by default uses + the ESP (EFI system partition) as its /boot + partition. It uses the initially reserved 512MiB at the start of the + disk. +# parted /dev/sda -- mkpart ESP fat32 1MiB 512MiB +# parted /dev/sda -- set 3 boot on + + + + + + + Once complete, you can follow with + . + +
+ +
+ Legacy Boot (MBR) + + + Here's an example partition scheme for Legacy Boot, using + /dev/sda as the device. + + + You can safely ignore parted's informational message + about needing to update /etc/fstab. + + + + + + + + + Create a MBR partition table. +# parted /dev/sda -- mklabel msdos + + + + + Add the root partition. This will fill the the disk + except for the end part, where the swap will live. +# parted /dev/sda -- mkpart primary 1MiB -8GiB + + + + + Finally, add a swap partition. The size required + will vary according to needs, here a 8GiB one is created. +# parted /dev/sda -- mkpart primary linux-swap -8GiB 100% + + + The swap partition size rules are no different than for other Linux + distributions. + + + + + + + + + Once complete, you can follow with + . + +
+ +
+ Formatting + + + Use the following commands: + + + + For initialising Ext4 partitions: mkfs.ext4. It is + recommended that you assign a unique symbolic label to the file system + using the option , + since this makes the file system configuration independent from device + changes. For example: + +# mkfs.ext4 -L nixos /dev/sda1 + + + + + For creating swap partitions: mkswap. Again it’s + recommended to assign a label to the swap partition: . For example: + +# mkswap -L swap /dev/sda2 + + + + + + + UEFI systems + + + + For creating boot partitions: mkfs.fat. Again + it’s recommended to assign a label to the boot partition: + . For example: + +# mkfs.fat -F 32 -n boot /dev/sda3 + + + + + + + + For creating LVM volumes, the LVM commands, e.g., + pvcreate, vgcreate, and + lvcreate. + + + + + For creating software RAID devices, use mdadm. + + + + +
+
+
+ Installing + + + + + Mount the target file system on which NixOS should be installed on + /mnt, e.g. + +# mount /dev/disk/by-label/nixos /mnt + + + + + + + + UEFI systems + + + + Mount the boot file system on /mnt/boot, e.g. + +# mkdir -p /mnt/boot +# mount /dev/disk/by-label/boot /mnt/boot + + + + + + + + + If your machine has a limited amount of memory, you may want to activate + swap devices now (swapon + device). The installer (or rather, + the build actions that it may spawn) may need quite a bit of RAM, + depending on your configuration. + +# swapon /dev/sda2 + + + + + You now need to create a file + /mnt/etc/nixos/configuration.nix that specifies the + intended configuration of the system. This is because NixOS has a + declarative configuration model: you create or edit a + description of the desired configuration of your system, and then NixOS + takes care of making it happen. The syntax of the NixOS configuration file + is described in , while a list + of available configuration options appears in + . A minimal example is shown in + . + + + The command nixos-generate-config can generate an + initial configuration file for you: + +# nixos-generate-config --root /mnt + You should then edit /mnt/etc/nixos/configuration.nix + to suit your needs: + +# nano /mnt/etc/nixos/configuration.nix + + If you’re using the graphical ISO image, other editors may be available + (such as vim). If you have network access, you can also + install other editors — for instance, you can install Emacs by running + nix-env -i emacs. + + + + + BIOS systems + + + + You must set the option + to specify on which disk + the GRUB boot loader is to be installed. Without it, NixOS cannot boot. + + + + + + UEFI systems + + + + You must set the option + to + true. nixos-generate-config + should do this automatically for new configurations when booted in UEFI + mode. + + + You may want to look at the options starting with + + and + + as well. + + + + + + If there are other operating systems running on the machine before + installing NixOS, the + option can be set to true to automatically add them to + the grub menu. + + + Another critical option is , specifying the + file systems that need to be mounted by NixOS. However, you typically + don’t need to set it yourself, because + nixos-generate-config sets it automatically in + /mnt/etc/nixos/hardware-configuration.nix from your + currently mounted file systems. (The configuration file + hardware-configuration.nix is included from + configuration.nix and will be overwritten by future + invocations of nixos-generate-config; thus, you + generally should not modify it.) + + + + Depending on your hardware configuration or type of file system, you may + need to set the option to + include the kernel modules that are necessary for mounting the root file + system, otherwise the installed system will not be able to boot. (If this + happens, boot from the installation media again, mount the target file + system on /mnt, fix + /mnt/etc/nixos/configuration.nix and rerun + nixos-install.) In most cases, + nixos-generate-config will figure out the required + modules. + + + + + + Do the installation: + +# nixos-install + 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 nixos-install. Otherwise, fix your + configuration.nix and then re-run + nixos-install. + + + As the last step, nixos-install will ask you to set the + password for the root user, e.g. + +setting root password... +Enter new UNIX password: *** +Retype new UNIX password: *** + + + For unattended installations, it is possible to use + nixos-install --no-root-passwd in order to disable + the password prompt entirely. + + + + + + + If everything went well: + +# reboot + + + + + You should now be able to boot into the installed NixOS. The GRUB boot + menu shows a list of available configurations + (initially just one). Every time you change the NixOS configuration (see + Changing Configuration + ), a new item is added to the menu. This allows you to easily roll back to + a previous configuration if something goes wrong. + + + You should log in and change the root password with + passwd. + + + You’ll probably want to create some user accounts as well, which can be + done with useradd: + +$ useradd -c 'Eelco Dolstra' -m eelco +$ passwd eelco + + + You may also want to install some software. For instance, + +$ nix-env -qa \* + shows what packages are available, and + +$ nix-env -i w3m + install the w3m browser. + + + +
+
+ Installation summary + + + To summarise, shows a typical + sequence of commands for installing NixOS on an empty hard drive (here + /dev/sda). shows a + corresponding configuration Nix expression. + + + + Example partition schemes for NixOS on <filename>/dev/sda</filename> (MBR) + +# parted /dev/sda -- mklabel msdos +# parted /dev/sda -- mkpart primary 1MiB -8GiB +# parted /dev/sda -- mkpart primary linux-swap -8GiB 100% + + + + Example partition schemes for NixOS on <filename>/dev/sda</filename> (UEFI) + +# parted /dev/sda -- mklabel gpt +# parted /dev/sda -- mkpart primary 512MiB -8GiB +# parted /dev/sda -- mkpart primary linux-swap -8GiB 100% +# parted /dev/sda -- mkpart ESP fat32 1MiB 512MiB +# parted /dev/sda -- set 3 boot on + + + + Commands for Installing NixOS on <filename>/dev/sda</filename> + + With a partitioned disk. + +# mkfs.ext4 -L nixos /dev/sda1 +# mkswap -L swap /dev/sda2 +# swapon /dev/sda2 +# mkfs.fat -F 32 -n boot /dev/sda3 # (for UEFI systems only) +# mount /dev/disk/by-label/nixos /mnt +# mkdir -p /mnt/boot # (for UEFI systems only) +# mount /dev/disk/by-label/boot /mnt/boot # (for UEFI systems only) +# nixos-generate-config --root /mnt +# nano /mnt/etc/nixos/configuration.nix +# nixos-install +# reboot + + + + + NixOS Configuration + +{ config, pkgs, ... }: { + imports = [ + # Include the results of the hardware scan. + ./hardware-configuration.nix + ]; + + = "/dev/sda"; # (for BIOS systems only) + = true; # (for UEFI systems only) + + # Note: setting fileSystems is generally not + # necessary, since nixos-generate-config figures them out + # automatically in hardware-configuration.nix. + #fileSystems."/".device = "/dev/disk/by-label/nixos"; + + # Enable the OpenSSH server. + services.sshd.enable = true; +} + + +
+
+ Additional installation notes + + + + + + + + + + +
+ diff --git a/nixos/doc/manual/installation/obtaining.xml b/nixos/doc/manual/installation/obtaining.xml new file mode 100644 index 0000000..56af5c0 --- /dev/null +++ b/nixos/doc/manual/installation/obtaining.xml @@ -0,0 +1,54 @@ + + Obtaining NixOS + + NixOS ISO images can be downloaded from the + NixOS download + page. 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. describes the + preferred method to prepare a USB stick. A number of alternative methods are + presented in the + NixOS + Wiki. + + + As an alternative to installing NixOS yourself, you can get a running NixOS + system through several other means: + + + + Using virtual appliances in Open Virtualization Format (OVF) that can be + imported into VirtualBox. These are available from the + NixOS download + page. + + + + + Using AMIs for Amazon’s EC2. To find one for your region and instance + type, please refer to the + list + of most recent AMIs. + + + + + Using NixOps, the NixOS-based cloud deployment tool, which allows you to + provision VirtualBox and EC2 NixOS instances from declarative + specifications. Check out the + NixOps homepage for + details. + + + + + diff --git a/nixos/doc/manual/installation/upgrading.xml b/nixos/doc/manual/installation/upgrading.xml new file mode 100644 index 0000000..69668b1 --- /dev/null +++ b/nixos/doc/manual/installation/upgrading.xml @@ -0,0 +1,134 @@ + + Upgrading NixOS + + The best way to keep your NixOS installation up to date is to use one of the + NixOS channels. 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: + + + + Stable channels, such as + nixos-17.03. + These only get conservative bug fixes and package upgrades. For instance, + a channel update may cause the Linux kernel on your system to be upgraded + from 4.9.16 to 4.9.17 (a minor bug fix), but not from + 4.9.x to 4.11.x (a + major change that has the potential to break things). Stable channels are + generally maintained until the next stable branch is created. + + + + + + The unstable channel, + nixos-unstable. + This corresponds to NixOS’s main development branch, and may thus see + radical changes between channel updates. It’s not recommended for + production systems. + + + + + Small channels, such as + nixos-17.03-small + or + nixos-unstable-small. + 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. + + + + To see what channels are available, go to + . (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 + to find the newest + supported stable release. + + + When you first install NixOS, you’re automatically subscribed to the NixOS + channel that corresponds to your installation source. For instance, if you + installed from a 17.03 ISO, you will be subscribed to the + nixos-17.03 channel. To see which NixOS channel you’re + subscribed to, run the following as root: + +# nix-channel --list | grep nixos +nixos https://nixos.org/channels/nixos-unstable + + To switch to a different NixOS channel, do + +# nix-channel --add https://nixos.org/channels/channel-name nixos + + (Be sure to include the nixos parameter at the end.) For + instance, to use the NixOS 17.03 stable channel: + +# nix-channel --add https://nixos.org/channels/nixos-17.03 nixos + + If you have a server, you may want to use the “small” channel instead: + +# nix-channel --add https://nixos.org/channels/nixos-17.03-small nixos + + And if you want to live on the bleeding edge: + +# nix-channel --add https://nixos.org/channels/nixos-unstable nixos + + + + You can then upgrade NixOS to the latest version in your chosen channel by + running + +# nixos-rebuild switch --upgrade + + which is equivalent to the more verbose nix-channel --update nixos; + nixos-rebuild switch. + + + + Channels are set per user. This means that running nix-channel + --add as a non root user (or without sudo) will not affect + configuration in /etc/nixos/configuration.nix + + + + + 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. + + +
+ Automatic Upgrades + + + You can keep a NixOS system up-to-date automatically by adding the following + to configuration.nix: + + = true; + + This enables a periodically executed systemd service named + nixos-upgrade.service. It runs nixos-rebuild + switch --upgrade to upgrade NixOS to the latest version in the + current channel. (To see when the service runs, see systemctl + list-timers.) You can also specify a channel explicitly, e.g. + + = https://nixos.org/channels/nixos-17.03; + + +
+ diff --git a/nixos/doc/manual/man-configuration.xml b/nixos/doc/manual/man-configuration.xml new file mode 100644 index 0000000..9f30b79 --- /dev/null +++ b/nixos/doc/manual/man-configuration.xml @@ -0,0 +1,31 @@ + + + configuration.nix + 5 + NixOS + + + + configuration.nix + NixOS system configuration specification + + + Description + + The file /etc/nixos/configuration.nix contains the + declarative specification of your NixOS system configuration. The command + nixos-rebuild takes this file and realises the system + configuration specified therein. + + + + Options + + You can use the following options in configuration.nix. + + + + diff --git a/nixos/doc/manual/man-nixos-build-vms.xml b/nixos/doc/manual/man-nixos-build-vms.xml new file mode 100644 index 0000000..87e4f3d --- /dev/null +++ b/nixos/doc/manual/man-nixos-build-vms.xml @@ -0,0 +1,120 @@ + + + nixos-build-vms + 8 + NixOS + + + + nixos-build-vms + build a network of virtual machines from a network of NixOS configurations + + + + nixos-build-vms + + + + + + + + + + + + + + network.nix + + + + + Description + + 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 bin/run-vms shell script + that is generated by this command. By default, a result + symlink is produced that points to the generated virtual network. + + + A network Nix expression has the following structure: + +{ + 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 + }; +} + + Each attribute in the expression represents a machine in the network (e.g. + test1 and test2) referring to a + function defining a NixOS configuration. In each NixOS configuration, two + attributes have a special meaning. The + deployment.targetHost specifies the address (domain name + or IP address) of the system which is used by ssh to + perform remote deployment operations. The + nixpkgs.localSystem.system attribute can be used to + specify an architecture for the target machine, such as + i686-linux which builds a 32-bit NixOS configuration. + Omitting this property will build the configuration for the same + architecture as the host system. + + + + Options + + This command accepts the following options: + + + + + + + + + Shows a trace of the output. + + + + + + + + + + Do not create a 'result' symlink. + + + + + + , + + + + Shows the usage of this command to the user. + + + + + + diff --git a/nixos/doc/manual/man-nixos-enter.xml b/nixos/doc/manual/man-nixos-enter.xml new file mode 100644 index 0000000..42edaa1 --- /dev/null +++ b/nixos/doc/manual/man-nixos-enter.xml @@ -0,0 +1,138 @@ + + + nixos-enter + 8 + NixOS + + + + nixos-enter + run a command in a NixOS chroot environment + + + + nixos-enter + + + + + root + + + + + + + system + + + + + + + shell-command + + + + + + + + + + + + + arguments + + + + + Description + + This command runs a command in a NixOS chroot environment, that is, in a + filesystem hierarchy previously prepared using + nixos-install. + + + + Options + + This command accepts the following options: + + + + + + + + + The path to the NixOS system you want to enter. It defaults to + /mnt. + + + + + + + + + + The NixOS system configuration to use. It defaults to + /nix/var/nix/profiles/system. You can enter a + previous NixOS configuration by specifying a path such as + /nix/var/nix/profiles/system-106-link. + + + + + + + + + + + + + The bash command to execute. + + + + + + + + + + Interpret the remaining arguments as the program name and arguments to be + invoked. The program is not executed in a shell. + + + + + + + Examples + + Start an interactive shell in the NixOS installation in + /mnt: + + +# nixos-enter /mnt + + + Run a shell command: + + +# nixos-enter -c 'ls -l /; cat /proc/mounts' + + + Run a non-shell command: + + +# nixos-enter -- cat /proc/mounts + + + diff --git a/nixos/doc/manual/man-nixos-generate-config.xml b/nixos/doc/manual/man-nixos-generate-config.xml new file mode 100644 index 0000000..43d6c26 --- /dev/null +++ b/nixos/doc/manual/man-nixos-generate-config.xml @@ -0,0 +1,214 @@ + + + nixos-generate-config + 8 + NixOS + + + + nixos-generate-config + generate NixOS configuration modules + + + + nixos-generate-config + + + + + + + + + root + + + + + + + dir + + + + + Description + + This command writes two NixOS configuration modules: + + + + + + + + This module sets NixOS configuration options based on your current + hardware configuration. In particular, it sets the + option to reflect all currently mounted file + systems, the option to reflect active swap + devices, and the options to ensure that + the initial ramdisk contains any kernel modules necessary for mounting + the root file system. + + + If this file already exists, it is overwritten. Thus, you should not + modify it manually. Rather, you should include it from your + /etc/nixos/configuration.nix, and re-run + nixos-generate-config to update it whenever your + hardware configuration changes. + + + + + + + + + + This is the main NixOS system configuration module. If it already + exists, it’s left unchanged. Otherwise, + nixos-generate-config will write a template for you + to customise. + + + + + + + + Options + + This command accepts the following options: + + + + + + + + + If this option is given, treat the directory + root as the root of the file system. This + means that configuration files will be written to + root/etc/nixos, and that + any file systems outside of root are ignored + for the purpose of generating the option. + + + + + + + + + + If this option is given, write the configuration files to the directory + dir instead of + /etc/nixos. + + + + + + + + + + Overwrite /etc/nixos/configuration.nix if it already + exists. + + + + + + + + + + Omit everything concerning file systems and swap devices from the + hardware configuration. + + + + + + + + + + Don't generate configuration.nix or + hardware-configuration.nix and print the hardware + configuration to stdout only. + + + + + + + Examples + + 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 /mnt and + /mnt/boot, you would run: + +$ nixos-generate-config --root /mnt + + The resulting file + /mnt/etc/nixos/hardware-configuration.nix might look + like this: + +# 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; +} + + It will also create a basic + /mnt/etc/nixos/configuration.nix, which you should edit + to customise the logical configuration of your system. This file includes + the result of the hardware scan as follows: + + imports = [ ./hardware-configuration.nix ]; + + + + After installation, if your hardware configuration changes, you can run: + +$ nixos-generate-config + + to update /etc/nixos/hardware-configuration.nix. Your + /etc/nixos/configuration.nix will + not be overwritten. + + + diff --git a/nixos/doc/manual/man-nixos-install.xml b/nixos/doc/manual/man-nixos-install.xml new file mode 100644 index 0000000..25f4f40 --- /dev/null +++ b/nixos/doc/manual/man-nixos-install.xml @@ -0,0 +1,267 @@ + + + nixos-install + 8 + NixOS + + + + nixos-install + install bootloader and NixOS + + + + nixos-install + + + + + path + + + + + + + root + + + + + + + path + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + number + + + + number + + + + name value + + + + + + + + + + + + + + + + + Description + + This command installs NixOS in the file system mounted on + /mnt, based on the NixOS configuration specified in + /mnt/etc/nixos/configuration.nix. It performs the + following steps: + + + + It copies Nix and its dependencies to + /mnt/nix/store. + + + + + It runs Nix in /mnt to build the NixOS configuration + specified in /mnt/etc/nixos/configuration.nix. + + + + + It installs the GRUB boot loader on the device specified in the option + (unless + is specified), and generates a GRUB + configuration file that boots into the NixOS configuration just + installed. + + + + + It prompts you for a password for the root account (unless + is specified). + + + + + + 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. + + + + Options + + This command accepts the following options: + + + + + + + + + Defaults to /mnt. If this option is given, treat the + directory root as the root of the NixOS + installation. + + + + + + + + + + If this option is provided, nixos-install will install + the specified closure rather than attempt to build one from + /mnt/etc/nixos/configuration.nix. + + + 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 nix-build + -I nixos-config=./configuration.nix '<nixos>' -A system + --no-out-link + + + + + + + + + + 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 + -I take precedence over NIX_PATH. + + + + + + + + + + + + + Sets the maximum number of build jobs that Nix will perform in parallel + to the specified number. The default is 1. A higher + value is useful on SMP systems or to exploit I/O latency. + + + + + + + + + + Sets the value of the NIX_BUILD_CORES 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 + enableParallelBuilding is set to + true, the builder passes the + flag to GNU Make. The + value 0 means that the builder should use all + available CPU cores in the system. + + + + + + name value + + + + Set the Nix configuration option name to + value. + + + + + + + + + + Causes Nix to print out a stack trace in case of Nix expression + evaluation errors. + + + + + + + + + + Synonym for man nixos-install. + + + + + + + Examples + + A typical NixOS installation is done by creating and mounting a file system + on /mnt, generating a NixOS configuration in + /mnt/etc/nixos/configuration.nix, and running + nixos-install. For instance, if we want to install NixOS + on an ext4 file system created in + /dev/sda1: + +$ mkfs.ext4 /dev/sda1 +$ mount /dev/sda1 /mnt +$ nixos-generate-config --root /mnt +$ # edit /mnt/etc/nixos/configuration.nix +$ nixos-install +$ reboot + + + + diff --git a/nixos/doc/manual/man-nixos-option.xml b/nixos/doc/manual/man-nixos-option.xml new file mode 100644 index 0000000..d436cce --- /dev/null +++ b/nixos/doc/manual/man-nixos-option.xml @@ -0,0 +1,137 @@ + + + nixos-option + 8 + NixOS + + + + nixos-option + inspect a NixOS configuration + + + + nixos-option + + path + + + + + + + + + + + + option.name + + + + + Description + + This command evaluates the configuration specified in + /etc/nixos/configuration.nix and returns the properties + of the option name given as argument. + + + When the option name is not an option, the command prints the list of + attributes contained in the attribute set. + + + + Options + + This command accepts the following options: + + + + + path + + + + This option is passed to the underlying + nix-instantiate invocation. + + + + + + + + + + This option enables verbose mode, which currently is just the Bash + set debug mode. + + + + + + + + + + This option causes the output to be rendered as XML. + + + + + + + Environment + + + + NIXOS_CONFIG + + + + Path to the main NixOS configuration module. Defaults to + /etc/nixos/configuration.nix. + + + + + + + Examples + + Investigate option values: +$ nixos-option boot.loader +This attribute set contains: +generationsDir +grub +initScript + +$ 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" + + + + + Bugs + + The author listed in the following section is wrong. If there is any other + bug, please report to Nicolas Pierron. + + + diff --git a/nixos/doc/manual/man-nixos-rebuild.xml b/nixos/doc/manual/man-nixos-rebuild.xml new file mode 100644 index 0000000..551a65f --- /dev/null +++ b/nixos/doc/manual/man-nixos-rebuild.xml @@ -0,0 +1,468 @@ + + + nixos-rebuild + 8 + NixOS + + + + nixos-rebuild + reconfigure a NixOS machine + + + + nixos-rebuild + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + name + + + + + + + + + Description + + This command updates the system so that it corresponds to the configuration + specified in /etc/nixos/configuration.nix. Thus, every + time you modify /etc/nixos/configuration.nix or any + NixOS module, you must run nixos-rebuild to make the + changes take effect. It builds the new system in + /nix/store, runs its activation script, and stop and + (re)starts any system services if needed. + + + This command has one required argument, which specifies the desired + operation. It must be one of the following: + + + + + + + + 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 + nixos-rebuild switch or nixos-rebuild + boot remain available in the GRUB menu. + + + + + + + + + + Build the new configuration and make it the boot default (as with + nixos-rebuild switch), but do not activate it. That + is, the system continues to run the previous configuration until the + next reboot. + + + + + + + + + + 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 nixos-rebuild + switch or nixos-rebuild boot). + + + + + + + + + + Build the new configuration, but neither activate it nor add it to the + GRUB boot menu. It leaves a symlink named result in + the current directory, which points to the output of the top-level + “system” derivation. This is essentially the same as doing + +$ nix-build /path/to/nixpkgs/nixos -A system + + Note that you do not need to be root to run + nixos-rebuild build. + + + + + + + + + + Show what store paths would be built or downloaded by any of the + operations above, but otherwise do nothing. + + + + + + + + + + Build the new configuration, but instead of activating it, show what + changes would be performed by the activation (i.e. by + nixos-rebuild test). For instance, this command will + print which systemd units would be restarted. The list of changes is not + guaranteed to be complete. + + + + + + + + + + Build a script that starts a NixOS virtual machine with the desired + configuration. It leaves a symlink result in the + current directory that points (under + result/bin/run-hostname-vm) + at the script that starts the VM. Thus, to test a NixOS configuration in + a virtual machine, you should do the following: + +$ nixos-rebuild build-vm +$ ./result/bin/run-*-vm + + + + The VM is implemented using the qemu package. For + best performance, you should load the kvm-intel or + kvm-amd kernel modules to get hardware + virtualisation. + + + 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 + nixos-rebuild; to change the VM’s configuration, + you must halt the VM and re-run the commands above. + + + The VM has its own ext3 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 + ./hostname.qcow2. + + + + + + + + + + + Like , 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 nixos-rebuild + switch), 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 /boot + partition, which is mounted read-only in the VM. + + + + + + + + Options + + This command accepts the following options: + + + + + + + + + Fetch the latest version of NixOS from the NixOS channel. + + + + + + + + + + Causes the boot loader to be (re)installed on the device specified by the + relevant configuration options. + + + + + + + + + + Normally, nixos-rebuild first builds the + nixUnstable 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. + + + + + + + + + + Equivalent to + . This option is useful if you call + nixos-rebuild frequently (e.g. if you’re hacking on + a NixOS module). + + + + + + + + + + Instead of building a new configuration as specified by + /etc/nixos/configuration.nix, roll back to the + previous configuration. (The previous configuration is defined as the one + before the “current” generation of the Nix profile + /nix/var/nix/profiles/system.) + + + + + + + + + + + + + Instead of using the Nix profile + /nix/var/nix/profiles/system to keep track of the + current and previous system configurations, use + /nix/var/nix/profiles/system-profiles/name. + When you use GRUB 2, for every system profile created with this flag, + NixOS will create a submenu named “NixOS - Profile + 'name'” in GRUB’s boot menu, containing + the current and previous configurations of this profile. + + + For instance, if you want to test a configuration file named + test.nix without affecting the default system + profile, you would do: + +$ nixos-rebuild switch -p test -I nixos-config=./test.nix + + The new configuration will appear in the GRUB 2 submenu “NixOS - + Profile 'test'”. + + + + + + + + + + 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 + is not set, the build will be copied back + to the local machine when done. + + + Note that, if 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. + + + You can include a remote user name in the host name + (user@host). You can also set ssh options by + defining the NIX_SSHOPTS environment variable. + + + + + + + + + + Specifies the NixOS target host. By setting this to something other than + localhost, 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 , + and you need root access. + + + If is not explicitly specified, + will implicitly be set to the same value as + . So, if you only specify + both building and activation will take + place remotely (and no build artifacts will be copied to the local + machine). + + + You can include a remote user name in the host name + (user@host). You can also set ssh options by + defining the NIX_SSHOPTS environment variable. + + + + + + In addition, nixos-rebuild accepts various Nix-related + flags, including / , + , , + and / + . See the Nix manual for details. + + + + Environment + + + + NIXOS_CONFIG + + + + Path to the main NixOS configuration module. Defaults to + /etc/nixos/configuration.nix. + + + + + + NIX_SSHOPTS + + + + Additional options to be passed to ssh on the command + line. + + + + + + + Files + + + + /run/current-system + + + + A symlink to the currently active system configuration in the Nix store. + + + + + + /nix/var/nix/profiles/system + + + + The Nix profile that contains the current and previous system + configurations. Used to generate the GRUB boot menu. + + + + + + + Bugs + + This command should be renamed to something more descriptive. + + + diff --git a/nixos/doc/manual/man-nixos-version.xml b/nixos/doc/manual/man-nixos-version.xml new file mode 100644 index 0000000..931c4a5 --- /dev/null +++ b/nixos/doc/manual/man-nixos-version.xml @@ -0,0 +1,112 @@ + + + nixos-version + 8 + NixOS + + + nixos-version + show the NixOS version + + + + nixos-version + + + + + + + + + + + Description + + This command shows the version of the currently active NixOS configuration. + For example: +$ nixos-version +16.03.1011.6317da4 (Emu) + + The version consists of the following elements: + + + + 16.03 + + + + The NixOS release, indicating the year and month in which it was + released (e.g. March 2016). + + + + + + 1011 + + + + 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 + git when the current NixOS configuration was built + from a checkout of the Nixpkgs Git repository rather than from a NixOS + channel. + + + + + + 6317da4 + + + + The first 7 characters of the commit in the Nixpkgs Git repository from + which this version was built. + + + + + + Emu + + + + 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. + + + + + + + + Options + + This command accepts the following options: + + + + + + + + + + + + Show the full SHA1 hash of the Git commit from which this configuration + was built, e.g. +$ nixos-version --hash +6317da40006f6bc2480c6781999c52d88dde2acf + + + + + + + diff --git a/nixos/doc/manual/man-pages.xml b/nixos/doc/manual/man-pages.xml new file mode 100644 index 0000000..0390dda --- /dev/null +++ b/nixos/doc/manual/man-pages.xml @@ -0,0 +1,20 @@ + + NixOS Reference Pages + + EelcoDolstra + Author + + 2007-2018Eelco Dolstra + + + + + + + + + + + diff --git a/nixos/doc/manual/manual.xml b/nixos/doc/manual/manual.xml new file mode 100644 index 0000000..12f52e1 --- /dev/null +++ b/nixos/doc/manual/manual.xml @@ -0,0 +1,48 @@ + + + NixOS Manual + Version + + + + Preface + + This manual describes how to install, use and extend NixOS, a Linux + distribution based on the purely functional package management system Nix. + + + If you encounter problems, please report them on the + Discourse or + on the + #nixos channel on Freenode. Bugs should be + reported in + NixOS’ + GitHub issue tracker. + + + + Commands prefixed with # have to be run as root, either + requiring to login as root user or temporarily switching to it using + sudo for example. + + + + + + + + + + Configuration Options + + + + diff --git a/nixos/doc/manual/options-to-docbook.xsl b/nixos/doc/manual/options-to-docbook.xsl new file mode 100644 index 0000000..72ac89d --- /dev/null +++ b/nixos/doc/manual/options-to-docbook.xsl @@ -0,0 +1,236 @@ + + + + + + + + + + + + + Configuration Options + + + + + + + + + + + + + + + + + + + + Type: + + + + + (read only) + + + + + + + Default: + + + + + + + + Example: + + + + + + + + + + + + + + + Related packages: + + + + + + + + Declared by: + + + + + + + Defined by: + + + + + + + + + + + + + + + + + + + +'' +'' + + + + + + + + + + null + + + + + + + '''' + + + "" + + + + + + + + + + + + true + + + + + false + + + + + [ + + + + + ] + + + + + + + + + + { + + + = + ; + + } + + + + + (build of ) + + + + + + + + + + + + https://github.com/NixOS/nixpkgs/blob/master/ + + + https://github.com/NixOS/nixpkgs/blob// + + + + + https://github.com/NixOS/nixops/blob//nix/ + + + file:// + + + + + + <nixpkgs/> + + + <nixops/> + + + + + + + + + + + + + λ + + + + diff --git a/nixos/doc/manual/postprocess-option-descriptions.xsl b/nixos/doc/manual/postprocess-option-descriptions.xsl new file mode 100644 index 0000000..1201c76 --- /dev/null +++ b/nixos/doc/manual/postprocess-option-descriptions.xsl @@ -0,0 +1,115 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/nixos/doc/manual/release-notes/release-notes.xml b/nixos/doc/manual/release-notes/release-notes.xml new file mode 100644 index 0000000..a222bfa --- /dev/null +++ b/nixos/doc/manual/release-notes/release-notes.xml @@ -0,0 +1,22 @@ + + Release Notes + + This section lists the release notes for each stable version of NixOS and + current unstable revision. + + + + + + + + + + + + + diff --git a/nixos/doc/manual/release-notes/rl-1310.xml b/nixos/doc/manual/release-notes/rl-1310.xml new file mode 100644 index 0000000..248bab7 --- /dev/null +++ b/nixos/doc/manual/release-notes/rl-1310.xml @@ -0,0 +1,11 @@ +
+ Release 13.10 (“Aardvark”, 2013/10/31) + + + This is the first stable release branch of NixOS. + +
diff --git a/nixos/doc/manual/release-notes/rl-1404.xml b/nixos/doc/manual/release-notes/rl-1404.xml new file mode 100644 index 0000000..8d8cea4 --- /dev/null +++ b/nixos/doc/manual/release-notes/rl-1404.xml @@ -0,0 +1,179 @@ +
+ Release 14.04 (“Baboon”, 2014/04/30) + + + 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: + + + + Installation on UEFI systems is now supported. See + for details. + + + + + Systemd has been updated to version 212, which has + numerous + improvements. NixOS now automatically starts systemd user instances + when you log in. You can define global user units through the + options. + + + + + NixOS is now based on Glibc 2.19 and GCC 4.8. + + + + + The default Linux kernel has been updated to 3.12. + + + + + KDE has been updated to 4.12. + + + + + GNOME 3.10 experimental support has been added. + + + + + Nix has been updated to 1.7 + (details). + + + + + NixOS now supports fully declarative management of users and groups. If + you set to false, + then the contents of /etc/passwd and + /etc/group will be + congruent + to your NixOS configuration. For instance, if you remove a user from + 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. If + is true (the + default), then behaviour is unchanged from NixOS 13.10. + + + + + 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 + for details. + + + + + Systemd units provided by packages can now be overridden from the NixOS + configuration. For instance, if a package foo provides + systemd units, you can say: + +systemd.packages = [ pkgs.foo ]; + + to enable those units. You can then set or override unit options in the + usual way, e.g. + +systemd.services.foo.wantedBy = [ "multi-user.target" ]; +systemd.services.foo.serviceConfig.MemoryLimit = "512M"; + + + + + + + + When upgrading from a previous release, please be aware of the following + incompatible changes: + + + + 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: + +nixpkgs.config.allowUnfree = true; + + Otherwise, you get an error message such as: + +error: package ‘nvidia-x11-331.49-3.12.17’ in ‘…/nvidia-x11/default.nix:56’ + has an unfree license, refusing to evaluate + + + + + + The Adobe Flash player is no longer enabled by default in the Firefox and + Chromium wrappers. To enable it, you must set: + +nixpkgs.config.allowUnfree = true; +nixpkgs.config.firefox.enableAdobeFlash = true; # for Firefox +nixpkgs.config.chromium.enableAdobeFlash = true; # for Chromium + + + + + + The firewall is now enabled by default. If you don’t want this, you need + to disable it explicitly: + +networking.firewall.enable = false; + + + + + + The option has been renamed to + . + + + + + The mysql55 service has been merged into the + mysql service, which no longer sets a default for the + option . + + + + + Package variants are now differentiated by suffixing the name, rather than + the version. For instance, sqlite-3.8.4.3-interactive + is now called sqlite-interactive-3.8.4.3. This + ensures that nix-env -i sqlite is unambiguous, and that + nix-env -u won’t “upgrade” + sqlite to sqlite-interactive or vice + versa. Notably, this change affects the Firefox wrapper (which provides + plugins), as it is now called firefox-wrapper. So when + using nix-env, you should do nix-env -e + firefox; nix-env -i firefox-wrapper if you want to keep using + the wrapper. This change does not affect declarative package management, + since attribute names like pkgs.firefoxWrapper were + already unambiguous. + + + + + The symlink /etc/ca-bundle.crt is gone. Programs + should instead use the environment variable + OPENSSL_X509_CERT_FILE (which points to + /etc/ssl/certs/ca-bundle.crt). + + + + +
diff --git a/nixos/doc/manual/release-notes/rl-1412.xml b/nixos/doc/manual/release-notes/rl-1412.xml new file mode 100644 index 0000000..139f61c --- /dev/null +++ b/nixos/doc/manual/release-notes/rl-1412.xml @@ -0,0 +1,467 @@ +
+ Release 14.12 (“Caterpillar”, 2014/12/30) + + + In addition to numerous new and upgraded packages, this release has the + following highlights: + + + + Systemd has been updated to version 217, which has numerous + improvements. + + + + + + Nix has been updated to 1.8. + + + + + NixOS is now based on Glibc 2.20. + + + + + KDE has been updated to 4.14. + + + + + The default Linux kernel has been updated to 3.14. + + + + + If is enabled (the default), changes + made to the declaration of a user or group will be correctly realised when + running nixos-rebuild. For instance, removing a user + specification from configuration.nix will cause the + actual user account to be deleted. If + is disabled, it is no longer necessary to specify UIDs or GIDs; if + omitted, they are allocated dynamically. + + + + + + + Following new services were added since the last release: + + + + atftpd + + + + + bosun + + + + + bspwm + + + + + chronos + + + + + collectd + + + + + consul + + + + + cpuminer-cryptonight + + + + + crashplan + + + + + dnscrypt-proxy + + + + + docker-registry + + + + + docker + + + + + etcd + + + + + fail2ban + + + + + fcgiwrap + + + + + fleet + + + + + fluxbox + + + + + gdm + + + + + geoclue2 + + + + + gitlab + + + + + gitolite + + + + + gnome3.gnome-documents + + + + + gnome3.gnome-online-miners + + + + + gnome3.gvfs + + + + + gnome3.seahorse + + + + + hbase + + + + + i2pd + + + + + influxdb + + + + + kubernetes + + + + + liquidsoap + + + + + lxc + + + + + mailpile + + + + + mesos + + + + + mlmmj + + + + + monetdb + + + + + mopidy + + + + + neo4j + + + + + nsd + + + + + openntpd + + + + + opentsdb + + + + + openvswitch + + + + + parallels-guest + + + + + peerflix + + + + + phd + + + + + polipo + + + + + prosody + + + + + radicale + + + + + redmine + + + + + riemann + + + + + scollector + + + + + seeks + + + + + siproxd + + + + + strongswan + + + + + tcsd + + + + + teamspeak3 + + + + + thermald + + + + + torque/mrom + + + + + torque/server + + + + + uhub + + + + + unifi + + + + + znc + + + + + zookeeper + + + + + + + When upgrading from a previous release, please be aware of the following + incompatible changes: + + + + The default version of Apache httpd is now 2.4. If you use the + option to pass literal Apache configuration + text, you may need to update it — see + Apache’s + documentation for details. If you wish to continue to use httpd + 2.2, add the following line to your NixOS configuration: + +services.httpd.package = pkgs.apacheHttpd_2_2; + + + + + + PHP 5.3 has been removed because it is no longer supported by the PHP + project. A migration + guide is available. + + + + + The host side of a container virtual Ethernet pair is now called + ve-container-name rather + than c-container-name. + + + + + GNOME 3.10 support has been dropped. The default GNOME version is now + 3.12. + + + + + VirtualBox has been upgraded to 4.3.20 release. Users may be required to + run rm -rf /tmp/.vbox*. The line imports = [ + <nixpkgs/nixos/modules/programs/virtualbox.nix> ] is no + longer necessary, use services.virtualboxHost.enable = + true instead. + + + 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 + vboxusers group. + + + + + Chromium has been updated to 39.0.2171.65. + is now enabled by default. + chromium*Wrapper packages no longer exist, because + upstream removed NSAPI support. chromium-stable has + been renamed to chromium. + + + + + Python packaging documentation is now part of nixpkgs manual. To override + the python packages available to a custom python you now use + pkgs.pythonFull.buildEnv.override instead of + pkgs.pythonFull.override. + + + + + boot.resumeDevice = "8:6" 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. + + + + + The system-wide default timezone for NixOS installations changed from + CET to UTC. To choose a different + timezone for your system, configure time.timeZone in + configuration.nix. A fairly complete list of possible + values for that setting is available at + . + + + + + GNU screen has been updated to 4.2.1, which breaks the ability to connect + to sessions created by older versions of screen. + + + + + The Intel GPU driver was updated to the 3.x prerelease version (used by + most distributions) and supports DRI3 now. + + + + +
diff --git a/nixos/doc/manual/release-notes/rl-1509.xml b/nixos/doc/manual/release-notes/rl-1509.xml new file mode 100644 index 0000000..e500c9d --- /dev/null +++ b/nixos/doc/manual/release-notes/rl-1509.xml @@ -0,0 +1,750 @@ +
+ Release 15.09 (“Dingo”, 2015/09/30) + + + In addition to numerous new and upgraded packages, this release has the + following highlights: + + + + + + The Haskell packages + infrastructure has been re-designed from the ground up ("Haskell + NG"). NixOS now distributes the latest version of every single package + registered on + Hackage -- well + in excess of 8,000 Haskell packages. Detailed instructions on how to use + that infrastructure can be found in the + User's + Guide to the Haskell Infrastructure. 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 + LTS Haskell release + since version 0.0 as well as the most recent + Stackage Nightly + snapshot. The announcement + "Full + Stackage Support in Nixpkgs" gives additional details. + + + + + Nix has been updated to version 1.10, which among other improvements + enables cryptographic signatures on binary caches for improved security. + + + + + You can now keep your NixOS system up to date automatically by setting + +system.autoUpgrade.enable = true; + + This will cause the system to periodically check for updates in your + current channel and run nixos-rebuild. + + + + + This release is based on Glibc 2.21, GCC 4.9 and Linux 3.18. + + + + + GNOME has been upgraded to 3.16. + + + + + Xfce has been upgraded to 4.12. + + + + + 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. + + + + + E19 has been upgraded to 0.16.8.15. + + + + + + The following new services were added since the last release: + + + + services/mail/exim.nix + + + + + services/misc/apache-kafka.nix + + + + + services/misc/canto-daemon.nix + + + + + services/misc/confd.nix + + + + + services/misc/devmon.nix + + + + + services/misc/gitit.nix + + + + + services/misc/ihaskell.nix + + + + + services/misc/mbpfan.nix + + + + + services/misc/mediatomb.nix + + + + + services/misc/mwlib.nix + + + + + services/misc/parsoid.nix + + + + + services/misc/plex.nix + + + + + services/misc/ripple-rest.nix + + + + + services/misc/ripple-data-api.nix + + + + + services/misc/subsonic.nix + + + + + services/misc/sundtek.nix + + + + + services/monitoring/cadvisor.nix + + + + + services/monitoring/das_watchdog.nix + + + + + services/monitoring/grafana.nix + + + + + services/monitoring/riemann-tools.nix + + + + + services/monitoring/teamviewer.nix + + + + + services/network-filesystems/u9fs.nix + + + + + services/networking/aiccu.nix + + + + + services/networking/asterisk.nix + + + + + services/networking/bird.nix + + + + + services/networking/charybdis.nix + + + + + services/networking/docker-registry-server.nix + + + + + services/networking/fan.nix + + + + + services/networking/firefox/sync-server.nix + + + + + services/networking/gateone.nix + + + + + services/networking/heyefi.nix + + + + + services/networking/i2p.nix + + + + + services/networking/lambdabot.nix + + + + + services/networking/mstpd.nix + + + + + services/networking/nix-serve.nix + + + + + services/networking/nylon.nix + + + + + services/networking/racoon.nix + + + + + services/networking/skydns.nix + + + + + services/networking/shout.nix + + + + + services/networking/softether.nix + + + + + services/networking/sslh.nix + + + + + services/networking/tinc.nix + + + + + services/networking/tlsdated.nix + + + + + services/networking/tox-bootstrapd.nix + + + + + services/networking/tvheadend.nix + + + + + services/networking/zerotierone.nix + + + + + services/scheduling/marathon.nix + + + + + services/security/fprintd.nix + + + + + services/security/hologram.nix + + + + + services/security/munge.nix + + + + + services/system/cloud-init.nix + + + + + services/web-servers/shellinabox.nix + + + + + services/web-servers/uwsgi.nix + + + + + services/x11/unclutter.nix + + + + + services/x11/display-managers/sddm.nix + + + + + system/boot/coredump.nix + + + + + system/boot/loader/loader.nix + + + + + system/boot/loader/generic-extlinux-compatible + + + + + system/boot/networkd.nix + + + + + system/boot/resolved.nix + + + + + system/boot/timesyncd.nix + + + + + tasks/filesystems/exfat.nix + + + + + tasks/filesystems/ntfs.nix + + + + + tasks/filesystems/vboxsf.nix + + + + + virtualisation/virtualbox-host.nix + + + + + virtualisation/vmware-guest.nix + + + + + virtualisation/xen-dom0.nix + + + + + + + When upgrading from a previous release, please be aware of the following + incompatible changes: + + + + sshd 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 + +system.stateVersion = "14.12"; + + The new option ensures that certain + configuration changes that could break existing systems (such as the + sshd host key setting) will maintain compatibility with + the specified NixOS release. NixOps sets the state version of existing + deployments automatically. + + + + + cron is no longer enabled by default, unless you have a + non-empty . To force + cron to be enabled, set . + + + + + 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 + . + + + + + Steam now doesn't need root rights to work. Instead of using + *-steam-chrootenv, you should now just run + steam. steamChrootEnv package was + renamed to steam, and old steam + package -- to steamOriginal. + + + + + CMPlayer has been renamed to bomi upstream. Package + cmplayer was accordingly renamed to + bomi + + + + + Atom Shell has been renamed to Electron upstream. Package + atom-shell was accordingly renamed to + electron + + + + + Elm is not released on Hackage anymore. You should now use + elmPackages.elm which contains the latest Elm platform. + + + + + The CUPS printing service has been updated to version + 2.0.2. Furthermore its systemd service has been renamed + to cups.service. + + + Local printers are no longer shared or advertised by default. This + behavior can be changed by enabling + or + respectively. + + + + + The VirtualBox host and guest options have been named more consistently. + They can now found in + instead of and + instead of + . + + + Also, there now is support for the vboxsf file system + using the configuration attribute. An example + of how this can be used in a configuration: + +fileSystems."/shiny" = { + device = "myshinysharedfolder"; + fsType = "vboxsf"; +}; + + + + + + "nix-env -qa" no longer discovers Haskell + packages by name. The only packages visible in the global scope are + ghc, cabal-install, and + stack, 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 nix-env -qa + 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: + + +nix-env -f "<nixpkgs>" -qaP -A haskellPackages + + + Executable programs written in Haskell can be installed with: + + +nix-env -f "<nixpkgs>" -iA haskellPackages.pandoc + + + Installing Haskell libraries this way, however, is no + longer supported. See the next item for more details. + + + + + Previous versions of NixOS came with a feature called + ghc-wrapper, a small script that allowed GHC to + transparently pick up on libraries installed in the user's profile. This + feature has been deprecated; ghc-wrapper was removed + from the distribution. The proper way to register Haskell libraries with + the compiler now is the haskellPackages.ghcWithPackages + function. The + User's + Guide to the Haskell Infrastructure provides more information about + this subject. + + + + + All Haskell builds that have been generated with version 1.x of the + cabal2nix utility are now invalid and need to be + re-generated with a current version of cabal2nix to + function. The most recent version of this tool can be installed by running + nix-env -i cabal2nix. + + + + + The haskellPackages set in Nixpkgs used to have a + function attribute called extension that users could + override in their ~/.nixpkgs/config.nix files to + configure additional attributes, etc. That function still exists, but it's + now called overrides. + + + + + The OpenBLAS library has been updated to version + 0.2.14. Support for the + x86_64-darwin 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. + + + + + The phpfpm is now using the default PHP version + (pkgs.php) instead of PHP 5.4 + (pkgs.php54). + + + + + The locate 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 + . + + + + + The Nix expression search path (NIX_PATH) no longer + contains /etc/nixos/nixpkgs by default. You can + override NIX_PATH by setting . + + + + + Python 2.6 has been marked as broken (as it no longer receives security + updates from upstream). + + + + + Any use of module arguments such as pkgs to access + library functions, or to define imports attributes will + now lead to an infinite loop at the time of the evaluation. + + + In case of an infinite loop, use the --show-trace + command line argument and read the line just above the error message. + +$ nixos-rebuild build --show-trace +… +while evaluating the module argument `pkgs' in "/etc/nixos/my-module.nix": +infinite recursion encountered + + + + Any use of pkgs.lib, should be replaced by + lib, after adding it as argument of the module. The + following module + +{ config, pkgs, ... }: + +with pkgs.lib; + +{ + options = { + foo = mkOption { … }; + }; + config = mkIf config.foo { … }; +} + + should be modified to look like: + +{ config, pkgs, lib, ... }: + +with lib; + +{ + options = { + foo = mkOption { option declaration }; + }; + config = mkIf config.foo { option definition }; +} + + + + When pkgs is used to download other projects to import + their modules, and only in such cases, it should be replaced by + (import <nixpkgs> {}). The following module + +{ config, pkgs, ... }: + +let + myProject = pkgs.fetchurl { + src = url; + sha256 = hash; + }; +in + +{ + imports = [ "${myProject}/module.nix" ]; +} + + should be modified to look like: + +{ config, pkgs, ... }: + +let + myProject = (import <nixpkgs> {}).fetchurl { + src = url; + sha256 = hash; + }; +in + +{ + imports = [ "${myProject}/module.nix" ]; +} + + + + + + + + Other notable improvements: + + + + The nixos and nixpkgs channels were unified, so one + can use nix-env -iA nixos.bash + instead of nix-env -iA nixos.pkgs.bash. See + the + commit for details. + + + + + Users running an SSH server who worry about the quality of their + /etc/ssh/moduli file with respect to the + vulnerabilities + discovered in the Diffie-Hellman key exchange can now replace + OpenSSH's default version with one they generated themselves using the new + option. + + + + + A newly packaged TeX Live 2015 is provided in + pkgs.texlive, split into 6500 nix packages. For basic + user documentation see + the + source. Beware of + an + issue when installing a too large package set. The plan is to + deprecate and maybe delete the original TeX packages until the next + release. + + + + + on all Python interpreters is now available + for nix-shell interoperability. + + + + +
diff --git a/nixos/doc/manual/release-notes/rl-1603.xml b/nixos/doc/manual/release-notes/rl-1603.xml new file mode 100644 index 0000000..9b512c4 --- /dev/null +++ b/nixos/doc/manual/release-notes/rl-1603.xml @@ -0,0 +1,671 @@ +
+ Release 16.03 (“Emu”, 2016/03/31) + + + In addition to numerous new and upgraded packages, this release has the + following highlights: + + + + + + Systemd 229, bringing + numerous + improvements over 217. + + + + + Linux 4.4 (was 3.18). + + + + + GCC 5.3 (was 4.9). Note that GCC 5 + changes + the C++ ABI in an incompatible way; this may cause problems if you + try to link objects compiled with different versions of GCC. + + + + + Glibc 2.23 (was 2.21). + + + + + Binutils 2.26 (was 2.23.1). See #909 + + + + + Improved support for ensuring + bitwise + reproducible builds. For example, stdenv now sets + the environment variable + SOURCE_DATE_EPOCH + to a deterministic value, and Nix has + gained + an option 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). + + + + + Perl 5.22. + + + + + + The following new services were added since the last release: + + + + services/monitoring/longview.nix + + + + + hardware/video/webcam/facetimehd.nix + + + + + i18n/input-method/default.nix + + + + + i18n/input-method/fcitx.nix + + + + + i18n/input-method/ibus.nix + + + + + i18n/input-method/nabi.nix + + + + + i18n/input-method/uim.nix + + + + + programs/fish.nix + + + + + security/acme.nix + + + + + security/audit.nix + + + + + security/oath.nix + + + + + services/hardware/irqbalance.nix + + + + + services/mail/dspam.nix + + + + + services/mail/opendkim.nix + + + + + services/mail/postsrsd.nix + + + + + services/mail/rspamd.nix + + + + + services/mail/rmilter.nix + + + + + services/misc/autofs.nix + + + + + services/misc/bepasty.nix + + + + + services/misc/calibre-server.nix + + + + + services/misc/cfdyndns.nix + + + + + services/misc/gammu-smsd.nix + + + + + services/misc/mathics.nix + + + + + services/misc/matrix-synapse.nix + + + + + services/misc/octoprint.nix + + + + + services/monitoring/hdaps.nix + + + + + services/monitoring/heapster.nix + + + + + services/monitoring/longview.nix + + + + + services/network-filesystems/netatalk.nix + + + + + services/network-filesystems/xtreemfs.nix + + + + + services/networking/autossh.nix + + + + + services/networking/dnschain.nix + + + + + services/networking/gale.nix + + + + + services/networking/miniupnpd.nix + + + + + services/networking/namecoind.nix + + + + + services/networking/ostinato.nix + + + + + services/networking/pdnsd.nix + + + + + services/networking/shairport-sync.nix + + + + + services/networking/supplicant.nix + + + + + services/search/kibana.nix + + + + + services/security/haka.nix + + + + + services/security/physlock.nix + + + + + services/web-apps/pump.io.nix + + + + + services/x11/hardware/libinput.nix + + + + + services/x11/window-managers/windowlab.nix + + + + + system/boot/initrd-network.nix + + + + + system/boot/initrd-ssh.nix + + + + + system/boot/loader/loader.nix + + + + + system/boot/networkd.nix + + + + + system/boot/resolved.nix + + + + + virtualisation/lxd.nix + + + + + virtualisation/rkt.nix + + + + + + + When upgrading from a previous release, please be aware of the following + incompatible changes: + + + + + + We no longer produce graphical ISO images and VirtualBox images for + i686-linux. A minimal ISO image is still provided. + + + + + Firefox and similar browsers are now wrapped by + default. The package and attribute names are plain + firefox or midori, etc. + Backward-compatibility attributes were set up, but note that + nix-env -u will not update your + current firefox-with-plugins; you have to uninstall it + and install firefox instead. + + + + + wmiiSnap has been replaced with + wmii_hg, but + services.xserver.windowManager.wmii.enable has been + updated respectively so this only affects you if you have explicitly + installed wmiiSnap. + + + + + jobs NixOS option has been removed. It served as + compatibility layer between Upstart jobs and SystemD services. All services + have been rewritten to use systemd.services + + + + + wmiimenu is removed, as it has been removed by the + developers upstream. Use wimenu from the + wmii-hg package. + + + + + 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. + ]; +} +]]> + will include the Gitit service configuration options. + + + + + nginx does not accept flags for enabling and disabling + modules anymore. Instead it accepts modules argument, + which is a list of modules to be built in. All modules now reside in + nginxModules set. Example configuration: + + + + + + s3sync 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 tarsnap and others. + + + + + ruby_1_8 has been removed as it's not supported from + upstream anymore and probably contains security issues. + + + + + tidy-html5 package is removed. Upstream only provided + (lib)tidy5 during development, and now they went back to + (lib)tidy to work as a drop-in replacement of the + original package that has been unmaintained for years. You can (still) use + the html-tidy package, which got updated to a stable + release from this new upstream. + + + + + extraDeviceOptions argument is removed from + bumblebee package. Instead there are now two separate + arguments: extraNvidiaDeviceOptions and + extraNouveauDeviceOptions for setting extra X11 options + for nvidia and nouveau drivers, respectively. + + + + + The Ctrl+Alt+Backspace key combination no longer kills + the X server by default. There's a new option + allowing to enable + the combination again. + + + + + emacsPackagesNg now contains all packages from the ELPA, + MELPA, and MELPA Stable repositories. + + + + + Data directory for Postfix MTA server is moved from + /var/postfix to /var/lib/postfix. + Old configurations are migrated automatically. + service.postfix module has also received many + improvements, such as correct directories' access rights, new + aliasFiles and mapFiles options and + more. + + + + + 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: + +fileSystems."/example" = { + device = "/dev/sdc"; + fsType = "btrfs"; + options = [ "noatime" "compress=lzo" "space_cache" "autodefrag" ]; +}; + + + + + + CUPS, installed by services.printing module, now has its + data directory in /var/lib/cups. Old configurations + from /etc/cups are moved there automatically, but + there might be problems. Also configuration options + services.printing.cupsdConf and + services.printing.cupsdFilesConf 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, + services.printing.extraConf and new option + services.printing.extraFilesConf should be enough; if + you encounter a situation when they are not, please file a bug. + + + There are also Gutenprint improvements; in particular, a new option + services.printing.gutenprint is added to enable + automatic updating of Gutenprint PPMs; it's greatly recommended to enable + it instead of adding gutenprint to the + drivers list. + + + + + services.xserver.vaapiDrivers has been removed. Use + hardware.opengl.extraPackages{,32} instead. You can also + specify VDPAU drivers there. + + + + + programs.ibus moved to + i18n.inputMethod.ibus. The option + programs.ibus.plugins changed to + i18n.inputMethod.ibus.engines and the option to enable + ibus changed from programs.ibus.enable to + i18n.inputMethod.enabled. + i18n.inputMethod.enabled should be set to the used input + method name, "ibus" for ibus. An example of the new + style: + +i18n.inputMethod.enabled = "ibus"; +i18n.inputMethod.ibus.engines = with pkgs.ibus-engines; [ anthy mozc ]; + + That is equivalent to the old version: + +programs.ibus.enable = true; +programs.ibus.plugins = with pkgs; [ ibus-anthy mozc ]; + + + + + + services.udev.extraRules option now writes rules to + 99-local.rules instead of + 10-local.rules. This makes all the user rules apply + after others, so their results wouldn't be overriden by anything else. + + + + + Large parts of the services.gitlab module has been been + rewritten. There are new configuration options available. The + stateDir option was renamned to + statePath and the satellitesDir + option was removed. Please review the currently available options. + + + + + The option no longer + interpret the dollar sign ($) as a shell variable, as such it should not be + escaped anymore. Thus the following zone data: + + +\$ORIGIN example.com. +\$TTL 1800 +@ IN SOA ns1.vpn.nbp.name. admin.example.com. ( + + + Should modified to look like the actual file expected by nsd: + + +$ORIGIN example.com. +$TTL 1800 +@ IN SOA ns1.vpn.nbp.name. admin.example.com. ( + + + + + service.syncthing.dataDir options now has to point to + exact folder where syncthing is writing to. Example configuration should + look something like: + + +services.syncthing = { + enable = true; + dataDir = "/home/somebody/.syncthing"; + user = "somebody"; +}; + + + + + networking.firewall.allowPing is now enabled by default. + Users are encouraged to configure an appropriate rate limit for their + machines using the Kernel interface at + /proc/sys/net/ipv4/icmp_ratelimit and + /proc/sys/net/ipv6/icmp/ratelimit or using the + firewall itself, i.e. by setting the NixOS option + networking.firewall.pingLimit. + + + + + Systems with some broadcom cards used to result into a generated config + that is no longer accepted. If you get errors like +error: path ‘/nix/store/*-broadcom-sta-*’ does not exist and cannot be created + you should either re-run nixos-generate-config or + manually replace + "${config.boot.kernelPackages.broadcom_sta}" by + config.boot.kernelPackages.broadcom_sta in your + /etc/nixos/hardware-configuration.nix. More discussion + is on the + github issue. + + + + + The services.xserver.startGnuPGAgent 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 + ~/.bashrc or some file that’s sourced when your + shell is started: + +GPG_TTY=$(tty) +export GPG_TTY + + If you want to use gpg-agent for SSH, too, add the following to your + session initialization (e.g. + displayManager.sessionCommands) + +gpg-connect-agent /bye +unset SSH_AGENT_PID +export SSH_AUTH_SOCK="''${HOME}/.gnupg/S.gpg-agent.ssh" + + and make sure that + +enable-ssh-support + + is included in your ~/.gnupg/gpg-agent.conf. You will + need to use ssh-add 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: + +gpg --import ~/.gnupg/secring.gpg + + The gpg-agent(1) man page has more details about this + subject, i.e. in the "EXAMPLES" section. + + + + + + Other notable improvements: + + + + + ejabberd module is brought back and now works on NixOS. + + + + + 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. + + + + +
diff --git a/nixos/doc/manual/release-notes/rl-1609.xml b/nixos/doc/manual/release-notes/rl-1609.xml new file mode 100644 index 0000000..4a2343e --- /dev/null +++ b/nixos/doc/manual/release-notes/rl-1609.xml @@ -0,0 +1,277 @@ +
+ Release 16.09 (“Flounder”, 2016/09/30) + + + In addition to numerous new and upgraded packages, this release has the + following highlights: + + + + + + Many NixOS configurations and Nix packages now use significantly less disk + space, thanks to the + extensive + work on closure size reduction. 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. + + + + + To improve security, packages are now + built + using various hardening features. See the Nixpkgs manual for more + information. + + + + + Support for PXE netboot. See + for documentation. + + + + + X.org server 1.18. If you use the ati_unfree driver, + 1.17 is still used due to an ABI incompatibility. + + + + + This release is based on Glibc 2.24, GCC 5.4.0 and systemd 231. The default + Linux kernel remains 4.4. + + + + + + The following new services were added since the last release: + + + + + + (this will get automatically generated at release time) + + + + + + When upgrading from a previous release, please be aware of the following + incompatible changes: + + + + + + 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 + were + changed late (August 2016) in the release cycle and differ from the + initial introduction of multiple outputs.) + + + + + Previous versions of Nixpkgs had support for all versions of the LTS + Haskell package set. That support has been dropped. The previously provided + haskell.packages.lts-x_y 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. + The + motivation for this change has been discussed at length on the + nix-dev mailing list and in + Github + issue #14897. Development strategies for Haskell hackers who want to + rely on Nix and NixOS have been described in + another + nix-dev article. + + + + + Shell aliases for systemd sub-commands + were + dropped: start, stop, + restart, status. + + + + + 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 + + + + + /var/empty is now immutable. Activation script runs + chattr +i to forbid any modifications inside the folder. + See the + pull request for what bugs this caused. + + + + + Gitlab's maintainance script gitlab-runner was removed + and split up into the more clearer gitlab-run and + gitlab-rake scripts, because + gitlab-runner is a component of Gitlab CI. + + + + + services.xserver.libinput.accelProfile default changed + from flat to adaptive, as per + + official documentation. + + + + + fonts.fontconfig.ultimate.rendering was removed because + our presets were obsolete for some time. New presets are hardcoded into + FreeType; you can select a preset via + fonts.fontconfig.ultimate.preset. You can customize + those presets via ordinary environment variables, using + environment.variables. + + + + + The audit service is no longer enabled by default. Use + security.audit.enable = true to explicitly enable it. + + + + + pkgs.linuxPackages.virtualbox 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 + pkgs.virtualbox instead. + + + + + goPackages was replaced with separated Go applications + in appropriate nixpkgs categories. Each Go package uses + its own dependency set. There's also a new go2nix tool + introduced to generate a Go package definition from its Go source + automatically. + + + + + services.mongodb.extraConfig configuration format was + changed to YAML. + + + + + PHP has been upgraded to 7.0 + + + + + + Other notable improvements: + + + + + + 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 +security.grsecurity.enable = true + to get a reasonably secure system without having to sacrifice too much + functionality. + + + + + Special filesystems, like /proc, /run + 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 nixos-rebuild switch if possible. One benefit + from this is improved security — most such filesystems are now mounted + with noexec, nodev and/or + nosuid options. + + + + + 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 + (networking.firewall.logReversePathDrops) for easier + debugging. + + + + + Containers configuration within + containers.<name>.config is + now + properly typed and checked. In particular, partial configurations + are merged correctly. + + + + + The directory container setuid wrapper programs, + /var/setuid-wrappers, + is now + updated atomically to prevent failures if the switch to a new configuration + is interrupted. + + + + + services.xserver.startGnuPGAgent has been removed due to + GnuPG 2.1.x bump. See + + how to achieve similar behavior. You might need to pkill + gpg-agent after the upgrade to prevent a stale agent being in the + way. + + + + + + Declarative users could share the uid due to the bug in the script handling + conflict resolution. + + + + + Gummi boot has been replaced using systemd-boot. + + + + + Hydra package and NixOS module were added for convenience. + + + +
diff --git a/nixos/doc/manual/release-notes/rl-1703.xml b/nixos/doc/manual/release-notes/rl-1703.xml new file mode 100644 index 0000000..6ca79e2 --- /dev/null +++ b/nixos/doc/manual/release-notes/rl-1703.xml @@ -0,0 +1,817 @@ +
+ Release 17.03 (“Gorilla”, 2017/03/31) + +
+ Highlights + + + In addition to numerous new and upgraded packages, this release has the + following highlights: + + + + + + Nixpkgs is now extensible through overlays. See the + Nixpkgs + manual for more information. + + + + + 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. + + + + + The default desktop environment now is KDE's Plasma 5. KDE 4 has been + removed + + + + + The setuid wrapper functionality now supports setting capabilities. + + + + + X.org server uses branch 1.19. Due to ABI incompatibilities, + ati_unfree keeps forcing 1.17 and + amdgpu-pro starts forcing 1.18. + + + + + Cross compilation has been rewritten. See the nixpkgs manual for details. + The most obvious breaking change is that in derivations there is no + .nativeDrv nor .crossDrv are now + cross by default, not native. + + + + + The overridePackages function has been rewritten to be + replaced by + + overlays + + + + + Packages in nixpkgs can be marked as insecure through listed + vulnerabilities. See the + Nixpkgs + manual for more information. + + + + + PHP now defaults to PHP 7.1 + + + +
+ +
+ New Services + + + The following new services were added since the last release: + + + + + + hardware/ckb.nix + + + + + hardware/mcelog.nix + + + + + hardware/usb-wwan.nix + + + + + hardware/video/capture/mwprocapture.nix + + + + + programs/adb.nix + + + + + programs/chromium.nix + + + + + programs/gphoto2.nix + + + + + programs/java.nix + + + + + programs/mtr.nix + + + + + programs/oblogout.nix + + + + + programs/vim.nix + + + + + programs/wireshark.nix + + + + + security/dhparams.nix + + + + + services/audio/ympd.nix + + + + + services/computing/boinc/client.nix + + + + + services/continuous-integration/buildbot/master.nix + + + + + services/continuous-integration/buildbot/worker.nix + + + + + services/continuous-integration/gitlab-runner.nix + + + + + services/databases/riak-cs.nix + + + + + services/databases/stanchion.nix + + + + + services/desktops/gnome3/gnome-terminal-server.nix + + + + + services/editors/infinoted.nix + + + + + services/hardware/illum.nix + + + + + services/hardware/trezord.nix + + + + + services/logging/journalbeat.nix + + + + + services/mail/offlineimap.nix + + + + + services/mail/postgrey.nix + + + + + services/misc/couchpotato.nix + + + + + services/misc/docker-registry.nix + + + + + services/misc/errbot.nix + + + + + services/misc/geoip-updater.nix + + + + + services/misc/gogs.nix + + + + + services/misc/leaps.nix + + + + + services/misc/nix-optimise.nix + + + + + services/misc/ssm-agent.nix + + + + + services/misc/sssd.nix + + + + + services/monitoring/arbtt.nix + + + + + services/monitoring/netdata.nix + + + + + services/monitoring/prometheus/default.nix + + + + + services/monitoring/prometheus/alertmanager.nix + + + + + services/monitoring/prometheus/blackbox-exporter.nix + + + + + services/monitoring/prometheus/json-exporter.nix + + + + + services/monitoring/prometheus/nginx-exporter.nix + + + + + services/monitoring/prometheus/node-exporter.nix + + + + + services/monitoring/prometheus/snmp-exporter.nix + + + + + services/monitoring/prometheus/unifi-exporter.nix + + + + + services/monitoring/prometheus/varnish-exporter.nix + + + + + services/monitoring/sysstat.nix + + + + + services/monitoring/telegraf.nix + + + + + services/monitoring/vnstat.nix + + + + + services/network-filesystems/cachefilesd.nix + + + + + services/network-filesystems/glusterfs.nix + + + + + services/network-filesystems/ipfs.nix + + + + + services/networking/dante.nix + + + + + services/networking/dnscrypt-wrapper.nix + + + + + services/networking/fakeroute.nix + + + + + services/networking/flannel.nix + + + + + services/networking/htpdate.nix + + + + + services/networking/miredo.nix + + + + + services/networking/nftables.nix + + + + + services/networking/powerdns.nix + + + + + services/networking/pdns-recursor.nix + + + + + services/networking/quagga.nix + + + + + services/networking/redsocks.nix + + + + + services/networking/wireguard.nix + + + + + services/system/cgmanager.nix + + + + + services/torrent/opentracker.nix + + + + + services/web-apps/atlassian/confluence.nix + + + + + services/web-apps/atlassian/crowd.nix + + + + + services/web-apps/atlassian/jira.nix + + + + + services/web-apps/frab.nix + + + + + services/web-apps/nixbot.nix + + + + + services/web-apps/selfoss.nix + + + + + services/web-apps/quassel-webserver.nix + + + + + services/x11/unclutter-xfixes.nix + + + + + services/x11/urxvtd.nix + + + + + system/boot/systemd-nspawn.nix + + + + + virtualisation/ecs-agent.nix + + + + + virtualisation/lxcfs.nix + + + + + virtualisation/openstack/keystone.nix + + + + + virtualisation/openstack/glance.nix + + + +
+ +
+ Backward Incompatibilities + + + When upgrading from a previous release, please be aware of the following + incompatible changes: + + + + + + Derivations have no .nativeDrv nor + .crossDrv and are now cross by default, not native. + + + + + stdenv.overrides is now expected to take + self and super arguments. See + lib.trivial.extends for what those parameters + represent. + + + + + ansible now defaults to ansible version 2 as version 1 + has been removed due to a serious + + vulnerability unpatched by upstream. + + + + + gnome alias has been removed along with + gtk, gtkmm and several others. Now + you need to use versioned attributes, like gnome3. + + + + + The attribute name of the Radicale daemon has been changed from + pythonPackages.radicale to radicale. + + + + + The stripHash bash function in + stdenv changed according to its documentation; it now + outputs the stripped name to stdout instead of putting + it in the variable strippedName. + + + + + 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. + + + + + Two lone top-level dict dbs moved into dictdDBs. This + affects: dictdWordnet which is now at + dictdDBs.wordnet and dictdWiktionary + which is now at dictdDBs.wiktionary + + + + + Parsoid service now uses YAML configuration format. + service.parsoid.interwikis is now called + service.parsoid.wikis and is a list of either API URLs + or attribute sets as specified in parsoid's documentation. + + + + + Ntpd was replaced by + systemd-timesyncd as the default service to synchronize + system time with a remote NTP server. The old behavior can be restored by + setting services.ntp.enable to true. + Upstream time servers for all NTP implementations are now configured using + networking.timeServers. + + + + + service.nylon is now declared using named instances. As + an example: + + services.nylon = { + enable = true; + acceptInterface = "br0"; + bindInterface = "tun1"; + port = 5912; + }; + + should be replaced with: + + services.nylon.myvpn = { + enable = true; + acceptInterface = "br0"; + bindInterface = "tun1"; + port = 5912; + }; + + this enables you to declare a SOCKS proxy for each uplink. + + + + + overridePackages function no longer exists. It is + replaced by + + overlays. For example, the following code: + + let + pkgs = import <nixpkgs> {}; + in + pkgs.overridePackages (self: super: ...) + + should be replaced by: + + let + pkgs = import <nixpkgs> {}; + in + import pkgs.path { overlays = [(self: super: ...)]; } + + + + + + 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 + networking.firewall.autoLoadConntrackHelpers and tune + networking.firewall.connectionTrackingModules to suit + your needs. + + + + + local_recipient_maps 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 + services.postfix.extraConfig. + + + + + 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 -4 and + -6 have been added. One notable incompatibility is that + specifying an interface (for link-local IPv6 for instance) is no longer + done with the -I flag, but by encoding the interface + into the address (ping fe80::1%eth0). + + + + + The socket handling of the services.rmilter module has + been fixed and refactored. As rmilter doesn't support binding to more than + one socket, the options bindUnixSockets and + bindInetSockets have been replaced by + services.rmilter.bindSocket.*. The default is still a + unix socket in /run/rmilter/rmilter.sock. Refer to the + options documentation for more information. + + + + + The fetch* functions no longer support md5, please use + sha256 instead. + + + + + The dnscrypt-proxy module interface has been streamlined around the + option. Where possible, legacy option + declarations are mapped to but will emit + warnings. The has been outright removed: to + use an unlisted resolver, use the option. + + + + + torbrowser now stores local state under + ~/.local/share/tor-browser by default. Any browser + profile data from the old location, ~/.torbrowser4, + must be migrated manually. + + + + + The ihaskell, monetdb, offlineimap and sitecopy services have been + removed. + + + +
+ +
+ Other Notable Changes + + + + + 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. + + + + + jre 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 + jre_headless. + + + + + Python 2.6 interpreter and package set have been removed. + + + + + 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. + + + + + 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 nix-shell. See the + Nixpkgs manual for details. + + + + + The Python package sets now use a fixed-point combinator and the sets are + available as attributes of the interpreters. + + + + + The Python function buildPythonPackage has been + improved and can be used to build from Setuptools source, Flit source, and + precompiled Wheels. + + + + + When adding new or updating current Python libraries, the expressions + should be put in separate files in + pkgs/development/python-modules and called from + python-packages.nix. + + + + + 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. + + + + + Containers using bridged networking no longer lose their connection after + changes to the host networking. + + + + + ZFS supports pool auto scrubbing. + + + + + The bind DNS utilities (e.g. dig) have been split into their own output + and are now also available in pkgs.dnsutils and it is + no longer necessary to pull in all of bind to use them. + + + + + Per-user configuration was moved from ~/.nixpkgs to + ~/.config/nixpkgs. The former is still valid for + config.nix for backwards compatibility. + + + +
+
diff --git a/nixos/doc/manual/release-notes/rl-1709.xml b/nixos/doc/manual/release-notes/rl-1709.xml new file mode 100644 index 0000000..795c51d --- /dev/null +++ b/nixos/doc/manual/release-notes/rl-1709.xml @@ -0,0 +1,899 @@ +
+ Release 17.09 (“Hummingbird”, 2017/09/??) + +
+ Highlights + + + In addition to numerous new and upgraded packages, this release has the + following highlights: + + + + + + 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. + + + + + 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. + + + + + The module 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: + +{ services.xserver.xrandrHeads = [ + "HDMI-0" + { + output = "DVI-0"; + primary = true; + monitorConfig = '' + Option "Rotate" "right" + ''; + } + ]; +} + + This will set the DVI-0 output to be the primary head, + even though HDMI-0 is the first head in the list. + + + + + The handling of SSL in the services.nginx module has + been cleaned up, renaming the misnamed enableSSL to + onlySSL which reflects its original intention. This is + not to be used with the already existing forceSSL 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 + enableSSL option to keep the previous behaviour. + + + Another addSSL option has been introduced to configure + both a non-SSL virtual host and an SSL virtual host with the same + configuration. + + + Options to configure resolver options and + upstream blocks have been introduced. See their + information for further details. + + + The port option has been replaced by a more generic + listen option which makes it possible to specify + multiple addresses, ports and SSL configs dependant on the new SSL + handling mentioned above. + + + +
+ +
+ New Services + + + The following new services were added since the last release: + + + + + + config/fonts/fontconfig-penultimate.nix + + + + + config/fonts/fontconfig-ultimate.nix + + + + + config/terminfo.nix + + + + + hardware/sensor/iio.nix + + + + + hardware/nitrokey.nix + + + + + hardware/raid/hpsa.nix + + + + + programs/browserpass.nix + + + + + programs/gnupg.nix + + + + + programs/qt5ct.nix + + + + + programs/slock.nix + + + + + programs/thefuck.nix + + + + + security/auditd.nix + + + + + security/lock-kernel-modules.nix + + + + + service-managers/docker.nix + + + + + service-managers/trivial.nix + + + + + services/admin/salt/master.nix + + + + + services/admin/salt/minion.nix + + + + + services/audio/slimserver.nix + + + + + services/cluster/kubernetes/default.nix + + + + + services/cluster/kubernetes/dns.nix + + + + + services/cluster/kubernetes/dashboard.nix + + + + + services/continuous-integration/hail.nix + + + + + services/databases/clickhouse.nix + + + + + services/databases/postage.nix + + + + + services/desktops/gnome3/gnome-disks.nix + + + + + services/desktops/gnome3/gpaste.nix + + + + + services/logging/SystemdJournal2Gelf.nix + + + + + services/logging/heartbeat.nix + + + + + services/logging/journalwatch.nix + + + + + services/logging/syslogd.nix + + + + + services/mail/mailhog.nix + + + + + services/mail/nullmailer.nix + + + + + services/misc/airsonic.nix + + + + + services/misc/autorandr.nix + + + + + services/misc/exhibitor.nix + + + + + services/misc/fstrim.nix + + + + + services/misc/gollum.nix + + + + + services/misc/irkerd.nix + + + + + services/misc/jackett.nix + + + + + services/misc/radarr.nix + + + + + services/misc/snapper.nix + + + + + services/monitoring/osquery.nix + + + + + services/monitoring/prometheus/collectd-exporter.nix + + + + + services/monitoring/prometheus/fritzbox-exporter.nix + + + + + services/network-filesystems/kbfs.nix + + + + + services/networking/dnscache.nix + + + + + services/networking/fireqos.nix + + + + + services/networking/iwd.nix + + + + + services/networking/keepalived/default.nix + + + + + services/networking/keybase.nix + + + + + services/networking/lldpd.nix + + + + + services/networking/matterbridge.nix + + + + + services/networking/squid.nix + + + + + services/networking/tinydns.nix + + + + + services/networking/xrdp.nix + + + + + services/security/shibboleth-sp.nix + + + + + services/security/sks.nix + + + + + services/security/sshguard.nix + + + + + services/security/torify.nix + + + + + services/security/usbguard.nix + + + + + services/security/vault.nix + + + + + services/system/earlyoom.nix + + + + + services/system/saslauthd.nix + + + + + services/web-apps/nexus.nix + + + + + services/web-apps/pgpkeyserver-lite.nix + + + + + services/web-apps/piwik.nix + + + + + services/web-servers/lighttpd/collectd.nix + + + + + services/web-servers/minio.nix + + + + + services/x11/display-managers/xpra.nix + + + + + services/x11/xautolock.nix + + + + + tasks/filesystems/bcachefs.nix + + + + + tasks/powertop.nix + + + +
+ +
+ Backward Incompatibilities + + + When upgrading from a previous release, please be aware of the following + incompatible changes: + + + + + + In an Qemu-based virtualization environment, the + network interface names changed from i.e. enp0s3 to + ens3. + + + This is due to a kernel configuration change. The new naming is consistent + with those of other Linux distributions with systemd. See + #29197 + for more information. + + + A machine is affected if the virt-what tool either + returns qemu or kvm + and has interface names used in any part of its NixOS + configuration, in particular if a static network configuration with + networking.interfaces is used. + + + Before rebooting affected machines, please ensure: + + + + Change the interface names in your NixOS configuration. The first + interface will be called ens3, the second one + ens8 and starting from there incremented by 1. + + + + + After changing the interface names, rebuild your system with + nixos-rebuild boot to activate the new configuration + after a reboot. If you switch to the new configuration right away you + might lose network connectivity! If using nixops, + deploy with nixops deploy --force-reboot. + + + + + + + + The following changes apply if the stateVersion is + changed to 17.09 or higher. For stateVersion = "17.03" + or lower the old behavior is preserved. + + + + + The postgres default version was changed from 9.5 to + 9.6. + + + + + The postgres superuser name has changed from + root to postgres to more closely + follow what other Linux distributions are doing. + + + + + The postgres default dataDir has + changed from /var/db/postgres to + /var/lib/postgresql/$psqlSchema where $psqlSchema is + 9.6 for example. + + + + + The mysql default dataDir has + changed from /var/mysql to + /var/lib/mysql. + + + + + Radicale's default package has changed from 1.x to 2.x. Instructions to + migrate can be found here + . It is also possible to use the newer version by setting the + package to radicale2, which is + done automatically when stateVersion is 17.09 or + higher. The extraArgs option has been added to allow + passing the data migration arguments specified in the instructions; see + the + radicale.nix + NixOS test for an example migration. + + + + + + + The aiccu package was removed. This is due to SixXS + sunsetting its IPv6 + tunnel. + + + + + The fanctl package and fan module + have been removed due to the developers not upstreaming their iproute2 + patches and lagging with compatibility to recent iproute2 versions. + + + + + Top-level idea package collection was renamed. All + JetBrains IDEs are now at jetbrains. + + + + + flexget's state database cannot be upgraded to its new + internal format, requiring removal of any existing + db-config.sqlite which will be automatically recreated. + + + + + The ipfs service now doesn't ignore the + dataDir 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 + +dataDir=<valueOfDataDir> +mv /var/lib/ipfs/.ipfs/* $dataDir +rmdir /var/lib/ipfs/.ipfs + + + + + + The caddy service was previously using an extra + .caddy directory in the data directory specified with + the dataDir option. The contents of the + .caddy directory are now expected to be in the + dataDir. + + + + + The ssh-agent user service is not started by default + anymore. Use programs.ssh.startAgent to enable it if + needed. There is also a new programs.gnupg.agent module + that creates a gpg-agent user service. It can also + serve as a SSH agent if enableSSHSupport is set. + + + + + The services.tinc.networks.<name>.listenAddress + 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 + services.tinc.networks.<name>.bindToAddress + instead. Refer to the description of the options for more details. + + + + + tlsdate package and module were removed. This is due to + the project being dead and not building with openssl 1.1. + + + + + wvdial package and module were removed. This is due to + the project being dead and not building with openssl 1.1. + + + + + cc-wrapper's setup-hook now exports a number of + environment variables corresponding to binutils binaries, (e.g. + LD, STRIP, RANLIB, 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. + + + + + services.firefox.syncserver 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. + + + + + The compiz window manager and package was removed. The + system support had been broken for several years. + + + + + Touchpad support should now be enabled through libinput + as synaptics is now deprecated. See the option + services.xserver.libinput.enable. + + + + + grsecurity/PaX support has been dropped, following upstream's decision to + cease free support. See + + upstream's announcement for more information. No complete + replacement for grsecurity/PaX is available presently. + + + + + services.mysql now has declarative configuration of + databases and users with the ensureDatabases and + ensureUsers options. + + + These options will never delete existing databases and users, especially + not when the value of the options are changed. + + + The MySQL users will be identified using + + Unix socket authentication. This authenticates the Unix user with + the same name only, and that without the need for a password. + + + If you have previously created a MySQL root user + with a password, you will need to add + root user for unix socket authentication before using + the new options. This can be done by running the following SQL script: + +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'; + + + + + + services.mysqlBackup now works by default without any + user setup, including for users other than mysql. + + + By default, the mysql user is no longer the user which + performs the backup. Instead a system account + mysqlbackup is used. + + + The mysqlBackup service is also now using systemd + timers instead of cron. + + + Therefore, the services.mysqlBackup.period option no + longer exists, and has been replaced with + services.mysqlBackup.calendar, which is in the format + of + systemd.time(7). + + + 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. + + + You can check that backups still work by running systemctl start + mysql-backup then systemctl status + mysql-backup. + + + + + Templated systemd services e.g container@name are now + handled currectly when switching to a new configuration, resulting in them + being reloaded. + + + + + Steam: the newStdcpp parameter was removed and should + not be needed anymore. + + + + + 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. + + + +
+ +
+ Other Notable Changes + + + + + Modules can now be disabled by using + + disabledModules, 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. + + + + + 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. + + + + + ZFS/SPL have been updated to 0.7.0, zfsUnstable, + splUnstable have therefore been removed. + + + + + The option now allows the value + null in addition to timezone strings. This value allows + changing the timezone of a system imperatively using timedatectl + set-timezone. The default timezone is still UTC. + + + + + Nixpkgs overlays may now be specified with a file as well as a directory. + The value of <nixpkgs-overlays> may be a file, and + ~/.config/nixpkgs/overlays.nix can be used instead of + the ~/.config/nixpkgs/overlays directory. + + + See the overlays chapter of the Nixpkgs manual for more details. + + + + + Definitions for /etc/hosts can now be specified + declaratively with networking.hosts. + + + + + 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. + + + This therefore leads to adding a new debug option to + set the log level to the previous verbose mode, to make debugging easier, + but still accessible easily. + + + Additionally a copytoram 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. + + + + + services.gitlab-runner.configOptions has been added to + specify the configuration of gitlab-runners declaratively. + + + + + services.jenkins.plugins has been added to install + plugins easily, this can be generated with jenkinsPlugins2nix. + + + + + services.postfix.config 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. + + + + + The GitLab package and module have been updated to the latest 10.0 + release. + + + + + The systemd-boot boot loader now lists the NixOS + version, kernel version and build date of all bootable generations. + + + + + 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 or setting it + to "random". + + + +
+
diff --git a/nixos/doc/manual/release-notes/rl-1803.xml b/nixos/doc/manual/release-notes/rl-1803.xml new file mode 100644 index 0000000..c14679e --- /dev/null +++ b/nixos/doc/manual/release-notes/rl-1803.xml @@ -0,0 +1,855 @@ +
+ Release 18.03 (“Impala”, 2018/04/04) + +
+ Highlights + + + In addition to numerous new and upgraded packages, this release has the + following highlights: + + + + + + End of support is planned for end of October 2018, handing over to 18.09. + + + + + 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. + + + + + Nix now defaults to 2.0; see its + release + notes. + + + + + Core version changes: linux: 4.9 -> 4.14, glibc: 2.25 -> 2.26, gcc: 6 -> + 7, systemd: 234 -> 237. + + + + + Desktop version changes: gnome: 3.24 -> 3.26, (KDE) plasma-desktop: 5.10 + -> 5.12. + + + + + 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: + + + + libmysql has been deprecated, please use + mysql.connector-c instead, a compatibility passthru + has been added to the MySQL packages. + + + + + The mysql57 package has a new + static output containing the static libraries + including libmysqld.a + + + + + + + + PHP now defaults to PHP 7.2, updated from 7.1. + + + +
+ +
+ New Services + + + The following new services were added since the last release: + + + + + + ./config/krb5/default.nix + + + + + ./hardware/digitalbitbox.nix + + + + + ./misc/label.nix + + + + + ./programs/ccache.nix + + + + + ./programs/criu.nix + + + + + ./programs/digitalbitbox/default.nix + + + + + ./programs/less.nix + + + + + ./programs/npm.nix + + + + + ./programs/plotinus.nix + + + + + ./programs/rootston.nix + + + + + ./programs/systemtap.nix + + + + + ./programs/sway.nix + + + + + ./programs/udevil.nix + + + + + ./programs/way-cooler.nix + + + + + ./programs/yabar.nix + + + + + ./programs/zsh/zsh-autoenv.nix + + + + + ./services/backup/borgbackup.nix + + + + + ./services/backup/crashplan-small-business.nix + + + + + ./services/desktops/dleyna-renderer.nix + + + + + ./services/desktops/dleyna-server.nix + + + + + ./services/desktops/pipewire.nix + + + + + ./services/desktops/gnome3/chrome-gnome-shell.nix + + + + + ./services/desktops/gnome3/tracker-miners.nix + + + + + ./services/hardware/fwupd.nix + + + + + ./services/hardware/interception-tools.nix + + + + + ./services/hardware/u2f.nix + + + + + ./services/hardware/usbmuxd.nix + + + + + ./services/mail/clamsmtp.nix + + + + + ./services/mail/dkimproxy-out.nix + + + + + ./services/mail/pfix-srsd.nix + + + + + ./services/misc/gitea.nix + + + + + ./services/misc/home-assistant.nix + + + + + ./services/misc/ihaskell.nix + + + + + ./services/misc/logkeys.nix + + + + + ./services/misc/novacomd.nix + + + + + ./services/misc/osrm.nix + + + + + ./services/misc/plexpy.nix + + + + + ./services/misc/pykms.nix + + + + + ./services/misc/tzupdate.nix + + + + + ./services/monitoring/fusion-inventory.nix + + + + + ./services/monitoring/prometheus/exporters.nix + + + + + ./services/network-filesystems/beegfs.nix + + + + + ./services/network-filesystems/davfs2.nix + + + + + ./services/network-filesystems/openafs/client.nix + + + + + ./services/network-filesystems/openafs/server.nix + + + + + ./services/network-filesystems/ceph.nix + + + + + ./services/networking/aria2.nix + + + + + ./services/networking/monero.nix + + + + + ./services/networking/nghttpx/default.nix + + + + + ./services/networking/nixops-dns.nix + + + + + ./services/networking/rxe.nix + + + + + ./services/networking/stunnel.nix + + + + + ./services/web-apps/matomo.nix + + + + + ./services/web-apps/restya-board.nix + + + + + ./services/web-servers/mighttpd2.nix + + + + + ./services/x11/fractalart.nix + + + + + ./system/boot/binfmt.nix + + + + + ./system/boot/grow-partition.nix + + + + + ./tasks/filesystems/ecryptfs.nix + + + + + ./virtualisation/hyperv-guest.nix + + + +
+ +
+ Backward Incompatibilities + + + When upgrading from a previous release, please be aware of the following + incompatible changes: + + + + + + sound.enable now defaults to false. + + + + + Dollar signs in options under 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. + + + + + The postage package (for web-based PostgreSQL + administration) has been renamed to pgmanage. The + corresponding module has also been renamed. To migrate please rename all + options to + . + + + + + 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 nix-env. The change + affects the following packages: + + + + 2048-in-terminal → + _2048-in-terminal + + + + + 90secondportraits → + _90secondportraits + + + + + 2bwm → _2bwm + + + + + 389-ds-base → _389-ds-base + + + + + + + + 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. + + + DSA support was + deprecated in + OpenSSH 7.0, due to it being too weak. To re-enable support, add + PubkeyAcceptedKeyTypes +ssh-dss to the end of your + . + + + After updating the keys to be stronger, anyone still on a pre-17.03 + version is safe to jump to 17.03, as vetted + here. + + + + + The openssh package now includes Kerberos support by + default; the openssh_with_kerberos package is now a + deprecated alias. If you do not want Kerberos support, you can do + openssh.override { withKerberos = false; }. Note, this + also applies to the openssh_hpn package. + + + + + cc-wrapper has been split in two; there is now also a + bintools-wrapper. The most commonly used files in + nix-support are now split between the two wrappers. + Some commonly used ones, like + nix-support/dynamic-linker, are duplicated for + backwards compatability, even though they rightly belong only in + bintools-wrapper. Other more obscure ones are just + moved. + + + + + 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. + + 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 propagatedNativeBuildInputs should instead + be propagatedBuildInputs. Thankfully, that was and is + the least used type of dependency. Also, it means that some + propagatedBuildInputs should instead be + depsTargetTargetPropagated. Other types dependencies + should be unaffected. + + + + + lib.addPassthru drv passthru is removed. Use + lib.extendDerivation true passthru drv instead. + + + + + The memcached service no longer accept dynamic socket + paths via . Unix sockets can be + still enabled by and + will be accessible at /run/memcached/memcached.sock. + + + + + The hardware.amdHybridGraphics.disable 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. + + + + + The merging of config options for + services.postfix.config was buggy. Previously, if other + options in the Postfix module like + services.postfix.useSrs 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, + lib.mkForce or lib.mkOverride can be + used. + + + + + The following changes apply if the stateVersion is + changed to 18.03 or higher. For stateVersion = "17.09" + or lower the old behavior is preserved. + + + + + matrix-synapse uses postgresql by default instead of + sqlite. Migration instructions can be found + + here . + + + + + + + The jid package has been removed, due to maintenance + overhead of a go package having non-versioned dependencies. + + + + + When using (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, Option "XkbRules" "base" may result in + broken keyboard layout. + + + + + The attic package was removed. A maintained fork called + Borg should be used + instead. Migration instructions can be found + here. + + + + + The Piwik analytics software was renamed to Matomo: + + + + The package pkgs.piwik was renamed to + pkgs.matomo. + + + + + The service services.piwik was renamed to + services.matomo. + + + + + The data directory /var/lib/piwik was renamed to + /var/lib/matomo. All files will be moved + automatically on first startup, but you might need to adjust your + backup scripts. + + + + + The default for the nginx configuration + changed from piwik.${config.networking.hostName} to + matomo.${config.networking.hostName}.${config.networking.domain} + if is set, + matomo.${config.networking.hostName} if it is not + set. If you change your , remember you'll + need to update the trustedHosts[] array in + /var/lib/matomo/config/config.ini.php as well. + + + + + The piwik user was renamed to + matomo. The service will adjust ownership + automatically for files in the data directory. If you use unix socket + authentication, remember to give the new matomo user + access to the database and to change the username to + matomo in the [database] section + of /var/lib/matomo/config/config.ini.php. + + + + + 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. + + + + + + + + nodejs-4_x is end-of-life. + nodejs-4_x, nodejs-slim-4_x and + nodePackages_4_x are removed. + + + + + The pump.io NixOS module was removed. It is now + maintained as an + external + module. + + + + + The Prosody XMPP server has received a major update. The following modules + were renamed: + + + + is now + + + + + + is now + + + + + + + Many new modules are now core modules, most notably + and + . + + + The better-performing libevent backend is now enabled + by default. + + + withCommunityModules now passes through the modules to + . Use + withOnlyInstalledCommunityModules for modules that + should not be enabled directly, e.g lib_ldap. + + + + + All prometheus exporter modules are now defined as submodules. The + exporters are configured using + services.prometheus.exporters. + + + +
+ +
+ Other Notable Changes + + + + + ZNC option now defaults to + true. That means that old configuration is not + overwritten by default when update to the znc options are made. + + + + + The option + has been added for wireless networks with WPA-Enterprise authentication. + There is also a new option to directly + configure wpa_supplicant and to + connect to hidden networks. + + + + + In the module the + following options have been removed: + + + + + + + + + + + + + + + + + + + + + + + + + + + + To assign static addresses to an interface the options + and should + be used instead. The options and + have been renamed to + respectively. The new options + and have been + added to set up static routing. + + + + + The option is now + 127.0.0.1 by default. Previously the default behaviour + was to listen on all interfaces. + + + + + services.btrfs.autoScrub has been added, to + periodically check btrfs filesystems for data corruption. If there's a + correct copy available, it will automatically repair corrupted blocks. + + + + + displayManager.lightdm.greeters.gtk.clock-format. has + been added, the clock format string (as expected by strftime, e.g. + %H:%M) to use with the lightdm gtk greeter panel. + + + If set to null the default clock format is used. + + + + + displayManager.lightdm.greeters.gtk.indicators has been + added, a list of allowed indicator modules to use with the lightdm gtk + greeter panel. + + + Built-in indicators include ~a11y, + ~language, ~session, + ~power, ~clock, + ~host, ~spacer. Unity indicators can + be represented by short name (e.g. sound, + power), service file name, or absolute path. + + + If set to null the default indicators are used. + + + In order to have the previous default configuration add + + services.xserver.displayManager.lightdm.greeters.gtk.indicators = [ + "~host" "~spacer" + "~clock" "~spacer" + "~session" + "~language" + "~a11y" + "~power" + ]; + + to your configuration.nix. + + + + + The NixOS test driver supports user services declared by + systemd.user.services. The methods + waitForUnit, getUnitInfo, + startJob and stopJob provide an + optional $user argument for that purpose. + + + + + Enabling bash completion on NixOS, + programs.bash.enableCompletion, will now also enable + completion for the Nix command line tools by installing the + nix-bash-completions + package. + + + +
+
diff --git a/nixos/doc/manual/release-notes/rl-1809.xml b/nixos/doc/manual/release-notes/rl-1809.xml new file mode 100644 index 0000000..8715a05 --- /dev/null +++ b/nixos/doc/manual/release-notes/rl-1809.xml @@ -0,0 +1,932 @@ +
+ Release 18.09 (“Jellyfish”, 2018/10/05) + +
+ Highlights + + + In addition to numerous new and upgraded packages, this release has the + following notable updates: + + + + + + End of support is planned for end of April 2019, handing over to 19.03. + + + + + 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. + + + + + Nix has been updated to 2.1; see its + release + notes. + + + + + Core versions: linux: 4.14 LTS (unchanged), glibc: 2.26 → 2.27, gcc: 7 + (unchanged), systemd: 237 → 239. + + + + + Desktop version changes: gnome: 3.26 → 3.28, (KDE) plasma-desktop: 5.12 + → 5.13. + + + + + + Notable changes and additions for 18.09 include: + + + + + + Support for wrapping binaries using firejail has been + added through programs.firejail.wrappedBinaries. + + + For example + + +programs.firejail = { + enable = true; + wrappedBinaries = { + firefox = "${lib.getBin pkgs.firefox}/bin/firefox"; + mpv = "${lib.getBin pkgs.mpv}/bin/mpv"; + }; +}; + + + This will place firefox and mpv + binaries in the global path wrapped by firejail. + + + + + User channels are now in the default NIX_PATH, allowing + users to use their personal nix-channel defined + channels in nix-build and nix-shell + commands, as well as in imports like import + <mychannel>. + + + For example + + +$ 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' + + + +
+ +
+ New Services + + + A curated selection of new services that were added since the last release: + + + + + + The services.cassandra 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 + Apache + Cassandra. + + + + + There is a new services.foundationdb module for + deploying + FoundationDB + clusters. + + + + + When enabled the iproute2 will copy the files expected + by ip route (e.g., rt_tables) in + /etc/iproute2. This allows to write aliases for + routing tables for instance. + + + + + services.strongswan-swanctl is a modern replacement for + services.strongswan. You can use either one of them to + setup IPsec VPNs but not both at the same time. + + + services.strongswan-swanctl uses the + swanctl + command which uses the modern + vici + Versatile IKE Configuration Interface. The deprecated + ipsec command used in + services.strongswan is using the legacy + stroke + configuration interface. + + + + + The new services.elasticsearch-curator service + periodically curates or manages, your Elasticsearch indices and snapshots. + + + + + + Every new services: + + + + + + ./config/xdg/autostart.nix + + + + + ./config/xdg/icons.nix + + + + + ./config/xdg/menus.nix + + + + + ./config/xdg/mime.nix + + + + + ./hardware/brightnessctl.nix + + + + + ./hardware/onlykey.nix + + + + + ./hardware/video/uvcvideo/default.nix + + + + + ./misc/documentation.nix + + + + + ./programs/firejail.nix + + + + + ./programs/iftop.nix + + + + + ./programs/sedutil.nix + + + + + ./programs/singularity.nix + + + + + ./programs/xss-lock.nix + + + + + ./programs/zsh/zsh-autosuggestions.nix + + + + + ./services/admin/oxidized.nix + + + + + ./services/backup/duplicati.nix + + + + + ./services/backup/restic.nix + + + + + ./services/backup/restic-rest-server.nix + + + + + ./services/cluster/hadoop/default.nix + + + + + ./services/databases/aerospike.nix + + + + + ./services/databases/monetdb.nix + + + + + ./services/desktops/bamf.nix + + + + + ./services/desktops/flatpak.nix + + + + + ./services/desktops/zeitgeist.nix + + + + + ./services/development/bloop.nix + + + + + ./services/development/jupyter/default.nix + + + + + ./services/hardware/lcd.nix + + + + + ./services/hardware/undervolt.nix + + + + + ./services/misc/clipmenu.nix + + + + + ./services/misc/gitweb.nix + + + + + ./services/misc/serviio.nix + + + + + ./services/misc/safeeyes.nix + + + + + ./services/misc/sysprof.nix + + + + + ./services/misc/weechat.nix + + + + + ./services/monitoring/datadog-agent.nix + + + + + ./services/monitoring/incron.nix + + + + + ./services/networking/dnsdist.nix + + + + + ./services/networking/freeradius.nix + + + + + ./services/networking/hans.nix + + + + + ./services/networking/morty.nix + + + + + ./services/networking/ndppd.nix + + + + + ./services/networking/ocserv.nix + + + + + ./services/networking/owamp.nix + + + + + ./services/networking/quagga.nix + + + + + ./services/networking/shadowsocks.nix + + + + + ./services/networking/stubby.nix + + + + + ./services/networking/zeronet.nix + + + + + ./services/security/certmgr.nix + + + + + ./services/security/cfssl.nix + + + + + ./services/security/oauth2_proxy_nginx.nix + + + + + ./services/web-apps/virtlyst.nix + + + + + ./services/web-apps/youtrack.nix + + + + + ./services/web-servers/hitch/default.nix + + + + + ./services/web-servers/hydron.nix + + + + + ./services/web-servers/meguca.nix + + + + + ./services/web-servers/nginx/gitweb.nix + + + + + ./virtualisation/kvmgt.nix + + + + + ./virtualisation/qemu-guest-agent.nix + + + +
+ +
+ Backward Incompatibilities + + + When upgrading from a previous release, please be aware of the following + incompatible changes: + + + + + + Some licenses that were incorrectly not marked as unfree now are. This is + the case for: + + + + cc-by-nc-sa-20: Creative Commons Attribution Non Commercial Share Alike + 2.0 + + + + + cc-by-nc-sa-25: Creative Commons Attribution Non Commercial Share Alike + 2.5 + + + + + cc-by-nc-sa-30: Creative Commons Attribution Non Commercial Share Alike + 3.0 + + + + + cc-by-nc-sa-40: Creative Commons Attribution Non Commercial Share Alike + 4.0 + + + + + cc-by-nd-30: Creative Commons Attribution-No Derivative Works v3.00 + + + + + msrla: Microsoft Research License Agreement + + + + + + + + The deprecated services.cassandra module has seen a + complete rewrite. (See above.) + + + + + lib.strict is removed. Use + builtins.seq instead. + + + + + The clementine package points now to the free + derivation. clementineFree is removed now and + clementineUnfree points to the package which is bundled + with the unfree libspotify package. + + + + + The netcat package is now taken directly from OpenBSD's + libressl, 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. + + + + + The services.docker-registry.extraConfig 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 + the + docker/distribution docs. + + + + + gnucash has changed from version 2.4 to 3.x. If you've + been using gnucash (version 2.4) instead of + gnucash26 (version 2.6) you must open your Gnucash data + file(s) with gnucash26 and then save them to upgrade + the file format. Then you may use your data file(s) with Gnucash 3.x. See + the upgrade + documentation. + Gnucash 2.4 is still available under the attribute + gnucash24. + + + + + services.munge now runs as user (and group) + munge instead of root. Make sure the key file is + accessible to the daemon. + + + + + dockerTools.buildImage now uses null + as default value for tag, which indicates that the nix + output hash will be used as tag. + + + + + The ELK stack: elasticsearch, + logstash and kibana has been + upgraded from 2.* to 6.3.*. The 2.* versions have been + unsupported since + last year so they have been removed. You can still use the 5.* + versions under the names elasticsearch5, + logstash5 and kibana5. + + + The elastic beats: filebeat, + heartbeat, metricbeat and + packetbeat have had the same treatment: they now target + 6.3.* as well. The 5.* versions are available under the names: + filebeat5, heartbeat5, + metricbeat5 and packetbeat5 + + + The ELK-6.3 stack now comes with + X-Pack by + default. Since X-Pack is licensed under the + Elastic + License the ELK packages now have an unfree license. To use them + you need to specify allowUnfree = true; in your nixpkgs + configuration. + + + Fortunately there is also a free variant of the ELK stack without X-Pack. + The packages are available under the names: + elasticsearch-oss, logstash-oss and + kibana-oss. + + + + + Options + boot.initrd.luks.devices.name.yubikey.ramfsMountPoint + boot.initrd.luks.devices.name.yubikey.storage.mountPoint + were removed. luksroot.nix 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. + + + + + stdenv.system and system 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 stdenv.buildPlatform.system + can be used instead for the old behavior. They should be using that + anyways for clarity. + + + + + Groups kvm and render are introduced now, as systemd requires them. + + + +
+ +
+ Other Notable Changes + + + + + dockerTools.pullImage relies on image digest instead of + image tag to download the image. The sha256 of a pulled + image has to be updated. + + + + + lib.attrNamesToStr has been deprecated. Use more + specific concatenation (lib.concat(Map)StringsSep) + instead. + + + + + lib.addErrorContextToAttrs has been deprecated. Use + builtins.addErrorContext directly. + + + + + lib.showVal has been deprecated. Use + lib.traceSeqN instead. + + + + + lib.traceXMLVal has been deprecated. Use + lib.traceValFn builtins.toXml instead. + + + + + lib.traceXMLValMarked has been deprecated. Use + lib.traceValFn (x: str + builtins.toXML x) instead. + + + + + The pkgs argument to NixOS modules can now be set + directly using nixpkgs.pkgs. Previously, only the + system, config and + overlays arguments could be used to influence + pkgs. + + + + + A NixOS system can now be constructed more easily based on a preexisting + invocation of Nixpkgs. For example: + +inherit (pkgs.nixos { + boot.loader.grub.enable = false; + fileSystems."/".device = "/dev/xvda1"; +}) toplevel kernel initialRamdisk manual; + + 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. + + + + + lib.traceValIfNot has been deprecated. Use + if/then/else and lib.traceValSeq + instead. + + + + + lib.traceCallXml has been deprecated. Please complain + if you use the function regularly. + + + + + The attribute lib.nixpkgsVersion has been deprecated in + favor of lib.version. Please refer to the discussion in + NixOS/nixpkgs#39416 + for further reference. + + + + + lib.recursiveUpdateUntil was not acting according to + its specification. It has been fixed to act according to the docstring, + and a test has been added. + + + + + The module for has two new options now: + + + + + + + + + Puts the generated Diffie-Hellman parameters into the Nix store instead + of managing them in a stateful manner in + /var/lib/dhparams. + + + + + + + + + + The default bit size to use for the generated Diffie-Hellman + parameters. + + + + + + + The path to the actual generated parameter files should now be queried + using + config.security.dhparams.params.name.path + because it might be either in the Nix store or in a directory configured + by . + + + + For developers: + + 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). + + + An example usage of this would be: + +{ config, ... }: + +{ + security.dhparams.params.myservice = {}; + environment.etc."myservice.conf".text = '' + dhparams = ${config.security.dhparams.params.myservice.path} + ''; +} + + + + + + + networking.networkmanager.useDnsmasq has been + deprecated. Use networking.networkmanager.dns instead. + + + + + The Kubernetes package has been bumped to major version 1.11. Please + consult the + release + notes for details on new features and api changes. + + + + + The option + services.kubernetes.apiserver.admissionControl was + renamed to + services.kubernetes.apiserver.enableAdmissionPlugins. + + + + + 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. + + + + + The option services.kubernetes.apiserver.address was + renamed to services.kubernetes.apiserver.bindAddress. + Note that the default value has changed from 127.0.0.1 to 0.0.0.0. + + + + + The option services.kubernetes.apiserver.publicAddress + was not used and thus has been removed. + + + + + The option + services.kubernetes.addons.dashboard.enableRBAC was + renamed to + services.kubernetes.addons.dashboard.rbac.enable. + + + + + The Kubernetes Dashboard now has only minimal RBAC permissions by default. + If dashboard cluster-admin rights are desired, set + services.kubernetes.addons.dashboard.rbac.clusterAdmin + 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: kubectl delete clusterrolebinding + kubernetes-dashboard + + + + + The programs.screen module provides allows to configure + /etc/screenrc, however the module behaved fairly + counterintuitive as the config exists, but the package wasn't available. + Since 18.09 pkgs.screen will be added to + environment.systemPackages. + + + + + The module now uses WPA2 by + default. + + + + + s6Dns, s6Networking, + s6LinuxUtils and s6PortableUtils + renamed to s6-dns, s6-networking, + s6-linux-utils and s6-portable-utils + respectively. + + + + + The module option is now defaulted to + true. + + + + + The config activation script of nixos-rebuild now + reloads + all user units for each authenticated user. + + + + + The default display manager is now LightDM. To use SLiM set + services.xserver.displayManager.slim.enable to + true. + + + + + 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 </para><para> to start a + new paragraph. + + + + + Top-level buildPlatform, + hostPlatform, and targetPlatform in + Nixpkgs are deprecated. Please use their equivalents in + stdenv instead: + stdenv.buildPlatform, + stdenv.hostPlatform, and + stdenv.targetPlatform. + + + +
+
diff --git a/nixos/doc/manual/release-notes/rl-1903.xml b/nixos/doc/manual/release-notes/rl-1903.xml new file mode 100644 index 0000000..89d9f48 --- /dev/null +++ b/nixos/doc/manual/release-notes/rl-1903.xml @@ -0,0 +1,413 @@ +
+ Release 19.03 (“Koi”, 2019/03/??) + +
+ Highlights + + + In addition to numerous new and upgraded packages, this release has the + following highlights: + + + + + + The default Python 3 interpreter is now CPython 3.7 instead of CPython 3.6. + + + +
+ +
+ New Services + + + The following new services were added since the last release: + + + + + + ./programs/nm-applet.nix + + + + + There is a new security.googleOsLogin module for using + OS Login + to manage SSH access to Google Compute Engine instances, which supersedes + the imperative and broken google-accounts-daemon used + in nixos/modules/virtualisation/google-compute-config.nix. + + + +
+ +
+ Backward Incompatibilities + + + When upgrading from a previous release, please be aware of the following + incompatible changes: + + + + + + The minimum version of Nix required to evaluate Nixpkgs is now 2.0. + + + + + For users of NixOS 18.03 and 19.03, NixOS defaults to Nix 2.0, but + supports using Nix 1.11 by setting nix.package = + pkgs.nix1;. 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. + + + + + For users of NixOS 17.09, you will first need to upgrade Nix by setting + nix.package = pkgs.nixStable2; and run + nixos-rebuild switch as the root + user. + + + + + For users of a daemon-less Nix installation on Linux or macOS, you can + upgrade Nix by running curl https://nixos.org/nix/install | + sh, or prior to doing a channel update, running + nix-env -iA nix. + + + 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. + + + + + For users of the Nix daemon on macOS, you can upgrade Nix by running + 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. + + + + + + + The Syncthing state and configuration data has been moved from + services.syncthing.dataDir to the newly defined + services.syncthing.configDir, which default to + /var/lib/syncthing/.config/syncthing. + This change makes possible to share synced directories using ACLs + without Syncthing resetting the permission on every start. + + + + + The ntp 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 + services.ntp.restrictDefault and + services.ntp.restrictSource to + []. + + + + + Package rabbitmq_server is renamed to + rabbitmq-server. + + + + + The light module no longer uses setuid binaries, but + udev rules. As a consequence users of that module have to belong to the + video group in order to use the executable (i.e. + users.users.yourusername.extraGroups = ["video"];). + + + + + Buildbot now supports Python 3 and its packages have been moved to + pythonPackages. The options + and + can be used to select + the Python 2 or 3 version of the package. + + + + + Options + services.znc.confOptions.networks.name.userName and + services.znc.confOptions.networks.name.modulePackages + were removed. They were never used for anything and can therefore safely be removed. + + + + + Package wasm has been renamed proglodyte-wasm. The package + wasm will be pointed to ocamlPackages.wasm in 19.09, so + make sure to update your configuration if you want to keep proglodyte-wasm + + + + + When the nixpkgs.pkgs option is set, NixOS will no + longer ignore the nixpkgs.overlays option. The old + behavior can be recovered by setting nixpkgs.overlays = + lib.mkForce [];. + + + + + OpenSMTPD has been upgraded to version 6.4.0p1. This release makes + backwards-incompatible changes to the configuration file format. See + man smtpd.conf for more information on the new file + format. + + + + + The versioned postgresql have been renamed to use + underscore number seperators. For example, postgresql96 + has been renamed to postgresql_9_6. + + + + + Package consul-ui and passthrough consul.ui have been removed. + The package consul now uses upstream releases that vendor the UI into the binary. + See #48714 + for details. + + + + + Slurm introduces the new option + services.slurm.stateSaveLocation, + which is now set to /var/spool/slurm by default + (instead of /var/spool). + Make sure to move all files to the new directory or to set the option accordingly. + + + The slurmctld now runs as user slurm instead of root. + If you want to keep slurmctld running as root, set + services.slurm.user = root. + + + The options services.slurm.nodeName and + services.slurm.partitionName are now sets of + strings to correctly reflect that fact that each of these + options can occour more than once in the configuration. + + + + + The solr package has been upgraded from 4.10.3 to 7.5.0 and has undergone + some major changes. The services.solr module has been updated to reflect + these changes. Please review http://lucene.apache.org/solr/ carefully before upgrading. + + + + + Package ckb is renamed to ckb-next, + and options hardware.ckb.* are renamed to + hardware.ckb-next.*. + + + + + The option services.xserver.displayManager.job.logToFile which was + previously set to true when using the display managers + lightdm, sddm or xpra has been + reset to the default value (false). + + + + + Network interface indiscriminate NixOS firewall options + (networking.firewall.allow*) are now preserved when also + setting interface specific rules such as networking.firewall.interfaces.en0.allow*. + These rules continue to use the pseudo device "default" + (networking.firewall.interfaces.default.*), and assigning + to this pseudo device will override the (networking.firewall.allow*) + options. + + + + + The nscd service now disables all caching of + passwd and group databases by + default. This was interferring with the correct functioning of the + libnss_systemd.so module which is used by + systemd to manage uids and usernames in the presence of + DynamicUser= in systemd services. This was already the + default behaviour in presence of services.sssd.enable = + true because nscd caching would interfere with + sssd 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. + + + If the old behaviour is desired, this can be restored by setting + the services.nscd.config option + with the desired caching parameters. + + 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 + ''; + + See #50316 + for details. + + + + + GitLab Shell previously used the nix store paths for the + gitlab-shell command in its + authorized_keys file, which might stop working after + garbage collection. To circumvent that, we regenerated that file on each + startup. As gitlab-shell has now been changed to use + /var/run/current-system/sw/bin/gitlab-shell, this is + not necessary anymore, but there might be leftover lines with a nix store + path. Regenerate the authorized_keys file via + sudo -u git -H gitlab-rake gitlab:shell:setup in that + case. + + + + + The pam_unix account module is now loaded with its + control field set to required instead of + sufficient, 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 + pam_unix. + 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 + .text]]>. + + + + + fish has been upgraded to 3.0. + It comes with a number of improvements and backwards incompatible changes. + See the fish release notes for more information. + + + +
+ +
+ Other Notable Changes + + + + + The module gained the option + which determines the used + Matomo version. + + + + + composableDerivation along with supporting library functions + has been removed. + + + + + The deprecated truecrypt package has been removed + and truecrypt attribute is now an alias for + veracrypt. VeraCrypt is backward-compatible with + TrueCrypt volumes. Note that cryptsetup also + supports loading TrueCrypt volumes. + + + + + 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 + Kubernetes v1.11. + 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: + . + + + + + The quassel-webserver package and module was removed from nixpkgs due to the lack + of maintainers. + + + + + The owncloud server packages and httpd subservice module were removed + from nixpkgs due to the lack of maintainers. + + + +
+
diff --git a/nixos/doc/manual/shell.nix b/nixos/doc/manual/shell.nix new file mode 100644 index 0000000..cc3609d --- /dev/null +++ b/nixos/doc/manual/shell.nix @@ -0,0 +1,8 @@ +let + pkgs = import ../../.. { }; +in +pkgs.mkShell { + name = "nixos-manual"; + + buildInputs = with pkgs; [ xmlformat jing xmloscopy ruby ]; +} diff --git a/nixos/doc/varlistentry-fixer.rb b/nixos/doc/varlistentry-fixer.rb new file mode 100755 index 0000000..6c7cc1e --- /dev/null +++ b/nixos/doc/varlistentry-fixer.rb @@ -0,0 +1,124 @@ +#!/usr/bin/env ruby + +# This script is written intended as a living, evolving tooling +# to fix oopsies within the docbook documentation. +# +# This is *not* a formatter. It, instead, handles some known cases +# where something bad happened, and fixing it manually is tedious. +# +# Read the code to see the different cases it handles. +# +# ALWAYS `make format` after fixing with this! +# ALWAYS read the changes, this tool isn't yet proven to be always right. + +require "rexml/document" +include REXML + +if ARGV.length < 1 then + $stderr.puts "Needs a filename." + exit 1 +end + +filename = ARGV.shift +doc = Document.new(File.open(filename)) + +$touched = false + +# Fixing varnames having a sibling element without spacing. +# This is to fix an initial `xmlformat` issue where `term` +# would mangle as spaces. +# +# +# types.separatedStringsep <---- +# +# ... +# +# Generates: types.separatedStringsep +# ^^^^ +# +# +# +# makeWrapperexecutablewrapperfileargs <---- +# +# +# Generates: makeWrapperexecutablewrapperfileargs +# ^^^^ ^^^^ ^^ ^^ +# +# +# namevalue <----- +# +# +# Generates: --optionnamevalue +# ^^ ^^ +doc.elements.each("//varlistentry/term") do |term| + ["varname", "function", "option", "replaceable"].each do |prev_name| + term.elements.each(prev_name) do |el| + if el.next_element and + el.next_element.name == "replaceable" and + el.next_sibling_node.class == Element + then + $touched = true + term.insert_after(el, Text.new(" ")) + end + end + end +end + + + +# +# nixos-option +# +# path <------ +# +# +# Generates: -Ipath +# ^^ +doc.elements.each("//cmdsynopsis/arg") do |term| + ["option", "replaceable"].each do |prev_name| + term.elements.each(prev_name) do |el| + if el.next_element and + el.next_element.name == "replaceable" and + el.next_sibling_node.class == Element + then + $touched = true + term.insert_after(el, Text.new(" ")) + end + end + end +end + +# +# +# +# +# +# +# +# +# +# +# name <---- +# +# +# Generates: [{--profile-name | -p }name] +# ^^^^ +doc.elements.each("//cmdsynopsis/arg") do |term| + ["group"].each do |prev_name| + term.elements.each(prev_name) do |el| + if el.next_element and + el.next_element.name == "replaceable" and + el.next_sibling_node.class == Element + then + $touched = true + term.insert_after(el, Text.new(" ")) + end + end + end +end + + +if $touched then + doc.context[:attribute_quote] = :quote + doc.write(output: File.open(filename, "w")) +end diff --git a/nixos/doc/xmlformat.conf b/nixos/doc/xmlformat.conf new file mode 100644 index 0000000..4a565c8 --- /dev/null +++ b/nixos/doc/xmlformat.conf @@ -0,0 +1,73 @@ +# +# DocBook Configuration file for "xmlformat" +# see http://www.kitebird.com/software/xmlformat/ +# 10 Sept. 2004 +# + +# Only block elements +ackno address appendix article biblioentry bibliography bibliomixed \ +biblioset blockquote book bridgehead callout calloutlist caption caution \ +chapter chapterinfo classsynopsis cmdsynopsis colophon constraintdef \ +constructorsynopsis dedication destructorsynopsis entry epigraph equation example \ +figure formalpara funcsynopsis glossary glossdef glossdiv glossentry glosslist \ +glosssee glossseealso graphic graphicco highlights imageobjectco important \ +index indexdiv indexentry indexinfo info informalequation informalexample \ +informalfigure informaltable legalnotice literallayout lot lotentry mediaobject \ +mediaobjectco msgmain msgset note orderedlist para part preface primaryie \ +procedure qandadiv qandaentry qandaset refentry refentrytitle reference \ +refnamediv refsect1 refsect2 refsect3 refsection revhistory screenshot sect1 \ +sect2 sect3 sect4 sect5 section seglistitem set setindex sidebar simpara \ +simplesect step substeps synopfragment synopsis table term title \ +toc variablelist varlistentry warning itemizedlist listitem \ +footnote colspec partintro row simplelist subtitle tbody tgroup thead tip + format block + normalize no + + +#appendix bibliography chapter glossary preface reference +# element-break 3 + +sect1 section + element-break 2 + + +# +para abstract + format block + entry-break 1 + exit-break 1 + normalize yes + wrap-length 79 + +title + format block + normalize = yes + entry-break = 0 + exit-break = 0 + +# Inline elements +abbrev accel acronym action application citation citebiblioid citerefentry citetitle \ +classname co code command computeroutput constant country database date email emphasis \ +envar errorcode errorname errortext errortype exceptionname fax filename \ +firstname firstterm footnoteref foreignphrase funcdef funcparams function \ +glossterm group guibutton guiicon guilabel guimenu guimenuitem guisubmenu \ +hardware holder honorific indexterm inlineequation inlinegraphic inlinemediaobject \ +interface interfacename \ +keycap keycode keycombo keysym lineage link literal manvolnum markup medialabel \ +menuchoice methodname methodparam modifier mousebutton olink ooclass ooexception \ +oointerface option optional otheraddr othername package paramdef parameter personname \ +phrase pob postcode productname prompt property quote refpurpose replaceable \ +returnvalue revnumber sgmltag state street structfield structname subscript \ +superscript surname symbol systemitem token trademark type ulink userinput \ +uri varargs varname void wordasword xref year mathphrase member tag + format inline + +programlisting screen + format verbatim + entry-break = 0 + exit-break = 0 + +# This is needed so that the spacing inside those tags is kept. +term cmdsynopsis arg + normalize yes + format block diff --git a/nixos/lib/build-vms.nix b/nixos/lib/build-vms.nix new file mode 100644 index 0000000..024f441 --- /dev/null +++ b/nixos/lib/build-vms.nix @@ -0,0 +1,99 @@ +{ system +, # Use a minimal kernel? + minimal ? false +, # Ignored + config ? null + # Nixpkgs, for qemu, lib and more +, pkgs +, # NixOS configuration to add to the VMs + extraConfigurations ? [] +}: + +with pkgs.lib; +with import ../lib/qemu-flags.nix { inherit pkgs; }; + +rec { + + inherit pkgs; + + qemu = pkgs.qemu_test; + + + # Build a virtual network from an attribute set `{ machine1 = + # config1; ... machineN = configN; }', where `machineX' is the + # hostname and `configX' is a NixOS system configuration. Each + # machine is given an arbitrary IP address in the virtual network. + buildVirtualNetwork = + nodes: let nodesOut = mapAttrs (n: buildVM nodesOut) (assignIPAddresses nodes); in nodesOut; + + + buildVM = + nodes: configurations: + + import ./eval-config.nix { + inherit system; + modules = configurations ++ + [ ../modules/virtualisation/qemu-vm.nix + ../modules/testing/test-instrumentation.nix # !!! should only get added for automated test runs + { key = "no-manual"; documentation.nixos.enable = false; } + { key = "qemu"; system.build.qemu = qemu; } + ] ++ optional minimal ../modules/testing/minimal-kernel.nix + ++ extraConfigurations; + extraArgs = { inherit nodes; }; + }; + + + # Given an attribute set { machine1 = config1; ... machineN = + # configN; }, sequentially assign IP addresses in the 192.168.1.0/24 + # range to each machine, and set the hostname to the attribute name. + assignIPAddresses = nodes: + + let + + machines = attrNames nodes; + + machinesNumbered = zipLists machines (range 1 254); + + nodes_ = flip map machinesNumbered (m: nameValuePair m.fst + [ ( { config, nodes, ... }: + let + interfacesNumbered = zipLists config.virtualisation.vlans (range 1 255); + interfaces = flip map interfacesNumbered ({ fst, snd }: + nameValuePair "eth${toString snd}" { ipv4.addresses = + [ { address = "192.168.${toString fst}.${toString m.snd}"; + prefixLength = 24; + } ]; + }); + in + { key = "ip-address"; + config = + { networking.hostName = m.fst; + + networking.interfaces = listToAttrs interfaces; + + networking.primaryIPAddress = + optionalString (interfaces != []) (head (head interfaces).value.ipv4.addresses).address; + + # Put the IP addresses of all VMs in this machine's + # /etc/hosts file. If a machine has multiple + # interfaces, use the IP address corresponding to + # the first interface (i.e. the first network in its + # virtualisation.vlans option). + networking.extraHosts = flip concatMapStrings machines + (m': let config = (getAttr m' nodes).config; in + optionalString (config.networking.primaryIPAddress != "") + ("${config.networking.primaryIPAddress} " + + "${config.networking.hostName}\n")); + + virtualisation.qemu.options = + flip map interfacesNumbered + ({ fst, snd }: qemuNICFlags snd fst m.snd); + }; + } + ) + (getAttr m.fst nodes) + ] ); + + in listToAttrs nodes_; + +} diff --git a/nixos/lib/eval-config.nix b/nixos/lib/eval-config.nix new file mode 100644 index 0000000..5f05b03 --- /dev/null +++ b/nixos/lib/eval-config.nix @@ -0,0 +1,67 @@ +# From an end-user configuration file (`configuration.nix'), build a NixOS +# configuration object (`config') from which we can retrieve option +# values. + +# !!! Please think twice before adding to this argument list! +# Ideally eval-config.nix would be an extremely thin wrapper +# around lib.evalModules, so that modular systems that have nixos configs +# as subcomponents (e.g. the container feature, or nixops if network +# expressions are ever made modular at the top level) can just use +# types.submodule instead of using eval-config.nix +{ # !!! system can be set modularly, would be nice to remove + system ? builtins.currentSystem +, # !!! is this argument needed any more? The pkgs argument can + # be set modularly anyway. + pkgs ? null +, # !!! what do we gain by making this configurable? + baseModules ? import ../modules/module-list.nix +, # !!! See comment about args in lib/modules.nix + extraArgs ? {} +, # !!! See comment about args in lib/modules.nix + specialArgs ? {} +, modules +, # !!! See comment about check in lib/modules.nix + check ? true +, prefix ? [] +, lib ? import ../../lib +}: + +let extraArgs_ = extraArgs; pkgs_ = pkgs; + extraModules = let e = builtins.getEnv "NIXOS_EXTRA_MODULE_PATH"; + in if e == "" then [] else [(import e)]; +in + +let + pkgsModule = rec { + _file = ./eval-config.nix; + key = _file; + config = { + # Explicit `nixpkgs.system` or `nixpkgs.localSystem` should override + # this. Since the latter defaults to the former, the former should + # default to the argument. That way this new default could propagate all + # they way through, but has the last priority behind everything else. + nixpkgs.system = lib.mkDefault system; + _module.args.pkgs = lib.mkIf (pkgs_ != null) (lib.mkForce pkgs_); + }; + }; + +in rec { + + # Merge the option definitions in all modules, forming the full + # system configuration. + inherit (lib.evalModules { + inherit prefix check; + modules = modules ++ extraModules ++ baseModules ++ [ pkgsModule ]; + args = extraArgs; + specialArgs = + { modulesPath = builtins.toString ../modules; } // specialArgs; + }) config options; + + # These are the extra arguments passed to every module. In + # particular, Nixpkgs is passed through the "pkgs" argument. + extraArgs = extraArgs_ // { + inherit modules baseModules; + }; + + inherit (config._module.args) pkgs; +} diff --git a/nixos/lib/from-env.nix b/nixos/lib/from-env.nix new file mode 100644 index 0000000..6bd71e4 --- /dev/null +++ b/nixos/lib/from-env.nix @@ -0,0 +1,4 @@ +# TODO: remove this file. There is lib.maybeEnv now +name: default: +let value = builtins.getEnv name; in +if value == "" then default else value diff --git a/nixos/lib/make-channel.nix b/nixos/lib/make-channel.nix new file mode 100644 index 0000000..9b920b9 --- /dev/null +++ b/nixos/lib/make-channel.nix @@ -0,0 +1,31 @@ +/* Build a channel tarball. These contain, in addition to the nixpkgs + * expressions themselves, files that indicate the version of nixpkgs + * that they represent. + */ +{ pkgs, nixpkgs, version, versionSuffix }: + +pkgs.releaseTools.makeSourceTarball { + name = "nixos-channel"; + + src = nixpkgs; + + officialRelease = false; # FIXME: fix this in makeSourceTarball + inherit version versionSuffix; + + buildInputs = [ pkgs.nix ]; + + distPhase = '' + rm -rf .git + echo -n $VERSION_SUFFIX > .version-suffix + echo -n ${nixpkgs.rev or nixpkgs.shortRev} > .git-revision + releaseName=nixos-$VERSION$VERSION_SUFFIX + mkdir -p $out/tarballs + cp -prd . ../$releaseName + chmod -R u+w ../$releaseName + ln -s . ../$releaseName/nixpkgs # hack to make ‘’ work + NIX_STATE_DIR=$TMPDIR nix-env -f ../$releaseName/default.nix -qaP --meta --xml \* > /dev/null + cd .. + chmod -R u+w $releaseName + tar cfJ $out/tarballs/$releaseName.tar.xz $releaseName + ''; +} diff --git a/nixos/lib/make-disk-image.nix b/nixos/lib/make-disk-image.nix new file mode 100644 index 0000000..6fec322 --- /dev/null +++ b/nixos/lib/make-disk-image.nix @@ -0,0 +1,244 @@ +{ pkgs +, lib + +, # The NixOS configuration to be installed onto the disk image. + config + +, # The size of the disk, in megabytes. + diskSize + + # The files and directories to be placed in the target file system. + # This is a list of attribute sets {source, target} where `source' + # is the file system object (regular file or directory) to be + # grafted in the file system at path `target'. +, contents ? [] + +, # Type of partition table to use; either "legacy", "efi", or "none". + # For "efi" images, the GPT partition table is used and a mandatory ESP + # partition of reasonable size is created in addition to the root partition. + # If `installBootLoader` is true, GRUB will be installed in EFI mode. + # For "legacy", the msdos partition table is used and a single large root + # partition is created. If `installBootLoader` is true, GRUB will be + # installed in legacy mode. + # For "none", no partition table is created. Enabling `installBootLoader` + # most likely fails as GRUB will probably refuse to install. + partitionTableType ? "legacy" + +, # The root file system type. + fsType ? "ext4" + +, # The initial NixOS configuration file to be copied to + # /etc/nixos/configuration.nix. + configFile ? null + +, # Shell code executed after the VM has finished. + postVM ? "" + +, name ? "nixos-disk-image" + +, # Disk image format, one of qcow2, qcow2-compressed, vpc, raw. + format ? "raw" +}: + +assert partitionTableType == "legacy" || partitionTableType == "efi" || partitionTableType == "none"; +# We use -E offset=X below, which is only supported by e2fsprogs +assert partitionTableType != "none" -> fsType == "ext4"; + +with lib; + +let format' = format; in let + + format = if format' == "qcow2-compressed" then "qcow2" else format'; + + compress = optionalString (format' == "qcow2-compressed") "-c"; + + filename = "nixos." + { + qcow2 = "qcow2"; + vpc = "vhd"; + raw = "img"; + }.${format}; + + rootPartition = { # switch-case + legacy = "1"; + efi = "2"; + }.${partitionTableType}; + + partitionDiskScript = { # switch-case + legacy = '' + parted --script $diskImage -- \ + mklabel msdos \ + mkpart primary ext4 1MiB -1 + ''; + efi = '' + parted --script $diskImage -- \ + mklabel gpt \ + mkpart ESP fat32 8MiB 256MiB \ + set 1 boot on \ + mkpart primary ext4 256MiB -1 + ''; + none = ""; + }.${partitionTableType}; + + nixpkgs = cleanSource pkgs.path; + + # FIXME: merge with channel.nix / make-channel.nix. + channelSources = pkgs.runCommand "nixos-${config.system.nixos.version}" {} '' + mkdir -p $out + cp -prd ${nixpkgs.outPath} $out/nixos + chmod -R u+w $out/nixos + if [ ! -e $out/nixos/nixpkgs ]; then + ln -s . $out/nixos/nixpkgs + fi + rm -rf $out/nixos/.git + echo -n ${config.system.nixos.versionSuffix} > $out/nixos/.version-suffix + ''; + + binPath = with pkgs; makeBinPath ( + [ rsync + utillinux + parted + e2fsprogs + lkl + config.system.build.nixos-install + config.system.build.nixos-enter + nix + ] ++ stdenv.initialPath); + + # I'm preserving the line below because I'm going to search for it across nixpkgs to consolidate + # image building logic. The comment right below this now appears in 4 different places in nixpkgs :) + # !!! should use XML. + sources = map (x: x.source) contents; + targets = map (x: x.target) contents; + + closureInfo = pkgs.closureInfo { rootPaths = [ config.system.build.toplevel channelSources ]; }; + + prepareImage = '' + export PATH=${binPath} + + # Yes, mkfs.ext4 takes different units in different contexts. Fun. + sectorsToKilobytes() { + echo $(( ( "$1" * 512 ) / 1024 )) + } + + sectorsToBytes() { + echo $(( "$1" * 512 )) + } + + mkdir $out + diskImage=nixos.raw + truncate -s ${toString diskSize}M $diskImage + + ${partitionDiskScript} + + ${if partitionTableType != "none" then '' + # Get start & length of the root partition in sectors to $START and $SECTORS. + eval $(partx $diskImage -o START,SECTORS --nr ${rootPartition} --pairs) + + mkfs.${fsType} -F -L nixos $diskImage -E offset=$(sectorsToBytes $START) $(sectorsToKilobytes $SECTORS)K + '' else '' + mkfs.${fsType} -F -L nixos $diskImage + ''} + + root="$PWD/root" + mkdir -p $root + + # Copy arbitrary other files into the image + # Semi-shamelessly copied from make-etc.sh. I (@copumpkin) shall factor this stuff out as part of + # https://github.com/NixOS/nixpkgs/issues/23052. + set -f + sources_=(${concatStringsSep " " sources}) + targets_=(${concatStringsSep " " targets}) + set +f + + for ((i = 0; i < ''${#targets_[@]}; i++)); do + source="''${sources_[$i]}" + target="''${targets_[$i]}" + + if [[ "$source" =~ '*' ]]; then + # If the source name contains '*', perform globbing. + mkdir -p $root/$target + for fn in $source; do + rsync -a --no-o --no-g "$fn" $root/$target/ + done + else + mkdir -p $root/$(dirname $target) + if ! [ -e $root/$target ]; then + rsync -a --no-o --no-g $source $root/$target + else + echo "duplicate entry $target -> $source" + exit 1 + fi + fi + done + + export HOME=$TMPDIR + + # Provide a Nix database so that nixos-install can copy closures. + export NIX_STATE_DIR=$TMPDIR/state + nix-store --load-db < ${closureInfo}/registration + + echo "running nixos-install..." + nixos-install --root $root --no-bootloader --no-root-passwd \ + --system ${config.system.build.toplevel} --channel ${channelSources} --substituters "" + + echo "copying staging root to image..." + cptofs -p ${optionalString (partitionTableType != "none") "-P ${rootPartition}"} -t ${fsType} -i $diskImage $root/* / + ''; +in pkgs.vmTools.runInLinuxVM ( + pkgs.runCommand name + { preVM = prepareImage; + buildInputs = with pkgs; [ utillinux e2fsprogs dosfstools ]; + postVM = '' + ${if format == "raw" then '' + mv $diskImage $out/${filename} + '' else '' + ${pkgs.qemu}/bin/qemu-img convert -f raw -O ${format} ${compress} $diskImage $out/${filename} + ''} + diskImage=$out/${filename} + ${postVM} + ''; + memSize = 1024; + } + '' + export PATH=${binPath}:$PATH + + rootDisk=${if partitionTableType != "none" then "/dev/vda${rootPartition}" else "/dev/vda"} + + # Some tools assume these exist + ln -s vda /dev/xvda + ln -s vda /dev/sda + + mountPoint=/mnt + mkdir $mountPoint + mount $rootDisk $mountPoint + + # Create the ESP and mount it. Unlike e2fsprogs, mkfs.vfat doesn't support an + # '-E offset=X' option, so we can't do this outside the VM. + ${optionalString (partitionTableType == "efi") '' + mkdir -p /mnt/boot + mkfs.vfat -n ESP /dev/vda1 + mount /dev/vda1 /mnt/boot + ''} + + # Install a configuration.nix + mkdir -p /mnt/etc/nixos + ${optionalString (configFile != null) '' + cp ${configFile} /mnt/etc/nixos/configuration.nix + ''} + + # Set up core system link, GRUB, etc. + NIXOS_INSTALL_BOOTLOADER=1 nixos-enter --root $mountPoint -- /nix/var/nix/profiles/system/bin/switch-to-configuration boot + + # The above scripts will generate a random machine-id and we don't want to bake a single ID into all our images + rm -f $mountPoint/etc/machine-id + + umount -R /mnt + + # Make sure resize2fs works. Note that resize2fs has stricter criteria for resizing than a normal + # mount, so the `-c 0` and `-i 0` don't affect it. Setting it to `now` doesn't produce deterministic + # output, of course, but we can fix that when/if we start making images deterministic. + ${optionalString (fsType == "ext4") '' + tune2fs -T now -c 0 -i 0 $rootDisk + ''} + '' +) diff --git a/nixos/lib/make-ext4-fs.nix b/nixos/lib/make-ext4-fs.nix new file mode 100644 index 0000000..47c6374 --- /dev/null +++ b/nixos/lib/make-ext4-fs.nix @@ -0,0 +1,76 @@ +# Builds an ext4 image containing a populated /nix/store with the closure +# of store paths passed in the storePaths parameter. The generated image +# is sized to only fit its contents, with the expectation that a script +# resizes the filesystem at boot time. +{ pkgs +, storePaths +, volumeLabel +, uuid ? "44444444-4444-4444-8888-888888888888" +, e2fsprogs +, libfaketime +, perl +, lkl +}: + +let + sdClosureInfo = pkgs.buildPackages.closureInfo { rootPaths = storePaths; }; +in + +pkgs.stdenv.mkDerivation { + name = "ext4-fs.img"; + + nativeBuildInputs = [e2fsprogs.bin libfaketime perl lkl]; + + buildCommand = + '' + # Add the closures of the top-level store objects. + storePaths=$(cat ${sdClosureInfo}/store-paths) + + # Make a crude approximation of the size of the target image. + # If the script starts failing, increase the fudge factors here. + numInodes=$(find $storePaths | wc -l) + numDataBlocks=$(du -c -B 4096 --apparent-size $storePaths | awk '$2 == "total" { print int($1 * 1.03) }') + bytes=$((2 * 4096 * $numInodes + 4096 * $numDataBlocks)) + echo "Creating an EXT4 image of $bytes bytes (numInodes=$numInodes, numDataBlocks=$numDataBlocks)" + + truncate -s $bytes $out + faketime -f "1970-01-01 00:00:01" mkfs.ext4 -L ${volumeLabel} -U ${uuid} $out + + # Also include a manifest of the closures in a format suitable for nix-store --load-db. + cp ${sdClosureInfo}/registration nix-path-registration + cptofs -t ext4 -i $out nix-path-registration / + + # Create nix/store before copying paths + faketime -f "1970-01-01 00:00:01" mkdir -p nix/store + cptofs -t ext4 -i $out nix / + + echo "copying store paths to image..." + cptofs -t ext4 -i $out $storePaths /nix/store/ + + # I have ended up with corrupted images sometimes, I suspect that happens when the build machine's disk gets full during the build. + if ! fsck.ext4 -n -f $out; then + echo "--- Fsck failed for EXT4 image of $bytes bytes (numInodes=$numInodes, numDataBlocks=$numDataBlocks) ---" + cat errorlog + return 1 + fi + + ( + # Resizes **snugly** to its actual limits (or closer to) + free=$(dumpe2fs $out | grep '^Free blocks:') + blocksize=$(dumpe2fs $out | grep '^Block size:') + blocks=$(dumpe2fs $out | grep '^Block count:') + blocks=$((''${blocks##*:})) # format the number. + blocksize=$((''${blocksize##*:})) # format the number. + # System can't boot with 0 blocks free. + # Add 16MiB of free space + fudge=$(( 16 * 1024 * 1024 / blocksize )) + size=$(( blocks - ''${free##*:} + fudge )) + + echo "Resizing from $blocks blocks to $size blocks. (~ $((size*blocksize/1024/1024))MiB)" + EXT2FS_NO_MTAB_OK=yes resize2fs $out -f $size + ) + + # And a final fsck, because of the previous truncating. + fsck.ext4 -n -f $out + ''; +} diff --git a/nixos/lib/make-iso9660-image.nix b/nixos/lib/make-iso9660-image.nix new file mode 100644 index 0000000..8cd19b6 --- /dev/null +++ b/nixos/lib/make-iso9660-image.nix @@ -0,0 +1,65 @@ +{ stdenv, closureInfo, xorriso, syslinux + +, # The file name of the resulting ISO image. + isoName ? "cd.iso" + +, # The files and directories to be placed in the ISO file system. + # This is a list of attribute sets {source, target} where `source' + # is the file system object (regular file or directory) to be + # grafted in the file system at path `target'. + contents + +, # In addition to `contents', the closure of the store paths listed + # in `packages' are also placed in the Nix store of the CD. This is + # a list of attribute sets {object, symlink} where `object' if a + # store path whose closure will be copied, and `symlink' is a + # symlink to `object' that will be added to the CD. + storeContents ? [] + +, # Whether this should be an El-Torito bootable CD. + bootable ? false + +, # Whether this should be an efi-bootable El-Torito CD. + efiBootable ? false + +, # Whether this should be an hybrid CD (bootable from USB as well as CD). + usbBootable ? false + +, # The path (in the ISO file system) of the boot image. + bootImage ? "" + +, # The path (in the ISO file system) of the efi boot image. + efiBootImage ? "" + +, # The path (outside the ISO file system) of the isohybrid-mbr image. + isohybridMbrImage ? "" + +, # Whether to compress the resulting ISO image with bzip2. + compressImage ? false + +, # The volume ID. + volumeID ? "" +}: + +assert bootable -> bootImage != ""; +assert efiBootable -> efiBootImage != ""; +assert usbBootable -> isohybridMbrImage != ""; + +stdenv.mkDerivation { + name = isoName; + builder = ./make-iso9660-image.sh; + buildInputs = [ xorriso syslinux ]; + + inherit isoName bootable bootImage compressImage volumeID efiBootImage efiBootable isohybridMbrImage usbBootable; + + # !!! should use XML. + sources = map (x: x.source) contents; + targets = map (x: x.target) contents; + + # !!! should use XML. + objects = map (x: x.object) storeContents; + symlinks = map (x: x.symlink) storeContents; + + # For obtaining the closure of `storeContents'. + closureInfo = closureInfo { rootPaths = map (x: x.object) storeContents; }; +} diff --git a/nixos/lib/make-iso9660-image.sh b/nixos/lib/make-iso9660-image.sh new file mode 100644 index 0000000..b7b1ab5 --- /dev/null +++ b/nixos/lib/make-iso9660-image.sh @@ -0,0 +1,136 @@ +source $stdenv/setup + +sources_=($sources) +targets_=($targets) + +objects=($objects) +symlinks=($symlinks) + + +# Remove the initial slash from a path, since genisofs likes it that way. +stripSlash() { + res="$1" + if test "${res:0:1}" = /; then res=${res:1}; fi +} + +# Escape potential equal signs (=) with backslash (\=) +escapeEquals() { + echo "$1" | sed -e 's/\\/\\\\/g' -e 's/=/\\=/g' +} + +# Queues an file/directory to be placed on the ISO. +# An entry consists of a local source path (2) and +# a destination path on the ISO (1). +addPath() { + target="$1" + source="$2" + echo "$(escapeEquals "$target")=$(escapeEquals "$source")" >> pathlist +} + +stripSlash "$bootImage"; bootImage="$res" + + +if test -n "$bootable"; then + + # The -boot-info-table option modifies the $bootImage file, so + # find it in `contents' and make a copy of it (since the original + # is read-only in the Nix store...). + for ((i = 0; i < ${#targets_[@]}; i++)); do + stripSlash "${targets_[$i]}" + if test "$res" = "$bootImage"; then + echo "copying the boot image ${sources_[$i]}" + cp "${sources_[$i]}" boot.img + chmod u+w boot.img + sources_[$i]=boot.img + fi + done + + isoBootFlags="-eltorito-boot ${bootImage} + -eltorito-catalog .boot.cat + -no-emul-boot -boot-load-size 4 -boot-info-table + --sort-weight 1 /isolinux" # Make sure isolinux is near the beginning of the ISO +fi + +if test -n "$usbBootable"; then + usbBootFlags="-isohybrid-mbr ${isohybridMbrImage}" +fi + +if test -n "$efiBootable"; then + efiBootFlags="-eltorito-alt-boot + -e $efiBootImage + -no-emul-boot + -isohybrid-gpt-basdat" +fi + +touch pathlist + + +# Add the individual files. +for ((i = 0; i < ${#targets_[@]}; i++)); do + stripSlash "${targets_[$i]}" + addPath "$res" "${sources_[$i]}" +done + + +# Add the closures of the top-level store objects. +for i in $(< $closureInfo/store-paths); do + addPath "${i:1}" "$i" +done + + +# Also include a manifest of the closures in a format suitable for +# nix-store --load-db. +if [[ ${#objects[*]} != 0 ]]; then + cp $closureInfo/registration nix-path-registration + addPath "nix-path-registration" "nix-path-registration" +fi + + +# Add symlinks to the top-level store objects. +for ((n = 0; n < ${#objects[*]}; n++)); do + object=${objects[$n]} + symlink=${symlinks[$n]} + if test "$symlink" != "none"; then + mkdir -p $(dirname ./$symlink) + ln -s $object ./$symlink + addPath "$symlink" "./$symlink" + fi +done + +mkdir -p $out/iso + +xorriso="xorriso + -as mkisofs + -iso-level 3 + -volid ${volumeID} + -appid nixos + -publisher nixos + -graft-points + -full-iso9660-filenames + ${isoBootFlags} + ${usbBootFlags} + ${efiBootFlags} + -r + -path-list pathlist + --sort-weight 0 / +" + +$xorriso -output $out/iso/$isoName + +if test -n "$usbBootable"; then + echo "Making image hybrid..." + if test -n "$efiBootable"; then + isohybrid --uefi $out/iso/$isoName + else + isohybrid $out/iso/$isoName + fi +fi + +if test -n "$compressImage"; then + echo "Compressing image..." + bzip2 $out/iso/$isoName +fi + +mkdir -p $out/nix-support +echo $system > $out/nix-support/system +echo "file iso $out/iso/$isoName" >> $out/nix-support/hydra-build-products diff --git a/nixos/lib/make-squashfs.nix b/nixos/lib/make-squashfs.nix new file mode 100644 index 0000000..7ab84e4 --- /dev/null +++ b/nixos/lib/make-squashfs.nix @@ -0,0 +1,25 @@ +{ stdenv, squashfsTools, closureInfo + +, # The root directory of the squashfs filesystem is filled with the + # closures of the Nix store paths listed here. + storeContents ? [] +}: + +stdenv.mkDerivation { + name = "squashfs.img"; + + nativeBuildInputs = [ squashfsTools ]; + + buildCommand = + '' + closureInfo=${closureInfo { rootPaths = storeContents; }} + + # Also include a manifest of the closures in a format suitable + # for nix-store --load-db. + cp $closureInfo/registration nix-path-registration + + # Generate the squashfs image. + mksquashfs nix-path-registration $(cat $closureInfo/store-paths) $out \ + -keep-as-directory -all-root -b 1048576 -comp xz -Xdict-size 100% + ''; +} diff --git a/nixos/lib/make-system-tarball.nix b/nixos/lib/make-system-tarball.nix new file mode 100644 index 0000000..dee91a6 --- /dev/null +++ b/nixos/lib/make-system-tarball.nix @@ -0,0 +1,56 @@ +{ stdenv, closureInfo, pixz + +, # The file name of the resulting tarball + fileName ? "nixos-system-${stdenv.hostPlatform.system}" + +, # The files and directories to be placed in the tarball. + # This is a list of attribute sets {source, target} where `source' + # is the file system object (regular file or directory) to be + # grafted in the file system at path `target'. + contents + +, # In addition to `contents', the closure of the store paths listed + # in `packages' are also placed in the Nix store of the tarball. This is + # a list of attribute sets {object, symlink} where `object' if a + # store path whose closure will be copied, and `symlink' is a + # symlink to `object' that will be added to the tarball. + storeContents ? [] + + # Extra commands to be executed before archiving files +, extraCommands ? "" + + # Extra tar arguments +, extraArgs ? "" + # Command used for compression +, compressCommand ? "pixz" + # Extension for the compressed tarball +, compressionExtension ? ".xz" + # extra inputs, like the compressor to use +, extraInputs ? [ pixz ] +}: + +let + symlinks = map (x: x.symlink) storeContents; + objects = map (x: x.object) storeContents; +in + +stdenv.mkDerivation { + name = "tarball"; + builder = ./make-system-tarball.sh; + buildInputs = extraInputs; + + inherit fileName extraArgs extraCommands compressCommand; + + # !!! should use XML. + sources = map (x: x.source) contents; + targets = map (x: x.target) contents; + + # !!! should use XML. + inherit symlinks objects; + + closureInfo = closureInfo { + rootPaths = objects; + }; + + extension = compressionExtension; +} diff --git a/nixos/lib/make-system-tarball.sh b/nixos/lib/make-system-tarball.sh new file mode 100644 index 0000000..1a0017a --- /dev/null +++ b/nixos/lib/make-system-tarball.sh @@ -0,0 +1,57 @@ +source $stdenv/setup + +sources_=($sources) +targets_=($targets) + +objects=($objects) +symlinks=($symlinks) + + +# Remove the initial slash from a path, since genisofs likes it that way. +stripSlash() { + res="$1" + if test "${res:0:1}" = /; then res=${res:1}; fi +} + +# Add the individual files. +for ((i = 0; i < ${#targets_[@]}; i++)); do + stripSlash "${targets_[$i]}" + mkdir -p "$(dirname "$res")" + cp -a "${sources_[$i]}" "$res" +done + + +# Add the closures of the top-level store objects. +chmod +w . +mkdir -p nix/store +for i in $(< $closureInfo/store-paths); do + cp -a "$i" "${i:1}" +done + + +# TODO tar ruxo +# Also include a manifest of the closures in a format suitable for +# nix-store --load-db. +cp $closureInfo/registration nix-path-registration + +# Add symlinks to the top-level store objects. +for ((n = 0; n < ${#objects[*]}; n++)); do + object=${objects[$n]} + symlink=${symlinks[$n]} + if test "$symlink" != "none"; then + mkdir -p $(dirname ./$symlink) + ln -s $object ./$symlink + fi +done + +$extraCommands + +mkdir -p $out/tarball + +rm env-vars + +time tar --sort=name --mtime='@1' --owner=0 --group=0 --numeric-owner -c * $extraArgs | $compressCommand > $out/tarball/$fileName.tar${extension} + +mkdir -p $out/nix-support +echo $system > $out/nix-support/system +echo "file system-tarball $out/tarball/$fileName.tar${extension}" > $out/nix-support/hydra-build-products diff --git a/nixos/lib/qemu-flags.nix b/nixos/lib/qemu-flags.nix new file mode 100644 index 0000000..779f037 --- /dev/null +++ b/nixos/lib/qemu-flags.nix @@ -0,0 +1,25 @@ +# QEMU flags shared between various Nix expressions. +{ pkgs }: + +let + zeroPad = n: if n < 10 then "0${toString n}" else toString n; +in + +{ + + qemuNICFlags = nic: net: machine: + [ "-device virtio-net-pci,netdev=vlan${toString nic},mac=52:54:00:12:${zeroPad net}:${zeroPad machine}" + "-netdev vde,id=vlan${toString nic},sock=$QEMU_VDE_SOCKET_${toString net}" + ]; + + qemuSerialDevice = if pkgs.stdenv.isi686 || pkgs.stdenv.isx86_64 then "ttyS0" + else if pkgs.stdenv.isAarch32 || pkgs.stdenv.isAarch64 then "ttyAMA0" + else throw "Unknown QEMU serial device for system '${pkgs.stdenv.hostPlatform.system}'"; + + qemuBinary = qemuPkg: { + "x86_64-linux" = "${qemuPkg}/bin/qemu-kvm -cpu kvm64"; + "armv7l-linux" = "${qemuPkg}/bin/qemu-system-arm -enable-kvm -machine virt -cpu host"; + "aarch64-linux" = "${qemuPkg}/bin/qemu-system-aarch64 -enable-kvm -machine virt,gic-version=host -cpu host"; + "x86_64-darwin" = "${qemuPkg}/bin/qemu-kvm -cpu kvm64"; + }.${pkgs.stdenv.hostPlatform.system} or "${qemuPkg}/bin/qemu-kvm"; +} diff --git a/nixos/lib/test-driver/Logger.pm b/nixos/lib/test-driver/Logger.pm new file mode 100644 index 0000000..3fe5ef6 --- /dev/null +++ b/nixos/lib/test-driver/Logger.pm @@ -0,0 +1,72 @@ +package Logger; + +use strict; +use Thread::Queue; +use XML::Writer; +use Encode qw(decode encode); + +sub new { + my ($class) = @_; + + my $logFile = defined $ENV{LOGFILE} ? "$ENV{LOGFILE}" : "/dev/null"; + my $log = new XML::Writer(OUTPUT => new IO::File(">$logFile")); + + my $self = { + log => $log, + logQueue => Thread::Queue->new() + }; + + $self->{log}->startTag("logfile"); + + bless $self, $class; + return $self; +} + +sub close { + my ($self) = @_; + $self->{log}->endTag("logfile"); + $self->{log}->end; +} + +sub drainLogQueue { + my ($self) = @_; + while (defined (my $item = $self->{logQueue}->dequeue_nb())) { + $self->{log}->dataElement("line", sanitise($item->{msg}), 'machine' => $item->{machine}, 'type' => 'serial'); + } +} + +sub maybePrefix { + my ($msg, $attrs) = @_; + $msg = $attrs->{machine} . ": " . $msg if defined $attrs->{machine}; + return $msg; +} + +sub nest { + my ($self, $msg, $coderef, $attrs) = @_; + print STDERR maybePrefix("$msg\n", $attrs); + $self->{log}->startTag("nest"); + $self->{log}->dataElement("head", $msg, %{$attrs}); + $self->drainLogQueue(); + eval { &$coderef }; + my $res = $@; + $self->drainLogQueue(); + $self->{log}->endTag("nest"); + die $@ if $@; +} + +sub sanitise { + my ($s) = @_; + $s =~ s/[[:cntrl:]\xff]//g; + $s = decode('UTF-8', $s, Encode::FB_DEFAULT); + return encode('UTF-8', $s, Encode::FB_CROAK); +} + +sub log { + my ($self, $msg, $attrs) = @_; + chomp $msg; + print STDERR maybePrefix("$msg\n", $attrs); + $self->drainLogQueue(); + $self->{log}->dataElement("line", $msg, %{$attrs}); +} + +1; diff --git a/nixos/lib/test-driver/Machine.pm b/nixos/lib/test-driver/Machine.pm new file mode 100644 index 0000000..a00fe25 --- /dev/null +++ b/nixos/lib/test-driver/Machine.pm @@ -0,0 +1,724 @@ +package Machine; + +use strict; +use threads; +use Socket; +use IO::Handle; +use POSIX qw(dup2); +use FileHandle; +use Cwd; +use File::Basename; +use File::Path qw(make_path); +use File::Slurp; + + +my $showGraphics = defined $ENV{'DISPLAY'}; + +my $sharedDir; + + +sub new { + my ($class, $args) = @_; + + my $startCommand = $args->{startCommand}; + + my $name = $args->{name}; + if (!$name) { + $startCommand =~ /run-(.*)-vm$/ if defined $startCommand; + $name = $1 || "machine"; + } + + if (!$startCommand) { + # !!! merge with qemu-vm.nix. + $startCommand = + "qemu-kvm -m 384 " . + "-net nic,model=virtio \$QEMU_OPTS "; + + if (defined $args->{hda}) { + if ($args->{hdaInterface} eq "scsi") { + $startCommand .= "-drive id=hda,file=" + . Cwd::abs_path($args->{hda}) + . ",werror=report,if=none " + . "-device scsi-hd,drive=hda "; + } else { + $startCommand .= "-drive file=" . Cwd::abs_path($args->{hda}) + . ",if=" . $args->{hdaInterface} + . ",werror=report "; + } + } + + $startCommand .= "-cdrom $args->{cdrom} " + if defined $args->{cdrom}; + $startCommand .= "-device piix3-usb-uhci -drive id=usbdisk,file=$args->{usb},if=none,readonly -device usb-storage,drive=usbdisk " + if defined $args->{usb}; + $startCommand .= "-bios $args->{bios} " + if defined $args->{bios}; + $startCommand .= $args->{qemuFlags} || ""; + } + + my $tmpDir = $ENV{'TMPDIR'} || "/tmp"; + unless (defined $sharedDir) { + $sharedDir = $tmpDir . "/xchg-shared"; + make_path($sharedDir, { mode => 0700, owner => $< }); + } + + my $allowReboot = 0; + $allowReboot = $args->{allowReboot} if defined $args->{allowReboot}; + + my $self = { + startCommand => $startCommand, + name => $name, + allowReboot => $allowReboot, + booted => 0, + pid => 0, + connected => 0, + socket => undef, + stateDir => "$tmpDir/vm-state-$name", + monitor => undef, + log => $args->{log}, + redirectSerial => $args->{redirectSerial} // 1, + }; + + mkdir $self->{stateDir}, 0700; + + bless $self, $class; + return $self; +} + + +sub log { + my ($self, $msg) = @_; + $self->{log}->log($msg, { machine => $self->{name} }); +} + + +sub nest { + my ($self, $msg, $coderef, $attrs) = @_; + $self->{log}->nest($msg, $coderef, { %{$attrs || {}}, machine => $self->{name} }); +} + + +sub name { + my ($self) = @_; + return $self->{name}; +} + + +sub stateDir { + my ($self) = @_; + return $self->{stateDir}; +} + + +sub start { + my ($self) = @_; + return if $self->{booted}; + + $self->log("starting vm"); + + # Create a socket pair for the serial line input/output of the VM. + my ($serialP, $serialC); + socketpair($serialP, $serialC, PF_UNIX, SOCK_STREAM, 0) or die; + + # Create a Unix domain socket to which QEMU's monitor will connect. + my $monitorPath = $self->{stateDir} . "/monitor"; + unlink $monitorPath; + my $monitorS; + socket($monitorS, PF_UNIX, SOCK_STREAM, 0) or die; + bind($monitorS, sockaddr_un($monitorPath)) or die "cannot bind monitor socket: $!"; + listen($monitorS, 1) or die; + + # Create a Unix domain socket to which the root shell in the guest will connect. + my $shellPath = $self->{stateDir} . "/shell"; + unlink $shellPath; + my $shellS; + socket($shellS, PF_UNIX, SOCK_STREAM, 0) or die; + bind($shellS, sockaddr_un($shellPath)) or die "cannot bind shell socket: $!"; + listen($shellS, 1) or die; + + # Start the VM. + my $pid = fork(); + die if $pid == -1; + + if ($pid == 0) { + close $serialP; + close $monitorS; + close $shellS; + if ($self->{redirectSerial}) { + open NUL, "{stateDir}; + $ENV{SHARED_DIR} = $sharedDir; + $ENV{USE_TMPDIR} = 1; + $ENV{QEMU_OPTS} = + ($self->{allowReboot} ? "" : "-no-reboot ") . + "-monitor unix:./monitor " . + "-chardev socket,id=shell,path=./shell -device virtio-serial -device virtconsole,chardev=shell " . + # socket backdoor, see "Debugging NixOS tests" section in NixOS manual + "-chardev socket,id=backdoor,path=./backdoor,server,nowait -device virtio-serial -device virtconsole,chardev=backdoor " . + "-device virtio-rng-pci " . + ($showGraphics ? "-serial stdio" : "-nographic") . " " . ($ENV{QEMU_OPTS} || ""); + chdir $self->{stateDir} or die; + exec $self->{startCommand}; + die "running VM script: $!"; + } + + # Process serial line output. + close $serialC; + + threads->create(\&processSerialOutput, $self, $serialP)->detach; + + sub processSerialOutput { + my ($self, $serialP) = @_; + while (<$serialP>) { + chomp; + s/\r$//; + print STDERR $self->{name}, "# $_\n"; + $self->{log}->{logQueue}->enqueue({msg => $_, machine => $self->{name}}); # !!! + } + } + + eval { + local $SIG{CHLD} = sub { die "QEMU died prematurely\n"; }; + + # Wait until QEMU connects to the monitor. + accept($self->{monitor}, $monitorS) or die; + + # Wait until QEMU connects to the root shell socket. QEMU + # does so immediately; this doesn't mean that the root shell + # has connected yet inside the guest. + accept($self->{socket}, $shellS) or die; + $self->{socket}->autoflush(1); + }; + die "$@" if $@; + + $self->waitForMonitorPrompt; + + $self->log("QEMU running (pid $pid)"); + + $self->{pid} = $pid; + $self->{booted} = 1; +} + + +# Send a command to the monitor and wait for it to finish. TODO: QEMU +# also has a JSON-based monitor interface now, but it doesn't support +# all commands yet. We should use it once it does. +sub sendMonitorCommand { + my ($self, $command) = @_; + $self->log("sending monitor command: $command"); + syswrite $self->{monitor}, "$command\n"; + return $self->waitForMonitorPrompt; +} + + +# Wait until the monitor sends "(qemu) ". +sub waitForMonitorPrompt { + my ($self) = @_; + my $res = ""; + my $s; + while (sysread($self->{monitor}, $s, 1024)) { + $res .= $s; + last if $res =~ s/\(qemu\) $//; + } + return $res; +} + + +# Call the given code reference repeatedly, with 1 second intervals, +# until it returns 1 or a timeout is reached. +sub retry { + my ($coderef) = @_; + my $n; + for ($n = 899; $n >=0; $n--) { + return if &$coderef($n); + sleep 1; + } + die "action timed out after $n seconds"; +} + + +sub connect { + my ($self) = @_; + return if $self->{connected}; + + $self->nest("waiting for the VM to finish booting", sub { + + $self->start; + + local $SIG{ALRM} = sub { die "timed out waiting for the VM to connect\n"; }; + alarm 300; + readline $self->{socket} or die "the VM quit before connecting\n"; + alarm 0; + + $self->log("connected to guest root shell"); + $self->{connected} = 1; + + }); +} + + +sub waitForShutdown { + my ($self) = @_; + return unless $self->{booted}; + + $self->nest("waiting for the VM to power off", sub { + waitpid $self->{pid}, 0; + $self->{pid} = 0; + $self->{booted} = 0; + $self->{connected} = 0; + }); +} + + +sub isUp { + my ($self) = @_; + return $self->{booted} && $self->{connected}; +} + + +sub execute_ { + my ($self, $command) = @_; + + $self->connect; + + print { $self->{socket} } ("( $command ); echo '|!=EOF' \$?\n"); + + my $out = ""; + + while (1) { + my $line = readline($self->{socket}); + die "connection to VM lost unexpectedly" unless defined $line; + #$self->log("got line: $line"); + if ($line =~ /^(.*)\|\!\=EOF\s+(\d+)$/) { + $out .= $1; + $self->log("exit status $2"); + return ($2, $out); + } + $out .= $line; + } +} + + +sub execute { + my ($self, $command) = @_; + my @res; + $self->nest("running command: $command", sub { + @res = $self->execute_($command); + }); + return @res; +} + + +sub succeed { + my ($self, @commands) = @_; + + my $res; + foreach my $command (@commands) { + $self->nest("must succeed: $command", sub { + my ($status, $out) = $self->execute_($command); + if ($status != 0) { + $self->log("output: $out"); + die "command `$command' did not succeed (exit code $status)\n"; + } + $res .= $out; + }); + } + + return $res; +} + + +sub mustSucceed { + succeed @_; +} + + +sub waitUntilSucceeds { + my ($self, $command) = @_; + $self->nest("waiting for success: $command", sub { + retry sub { + my ($status, $out) = $self->execute($command); + return 1 if $status == 0; + }; + }); +} + + +sub waitUntilFails { + my ($self, $command) = @_; + $self->nest("waiting for failure: $command", sub { + retry sub { + my ($status, $out) = $self->execute($command); + return 1 if $status != 0; + }; + }); +} + + +sub fail { + my ($self, $command) = @_; + $self->nest("must fail: $command", sub { + my ($status, $out) = $self->execute_($command); + die "command `$command' unexpectedly succeeded" + if $status == 0; + }); +} + + +sub mustFail { + fail @_; +} + + +sub getUnitInfo { + my ($self, $unit, $user) = @_; + my ($status, $lines) = $self->systemctl("--no-pager show \"$unit\"", $user); + return undef if $status != 0; + my $info = {}; + foreach my $line (split '\n', $lines) { + $line =~ /^([^=]+)=(.*)$/ or next; + $info->{$1} = $2; + } + return $info; +} + +sub systemctl { + my ($self, $q, $user) = @_; + if ($user) { + $q =~ s/'/\\'/g; + return $self->execute("su -l $user -c \$'XDG_RUNTIME_DIR=/run/user/`id -u` systemctl --user $q'"); + } + + return $self->execute("systemctl $q"); +} + +# Fail if the given systemd unit is not in the "active" state. +sub requireActiveUnit { + my ($self, $unit) = @_; + $self->nest("checking if unit ‘$unit’ has reached state 'active'", sub { + my $info = $self->getUnitInfo($unit); + my $state = $info->{ActiveState}; + if ($state ne "active") { + die "Expected unit ‘$unit’ to to be in state 'active' but it is in state ‘$state’\n"; + }; + }); +} + +# Wait for a systemd unit to reach the "active" state. +sub waitForUnit { + my ($self, $unit, $user) = @_; + $self->nest("waiting for unit ‘$unit’", sub { + retry sub { + my $info = $self->getUnitInfo($unit, $user); + my $state = $info->{ActiveState}; + die "unit ‘$unit’ reached state ‘$state’\n" if $state eq "failed"; + if ($state eq "inactive") { + # If there are no pending jobs, then assume this unit + # will never reach active state. + my ($status, $jobs) = $self->systemctl("list-jobs --full 2>&1", $user); + if ($jobs =~ /No jobs/) { # FIXME: fragile + # Handle the case where the unit may have started + # between the previous getUnitInfo() and + # list-jobs. + my $info2 = $self->getUnitInfo($unit); + die "unit ‘$unit’ is inactive and there are no pending jobs\n" + if $info2->{ActiveState} eq $state; + } + } + return 1 if $state eq "active"; + }; + }); +} + + +sub waitForJob { + my ($self, $jobName) = @_; + return $self->waitForUnit($jobName); +} + + +# Wait until the specified file exists. +sub waitForFile { + my ($self, $fileName) = @_; + $self->nest("waiting for file ‘$fileName’", sub { + retry sub { + my ($status, $out) = $self->execute("test -e $fileName"); + return 1 if $status == 0; + } + }); +} + +sub startJob { + my ($self, $jobName, $user) = @_; + $self->systemctl("start $jobName", $user); + # FIXME: check result +} + +sub stopJob { + my ($self, $jobName, $user) = @_; + $self->systemctl("stop $jobName", $user); +} + + +# Wait until the machine is listening on the given TCP port. +sub waitForOpenPort { + my ($self, $port) = @_; + $self->nest("waiting for TCP port $port", sub { + retry sub { + my ($status, $out) = $self->execute("nc -z localhost $port"); + return 1 if $status == 0; + } + }); +} + + +# Wait until the machine is not listening on the given TCP port. +sub waitForClosedPort { + my ($self, $port) = @_; + retry sub { + my ($status, $out) = $self->execute("nc -z localhost $port"); + return 1 if $status != 0; + } +} + + +sub shutdown { + my ($self) = @_; + return unless $self->{booted}; + + print { $self->{socket} } ("poweroff\n"); + + $self->waitForShutdown; +} + + +sub crash { + my ($self) = @_; + return unless $self->{booted}; + + $self->log("forced crash"); + + $self->sendMonitorCommand("quit"); + + $self->waitForShutdown; +} + + +# Make the machine unreachable by shutting down eth1 (the multicast +# interface used to talk to the other VMs). We keep eth0 up so that +# the test driver can continue to talk to the machine. +sub block { + my ($self) = @_; + $self->sendMonitorCommand("set_link virtio-net-pci.1 off"); +} + + +# Make the machine reachable. +sub unblock { + my ($self) = @_; + $self->sendMonitorCommand("set_link virtio-net-pci.1 on"); +} + + +# Take a screenshot of the X server on :0.0. +sub screenshot { + my ($self, $filename) = @_; + my $dir = $ENV{'out'} || Cwd::abs_path("."); + $filename = "$dir/${filename}.png" if $filename =~ /^\w+$/; + my $tmp = "${filename}.ppm"; + my $name = basename($filename); + $self->nest("making screenshot ‘$name’", sub { + $self->sendMonitorCommand("screendump $tmp"); + system("pnmtopng $tmp > ${filename}") == 0 + or die "cannot convert screenshot"; + unlink $tmp; + }, { image => $name } ); +} + +# Get the text of TTY +sub getTTYText { + my ($self, $tty) = @_; + + my ($status, $out) = $self->execute("fold -w\$(stty -F /dev/tty${tty} size | awk '{print \$2}') /dev/vcs${tty}"); + return $out; +} + +# Wait until TTY's text matches a particular regular expression +sub waitUntilTTYMatches { + my ($self, $tty, $regexp) = @_; + + $self->nest("waiting for $regexp to appear on tty $tty", sub { + retry sub { + my ($retries_remaining) = @_; + if ($retries_remaining == 0) { + $self->log("Last chance to match /$regexp/ on TTY$tty, which currently contains:"); + $self->log($self->getTTYText($tty)); + } + + return 1 if $self->getTTYText($tty) =~ /$regexp/; + } + }); +} + +# Debugging: Dump the contents of the TTY +sub dumpTTYContents { + my ($self, $tty) = @_; + + $self->execute("fold -w 80 /dev/vcs${tty} | systemd-cat"); +} + +# Take a screenshot and return the result as text using optical character +# recognition. +sub getScreenText { + my ($self) = @_; + + system("command -v tesseract &> /dev/null") == 0 + or die "getScreenText used but enableOCR is false"; + + my $text; + $self->nest("performing optical character recognition", sub { + my $tmpbase = Cwd::abs_path(".")."/ocr"; + my $tmpin = $tmpbase."in.ppm"; + + $self->sendMonitorCommand("screendump $tmpin"); + + my $magickArgs = "-filter Catrom -density 72 -resample 300 " + . "-contrast -normalize -despeckle -type grayscale " + . "-sharpen 1 -posterize 3 -negate -gamma 100 " + . "-blur 1x65535"; + my $tessArgs = "-c debug_file=/dev/null --psm 11 --oem 2"; + + $text = `convert $magickArgs $tmpin tiff:- | tesseract - - $tessArgs`; + my $status = $? >> 8; + unlink $tmpin; + + die "OCR failed with exit code $status" if $status != 0; + }); + return $text; +} + + +# Wait until a specific regexp matches the textual contents of the screen. +sub waitForText { + my ($self, $regexp) = @_; + $self->nest("waiting for $regexp to appear on the screen", sub { + retry sub { + my ($retries_remaining) = @_; + if ($retries_remaining == 0) { + $self->log("Last chance to match /$regexp/ on the screen, which currently contains:"); + $self->log($self->getScreenText); + } + + return 1 if $self->getScreenText =~ /$regexp/; + } + }); +} + + +# Wait until it is possible to connect to the X server. Note that +# testing the existence of /tmp/.X11-unix/X0 is insufficient. +sub waitForX { + my ($self, $regexp) = @_; + $self->nest("waiting for the X11 server", sub { + retry sub { + my ($status, $out) = $self->execute("journalctl -b SYSLOG_IDENTIFIER=systemd | grep 'Reached target Current graphical'"); + return 0 if $status != 0; + ($status, $out) = $self->execute("[ -e /tmp/.X11-unix/X0 ]"); + return 1 if $status == 0; + } + }); +} + + +sub getWindowNames { + my ($self) = @_; + my $res = $self->mustSucceed( + q{xwininfo -root -tree | sed 's/.*0x[0-9a-f]* \"\([^\"]*\)\".*/\1/; t; d'}); + return split /\n/, $res; +} + + +sub waitForWindow { + my ($self, $regexp) = @_; + $self->nest("waiting for a window to appear", sub { + retry sub { + my @names = $self->getWindowNames; + + my ($retries_remaining) = @_; + if ($retries_remaining == 0) { + $self->log("Last chance to match /$regexp/ on the the window list, which currently contains:"); + $self->log(join(", ", @names)); + } + + foreach my $n (@names) { + return 1 if $n =~ /$regexp/; + } + } + }); +} + + +sub copyFileFromHost { + my ($self, $from, $to) = @_; + my $s = `cat $from` or die; + $s =~ s/'/'\\''/g; + $self->mustSucceed("echo '$s' > $to"); +} + + +my %charToKey = ( + 'A' => "shift-a", 'N' => "shift-n", '-' => "0x0C", '_' => "shift-0x0C", '!' => "shift-0x02", + 'B' => "shift-b", 'O' => "shift-o", '=' => "0x0D", '+' => "shift-0x0D", '@' => "shift-0x03", + 'C' => "shift-c", 'P' => "shift-p", '[' => "0x1A", '{' => "shift-0x1A", '#' => "shift-0x04", + 'D' => "shift-d", 'Q' => "shift-q", ']' => "0x1B", '}' => "shift-0x1B", '$' => "shift-0x05", + 'E' => "shift-e", 'R' => "shift-r", ';' => "0x27", ':' => "shift-0x27", '%' => "shift-0x06", + 'F' => "shift-f", 'S' => "shift-s", '\'' => "0x28", '"' => "shift-0x28", '^' => "shift-0x07", + 'G' => "shift-g", 'T' => "shift-t", '`' => "0x29", '~' => "shift-0x29", '&' => "shift-0x08", + 'H' => "shift-h", 'U' => "shift-u", '\\' => "0x2B", '|' => "shift-0x2B", '*' => "shift-0x09", + 'I' => "shift-i", 'V' => "shift-v", ',' => "0x33", '<' => "shift-0x33", '(' => "shift-0x0A", + 'J' => "shift-j", 'W' => "shift-w", '.' => "0x34", '>' => "shift-0x34", ')' => "shift-0x0B", + 'K' => "shift-k", 'X' => "shift-x", '/' => "0x35", '?' => "shift-0x35", + 'L' => "shift-l", 'Y' => "shift-y", ' ' => "spc", + 'M' => "shift-m", 'Z' => "shift-z", "\n" => "ret", +); + + +sub sendKeys { + my ($self, @keys) = @_; + foreach my $key (@keys) { + $key = $charToKey{$key} if exists $charToKey{$key}; + $self->sendMonitorCommand("sendkey $key"); + } +} + + +sub sendChars { + my ($self, $chars) = @_; + $self->nest("sending keys ‘$chars’", sub { + $self->sendKeys(split //, $chars); + }); +} + + +# Sleep N seconds (in virtual guest time, not real time). +sub sleep { + my ($self, $time) = @_; + $self->succeed("sleep $time"); +} + + +# Forward a TCP port on the host to a TCP port on the guest. Useful +# during interactive testing. +sub forwardPort { + my ($self, $hostPort, $guestPort) = @_; + $hostPort = 8080 unless defined $hostPort; + $guestPort = 80 unless defined $guestPort; + $self->sendMonitorCommand("hostfwd_add tcp::$hostPort-:$guestPort"); +} + + +1; diff --git a/nixos/lib/test-driver/log2html.xsl b/nixos/lib/test-driver/log2html.xsl new file mode 100644 index 0000000..0485412 --- /dev/null +++ b/nixos/lib/test-driver/log2html.xsl @@ -0,0 +1,135 @@ + + + + + + + + + + + +