From a099ca45054940b63b1615920de158ebafb25ea8 Mon Sep 17 00:00:00 2001 From: Mikey Ariel Date: Sun, 24 Aug 2014 19:18:18 +0200 Subject: [PATCH] Chunk NixOS manual [Squashed commits to make git blame etc. more likely to work. -ED] --- .../manual/administration/boot-problems.xml | 65 + .../manual/administration/cleaning-store.xml | 62 + .../administration/container-networking.xml | 50 + .../doc/manual/administration/containers.xml | 34 + .../manual/administration/control-groups.xml | 75 + .../administration/declarative-containers.xml | 52 + .../administration/imperative-containers.xml | 124 ++ nixos/doc/manual/administration/logging.xml | 52 + .../administration/maintenance-mode.xml | 18 + .../administration/network-problems.xml | 33 + nixos/doc/manual/administration/rebooting.xml | 44 + nixos/doc/manual/administration/rollback.xml | 48 + nixos/doc/manual/administration/running.xml | 24 + .../manual/administration/service-mgmt.xml | 83 + .../administration/store-corruption.xml | 37 + .../manual/administration/troubleshooting.xml | 18 + .../manual/administration/user-sessions.xml | 53 + nixos/doc/manual/configuration.xml | 1563 ----------------- .../configuration/LUKS-file-systems.xml | 42 + .../doc/manual/configuration/abstractions.xml | 166 ++ .../configuration/ad-hoc-network-config.xml | 24 + .../manual/configuration/ad-hoc-packages.xml | 63 + .../configuration/adding-custom-packages.xml | 84 + .../doc/manual/configuration/config-file.xml | 213 +++ .../manual/configuration/config-syntax.xml | 27 + .../manual/configuration/configuration.xml | 29 + .../configuration/customizing-packages.xml | 92 + .../configuration/declarative-packages.xml | 43 + .../doc/manual/configuration/file-systems.xml | 40 + nixos/doc/manual/configuration/firewall.xml | 38 + .../doc/manual/configuration/ipv4-config.xml | 47 + .../doc/manual/configuration/ipv6-config.xml | 19 + .../doc/manual/configuration/linux-kernel.xml | 69 + nixos/doc/manual/configuration/modularity.xml | 143 ++ .../manual/configuration/network-manager.xml | 27 + nixos/doc/manual/configuration/networking.xml | 22 + .../doc/manual/configuration/package-mgmt.xml | 34 + nixos/doc/manual/configuration/ssh.xml | 32 + nixos/doc/manual/configuration/summary.xml | 191 ++ nixos/doc/manual/configuration/user-mgmt.xml | 95 + nixos/doc/manual/configuration/wireless.xml | 41 + nixos/doc/manual/configuration/x-windows.xml | 94 + nixos/doc/manual/containers.xml | 242 --- nixos/doc/manual/development.xml | 1119 ------------ .../doc/manual/development/building-nixos.xml | 32 + .../doc/manual/development/building-parts.xml | 113 ++ nixos/doc/manual/development/development.xml | 20 + nixos/doc/manual/development/nixos-tests.xml | 19 + .../development/option-declarations.xml | 141 ++ nixos/doc/manual/development/option-def.xml | 112 ++ .../development/running-nixos-tests.xml | 77 + nixos/doc/manual/development/sources.xml | 95 + .../manual/development/testing-installer.xml | 27 + .../manual/development/writing-modules.xml | 175 ++ .../development/writing-nixos-tests.xml | 251 +++ nixos/doc/manual/installation.xml | 570 ------ .../manual/installation/changing-config.xml | 90 + .../doc/manual/installation/installation.xml | 21 + .../manual/installation/installing-UEFI.xml | 51 + .../manual/installation/installing-USB.xml | 30 + nixos/doc/manual/installation/installing.xml | 264 +++ nixos/doc/manual/installation/obtaining.xml | 44 + nixos/doc/manual/installation/upgrading.xml | 90 + nixos/doc/manual/manual.xml | 24 +- .../manual/release-notes/release-notes.xml | 17 + nixos/doc/manual/release-notes/rl-1310.xml | 11 + .../rl-1404.xml} | 50 +- nixos/doc/manual/release-notes/rl-1410.xml | 22 + nixos/doc/manual/running.xml | 369 ---- nixos/doc/manual/troubleshooting.xml | 199 --- 70 files changed, 4264 insertions(+), 4121 deletions(-) create mode 100644 nixos/doc/manual/administration/boot-problems.xml create mode 100644 nixos/doc/manual/administration/cleaning-store.xml create mode 100644 nixos/doc/manual/administration/container-networking.xml create mode 100644 nixos/doc/manual/administration/containers.xml create mode 100644 nixos/doc/manual/administration/control-groups.xml create mode 100644 nixos/doc/manual/administration/declarative-containers.xml create mode 100644 nixos/doc/manual/administration/imperative-containers.xml create mode 100644 nixos/doc/manual/administration/logging.xml create mode 100644 nixos/doc/manual/administration/maintenance-mode.xml create mode 100644 nixos/doc/manual/administration/network-problems.xml create mode 100644 nixos/doc/manual/administration/rebooting.xml create mode 100644 nixos/doc/manual/administration/rollback.xml create mode 100644 nixos/doc/manual/administration/running.xml create mode 100644 nixos/doc/manual/administration/service-mgmt.xml create mode 100644 nixos/doc/manual/administration/store-corruption.xml create mode 100644 nixos/doc/manual/administration/troubleshooting.xml create mode 100644 nixos/doc/manual/administration/user-sessions.xml delete mode 100644 nixos/doc/manual/configuration.xml create mode 100644 nixos/doc/manual/configuration/LUKS-file-systems.xml create mode 100644 nixos/doc/manual/configuration/abstractions.xml create mode 100644 nixos/doc/manual/configuration/ad-hoc-network-config.xml create mode 100644 nixos/doc/manual/configuration/ad-hoc-packages.xml create mode 100644 nixos/doc/manual/configuration/adding-custom-packages.xml create mode 100644 nixos/doc/manual/configuration/config-file.xml create mode 100644 nixos/doc/manual/configuration/config-syntax.xml create mode 100644 nixos/doc/manual/configuration/configuration.xml create mode 100644 nixos/doc/manual/configuration/customizing-packages.xml create mode 100644 nixos/doc/manual/configuration/declarative-packages.xml create mode 100644 nixos/doc/manual/configuration/file-systems.xml create mode 100644 nixos/doc/manual/configuration/firewall.xml create mode 100644 nixos/doc/manual/configuration/ipv4-config.xml create mode 100644 nixos/doc/manual/configuration/ipv6-config.xml create mode 100644 nixos/doc/manual/configuration/linux-kernel.xml create mode 100644 nixos/doc/manual/configuration/modularity.xml create mode 100644 nixos/doc/manual/configuration/network-manager.xml create mode 100644 nixos/doc/manual/configuration/networking.xml create mode 100644 nixos/doc/manual/configuration/package-mgmt.xml create mode 100644 nixos/doc/manual/configuration/ssh.xml create mode 100644 nixos/doc/manual/configuration/summary.xml create mode 100644 nixos/doc/manual/configuration/user-mgmt.xml create mode 100644 nixos/doc/manual/configuration/wireless.xml create mode 100644 nixos/doc/manual/configuration/x-windows.xml delete mode 100644 nixos/doc/manual/containers.xml delete mode 100644 nixos/doc/manual/development.xml create mode 100644 nixos/doc/manual/development/building-nixos.xml create mode 100644 nixos/doc/manual/development/building-parts.xml create mode 100644 nixos/doc/manual/development/development.xml create mode 100644 nixos/doc/manual/development/nixos-tests.xml create mode 100644 nixos/doc/manual/development/option-declarations.xml create mode 100644 nixos/doc/manual/development/option-def.xml create mode 100644 nixos/doc/manual/development/running-nixos-tests.xml create mode 100644 nixos/doc/manual/development/sources.xml create mode 100644 nixos/doc/manual/development/testing-installer.xml create mode 100644 nixos/doc/manual/development/writing-modules.xml create mode 100644 nixos/doc/manual/development/writing-nixos-tests.xml delete mode 100644 nixos/doc/manual/installation.xml create mode 100644 nixos/doc/manual/installation/changing-config.xml create mode 100644 nixos/doc/manual/installation/installation.xml create mode 100644 nixos/doc/manual/installation/installing-UEFI.xml create mode 100644 nixos/doc/manual/installation/installing-USB.xml create mode 100644 nixos/doc/manual/installation/installing.xml create mode 100644 nixos/doc/manual/installation/obtaining.xml create mode 100644 nixos/doc/manual/installation/upgrading.xml create mode 100644 nixos/doc/manual/release-notes/release-notes.xml create mode 100644 nixos/doc/manual/release-notes/rl-1310.xml rename nixos/doc/manual/{release-notes.xml => release-notes/rl-1404.xml} (83%) create mode 100644 nixos/doc/manual/release-notes/rl-1410.xml delete mode 100644 nixos/doc/manual/running.xml delete mode 100644 nixos/doc/manual/troubleshooting.xml diff --git a/nixos/doc/manual/administration/boot-problems.xml b/nixos/doc/manual/administration/boot-problems.xml new file mode 100644 index 000000000000..be6ff3aac0fe --- /dev/null +++ b/nixos/doc/manual/administration/boot-problems.xml @@ -0,0 +1,65 @@ +
+ +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 +systemd1. + +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.) + +
\ No newline at end of file diff --git a/nixos/doc/manual/administration/cleaning-store.xml b/nixos/doc/manual/administration/cleaning-store.xml new file mode 100644 index 000000000000..41dc65795b68 --- /dev/null +++ b/nixos/doc/manual/administration/cleaning-store.xml @@ -0,0 +1,62 @@ + + +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: + + +nix.gc.automatic = true; +nix.gc.dates = "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. + + \ No newline at end of file diff --git a/nixos/doc/manual/administration/container-networking.xml b/nixos/doc/manual/administration/container-networking.xml new file mode 100644 index 000000000000..adea3e69840d --- /dev/null +++ b/nixos/doc/manual/administration/container-networking.xml @@ -0,0 +1,50 @@ +
+ + +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: + + +networking.nat.enable = true; +networking.nat.internalInterfaces = ["ve-+"]; +networking.nat.externalInterface = "eth0"; + +where eth0 should be replaced with the desired +external interface. Note that ve-+ is a wildcard +that matches all container interfaces. + +
\ No newline at end of file diff --git a/nixos/doc/manual/administration/containers.xml b/nixos/doc/manual/administration/containers.xml new file mode 100644 index 000000000000..4cd2c8ae5563 --- /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 000000000000..86c684cdfe5d --- /dev/null +++ b/nixos/doc/manual/administration/control-groups.xml @@ -0,0 +1,75 @@ + + +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) +and 640 MiB of RAM (including swap): + + +systemd.services.httpd.serviceConfig.MemoryLimit = "512M"; +systemd.services.httpd.serviceConfig.ControlGroupAttribute = [ "memory.memsw.limit_in_bytes 640M" ]; + + + + +The command systemd-cgtop shows a +continuously updated list of all cgroups with their CPU and memory +usage. + + \ No newline at end of file diff --git a/nixos/doc/manual/administration/declarative-containers.xml b/nixos/doc/manual/administration/declarative-containers.xml new file mode 100644 index 000000000000..177ebdd8db17 --- /dev/null +++ b/nixos/doc/manual/administration/declarative-containers.xml @@ -0,0 +1,52 @@ +
+ +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, ... }: + { services.postgresql.enable = true; + services.postgresql.package = pkgs.postgresql92; + }; + }; + + +If you run nixos-rebuild switch, the container will +be built and started. If the container was already running, it will be +updated in place, without rebooting. + +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. + +
\ No newline at end of file diff --git a/nixos/doc/manual/administration/imperative-containers.xml b/nixos/doc/manual/administration/imperative-containers.xml new file mode 100644 index 000000000000..6131d4e04ea8 --- /dev/null +++ b/nixos/doc/manual/administration/imperative-containers.xml @@ -0,0 +1,124 @@ +
+ +Imperative Container Management + +We’ll cover imperative container management using +nixos-container first. 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 'services.openssh.enable = true; \ + users.extraUsers.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 succesfully, 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 'services.httpd.enable = true; \ + services.httpd.adminAddr = "foo@example.org";' + +$ 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 + + + + +
\ No newline at end of file diff --git a/nixos/doc/manual/administration/logging.xml b/nixos/doc/manual/administration/logging.xml new file mode 100644 index 000000000000..1d5df7770e29 --- /dev/null +++ b/nixos/doc/manual/administration/logging.xml @@ -0,0 +1,52 @@ + + +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. + + \ No newline at end of file diff --git a/nixos/doc/manual/administration/maintenance-mode.xml b/nixos/doc/manual/administration/maintenance-mode.xml new file mode 100644 index 000000000000..15c1f902da79 --- /dev/null +++ b/nixos/doc/manual/administration/maintenance-mode.xml @@ -0,0 +1,18 @@ +
+ +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. + +
\ No newline at end of file diff --git a/nixos/doc/manual/administration/network-problems.xml b/nixos/doc/manual/administration/network-problems.xml new file mode 100644 index 000000000000..5ba1bfd5ac9a --- /dev/null +++ b/nixos/doc/manual/administration/network-problems.xml @@ -0,0 +1,33 @@ +
+ +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 +http://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/ + + + + +
\ No newline at end of file diff --git a/nixos/doc/manual/administration/rebooting.xml b/nixos/doc/manual/administration/rebooting.xml new file mode 100644 index 000000000000..d1db7b141cf2 --- /dev/null +++ b/nixos/doc/manual/administration/rebooting.xml @@ -0,0 +1,44 @@ + + +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. + + \ No newline at end of file diff --git a/nixos/doc/manual/administration/rollback.xml b/nixos/doc/manual/administration/rollback.xml new file mode 100644 index 000000000000..23a3ece7c070 --- /dev/null +++ b/nixos/doc/manual/administration/rollback.xml @@ -0,0 +1,48 @@ +
+ +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 + + + + +
\ No newline at end of file diff --git a/nixos/doc/manual/administration/running.xml b/nixos/doc/manual/administration/running.xml new file mode 100644 index 000000000000..9091511ed527 --- /dev/null +++ b/nixos/doc/manual/administration/running.xml @@ -0,0 +1,24 @@ + + +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 000000000000..c0940a42f307 --- /dev/null +++ b/nixos/doc/manual/administration/service-mgmt.xml @@ -0,0 +1,83 @@ + + +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 000000000000..0160cb45358b --- /dev/null +++ b/nixos/doc/manual/administration/store-corruption.xml @@ -0,0 +1,37 @@ +
+ +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. + +
\ No newline at end of file diff --git a/nixos/doc/manual/administration/troubleshooting.xml b/nixos/doc/manual/administration/troubleshooting.xml new file mode 100644 index 000000000000..351fb1883310 --- /dev/null +++ b/nixos/doc/manual/administration/troubleshooting.xml @@ -0,0 +1,18 @@ + + +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 000000000000..05e2c1a9b29f --- /dev/null +++ b/nixos/doc/manual/administration/user-sessions.xml @@ -0,0 +1,53 @@ + + +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 + + + + + \ No newline at end of file diff --git a/nixos/doc/manual/configuration.xml b/nixos/doc/manual/configuration.xml deleted file mode 100644 index 64372f3bbf14..000000000000 --- a/nixos/doc/manual/configuration.xml +++ /dev/null @@ -1,1563 +0,0 @@ - - -Configuring NixOS - -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. - - - - -
Configuration syntax - -
The basics - -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. - -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, ... }: - -{ services.httpd.enable = true; - services.httpd.adminAddr = "alice@example.org"; - services.httpd.documentRoot = "/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.enabl' 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. - - -networking.hostName = "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. - - -networking.extraHosts = - '' - 127.0.0.2 other-localhost - 10.0.0.1 server - ''; - - - The main difference is that preceding whitespace is - automatically stripped from each line, and that characters like - " and \ are not special - (making it more convenient for including things like shell - code). - - - - - Booleans - - These can be true or - false, e.g. - - -networking.firewall.enable = true; -networking.firewall.allowPing = false; - - - - - - - Integers - - For example, - - -boot.kernel.sysctl."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 - - -fileSystems."/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: - - -boot.kernelModules = [ "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: - - -environment.systemPackages = - [ pkgs.thunderbird - pkgs.emacs - ]; - -postgresql.package = pkgs.postgresql90; - - - The latter option definition changes the default PostgreSQL - package used by NixOS’s PostgreSQL service to 9.0. For more - information on packages, including how to add new ones, see - . - - - - - - - -
- - -
Abstractions - -If you find yourself repeating yourself over and over, it’s time -to abstract. Take, for instance, this Apache HTTP Server configuration: - - -{ - services.httpd.virtualHosts = - [ { hostName = "example.org"; - documentRoot = "/webroot"; - adminAddr = "alice@example.org"; - enableUserDir = true; - } - { hostName = "example.org"; - documentRoot = "/webroot"; - adminAddr = "alice@example.org"; - enableUserDir = true; - enableSSL = true; - sslServerCert = "/root/ssl-example-org.crt"; - sslServerKey = "/root/ssl-example-org.key"; - } - ]; -} - - -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 -{ - services.httpd.virtualHosts = - [ 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: - - -{ - services.httpd.virtualHosts = - 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: - - -{ - services.httpd.virtualHosts = - let - makeVirtualHost = name: - { hostName = name; - documentRoot = "/webroot"; - adminAddr = "alice@example.org"; - }; - in - [ (makeVirtualHost "example.org") - (makeVirtualHost "example.com") - (makeVirtualHost "example.gov") - (makeVirtualHost "example.nl") - ]; -} - - -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: - - -{ - services.httpd.virtualHosts = - 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: - - -{ - services.httpd.virtualHosts = - let - makeVirtualHost = { name, root }: - { hostName = name; - documentRoot = root; - adminAddr = "alice@example.org"; - }; - in map makeVirtualHost - [ { name = "example.org"; root = "/sites/example.org"; } - { name = "example.com"; root = "/sites/example.com"; } - { name = "example.gov"; root = "/sites/example.gov"; } - { name = "example.nl"; root = "/sites/example.nl"; } - ]; -} - - -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. - -
- - -
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 ]; - services.httpd.enable = true; - environment.systemPackages = [ pkgs.emacs ]; - ... -} - - -Here, we include two modules from the same directory, -vpn.nix and kde.nix. The -latter might look like this: - - -{ config, pkgs, ... }: - -{ services.xserver.enable = true; - services.xserver.displayManager.kdm.enable = true; - services.xserver.desktopManager.kde4.enable = true; - environment.systemPackages = [ pkgs.kde4.kscreensaver ]; -} - - -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: - - -boot.kernelModules = 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: - - -services.httpd.adminAddr = 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 moduleIf 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, ... }: - -{ environment.systemPackages = - if config.services.xserver.enable 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 services.xserver.enable -true - -$ nixos-option boot.kernelModules -[ "tun" "ipv6" "loop" ... ] - - -Interactive exploration of the configuration is possible using -nix-repl, -a read-eval-print loop for Nix expressions. It’s not installed by -default; run nix-env -i nix-repl to get it. A -typical use: - - -$ nix-repl '<nixos>' - -nix-repl> config.networking.hostName -"mandark" - -nix-repl> map (x: x.hostName) config.services.httpd.virtualHosts -[ "example.org" "example.gov" ] - - - - -
- - -
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; } - An set with attributes names x and y - - - { foo.bar = 1; } - A nested set, equivalent to { foo = { bar = 1; }; } - - - rec { x = "bla"; 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!") - - - 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 ]) - - - - - - - -
- - -
- - - - -
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. - - - - - -The next two sections describe these two styles. - - -
Declarative package management - -With declarative package management, you specify which packages -you want on your system by setting the option -. For instance, adding the -following line to configuration.nix enables the -Mozilla Thunderbird email application: - - -environment.systemPackages = [ pkgs.thunderbird ]; - - -The effect of this specification is that the Thunderbird package from -Nixpkgs will be built or downloaded as part of the system when you run -nixos-rebuild switch. - -You can get a list of the available packages as follows: - -$ nix-env -qaP '*' --description -nixos.pkgs.firefox firefox-23.0 Mozilla Firefox - the browser, reloaded -... - - -The first column in the output is the attribute -name, such as -nixos.pkgs.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. - - -
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: - - -environment.systemPackages = [ (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, -environment.systemPackages would be a list with two -elements.) - -Even greater customisation is possible using the function -overrideDerivation. While the -override mechanism above overrides the arguments of -a package function, overrideDerivation allows -changing the result of the function. This -permits changing any aspect of the package, such as the source code. -For instance, if you want to override the source code of Emacs, you -can say: - - -environment.systemPackages = - [ (pkgs.lib.overrideDerivation pkgs.emacs (attrs: { - name = "emacs-25.0-pre"; - src = /path/to/my/emacs/tree; - })) - ]; - - -Here, overrideDerivation 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. The original attributes are accessible via -attrs. - -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.) - -
- -
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 git://github.com/NixOS/nixpkgs.git -$ cd nixpkgs - - -Then you write and test the package as described in the Nixpkgs -manual. Finally, you add it to -environment.systemPackages, e.g. - - -environment.systemPackages = [ 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: - - -environment.systemPackages = - let - my-hello = with pkgs; stdenv.mkDerivation rec { - name = "hello-2.8"; - src = fetchurl { - url = "mirror://gnu/hello/${name}.tar.gz"; - sha256 = "0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6"; - }; - }; - in - [ my-hello ]; - - -Of course, you can also move the definition of -my-hello into a separate Nix expression, e.g. - -environment.systemPackages = [ (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! - - - - -
- -
- - -
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.pkgs.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-env1 -manpage or the Nix manual. - -
- - -
- - - - -
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: - - -users.extraUsers.alice = - { createHome = true; - home = "/home/alice"; - description = "Alice Foobar"; - extraGroups = [ "wheel" "networkmanager" ]; - useDefaultShell = true; - 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 users.mutableUsers to false, then the contents of /etc/passwd -and /etc/group will be congruent to your NixOS configuration. For instance, -if you remove a user from users.extraUsers and run nixos-rebuild, the user -account will cease to exist. Also, imperative commands for managing users -and groups, such as useradd, are no longer available. - -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: - - -users.extraGroups.students.gid = 1000; - - -As with users, the group ID (gid) is optional and will be assigned -automatically if it’s missing. - -Currently declarative user management is not perfect: -nixos-rebuild does not know how to realise certain -configuration changes. This includes removing a user or group, and -removing group membership from a user. - -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 - -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. - -
- - - - -
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: - - -fileSystems."/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. - -
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/sda2: - - -$ cryptsetup luksFormat /dev/sda2 - -WARNING! -======== -This will overwrite data on /dev/sda2 irrevocably. - -Are you sure? (Type uppercase yes): YES -Enter LUKS passphrase: *** -Verify passphrase: *** - -$ cryptsetup luksOpen /dev/sda2 crypted -Enter passphrase for /dev/sda2: *** - -$ 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 = [ { device = "/dev/sda2"; name = "crypted"; } ]; -fileSystems."/".device = "/dev/mapper/crypted"; - - - - -
- -
- - - - -
X Window System - -The X Window System (X11) provides the basis of NixOS’ graphical -user interface. It can be enabled as follows: - -services.xserver.enable = 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. - -services.xserver.videoDrivers = [ "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: - -services.xserver.desktopManager.kde4.enable = true; -services.xserver.desktopManager.xfce.enable = true; -services.xserver.windowManager.xmonad.enable = true; -services.xserver.windowManager.twm.enable = true; -services.xserver.windowManager.icewm.enable = true; - - - -NixOS’s default display manager (the -program that provides a graphical login prompt and manages the X -server) is SLiM. You can select KDE’s kdm instead: - -services.xserver.displayManager.kdm.enable = true; - - - -The X server is started automatically at boot time. If you -don’t want this to happen, you can set: - -services.xserver.autorun = 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: - -services.xserver.videoDrivers = [ "nvidia" ]; - -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: - -services.xserver.driSupport32Bit = true; - - - -
- - -
Touchpads - -Support for Synaptics touchpads (found in many laptops such as -the Dell Latitude series) can be enabled as follows: - -services.xserver.synaptics.enable = true; - -The driver has many options (see ). For -instance, the following enables two-finger scrolling: - -services.xserver.synaptics.twoFingerScroll = true; - - - -
- - -
- - - - -
Networking - -
NetworkManager - -To facilitate network configuration, some desktop environments -use NetworkManager. You can enable NetworkManager by setting: - - -services.networkmanager.enable = 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. - -services.networkmanager and -services.wireless can not be enabled at the same time: -you can still connect to the wireless networks using -NetworkManager. - -
- -
Secure shell access - -Secure shell (SSH) access to your machine can be enabled by -setting: - - -services.openssh.enable = true; - - -By default, root logins using a password are disallowed. They can be -disabled entirely by setting -services.openssh.permitRootLogin to -"no". - -You can declaratively specify authorised RSA/DSA public keys for -a user as follows: - - - -users.extraUsers.alice.openssh.authorizedKeys.keys = - [ "ssh-dss AAAAB3NzaC1kc3MAAACBAPIkGWVEt4..." ]; - - - - -
- - -
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 = { ipAddress = "192.168.1.2"; prefixLength = 24; }; - - -(The network prefix can also be specified using the option -subnetMask, -e.g. "255.255.255.0", but this is deprecated.) -Typically you’ll also want to set a default gateway and set of name -servers: - - -networking.defaultGateway = "192.168.1.1"; -networking.nameservers = [ "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 : - - -networking.hostName = "cartman"; - - -The default host name is nixos. Set it to the -empty string ("") to allow the DHCP server to -provide the host name. - -
- - -
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: - - -networking.enableIPv6 = false; - - - - -
- - -
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: - - -networking.firewall.enable = false; - - -If the firewall is enabled, you can open specific TCP ports to the -outside world: - - -networking.firewall.allowedTCPPorts = [ 80 443 ]; - - -Note that TCP port 22 (ssh) is opened automatically if the SSH daemon -is enabled (). UDP -ports can be opened through -. Also of -interest is - - -networking.firewall.allowPing = true; - - -to allow the machine to respond to ping requests. (ICMPv6 pings are -always allowed.) - -
- - -
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: - - -networking.wireless.enable = true; - - -NixOS currently does not generate wpa_supplicant's -configuration file, /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 - - - -
- - -
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: - - -networking.localCommands = - '' - ip -6 addr add 2001:610:685:1::1/64 dev eth0 - ''; - - - - -
- - - - - -
- - - - -
Linux kernel - -You can override the Linux kernel and associated packages using -the option . For instance, this -selects the Linux 3.10 kernel: - -boot.kernelPackages = 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: - -cat /proc/config.gz | gunzip - -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. - -boot.kernelModules = [ "fuse" "kvm-intel" "coretemp" ]; - -If the module is required early during the boot (e.g. to mount the -root file system), you can use -: - -boot.initrd.extraKernelModules = [ "cifs" ]; - -This causes the specified modules and their dependencies to be added -to the initial ramdark. - -Kernel runtime parameters can be set through -, e.g. - -boot.kernel.sysctl."net.ipv4.tcp_keepalive_time" = 120; - -sets the kernel’s TCP keepalive time to 120 seconds. To see the -available parameters, run sysctl -a. - -
- - - - - - 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 000000000000..45475dbcd446 --- /dev/null +++ b/nixos/doc/manual/configuration/LUKS-file-systems.xml @@ -0,0 +1,42 @@ +
+ +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/sda2: + + +$ cryptsetup luksFormat /dev/sda2 + +WARNING! +======== +This will overwrite data on /dev/sda2 irrevocably. + +Are you sure? (Type uppercase yes): YES +Enter LUKS passphrase: *** +Verify passphrase: *** + +$ cryptsetup luksOpen /dev/sda2 crypted +Enter passphrase for /dev/sda2: *** + +$ 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 = [ { device = "/dev/sda2"; name = "crypted"; } ]; +fileSystems."/".device = "/dev/mapper/crypted"; + + + + +
diff --git a/nixos/doc/manual/configuration/abstractions.xml b/nixos/doc/manual/configuration/abstractions.xml new file mode 100644 index 000000000000..cbd54bca62f9 --- /dev/null +++ b/nixos/doc/manual/configuration/abstractions.xml @@ -0,0 +1,166 @@ +
+ +Abstractions + +If you find yourself repeating yourself over and over, it’s time +to abstract. Take, for instance, this Apache HTTP Server configuration: + + +{ + services.httpd.virtualHosts = + [ { hostName = "example.org"; + documentRoot = "/webroot"; + adminAddr = "alice@example.org"; + enableUserDir = true; + } + { hostName = "example.org"; + documentRoot = "/webroot"; + adminAddr = "alice@example.org"; + enableUserDir = true; + enableSSL = true; + sslServerCert = "/root/ssl-example-org.crt"; + sslServerKey = "/root/ssl-example-org.key"; + } + ]; +} + + +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 +{ + services.httpd.virtualHosts = + [ 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: + + +{ + services.httpd.virtualHosts = + 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: + + +{ + services.httpd.virtualHosts = + let + makeVirtualHost = name: + { hostName = name; + documentRoot = "/webroot"; + adminAddr = "alice@example.org"; + }; + in + [ (makeVirtualHost "example.org") + (makeVirtualHost "example.com") + (makeVirtualHost "example.gov") + (makeVirtualHost "example.nl") + ]; +} + + +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: + + +{ + services.httpd.virtualHosts = + 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: + + +{ + services.httpd.virtualHosts = + let + makeVirtualHost = { name, root }: + { hostName = name; + documentRoot = root; + adminAddr = "alice@example.org"; + }; + in map makeVirtualHost + [ { name = "example.org"; root = "/sites/example.org"; } + { name = "example.com"; root = "/sites/example.com"; } + { name = "example.gov"; root = "/sites/example.gov"; } + { name = "example.nl"; root = "/sites/example.nl"; } + ]; +} + + +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 000000000000..26a572ba1fb5 --- /dev/null +++ b/nixos/doc/manual/configuration/ad-hoc-network-config.xml @@ -0,0 +1,24 @@ +
+ +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: + + +networking.localCommands = + '' + 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 000000000000..e237e20c4fff --- /dev/null +++ b/nixos/doc/manual/configuration/ad-hoc-packages.xml @@ -0,0 +1,63 @@ +
+ +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.pkgs.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-env1 +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 000000000000..c1789fcbc041 --- /dev/null +++ b/nixos/doc/manual/configuration/adding-custom-packages.xml @@ -0,0 +1,84 @@ +
+ +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 git://github.com/NixOS/nixpkgs.git +$ cd nixpkgs + + +Then you write and test the package as described in the Nixpkgs +manual. Finally, you add it to +environment.systemPackages, e.g. + + +environment.systemPackages = [ 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: + + +environment.systemPackages = + let + my-hello = with pkgs; stdenv.mkDerivation rec { + name = "hello-2.8"; + src = fetchurl { + url = "mirror://gnu/hello/${name}.tar.gz"; + sha256 = "0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6"; + }; + }; + in + [ my-hello ]; + + +Of course, you can also move the definition of +my-hello into a separate Nix expression, e.g. + +environment.systemPackages = [ (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 000000000000..2a58ff25941c --- /dev/null +++ b/nixos/doc/manual/configuration/config-file.xml @@ -0,0 +1,213 @@ +
+ +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, ... }: + +{ services.httpd.enable = true; + services.httpd.adminAddr = "alice@example.org"; + services.httpd.documentRoot = "/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.enabl' 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. + + +networking.hostName = "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. + + +networking.extraHosts = + '' + 127.0.0.2 other-localhost + 10.0.0.1 server + ''; + + + The main difference is that preceding whitespace is + automatically stripped from each line, and that characters like + " and \ are not special + (making it more convenient for including things like shell + code). + + + + + Booleans + + These can be true or + false, e.g. + + +networking.firewall.enable = true; +networking.firewall.allowPing = false; + + + + + + + Integers + + For example, + + +boot.kernel.sysctl."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 + + +fileSystems."/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: + + +boot.kernelModules = [ "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: + + +environment.systemPackages = + [ pkgs.thunderbird + pkgs.emacs + ]; + +postgresql.package = pkgs.postgresql90; + + + The latter option definition changes the default PostgreSQL + package used by NixOS’s PostgreSQL service to 9.0. For more + information on packages, including how to add new ones, see + . + + + + + + + +
diff --git a/nixos/doc/manual/configuration/config-syntax.xml b/nixos/doc/manual/configuration/config-syntax.xml new file mode 100644 index 000000000000..87847f8451ec --- /dev/null +++ b/nixos/doc/manual/configuration/config-syntax.xml @@ -0,0 +1,27 @@ + + +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 000000000000..e15c700017c4 --- /dev/null +++ b/nixos/doc/manual/configuration/configuration.xml @@ -0,0 +1,29 @@ + + +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 000000000000..6ee7a95dc6fa --- /dev/null +++ b/nixos/doc/manual/configuration/customizing-packages.xml @@ -0,0 +1,92 @@ +
+ +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: + + +environment.systemPackages = [ (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, +environment.systemPackages would be a list with two +elements.) + +Even greater customisation is possible using the function +overrideDerivation. While the +override mechanism above overrides the arguments of +a package function, overrideDerivation allows +changing the result of the function. This +permits changing any aspect of the package, such as the source code. +For instance, if you want to override the source code of Emacs, you +can say: + + +environment.systemPackages = + [ (pkgs.lib.overrideDerivation pkgs.emacs (attrs: { + name = "emacs-25.0-pre"; + src = /path/to/my/emacs/tree; + })) + ]; + + +Here, overrideDerivation 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. The original attributes are accessible via +attrs. + +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 000000000000..6de38b452e24 --- /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: + + +environment.systemPackages = [ pkgs.thunderbird ]; + + +The effect of this specification is that the Thunderbird package from +Nixpkgs will be built or downloaded as part of the system when you run +nixos-rebuild switch. + +You can get a list of the available packages as follows: + +$ nix-env -qaP '*' --description +nixos.pkgs.firefox firefox-23.0 Mozilla Firefox - the browser, reloaded +... + + +The first column in the output is the attribute +name, such as +nixos.pkgs.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 000000000000..52ad6d62f130 --- /dev/null +++ b/nixos/doc/manual/configuration/file-systems.xml @@ -0,0 +1,40 @@ + + +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: + + +fileSystems."/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. + + + + diff --git a/nixos/doc/manual/configuration/firewall.xml b/nixos/doc/manual/configuration/firewall.xml new file mode 100644 index 000000000000..87406c28c2f7 --- /dev/null +++ b/nixos/doc/manual/configuration/firewall.xml @@ -0,0 +1,38 @@ +
+ +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: + + +networking.firewall.enable = false; + + +If the firewall is enabled, you can open specific TCP ports to the +outside world: + + +networking.firewall.allowedTCPPorts = [ 80 443 ]; + + +Note that TCP port 22 (ssh) is opened automatically if the SSH daemon +is enabled (). UDP +ports can be opened through +. Also of +interest is + + +networking.firewall.allowPing = true; + + +to allow the machine to respond to ping requests. (ICMPv6 pings are +always allowed.) + +
diff --git a/nixos/doc/manual/configuration/ipv4-config.xml b/nixos/doc/manual/configuration/ipv4-config.xml new file mode 100644 index 000000000000..e2c51518349d --- /dev/null +++ b/nixos/doc/manual/configuration/ipv4-config.xml @@ -0,0 +1,47 @@ +
+ +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 = { ipAddress = "192.168.1.2"; prefixLength = 24; }; + + +(The network prefix can also be specified using the option +subnetMask, +e.g. "255.255.255.0", but this is deprecated.) +Typically you’ll also want to set a default gateway and set of name +servers: + + +networking.defaultGateway = "192.168.1.1"; +networking.nameservers = [ "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 : + + +networking.hostName = "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 000000000000..592bf20e545d --- /dev/null +++ b/nixos/doc/manual/configuration/ipv6-config.xml @@ -0,0 +1,19 @@ +
+ +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: + + +networking.enableIPv6 = false; + + + + +
diff --git a/nixos/doc/manual/configuration/linux-kernel.xml b/nixos/doc/manual/configuration/linux-kernel.xml new file mode 100644 index 000000000000..8fe2f5255df3 --- /dev/null +++ b/nixos/doc/manual/configuration/linux-kernel.xml @@ -0,0 +1,69 @@ + + +Linux Kernel + +You can override the Linux kernel and associated packages using +the option . For instance, this +selects the Linux 3.10 kernel: + +boot.kernelPackages = 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: + +cat /proc/config.gz | gunzip + +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. + +boot.kernelModules = [ "fuse" "kvm-intel" "coretemp" ]; + +If the module is required early during the boot (e.g. to mount the +root file system), you can use +: + +boot.initrd.extraKernelModules = [ "cifs" ]; + +This causes the specified modules and their dependencies to be added +to the initial ramdark. + +Kernel runtime parameters can be set through +, e.g. + +boot.kernel.sysctl."net.ipv4.tcp_keepalive_time" = 120; + +sets the kernel’s TCP keepalive time to 120 seconds. To see the +available parameters, run sysctl -a. + + diff --git a/nixos/doc/manual/configuration/modularity.xml b/nixos/doc/manual/configuration/modularity.xml new file mode 100644 index 000000000000..d95091bd1628 --- /dev/null +++ b/nixos/doc/manual/configuration/modularity.xml @@ -0,0 +1,143 @@ +
+ +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 ]; + services.httpd.enable = true; + environment.systemPackages = [ pkgs.emacs ]; + ... +} + + +Here, we include two modules from the same directory, +vpn.nix and kde.nix. The +latter might look like this: + + +{ config, pkgs, ... }: + +{ services.xserver.enable = true; + services.xserver.displayManager.kdm.enable = true; + services.xserver.desktopManager.kde4.enable = true; + environment.systemPackages = [ pkgs.kde4.kscreensaver ]; +} + + +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: + + +boot.kernelModules = 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: + + +services.httpd.adminAddr = 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 moduleIf 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, ... }: + +{ environment.systemPackages = + if config.services.xserver.enable 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 services.xserver.enable +true + +$ nixos-option boot.kernelModules +[ "tun" "ipv6" "loop" ... ] + + +Interactive exploration of the configuration is possible using +nix-repl, +a read-eval-print loop for Nix expressions. It’s not installed by +default; run nix-env -i nix-repl to get it. A +typical use: + + +$ nix-repl '<nixos>' + +nix-repl> config.networking.hostName +"mandark" + +nix-repl> map (x: x.hostName) config.services.httpd.virtualHosts +[ "example.org" "example.gov" ] + + + + +
diff --git a/nixos/doc/manual/configuration/network-manager.xml b/nixos/doc/manual/configuration/network-manager.xml new file mode 100644 index 000000000000..e65060021b40 --- /dev/null +++ b/nixos/doc/manual/configuration/network-manager.xml @@ -0,0 +1,27 @@ +
+ +NetworkManager + +To facilitate network configuration, some desktop environments +use NetworkManager. You can enable NetworkManager by setting: + + +services.networkmanager.enable = 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. + +services.networkmanager and +services.wireless can not 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 000000000000..5f08bc1f1275 --- /dev/null +++ b/nixos/doc/manual/configuration/networking.xml @@ -0,0 +1,22 @@ + + +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 000000000000..73c1722da02c --- /dev/null +++ b/nixos/doc/manual/configuration/package-mgmt.xml @@ -0,0 +1,34 @@ + + +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/ssh.xml b/nixos/doc/manual/configuration/ssh.xml new file mode 100644 index 000000000000..7c928baaf896 --- /dev/null +++ b/nixos/doc/manual/configuration/ssh.xml @@ -0,0 +1,32 @@ +
+ +Secure Shell Access + +Secure shell (SSH) access to your machine can be enabled by +setting: + + +services.openssh.enable = true; + + +By default, root logins using a password are disallowed. They can be +disabled entirely by setting +services.openssh.permitRootLogin to +"no". + +You can declaratively specify authorised RSA/DSA public keys for +a user as follows: + + + +users.extraUsers.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 000000000000..9bb5e35e16bc --- /dev/null +++ b/nixos/doc/manual/configuration/summary.xml @@ -0,0 +1,191 @@ +
+ +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; } + An set with attributes names x and y + + + { foo.bar = 1; } + A nested set, equivalent to { foo = { bar = 1; }; } + + + rec { x = "bla"; 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!") + + + 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 000000000000..40dc687d03bb --- /dev/null +++ b/nixos/doc/manual/configuration/user-mgmt.xml @@ -0,0 +1,95 @@ + + +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: + + +users.extraUsers.alice = + { createHome = true; + home = "/home/alice"; + description = "Alice Foobar"; + extraGroups = [ "wheel" "networkmanager" ]; + useDefaultShell = true; + 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 users.mutableUsers to false, then the contents of /etc/passwd +and /etc/group will be congruent to your NixOS configuration. For instance, +if you remove a user from users.extraUsers and run nixos-rebuild, the user +account will cease to exist. Also, imperative commands for managing users +and groups, such as useradd, are no longer available. + +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: + + +users.extraGroups.students.gid = 1000; + + +As with users, the group ID (gid) is optional and will be assigned +automatically if it’s missing. + +Currently declarative user management is not perfect: +nixos-rebuild does not know how to realise certain +configuration changes. This includes removing a user or group, and +removing group membership from a user. + +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 + +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 000000000000..373a9168cc87 --- /dev/null +++ b/nixos/doc/manual/configuration/wireless.xml @@ -0,0 +1,41 @@ +
+ +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: + + +networking.wireless.enable = true; + + +NixOS currently does not generate wpa_supplicant's +configuration file, /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 000000000000..bc58bb1f0669 --- /dev/null +++ b/nixos/doc/manual/configuration/x-windows.xml @@ -0,0 +1,94 @@ + + +X Window System + +The X Window System (X11) provides the basis of NixOS’ graphical +user interface. It can be enabled as follows: + +services.xserver.enable = 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. + +services.xserver.videoDrivers = [ "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: + +services.xserver.desktopManager.kde4.enable = true; +services.xserver.desktopManager.xfce.enable = true; +services.xserver.windowManager.xmonad.enable = true; +services.xserver.windowManager.twm.enable = true; +services.xserver.windowManager.icewm.enable = true; + + + +NixOS’s default display manager (the +program that provides a graphical login prompt and manages the X +server) is SLiM. You can select KDE’s kdm instead: + +services.xserver.displayManager.kdm.enable = true; + + + +The X server is started automatically at boot time. If you +don’t want this to happen, you can set: + +services.xserver.autorun = 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: + +services.xserver.videoDrivers = [ "nvidia" ]; + +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: + +services.xserver.driSupport32Bit = true; + + + + + + +Touchpads + +Support for Synaptics touchpads (found in many laptops such as +the Dell Latitude series) can be enabled as follows: + +services.xserver.synaptics.enable = true; + +The driver has many options (see ). For +instance, the following enables two-finger scrolling: + +services.xserver.synaptics.twoFingerScroll = true; + + + + + + + diff --git a/nixos/doc/manual/containers.xml b/nixos/doc/manual/containers.xml deleted file mode 100644 index 2530d5195212..000000000000 --- a/nixos/doc/manual/containers.xml +++ /dev/null @@ -1,242 +0,0 @@ - - -Containers - -NixOS allows you to easily run other NixOS instances as -containers. Containers are a light-weight -approach to virtualisation that runs software in the container at the -same speed as in the host system. NixOS containers share the Nix store -of the host, making container creation very efficient. - -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. - - -
Imperative container management - -We’ll cover imperative container management using -nixos-container first. 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 'services.openssh.enable = true; \ - users.extraUsers.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 succesfully, 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 'services.httpd.enable = true; \ - services.httpd.adminAddr = "foo@example.org";' - -$ 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 - - - - -
- - -
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, ... }: - { services.postgresql.enable = true; - services.postgresql.package = pkgs.postgresql92; - }; - }; - - -If you run nixos-rebuild switch, the container will -be built and started. If the container was already running, it will be -updated in place, without rebooting. - -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. - -
- - -
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: - - -networking.nat.enable = true; -networking.nat.internalInterfaces = ["ve-+"]; -networking.nat.externalInterface = "eth0"; - -where eth0 should be replaced with the desired -external interface. Note that ve-+ is a wildcard -that matches all container interfaces. - -
- - - - diff --git a/nixos/doc/manual/development.xml b/nixos/doc/manual/development.xml deleted file mode 100644 index 2f0c2a7aa8da..000000000000 --- a/nixos/doc/manual/development.xml +++ /dev/null @@ -1,1119 +0,0 @@ - - -Development - -This chapter describes how you can modify and extend -NixOS. - - - - -
- -Getting the sources - -By default, NixOS’s nixos-rebuild command -uses the NixOS and Nixpkgs sources provided by the -nixos-unstable 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 done using the following command: - - -$ nixos-checkout /my/sources - - -or - - -$ mkdir -p /my/sources -$ cd /my/sources -$ nix-env -i git -$ git clone git://github.com/NixOS/nixpkgs.git - - -This will check out the latest NixOS sources to -/my/sources/nixpkgs/nixos -and the Nixpkgs sources to -/my/sources/nixpkgs. -(The NixOS source tree lives in a subdirectory of the Nixpkgs -repository.) - -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 -14.04.273.ea1952b (Baboon) - -$ git checkout -b local ea1952b - - -Or, to base your local branch on the latest version available in the -NixOS channel: - - -$ curl -sI http://nixos.org/channels/nixos-unstable/ | grep Location -Location: http://releases.nixos.org/nixos/unstable/nixos-14.10pre43986.acaf4a6/ - -$ git checkout -b local acaf4a6 - - -You can then use git rebase to sync your local -branch with the upstream branch, and 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. - - - -
- - - - -
- -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 cron). - -NixOS module for the “locate” service - -{ config, lib, pkgs, ... }: - -with lib; - -let locatedb = "/var/cache/locatedb"; in - -{ - options = { - - services.locate = { - - enable = mkOption { - type = types.bool; - default = false; - description = '' - If enabled, NixOS will periodically update the database of - files used by the locate command. - ''; - }; - - period = mkOption { - type = types.str; - default = "15 02 * * *"; - description = '' - This option defines (in the format used by cron) when the - locate database is updated. The default is to update at - 02:15 at night every day. - ''; - }; - - }; - - }; - - config = { - - systemd.services.update-locatedb = - { description = "Update Locate Database"; - path = [ pkgs.su ]; - script = - '' - mkdir -m 0755 -p $(dirname ${locatedb}) - exec updatedb --localuser=nobody --output=${locatedb} --prunepaths='/tmp /var/tmp /media /run' - ''; - }; - - services.cron.systemCronJobs = optional config.services.locate.enable - "${config.services.locate.period} root ${config.systemd.package}/bin/systemctl start update-locatedb.service"; - - }; -} - - -
Option declarations - -An option declaration specifies the name, type and description -of a NixOS configuration option. It is illegal to define an option -that hasn’t been declared in any module. A option declaration -generally looks like this: - - -options = { - name = mkOption { - type = type specification; - default = default value; - example = example value; - description = "Description for use in the NixOS manual."; - }; -}; - - - - -The function mkOption accepts the following arguments. - - - - - type - - The type of the option (see below). It may be omitted, - but that’s not advisable since it may lead to errors that are - hard to diagnose. - - - - - default - - The default value used if no value is defined by any - module. A default is not required; in that case, if the option - value is ever used, an error will be thrown. - - - - - 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. - - - - - - - -Here is a non-exhaustive list of option types: - - - - - types.bool - - A Boolean. - - - - - types.int - - An integer. - - - - - types.str - - A string. - - - - - types.lines - - A string. If there are multiple definitions, they are - concatenated, with newline characters in between. - - - - - types.path - - A path, defined as anything that, when coerced to a - string, starts with a slash. This includes derivations. - - - - - types.listOf t - - A list of elements of type t - (e.g., types.listOf types.str is a list of - strings). Multiple definitions are concatenated together. - - - - - types.attrsOf t - - A set of elements of type t - (e.g., types.attrsOf types.int is a set of - name/value pairs, the values being integers). - - - - - types.nullOr t - - Either the value null or something of - type t. - - - - - -You can also create new types using the function -mkOptionType. See -lib/types.nix in Nixpkgs for details. - -
- - -
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 = [ ... ]; - }) - ]; - - - - - - -
- - -
Important options - -NixOS has many options, but some are of particular importance to -module writers. - - - - - - - This set defines files in /etc. A - typical use is: - -environment.etc."os-release".text = - '' - NAME=NixOS - ... - ''; - - which causes a file named /etc/os-release - to be created with the given contents. - - - - - - - A set of shell script fragments that must be executed - whenever the configuration is activated (i.e., at boot time, or - after running nixos-rebuild switch). For instance, - -system.activationScripts.media = - '' - mkdir -m 0755 -p /media - ''; - - causes the directory /media to be created. - Activation scripts must be idempotent. They should not start - background processes such as daemons; use - for that. - - - - - - - This is the set of systemd services. Example: - -systemd.services.dhcpcd = - { description = "DHCP Client"; - wantedBy = [ "multi-user.target" ]; - after = [ "systemd-udev-settle.service" ]; - path = [ dhcpcd pkgs.nettools pkgs.openresolv ]; - serviceConfig = - { Type = "forking"; - PIDFile = "/run/dhcpcd.pid"; - ExecStart = "${dhcpcd}/sbin/dhcpcd --config ${dhcpcdConf}"; - Restart = "always"; - }; - }; - - which creates the systemd unit - dhcpcd.service. The option - determined which other units pull this - one in; multi-user.target is the default - target of the system, so dhcpcd.service will - always be started. The option - provides the main - command for the service; it’s also possible to provide pre-start - actions, stop scripts, and so on. - - - - - - - - If your service requires special UIDs or GIDs, you can - define them with these options. See for details. - - - - - -
- - -
- - - - -
- -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.manual - 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. - - - - - - - -
- - - - -
- -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. To build them -you have to set NIXOS_CONFIG before -running nix-build to build the ISO. - - -$ nix-build -A config.system.build.isoImage -I nixos-config=modules/installer/cd-dvd/installation-cd-minimal.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 - - - -
- - - - -
- -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: - - -$ nix-build -A config.system.build.nixos-install -$ mount -t tmpfs none /mnt -$ ./result/bin/nixos-install - -To start a login shell in the new NixOS installation in -/mnt: - - -$ ./result/bin/nixos-install --chroot - - - - -
- - - - - -
- -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. - -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/; - - -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. - - - - 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. - - - - waitForWindow - Wait until an X11 window has appeared whose name - matches the given regular expression, e.g., - waitForWindow(qr/Terminal/). - - - - - - - - - -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 - - - - -It is also possible to run the test environment interactively, -allowing you to experiment with the VMs. For example: - - -$ nix-build login.nix -A driver -$ ./result/bin/nixos-run-vms - - -The script nixos-run-vms starts the virtual -machines defined by test. The root file system of the VMs is created -on the fly and kept across VM restarts in -./hostname.qcow2. - -Finally, the test itself can be run interactively. This is -particularly useful when developing or debugging a test: - - -$ nix-build tests/ -A nfs.driver -$ ./result/bin/nixos-test-driver -starting VDE switch for network 1 -> - - -You can then take any Perl statement, e.g. - - -> startAll -> $machine->succeed("touch /tmp/foo") - - -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). - - - -
- - - diff --git a/nixos/doc/manual/development/building-nixos.xml b/nixos/doc/manual/development/building-nixos.xml new file mode 100644 index 000000000000..21c5bfe6a5b1 --- /dev/null +++ b/nixos/doc/manual/development/building-nixos.xml @@ -0,0 +1,32 @@ + + +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. To build them +you have to set NIXOS_CONFIG before +running nix-build to build the ISO. + + +$ nix-build -A config.system.build.isoImage -I nixos-config=modules/installer/cd-dvd/installation-cd-minimal.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 + + + + \ No newline at end of file diff --git a/nixos/doc/manual/development/building-parts.xml b/nixos/doc/manual/development/building-parts.xml new file mode 100644 index 000000000000..cb8dee039c8e --- /dev/null +++ b/nixos/doc/manual/development/building-parts.xml @@ -0,0 +1,113 @@ + + +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.manual + 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. + + + + + + + + \ No newline at end of file diff --git a/nixos/doc/manual/development/development.xml b/nixos/doc/manual/development/development.xml new file mode 100644 index 000000000000..747159c44270 --- /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/nixos-tests.xml b/nixos/doc/manual/development/nixos-tests.xml new file mode 100644 index 000000000000..a98da9933309 --- /dev/null +++ b/nixos/doc/manual/development/nixos-tests.xml @@ -0,0 +1,19 @@ + + +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. + + + + + \ No newline at end of file diff --git a/nixos/doc/manual/development/option-declarations.xml b/nixos/doc/manual/development/option-declarations.xml new file mode 100644 index 000000000000..6d93dc5c0094 --- /dev/null +++ b/nixos/doc/manual/development/option-declarations.xml @@ -0,0 +1,141 @@ +
+ +Option Declarations + +An option declaration specifies the name, type and description +of a NixOS configuration option. It is illegal to define an option +that hasn’t been declared in any module. A option declaration +generally looks like this: + + +options = { + name = mkOption { + type = type specification; + default = default value; + example = example value; + description = "Description for use in the NixOS manual."; + }; +}; + + + + +The function mkOption accepts the following arguments. + + + + + type + + The type of the option (see below). It may be omitted, + but that’s not advisable since it may lead to errors that are + hard to diagnose. + + + + + default + + The default value used if no value is defined by any + module. A default is not required; in that case, if the option + value is ever used, an error will be thrown. + + + + + 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. + + + + + + + +Here is a non-exhaustive list of option types: + + + + + types.bool + + A Boolean. + + + + + types.int + + An integer. + + + + + types.str + + A string. + + + + + types.lines + + A string. If there are multiple definitions, they are + concatenated, with newline characters in between. + + + + + types.path + + A path, defined as anything that, when coerced to a + string, starts with a slash. This includes derivations. + + + + + types.listOf t + + A list of elements of type t + (e.g., types.listOf types.str is a list of + strings). Multiple definitions are concatenated together. + + + + + types.attrsOf t + + A set of elements of type t + (e.g., types.attrsOf types.int is a set of + name/value pairs, the values being integers). + + + + + types.nullOr t + + Either the value null or something of + type t. + + + + + +You can also create new types using the function +mkOptionType. See +lib/types.nix in Nixpkgs for details. + +
\ No newline at end of file diff --git a/nixos/doc/manual/development/option-def.xml b/nixos/doc/manual/development/option-def.xml new file mode 100644 index 000000000000..4e267ecfd1e3 --- /dev/null +++ b/nixos/doc/manual/development/option-def.xml @@ -0,0 +1,112 @@ +
+ +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 = [ ... ]; + }) + ]; + + + + + + +
\ No newline at end of file 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 000000000000..d9be761eb01d --- /dev/null +++ b/nixos/doc/manual/development/running-nixos-tests.xml @@ -0,0 +1,77 @@ +
+ +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 + + + + +It is also possible to run the test environment interactively, +allowing you to experiment with the VMs. For example: + + +$ nix-build login.nix -A driver +$ ./result/bin/nixos-run-vms + + +The script nixos-run-vms starts the virtual +machines defined by test. The root file system of the VMs is created +on the fly and kept across VM restarts in +./hostname.qcow2. + +Finally, the test itself can be run interactively. This is +particularly useful when developing or debugging a test: + + +$ nix-build tests/ -A nfs.driver +$ ./result/bin/nixos-test-driver +starting VDE switch for network 1 +> + + +You can then take any Perl statement, e.g. + + +> startAll +> $machine->succeed("touch /tmp/foo") + + +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). + +
\ No newline at end of file diff --git a/nixos/doc/manual/development/sources.xml b/nixos/doc/manual/development/sources.xml new file mode 100644 index 000000000000..992a07af9813 --- /dev/null +++ b/nixos/doc/manual/development/sources.xml @@ -0,0 +1,95 @@ + + +Getting the Sources + +By default, NixOS’s nixos-rebuild command +uses the NixOS and Nixpkgs sources provided by the +nixos-unstable 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 done using the following command: + + +$ nixos-checkout /my/sources + + +or + + +$ mkdir -p /my/sources +$ cd /my/sources +$ nix-env -i git +$ git clone git://github.com/NixOS/nixpkgs.git + + +This will check out the latest NixOS sources to +/my/sources/nixpkgs/nixos +and the Nixpkgs sources to +/my/sources/nixpkgs. +(The NixOS source tree lives in a subdirectory of the Nixpkgs +repository.) + +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 +14.04.273.ea1952b (Baboon) + +$ git checkout -b local ea1952b + + +Or, to base your local branch on the latest version available in the +NixOS channel: + + +$ curl -sI http://nixos.org/channels/nixos-unstable/ | grep Location +Location: http://releases.nixos.org/nixos/unstable/nixos-14.10pre43986.acaf4a6/ + +$ git checkout -b local acaf4a6 + + +You can then use git rebase to sync your local +branch with the upstream branch, and 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. + + + + \ No newline at end of file diff --git a/nixos/doc/manual/development/testing-installer.xml b/nixos/doc/manual/development/testing-installer.xml new file mode 100644 index 000000000000..87e40e326171 --- /dev/null +++ b/nixos/doc/manual/development/testing-installer.xml @@ -0,0 +1,27 @@ + + +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: + + +$ nix-build -A config.system.build.nixos-install +$ mount -t tmpfs none /mnt +$ ./result/bin/nixos-install + +To start a login shell in the new NixOS installation in +/mnt: + + +$ ./result/bin/nixos-install --chroot + + + + + \ No newline at end of file diff --git a/nixos/doc/manual/development/writing-modules.xml b/nixos/doc/manual/development/writing-modules.xml new file mode 100644 index 000000000000..9cf29e5dc57d --- /dev/null +++ b/nixos/doc/manual/development/writing-modules.xml @@ -0,0 +1,175 @@ + + +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 cron). + +NixOS Module for the “locate” Service + +{ config, lib, pkgs, ... }: + +with lib; + +let locatedb = "/var/cache/locatedb"; in + +{ + options = { + + services.locate = { + + enable = mkOption { + type = types.bool; + default = false; + description = '' + If enabled, NixOS will periodically update the database of + files used by the locate command. + ''; + }; + + period = mkOption { + type = types.str; + default = "15 02 * * *"; + description = '' + This option defines (in the format used by cron) when the + locate database is updated. The default is to update at + 02:15 at night every day. + ''; + }; + + }; + + }; + + config = { + + systemd.services.update-locatedb = + { description = "Update Locate Database"; + path = [ pkgs.su ]; + script = + '' + mkdir -m 0755 -p $(dirname ${locatedb}) + exec updatedb --localuser=nobody --output=${locatedb} --prunepaths='/tmp /var/tmp /media /run' + ''; + }; + + services.cron.systemCronJobs = optional config.services.locate.enable + "${config.services.locate.period} root ${config.systemd.package}/bin/systemctl start update-locatedb.service"; + + }; +} + + + + + + \ No newline at end of file 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 000000000000..bbb655eed2a6 --- /dev/null +++ b/nixos/doc/manual/development/writing-nixos-tests.xml @@ -0,0 +1,251 @@ +
+ +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/; + + +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. + + + + 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. + + + + waitForWindow + Wait until an X11 window has appeared whose name + matches the given regular expression, e.g., + waitForWindow(qr/Terminal/). + + + + + + +
\ No newline at end of file diff --git a/nixos/doc/manual/installation.xml b/nixos/doc/manual/installation.xml deleted file mode 100644 index 4cbfcc229fa4..000000000000 --- a/nixos/doc/manual/installation.xml +++ /dev/null @@ -1,570 +0,0 @@ - - -Installing NixOS - - - - -
- -Obtaining NixOS - -NixOS ISO images can be downloaded from the NixOS -homepage. These can be burned onto a CD. It is also possible -to copy them onto a USB stick and install NixOS from there. For -details, see 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 - homepage. - - - 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. - - - - - -
- - - - -
- -Installation - - - - Boot from the CD. - - The CD contains a basic NixOS installation. (It - also contains Memtest86+, useful if you want to test new hardware.) - When it’s finished booting, it should have detected most of your - hardware and brought up networking (check - ifconfig). 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. - - The NixOS manual is available on virtual console 8 - (press Alt+F8 to access). - - Login as root and the empty - password. - - If you downloaded the graphical ISO image, you can - run start display-manager to start KDE. - - The NixOS installer doesn’t do any partitioning or - formatting yet, so you need to that yourself. Use the following - commands: - - - - For partitioning: - fdisk. - - 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 creating LVM volumes, the LVM commands, e.g., - - -$ pvcreate /dev/sda1 /dev/sdb1 -$ vgcreate MyVolGroup /dev/sda1 /dev/sdb1 -$ lvcreate --size 2G --name bigdisk MyVolGroup -$ lvcreate --size 1G --name smalldisk MyVolGroup - - - - For creating software RAID devices, use - mdadm. - - - - - - Mount the target file system on which NixOS should - be installed on /mnt, e.g. - - -$ mount /dev/disk/by-label/nixos /mnt - - - - - 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. - - - - 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 - - - The vim text editor is also available. - - You must set the option - to specify on which disk - the GRUB boot loader is to be installed. Without it, NixOS cannot - boot. - - 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 CD 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. - - Examples of real-world NixOS configuration files can be - found at . - - - - 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: *** - - - - - - - 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 ), a new item appears in the menu. - This allows you to easily roll back to another 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. - - - - - -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. - -Commands for installing NixOS on <filename>/dev/sda</filename> - -$ fdisk /dev/sda # (or whatever device you want to install on) -$ mkfs.ext4 -L nixos /dev/sda1 -$ mkswap -L swap /dev/sda2 -$ swapon /dev/sda2 -$ mount /dev/disk/by-label/nixos /mnt -$ nixos-generate-config --root /mnt -$ nano /mnt/etc/nixos/configuration.nix -$ nixos-install -$ reboot - - -NixOS configuration - -{ config, pkgs, ... }: - -{ - imports = - [ # Include the results of the hardware scan. - ./hardware-configuration.nix - ]; - - boot.loader.grub.device = "/dev/sda"; - - # 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; -} - - -
- -UEFI Installation - -NixOS can also be installed on UEFI systems. The procedure -is by and large the same as a BIOS installation, with the following -changes: - - - - You should boot the live CD in UEFI mode (consult your - specific hardware's documentation for instructions). You may find - the rEFInd - boot manager useful. - - - Instead of fdisk, you should use - gdisk to partition your disks. You will need to - have a separate partition for /boot with - partition code EF00, and it should be formatted as a - vfat filesystem. - - - You must set to - true. nixos-generate-config - should do this automatically for new configurations when booted in - UEFI mode. - - - After having mounted your installation partition to - /mnt, you must mount the boot partition - to /mnt/boot. - - - You may want to look at the options starting with - and - as well. - - - To see console messages during early boot, add "fbcon" - to your . - - - - -
- -
- -Booting from a USB stick - -For systems without CD drive, the NixOS livecd can be booted from -a usb stick. For non-UEFI installations, -unetbootin -will work. For UEFI installations, you should mount the ISO, copy its contents -verbatim to your drive, then either: - - - - Change the label of the disk partition to the label of the ISO - (visible with the blkid command), or - - - Edit loader/entries/nixos-livecd.conf on the drive - and change the root= field in the options - line to point to your drive (see the documentation on root= - in - the kernel documentation for more details). - - - -
- -
- - - - -
- -Changing the configuration - -The file /etc/nixos/configuration.nix -contains the current configuration of your machine. Whenever you’ve -changed something to 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. 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 - - - - -
- - - - -
- -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-14.04. - These only get conservative bug fixes and package upgrades. For - instance, a channel update may cause the Linux kernel on your - system to be upgraded from 3.4.66 to 3.4.67 (a minor bug fix), but - not from 3.4.x to - 3.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. - - - -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.) - -When you first install NixOS, you’re automatically subscribed to -the NixOS channel that corresponds to your installation source. For -instance, if you installed from a 14.04 ISO, you will be subscribed to -the nixos-14.04 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 http://nixos.org/channels/channel-name nixos - - -(Be sure to include the nixos parameter at the -end.) For instance, to use the NixOS 14.04 stable channel: - - -$ nix-channel --add http://nixos.org/channels/nixos-14.04 nixos - - -But it you want to live on the bleeding edge: - - -$ nix-channel --add http://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. - -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. - -
- - diff --git a/nixos/doc/manual/installation/changing-config.xml b/nixos/doc/manual/installation/changing-config.xml new file mode 100644 index 000000000000..aa31742434e4 --- /dev/null +++ b/nixos/doc/manual/installation/changing-config.xml @@ -0,0 +1,90 @@ + + +Changing the Configuration + +The file /etc/nixos/configuration.nix +contains the current configuration of your machine. Whenever you’ve +changed something to 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. 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 000000000000..ee61bedc4183 --- /dev/null +++ b/nixos/doc/manual/installation/installation.xml @@ -0,0 +1,21 @@ + + +Installation + + + +This section describes how to obtain, install, and configure +NixOS for first-time use. + + + + + + + + + diff --git a/nixos/doc/manual/installation/installing-UEFI.xml b/nixos/doc/manual/installation/installing-UEFI.xml new file mode 100644 index 000000000000..dbd5606c4a56 --- /dev/null +++ b/nixos/doc/manual/installation/installing-UEFI.xml @@ -0,0 +1,51 @@ +
+ +UEFI Installation + +NixOS can also be installed on UEFI systems. The procedure +is by and large the same as a BIOS installation, with the following +changes: + + + + You should boot the live CD in UEFI mode (consult your + specific hardware's documentation for instructions). You may find + the rEFInd + boot manager useful. + + + Instead of fdisk, you should use + gdisk to partition your disks. You will need to + have a separate partition for /boot with + partition code EF00, and it should be formatted as a + vfat filesystem. + + + You must set to + true. nixos-generate-config + should do this automatically for new configurations when booted in + UEFI mode. + + + After having mounted your installation partition to + /mnt, you must mount the boot partition + to /mnt/boot. + + + You may want to look at the options starting with + and + as well. + + + To see console messages during early boot, add "fbcon" + to your . + + + + +
diff --git a/nixos/doc/manual/installation/installing-USB.xml b/nixos/doc/manual/installation/installing-USB.xml new file mode 100644 index 000000000000..97e3d2eaa1c0 --- /dev/null +++ b/nixos/doc/manual/installation/installing-USB.xml @@ -0,0 +1,30 @@ +
+ +Booting from a USB Drive + +For systems without CD drive, the NixOS livecd can be booted from +a usb stick. For non-UEFI installations, +unetbootin +will work. For UEFI installations, you should mount the ISO, copy its contents +verbatim to your drive, then either: + + + + Change the label of the disk partition to the label of the ISO + (visible with the blkid command), or + + + Edit loader/entries/nixos-livecd.conf on the drive + and change the root= field in the options + line to point to your drive (see the documentation on root= + in + the kernel documentation for more details). + + + + +
diff --git a/nixos/doc/manual/installation/installing.xml b/nixos/doc/manual/installation/installing.xml new file mode 100644 index 000000000000..793b503ad97a --- /dev/null +++ b/nixos/doc/manual/installation/installing.xml @@ -0,0 +1,264 @@ + + +Installing NixOS + + + + Boot from the CD. + + The CD contains a basic NixOS installation. (It + also contains Memtest86+, useful if you want to test new hardware.) + When it’s finished booting, it should have detected most of your + hardware and brought up networking (check + ifconfig). 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. + + The NixOS manual is available on virtual console 8 + (press Alt+F8 to access). + + Login as root and the empty + password. + + If you downloaded the graphical ISO image, you can + run start display-manager to start KDE. + + The NixOS installer doesn’t do any partitioning or + formatting yet, so you need to that yourself. Use the following + commands: + + + + For partitioning: + fdisk. + + 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 creating LVM volumes, the LVM commands, e.g., + + +$ pvcreate /dev/sda1 /dev/sdb1 +$ vgcreate MyVolGroup /dev/sda1 /dev/sdb1 +$ lvcreate --size 2G --name bigdisk MyVolGroup +$ lvcreate --size 1G --name smalldisk MyVolGroup + + + + For creating software RAID devices, use + mdadm. + + + + + + Mount the target file system on which NixOS should + be installed on /mnt, e.g. + + +$ mount /dev/disk/by-label/nixos /mnt + + + + + 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. + + + + 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 + + + The vim text editor is also available. + + You must set the option + to specify on which disk + the GRUB boot loader is to be installed. Without it, NixOS cannot + boot. + + 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 CD 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. + + Examples of real-world NixOS configuration files can be + found at . + + + + 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: *** + + + + + + + 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 (seeChanging + Configuration ), a new item appears in the menu. This allows you to + easily roll back to another 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. + + + + + +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. + +Commands for Installing NixOS on <filename>/dev/sda</filename> + +$ fdisk /dev/sda # (or whatever device you want to install on) +$ mkfs.ext4 -L nixos /dev/sda1 +$ mkswap -L swap /dev/sda2 +$ swapon /dev/sda2 +$ mount /dev/disk/by-label/nixos /mnt +$ nixos-generate-config --root /mnt +$ nano /mnt/etc/nixos/configuration.nix +$ nixos-install +$ reboot + + +NixOS Configuration + +{ config, pkgs, ... }: + +{ + imports = + [ # Include the results of the hardware scan. + ./hardware-configuration.nix + ]; + + boot.loader.grub.device = "/dev/sda"; + + # 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; +} + + + + + + diff --git a/nixos/doc/manual/installation/obtaining.xml b/nixos/doc/manual/installation/obtaining.xml new file mode 100644 index 000000000000..ceeeb5c0ac09 --- /dev/null +++ b/nixos/doc/manual/installation/obtaining.xml @@ -0,0 +1,44 @@ + + +Obtaining NixOS + +NixOS ISO images can be downloaded from the NixOS +homepage. These can be burned onto a CD. It is also possible +to copy them onto a USB stick and install NixOS from there. For +details, see 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 + homepage. + + + 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 000000000000..ed71a7e23a30 --- /dev/null +++ b/nixos/doc/manual/installation/upgrading.xml @@ -0,0 +1,90 @@ + + +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-14.04. + These only get conservative bug fixes and package upgrades. For + instance, a channel update may cause the Linux kernel on your + system to be upgraded from 3.4.66 to 3.4.67 (a minor bug fix), but + not from 3.4.x to + 3.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. + + + +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.) + +When you first install NixOS, you’re automatically subscribed to +the NixOS channel that corresponds to your installation source. For +instance, if you installed from a 14.04 ISO, you will be subscribed to +the nixos-14.04 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 http://nixos.org/channels/channel-name nixos + + +(Be sure to include the nixos parameter at the +end.) For instance, to use the NixOS 14.04 stable channel: + + +$ nix-channel --add http://nixos.org/channels/nixos-14.04 nixos + + +But it you want to live on the bleeding edge: + + +$ nix-channel --add http://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. + +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. + + diff --git a/nixos/doc/manual/manual.xml b/nixos/doc/manual/manual.xml index f51a04cdf25b..a3ad76209ac8 100644 --- a/nixos/doc/manual/manual.xml +++ b/nixos/doc/manual/manual.xml @@ -1,15 +1,14 @@ - + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="NixOSManual"> + - NixOS Manual Version - - Preface @@ -29,19 +28,14 @@ - - - - + + + - - - - - + - Configuration options + Configuration Options 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 000000000000..fb82d5adcefb --- /dev/null +++ b/nixos/doc/manual/release-notes/release-notes.xml @@ -0,0 +1,17 @@ + + +Release Notes + + +This section lists the release notes for each stable version of NixOS. + + + + + + + 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 000000000000..234fb5a643f6 --- /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. + + \ No newline at end of file diff --git a/nixos/doc/manual/release-notes.xml b/nixos/doc/manual/release-notes/rl-1404.xml similarity index 83% rename from nixos/doc/manual/release-notes.xml rename to nixos/doc/manual/release-notes/rl-1404.xml index 52e88bb4c861..74af1ed12741 100644 --- a/nixos/doc/manual/release-notes.xml +++ b/nixos/doc/manual/release-notes/rl-1404.xml @@ -1,34 +1,8 @@ - - -Release notes - - - -
- -Release 14.10 (“Caterpillar”, 2014/10/??) - -When upgrading from a previous release, please be aware of the -following incompatible changes: - - - - The host side of a container virtual Ethernet pair - is now called ve-container-name - rather than c-container-name. - - - - - -
- - - - -
+ Release 14.04 (“Baboon”, 2014/04/30) @@ -183,16 +157,4 @@ networking.firewall.enable = false; -
- - - -
- -Release 13.10 (“Aardvark”, 2013/10/31) - -This is the first stable release branch of NixOS. - -
- - + \ No newline at end of file diff --git a/nixos/doc/manual/release-notes/rl-1410.xml b/nixos/doc/manual/release-notes/rl-1410.xml new file mode 100644 index 000000000000..09da15ce2361 --- /dev/null +++ b/nixos/doc/manual/release-notes/rl-1410.xml @@ -0,0 +1,22 @@ + + +Release 14.10 (“Caterpillar”, 2014/10/??) + +When upgrading from a previous release, please be aware of the +following incompatible changes: + + + + The host side of a container virtual Ethernet pair + is now called ve-container-name + rather than c-container-name. + + + + + + \ No newline at end of file diff --git a/nixos/doc/manual/running.xml b/nixos/doc/manual/running.xml deleted file mode 100644 index e1a358df2aac..000000000000 --- a/nixos/doc/manual/running.xml +++ /dev/null @@ -1,369 +0,0 @@ - - -Running NixOS - -This chapter describes various aspects of managing a running -NixOS system, such as how to use the systemd -service manager. - - - - -
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). - - - -
- - - - -
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. - -
- - - - -
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 - - - - -
- - - - -
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) -and 640 MiB of RAM (including swap): - - -systemd.services.httpd.serviceConfig.MemoryLimit = "512M"; -systemd.services.httpd.serviceConfig.ControlGroupAttribute = [ "memory.memsw.limit_in_bytes 640M" ]; - - - - -The command systemd-cgtop shows a -continuously updated list of all cgroups with their CPU and memory -usage. - -
- - - - -
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. - -
- - - - -
Cleaning up 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: - - -nix.gc.automatic = true; -nix.gc.dates = "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. - -
- - - diff --git a/nixos/doc/manual/troubleshooting.xml b/nixos/doc/manual/troubleshooting.xml deleted file mode 100644 index c7d65112b649..000000000000 --- a/nixos/doc/manual/troubleshooting.xml +++ /dev/null @@ -1,199 +0,0 @@ - - -Troubleshooting - - - - -
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 -systemd1. - -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.) - -
- - - - -
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. - -
- - - - -
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 - - - - -
- - - - -
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. - -
- - - - -
Nix network issues - -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 -http://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/ - - - - -
- - -