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.listOft
-
- A list of elements of type t
- (e.g., types.listOf types.str is a list of
- strings). Multiple definitions are concatenated together.
-
-
-
-
- types.attrsOft
-
- 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.nullOrt
-
- 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.listOft
+
+ A list of elements of type t
+ (e.g., types.listOf types.str is a list of
+ strings). Multiple definitions are concatenated together.
+
+
+
+
+ types.attrsOft
+
+ 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.nullOrt
+
+ 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 ManualVersion
-
-
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/
-
-
-
-
-
-
-
-