From 5c1f8cbc70cd5e6867ef6a2a06d27a40daa07010 Mon Sep 17 00:00:00 2001 From: Eelco Dolstra Date: Thu, 10 Oct 2013 13:28:20 +0200 Subject: Move all of NixOS to nixos/ in preparation of the repository merge --- nixos/doc/config-examples/basic.nix | 21 + .../closed-install-configuration.nix | 32 + nixos/doc/config-examples/root-on-lvm.nix | 27 + nixos/doc/config-examples/svn-server.nix | 36 + nixos/doc/config-examples/x86_64-usbstick.nix | 20 + nixos/doc/manual/configuration.xml | 810 +++++++++++++++++++++ nixos/doc/manual/default.nix | 98 +++ nixos/doc/manual/development.xml | 599 +++++++++++++++ nixos/doc/manual/installation.xml | 340 +++++++++ nixos/doc/manual/man-configuration.xml | 38 + nixos/doc/manual/man-nixos-build-vms.xml | 110 +++ nixos/doc/manual/man-nixos-option.xml | 170 +++++ nixos/doc/manual/man-nixos-rebuild.xml | 300 ++++++++ nixos/doc/manual/man-pages.xml | 31 + nixos/doc/manual/manual.xml | 62 ++ nixos/doc/manual/options-to-docbook.xsl | 187 +++++ nixos/doc/manual/running.xml | 369 ++++++++++ nixos/doc/manual/style.css | 268 +++++++ nixos/doc/manual/troubleshooting.xml | 198 +++++ nixos/doc/manual/userconfiguration.xml | 80 ++ 20 files changed, 3796 insertions(+) create mode 100644 nixos/doc/config-examples/basic.nix create mode 100644 nixos/doc/config-examples/closed-install-configuration.nix create mode 100644 nixos/doc/config-examples/root-on-lvm.nix create mode 100644 nixos/doc/config-examples/svn-server.nix create mode 100644 nixos/doc/config-examples/x86_64-usbstick.nix create mode 100644 nixos/doc/manual/configuration.xml create mode 100644 nixos/doc/manual/default.nix create mode 100644 nixos/doc/manual/development.xml create mode 100644 nixos/doc/manual/installation.xml create mode 100644 nixos/doc/manual/man-configuration.xml create mode 100644 nixos/doc/manual/man-nixos-build-vms.xml create mode 100644 nixos/doc/manual/man-nixos-option.xml create mode 100644 nixos/doc/manual/man-nixos-rebuild.xml create mode 100644 nixos/doc/manual/man-pages.xml create mode 100644 nixos/doc/manual/manual.xml create mode 100644 nixos/doc/manual/options-to-docbook.xsl create mode 100644 nixos/doc/manual/running.xml create mode 100644 nixos/doc/manual/style.css create mode 100644 nixos/doc/manual/troubleshooting.xml create mode 100644 nixos/doc/manual/userconfiguration.xml (limited to 'nixos/doc') diff --git a/nixos/doc/config-examples/basic.nix b/nixos/doc/config-examples/basic.nix new file mode 100644 index 00000000000..da37cfb8c28 --- /dev/null +++ b/nixos/doc/config-examples/basic.nix @@ -0,0 +1,21 @@ +{ + boot = { + loader.grub.device = "/dev/sda"; + }; + + fileSystems = [ + { mountPoint = "/"; + device = "/dev/sda1"; + } + ]; + + swapDevices = [ + { device = "/dev/sdb1"; } + ]; + + services = { + openssh = { + enable = true; + }; + }; +} diff --git a/nixos/doc/config-examples/closed-install-configuration.nix b/nixos/doc/config-examples/closed-install-configuration.nix new file mode 100644 index 00000000000..0cebacdb0cc --- /dev/null +++ b/nixos/doc/config-examples/closed-install-configuration.nix @@ -0,0 +1,32 @@ +{ + boot = { + loader.grub.device = "/dev/sda"; + copyKernels = true; + bootMount = "(hd0,0)"; + }; + + fileSystems = [ + { mountPoint = "/"; + device = "/dev/sda3"; + } + { mountPoint = "/boot"; + device = "/dev/sda1"; + neededForBoot = true; + } + ]; + + swapDevices = [ + { device = "/dev/sda2"; } + ]; + + services = { + sshd = { + enable = true; + }; + }; + + fonts = { + enableFontConfig = false; + }; + +} diff --git a/nixos/doc/config-examples/root-on-lvm.nix b/nixos/doc/config-examples/root-on-lvm.nix new file mode 100644 index 00000000000..2ea1e547921 --- /dev/null +++ b/nixos/doc/config-examples/root-on-lvm.nix @@ -0,0 +1,27 @@ +# This configuration has / on a LVM volume. Since Grub +# doesn't know about LVM, a separate /boot is therefore +# needed. +# +# In this example, labels are used for file systems and +# swap devices: "boot" might be /dev/sda1, "root" might be +# /dev/my-volume-group/root, and "swap" might be /dev/sda2. +# In particular there is no specific reference to the fact +# that / is on LVM; that's figured out automatically. + +{ + boot.loader.grub.device = "/dev/sda"; + boot.initrd.kernelModules = ["ata_piix"]; + + fileSystems = [ + { mountPoint = "/"; + label = "root"; + } + { mountPoint = "/boot"; + label = "boot"; + } + ]; + + swapDevices = [ + { label = "swap"; } + ]; +} diff --git a/nixos/doc/config-examples/svn-server.nix b/nixos/doc/config-examples/svn-server.nix new file mode 100644 index 00000000000..e727007117b --- /dev/null +++ b/nixos/doc/config-examples/svn-server.nix @@ -0,0 +1,36 @@ +{ + boot = { + loader.grub.device = "/dev/sda"; + }; + + fileSystems = [ + { mountPoint = "/"; + device = "/dev/sda1"; + } + ]; + + services = { + + sshd = { + enable = true; + }; + + httpd = { + enable = true; + adminAddr = "admin@example.org"; + + subservices = { + + subversion = { + enable = true; + dataDir = "/data/subversion"; + notificationSender = "svn@example.org"; + }; + + }; + + }; + + }; + +} diff --git a/nixos/doc/config-examples/x86_64-usbstick.nix b/nixos/doc/config-examples/x86_64-usbstick.nix new file mode 100644 index 00000000000..374d3ba3bc7 --- /dev/null +++ b/nixos/doc/config-examples/x86_64-usbstick.nix @@ -0,0 +1,20 @@ +# Configuration file used to install NixOS-x86_64 on a USB stick. + +{ + boot = { + loader.grub.device = "/dev/sda"; + initrd = { + kernelModules = ["usb_storage" "ehci_hcd" "ohci_hcd"]; + }; + }; + + fileSystems = [ + { mountPoint = "/"; + label = "nixos-usb"; + } + ]; + + fonts = { + enableFontConfig = false; + }; +} diff --git a/nixos/doc/manual/configuration.xml b/nixos/doc/manual/configuration.xml new file mode 100644 index 00000000000..965ba73105a --- /dev/null +++ b/nixos/doc/manual/configuration.xml @@ -0,0 +1,810 @@ + + +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 that file only take +effect after you run nixos-rebuild. + + + + +
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 overriden 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 <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" ]; + isSystemUser = false; + useDefaultShell = true; + openssh.authorizedKeys.keys = [ "ssh-dss AAAAB3Nza... alice@foobar" ]; + }; + + +Note that alice is a member of the +wheel group, which allows her to use +sudo to execute commands as +root. 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. + +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: + +service.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 + +
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 can be enabled as follows: + + +networking.firewall.enable = true; + + +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 + + +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 in +/run/booted-system/kernel-modules/config. 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/default.nix b/nixos/doc/manual/default.nix new file mode 100644 index 00000000000..e6edb30985c --- /dev/null +++ b/nixos/doc/manual/default.nix @@ -0,0 +1,98 @@ +{ pkgs, options +# revision can have multiple values: local, HEAD or any revision number. +, revision ? "HEAD" +}: + +let + + # To prevent infinite recursion, remove system.path from the + # options. Not sure why this happens. + options_ = + options // + { system = removeAttrs options.system ["path"]; }; + + optionsXML = builtins.toFile "options.xml" (builtins.unsafeDiscardStringContext + (builtins.toXML (pkgs.lib.optionAttrSetToDocList "" options_))); + + optionsDocBook = pkgs.runCommand "options-db.xml" {} '' + ${pkgs.libxslt}/bin/xsltproc \ + --stringparam revision '${revision}' \ + -o $out ${./options-to-docbook.xsl} ${optionsXML} + ''; + +in rec { + + # Generate the NixOS manual. + manual = pkgs.stdenv.mkDerivation { + name = "nixos-manual"; + + sources = pkgs.lib.sourceFilesBySuffices ./. [".xml"]; + + buildInputs = [ pkgs.libxml2 pkgs.libxslt ]; + + xsltFlags = '' + --param section.autolabel 1 + --param section.label.includes.component.label 1 + --param html.stylesheet 'style.css' + --param xref.with.number.and.title 1 + --param toc.section.depth 3 + --param admon.style ''' + --param callout.graphics.extension '.gif' + ''; + + buildCommand = '' + ln -s $sources/*.xml . # */ + ln -s ${optionsDocBook} options-db.xml + + # Check the validity of the manual sources. + xmllint --noout --nonet --xinclude --noxincludenode \ + --relaxng ${pkgs.docbook5}/xml/rng/docbook/docbook.rng \ + manual.xml + + # Generate the HTML manual. + dst=$out/share/doc/nixos + ensureDir $dst + xsltproc $xsltFlags --nonet --xinclude \ + --output $dst/manual.html \ + ${pkgs.docbook5_xsl}/xml/xsl/docbook/xhtml/docbook.xsl \ + ./manual.xml + + mkdir -p $dst/images/callouts + cp ${pkgs.docbook5_xsl}/xml/xsl/docbook/images/callouts/*.gif $dst/images/callouts/ + + cp ${./style.css} $dst/style.css + + ensureDir $out/nix-support + echo "doc manual $dst manual.html" >> $out/nix-support/hydra-build-products + ''; # */ + }; + + # Generate the NixOS manpages. + manpages = pkgs.stdenv.mkDerivation { + name = "nixos-manpages"; + + sources = pkgs.lib.sourceFilesBySuffices ./. [".xml"]; + + buildInputs = [ pkgs.libxml2 pkgs.libxslt ]; + + buildCommand = '' + ln -s $sources/*.xml . # */ + ln -s ${optionsDocBook} options-db.xml + + # Check the validity of the manual sources. + xmllint --noout --nonet --xinclude --noxincludenode \ + --relaxng ${pkgs.docbook5}/xml/rng/docbook/docbook.rng \ + ./man-pages.xml + + # Generate manpages. + ensureDir $out/share/man + xsltproc --nonet --xinclude \ + --param man.output.in.separate.dir 1 \ + --param man.output.base.dir "'$out/share/man/'" \ + --param man.endnotes.are.numbered 0 \ + ${pkgs.docbook5_xsl}/xml/xsl/docbook/manpages/docbook.xsl \ + ./man-pages.xml + ''; + }; + +} diff --git a/nixos/doc/manual/development.xml b/nixos/doc/manual/development.xml new file mode 100644 index 00000000000..d8b5f6f571c --- /dev/null +++ b/nixos/doc/manual/development.xml @@ -0,0 +1,599 @@ + + +Development + +This chapter has some random notes on hacking on +NixOS. + + + + +
+ +Hacking on NixOS + +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/nixos.git +$ git clone git://github.com/NixOS/nixpkgs.git + + +This will check out the latest NixOS sources to +/my/sources/nixos and +the Nixpkgs sources to +/my/sources/nixpkgs. +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 /my/sources + + + + +nixos-rebuild affects only the system profile. +To install packages to your user profile from expressions in +/my/sources, use +nix-env -f /my/sources/nixpkgs, +or change the default by replacing the symlink in +~/.nix-defexpr: + + +$ rm -f ~/.nix-defexpr/channels +$ ln -s /my/sources/nixpkgs ~/.nix-defexpr/nixpkgs + + + + +You should not pass the base directory +/my/sources +to nix-env, as it will break after interpreting expressions +in nixos/ as packages. + +
+ + + + +
+ +Extending NixOS + +NixOS is based on a modular system for declarative configuration. + This system combines multiple modules to produce one + configuration. One of the module which compose your computer + configuration is /etc/nixos/configuration.nix. Other + modules are available under NixOS modules + directory + +A module is a file which handles one specific part of the + configuration. This part of the configuration could correspond to + hardware, a service, network settings, or preferences. A module + configuration does not have to handle everything from scratch, it can base + its configuration on other configurations provided by other modules. Thus + a module can define options to setup its + configuration, and it can also declare options to be + fed by other modules. + + + +A module is a file which contains a Nix + expression. This expression should be either an expression which gets + evaluated into an attribute set or a function which returns an attribute + set. + +When the expression is a function, it should expect only one argument + which is an attribute set containing an attribute + named config and another attribute + named pkgs. The config attribute + contains the result of the merge of all modules. This attribute is + evaluated lazily, such as any Nix expression. For more details on how + options are merged, see the details in . + The pkgs attribute + contains nixpkgs attribute set of packages. This + attribute is necessary for declaring options. + +Usual module content + +{ config, pkgs, ... }: + +{ + imports = + [ + ]; + + options = { + + }; + + config = { + + }; +} + + + Illustrates + a module skeleton. + + + + This line makes the current Nix expression a function. This + line can be omitted if there is no reference to pkgs + and config inside the module. + + + + This list is used to enumerate path to other modules which are + declaring options used by the current module. In NixOS, default modules + are listed in the file modules/module-list.nix. + The default modules don't need to be added in the import list. + + + + This attribute set contains an attribute set of option + declaration. + + + + This attribute set contains an attribute set of option + definitions. If the module does not have any imported + modules or any option declarations, then this attribute set can be used + in place of its parent attribute set. This is a common case for simple + modules such + as /etc/nixos/configuration.nix. + + + + + + + +A module defines a configuration which would be + interpreted by other modules. To define a configuration, a module needs + to provide option definitions. An option definition is a simple + attribute assignment. + +Option definitions are made in a declarative manner. Without + properties, options will always be defined with the same value. To + introduce more flexibility in the system, option definitions are guarded + by properties. + +Properties are means to introduce conditional values inside option + definitions. This conditional values can be distinguished in two + categories. The condition which are local to the current configuration + and conditions which are dependent on others configurations. Local + properties are mkIf + and mkAssert. Global properties + are mkOverride, mkDefault + and mkOrder. + +mkIf is used to remove the option definitions which + are below it if the condition is evaluated to + false. mkAssert expects the condition to be evaluated + to true otherwise it raises an error message. + +mkOverride is used to mask previous definitions if + the current value has a lower mask number. The mask value is 100 (default) + for any option definition which does not use this property. + Thus, mkDefault is just a short-cut with a higher mask + (1000) than the default mask value. This means that a module can set an + option definition as a preference, and still let another module defining + it with a different value without using any property. + +mkOrder is used to sort definitions based on the + rank number. The rank number will sort all options definitions before + giving the sorted list of option definition to the merge function defined + in the option declaration. A lower rank will move the definition to the + beginning and a higher rank will move the option toward the end. The + default rank is 100. + + + +A module may declare options which are used by + other module to change the configuration provided by the current module. + Changes to the option definitions are made with properties which are using + values extracted from the result of the merge of all modules + (the config argument). + +The config argument reproduce the same hierarchy of + all options declared in all modules. For each option, the result of the + option is available, it is either the default value or the merge of all + definitions of the option. + +Options are declared with the + function pkgs.lib.mkOption. This function expects an + attribute set which at least provides a description. A default value, an + example, a type, a merge function and a post-process function can be + added. + +Types are used to provide a merge strategy for options and to ensure + the type of each option definitions. They are defined + in pkgs.lib.types. + +The merge function expects a list of option definitions and merge + them to obtain one result of the same type. + +The post-process function (named apply) takes the + result of the merge or of the default value, and produce an output which + could have a different type than the type expected by the option. + + + +Locate Module Example + +{ config, pkgs, ... }: + +with pkgs.lib; + +let + cfg = config.services.locate; + locatedb = "/var/cache/locatedb"; + logfile = "/var/log/updatedb"; + cmd =''root updatedb --localuser=nobody --output=${locatedb} > ${logfile}''; +in + +{ + imports = [ /etc/nixos/nixos/modules/services/scheduling/cron.nix ]; + + options = { + services.locate = { + enable = mkOption { + default = false; + example = true; + type = with types; bool; + description = '' + If enabled, NixOS will periodically update the database of + files used by the locate command. + ''; + }; + + period = mkOption { + default = "15 02 * * *"; + type = with types; uniq string; + 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 = mkIf cfg.enable { + services.cron = { + enable = true; + systemCronJobs = "${cfg.period} root ${cmd}"; + }; + }; +} + + + illustrates a module which handles + the regular update of the database which index all files on the file + system. This modules has option definitions to rely on the cron service + to run the command at predefined dates. In addition, this modules + provides option declarations to enable the indexing and to use different + period of time to run the indexing. Properties are used to prevent + ambiguous definitions of option (enable locate service and disable cron + services) and to ensure that no options would be defined if the locate + service is not enabled. + +
+ + + + +
+ +Building specific parts of NixOS + + + + +$ nix-build /etc/nixos/nixos -A attr + +where attr is an attribute in +/etc/nixos/nixos/default.nix. Attributes of interest include: + + + + + config + The computer configuration generated from + the NIXOS_CONFIG environment variable (default + is /etc/nixos/configuration.nix) with the NixOS + default set of modules. + + + + system + The derivation which build your computer system. It is + built by the command nixos-rebuild + build + + + + vm + The derivation which build your computer system inside a + virtual machine. It is built by the command nixos-rebuild + build-vm + + + + + + +Most parts of NixOS can be built through the config +attribute set. This attribute set allows you to have a view of the merged +option definitions and all its derivations. Important derivations are store +inside the option and can be listed with the +command nix-instantiate --xml --eval-only /etc/nixos/nixos -A +config.system.build + + +
+ + + + +
+ +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. + + +$ export NIXOS_CONFIG=/etc/nixos/nixos/modules/installer/cd-dvd/installation-cd-minimal.nix +$ nix-build /etc/nixos/nixos -A config.system.build.isoImage + + + +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/building the NixOS Manual + +A quick way to see if your documentation improvements +or option descriptions look good: + + +$ nix-build -A config.system.build.manual + + + +
+ + + + +
+ +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: + + +$ export NIXOS_CONFIG=/etc/nixos/nixos/modules/installer/cd-dvd/installation-cd-minimal.nix +$ nix-build /etc/nixos/nixos -A config.system.build.nixosInstall +$ dd if=/dev/zero of=diskimage seek=2G count=0 bs=1 +$ yes | mke2fs -j diskimage +$ mount -o loop diskimage /mnt +$ ./result/bin/nixos-install + + + +
+ + + + + +
+ +Testing the <literal>initrd</literal> + +A quick way to test whether the kernel and the initial ramdisk +boot correctly is to use QEMU’s and + options: + + +$ nix-build /etc/nixos/nixos -A config.system.build.initialRamdisk -o initrd +$ nix-build /etc/nixos/nixos -A config.system.build.kernel -o kernel +$ qemu-system-x86_64 -kernel ./kernel/bzImage -initrd ./initrd/initrd -hda /dev/null + + + + +
+ +
+ + Whole-system testing using virtual machines + + + Complete NixOS GNU/Linux systems can be tested in virtual machines + (VMs). This makes it possible to test a system upgrade or + configuration change before rebooting into it, using the + nixos-rebuild build-vm or + nixos-rebuild build-vm-with-bootloader command. + + + + + + The tests/ directory in the NixOS source tree + contains several whole-system unit tests. + These tests can be runNixOS tests can be run both from + NixOS and from a non-NixOS GNU/Linux distribution, provided the + Nix package manager is installed. from the NixOS + source tree as follows: + + +$ nix-build tests/ -A nfs.test + + + This performs an automated test of the NFS client and server + functionality in the Linux kernel, including file locking + semantics (e.g., whether locks are maintained across server + crashes). It will first build or download all the dependencies of + the test (e.g., all packages needed to run a NixOS VM). The test + is defined in + tests/nfs.nix. If the test succeeds, + nix-build will place a symlink + ./result in the current directory pointing at + the location in the Nix store of the test results (e.g., + screenshots, test reports, and so on). In particular, a + pretty-printed log of the test is written to + log.html, which can be viewed using a web + browser like this: + + +$ 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 tests/ -A nfs.driver +$ ./result/bin/nixos-run-vms + + + The script nixos-run-vms starts the three + virtual machines defined in the NFS test using QEMU/KVM. 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 +> + + + Perl statements can now be typed in to start or manipulate the + VMs: + + +> startAll; +(the VMs start booting) +> $server->waitForJob("nfs-kernel-nfsd"); +> $client1->succeed("flock -x /data/lock -c 'sleep 100000' &"); +> $client2->fail("flock -n -s /data/lock true"); +> $client1->shutdown; +(this releases client1's lock) +> $client2->succeed("flock -n -s /data/lock true"); + + + 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). + + + + This and other tests are continuously run on the Hydra + instance at nixos.org, which allows + developers to be notified of any regressions introduced by a NixOS + or Nixpkgs change. + + + + The actual Nix programming interface to VM testing is in NixOS, + under + lib/testing.nix. This file defines a + function which takes an attribute set containing a + nixpkgs attribute (the path to a Nixpkgs + checkout), and a system attribute (the system + type). It returns an attribute set containing several utility + functions, among which the main entry point is + makeTest. + + + + The makeTest function takes a function similar to + that found in + tests/nfs.nix (discussed above). It + returns an attribute set containing (among others): + + + + + test + A derivation containing the test log as an HTML file, + as seen above, suitable for presentation in the Hydra continuous + build system. + + + + report + A derivation containing a code coverage report, with + meta-data suitable for Hydra. + + + + driver + A derivation containing scripts to run the VM test or + interact with the VM network interactively, as seen above. + + + + + + +
+ + diff --git a/nixos/doc/manual/installation.xml b/nixos/doc/manual/installation.xml new file mode 100644 index 00000000000..3068fa5cb94 --- /dev/null +++ b/nixos/doc/manual/installation.xml @@ -0,0 +1,340 @@ + + +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. + +
+ + + + +
+ +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, 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 + . This will + make the file system configuration independent from device + changes. + + 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. + + + + 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 configuration that + you want to be built and activated, and then NixOS takes care of + realising that configuration. The command + nixos-option can generate an initial + configuration file for you: + + +$ nixos-option --install + + It tries to figure out the kernel modules necessary for mounting + the root device, as well as various other hardware + characteristics. However, it doesn’t try to figure out the + option yet. + + You should edit + /mnt/etc/nixos/configuration.nix to suit your + needs. The text editors nano and + vim are available. + + You need to specify a root file system in + and the target device for the Grub boot + loader in . See + for a list of the available configuration + options. + + It is very important that you specify in the option + all 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-option --install will figure out the + required modules. + + Examples of real-world NixOS configuration files can be + found at . + + + + 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. + + + + Do the installation: + + +$ nixos-install + + Cross fingers. + + 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. + + + + + + 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 (idem) +$ mkswap -L swap /dev/sda2 (idem) +$ mount LABEL=nixos /mnt +$ nixos-option --install +$ nano /mnt/etc/nixos/configuration.nix +(in particular, set the fileSystems and swapDevices options) +$ nixos-install +$ reboot + + +NixOS configuration + +{ + boot.loader.grub.device = "/dev/sda"; + + fileSystems."/".device = "/dev/disk/by-label/nixos"; + + swapDevices = + [ { device = "/dev/disk/by-label/swap"; } ]; + + services.sshd.enable = true; +} + + +
+ + + + + +
+ +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). + +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). + +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 virtual machine that contains the +desired configuration. Just do + + +$ nixos-rebuild build-vm +$ ./result/bin/run-*-vm + + +The VM does not have use any data from your host system, so your +existing user accounts and home directories will not be +available. + +
+ + + + + +
+ +Upgrading NixOS + +The best way to keep your NixOS installation up to date is to +use the nixos-unstable channel. (A channel is a +Nix mechanism for distributing Nix expressions and associated +binaries.) The NixOS channel is updated automatically from NixOS’s +Git repository after running certain tests and building most +packages. + +NixOS automatically subscribes you to the NixOS channel. If for +some reason this is not the case, just do + + +$ nix-channel --add http://nixos.org/channels/nixos-unstable + + +You can then upgrade NixOS to the latest version in the channel by +running + + +$ nix-channel --update nixos + + +and running the nixos-rebuild command as described +in . + +
+ + diff --git a/nixos/doc/manual/man-configuration.xml b/nixos/doc/manual/man-configuration.xml new file mode 100644 index 00000000000..d49369d2c58 --- /dev/null +++ b/nixos/doc/manual/man-configuration.xml @@ -0,0 +1,38 @@ + + + + configuration.nix + 5 + NixOS + + + + + configuration.nix + NixOS system configuration specification + + + +Description + +The file /etc/nixos/configuration.nix +contains the declarative specification of your NixOS system +configuration. The command nixos-rebuild takes +this file and realises the system configuration specified +therein. + + + + +Options + +You can use the following options in +configuration.nix. + + + + + + diff --git a/nixos/doc/manual/man-nixos-build-vms.xml b/nixos/doc/manual/man-nixos-build-vms.xml new file mode 100644 index 00000000000..f37677629d0 --- /dev/null +++ b/nixos/doc/manual/man-nixos-build-vms.xml @@ -0,0 +1,110 @@ + + + + nixos-build-vms + 8 + NixOS + + + + + nixos-build-vms + build a network of virtual machines from a network of NixOS configurations + + + + + nixos-build-vms + + + + network.nix + + + +Description + +This command builds a network of QEMU-KVM virtual machines of a Nix expression +specifying a network of NixOS machines. The virtual network can be started by +executing the bin/run-vms shell script that is generated by +this command. By default, a result symlink is produced that +points to the generated virtual network. + + +A network Nix expression has the following structure: + + +{ + test1 = {pkgs, config, ...}: + { + services.openssh.enable = true; + nixpkgs.system = "i686-linux"; + deployment.targetHost = "test1.example.net"; + + # Other NixOS options + }; + + test2 = {pkgs, config, ...}: + { + services.openssh.enable = true; + services.httpd.enable = true; + environment.systemPackages = [ pkgs.lynx ]; + nixpkgs.system = "x86_64-linux"; + deployment.targetHost = "test2.example.net"; + + # Other NixOS options + }; +} + + +Each attribute in the expression represents a machine in the network +(e.g. test1 and test2) +referring to a function defining a NixOS configuration. +In each NixOS configuration, two attributes have a special meaning. +The deployment.targetHost specifies the address +(domain name or IP address) +of the system which is used by ssh to perform +remote deployment operations. The nixpkgs.system +attribute can be used to specify an architecture for the target machine, +such as i686-linux which builds a 32-bit NixOS +configuration. Omitting this property will build the configuration +for the same architecture as the host system. + + + + +Options + +This command accepts the following options: + + + + + + + Shows a trace of the output. + + + + + + + Do not create a 'result' symlink. + + + + + , + + Shows the usage of this command to the user. + + + + + + + + + diff --git a/nixos/doc/manual/man-nixos-option.xml b/nixos/doc/manual/man-nixos-option.xml new file mode 100644 index 00000000000..f7a8ce403dc --- /dev/null +++ b/nixos/doc/manual/man-nixos-option.xml @@ -0,0 +1,170 @@ + + + + nixos-option + 8 + NixOS + + + + + nixos-option + inspect a NixOS configuration + + + + + nixos-option + + + + + + + option.name + + + nixos-option + + + + + +Description + +This command evaluates the configuration specified in +/etc/nixos/configuration.nix and returns the properties +of the option name given as argument. By default, it returns the value of +the option. + +When the option name is not an option, the command prints the list of +attributes in contained in the attribute set. This could used to provide +completion in some editors. + +When the option (or ) is +used with no option name, this command generates a template configuration +with a scan of the target system. It produces a template configuration +in /etc/nixos/configuration.nix, and a scan of the +machine in /etc/nixos/hardware-configuration.nix. The +scan of the machine is produced +by nixos-hardware-scan. + + + +Options + +This command accepts the following options: + + + + + , + + Use the installation configuration instead of current system + configuration. Generate a template configuration if no option name is + specified. + + + + + , + + Returns the value of the option. This is the default operation + if no other options are defined. + + + + + , + + Return the default value, the example and the description of the + option when available. + + + + + , + + Return the locations where the option is declared and where it + is defined. This is extremely useful to find sources of errors in + your configuration. + + + + + + + + +Environment + + + + + mountPoint + + Location of the target file system. Defaults to + /mnt. This environment variable is only used in + combinaison with option. + + + + + NIXOS_CONFIG + + Path to the main NixOS configuration module. Defaults to + /etc/nixos/configuration.nix. + + + + + + + + +Examples + +Investigate option values: + +$ nixos-option boot.loader +This attribute set contains: +generationsDir +grub +initScript + +$ nixos-option boot.loader.grub.enable +true + +Prints option information: + +$ nixos-option -d networking.hostName +Default: "nixos" +Description: +The name of the machine. Leave it empty if you want to obtain +it from a DHCP server (if using DHCP). + +Find the locations which are declaring and defining an option: + +$ nixos-option -l hardware.firmware +Declared by: + /mnt/data/nix-sources/nixos/modules/services/hardware/udev.nix + +Defined by: + /etc/nixos/nixos/modules/system/boot/kernel.nix + /etc/nixos/nixos/modules/hardware/network/rt73.nix + /etc/nixos/nixos/modules/hardware/network/intel-3945abg.nix + /etc/nixos/nixos/modules/hardware/network/intel-2200bg.nix + + + +Bugs + +The author listed in the following section is wrong. If there is any + other bug, please report to Nicolas Pierron. + + + + + diff --git a/nixos/doc/manual/man-nixos-rebuild.xml b/nixos/doc/manual/man-nixos-rebuild.xml new file mode 100644 index 00000000000..e43dafd3cfe --- /dev/null +++ b/nixos/doc/manual/man-nixos-rebuild.xml @@ -0,0 +1,300 @@ + + + + nixos-rebuild + 8 + NixOS + + + + + nixos-rebuild + reconfigure a NixOS machine + + + + + nixos-rebuild + + + + + + + + + + + + + + + + + + + + + +Description + +This command updates the system so that it corresponds to the +configuration specified in +/etc/nixos/configuration.nix. Thus, every time +you modify /etc/nixos/configuration.nix or any +NixOS module, you must run nixos-rebuild to make +the changes take effect. It builds the new system in +/nix/store, runs its activation script, and stop +and (re)starts any system services if needed. + +This command has one required argument, which specifies the +desired operation. It must be one of the following: + + + + + + + Build and activate the new configuration, and make it the + boot default. That is, the configuration is added to the GRUB + boot menu as the default meny entry, so that subsequent reboots + will boot the system into the new configuration. Previous + configurations activated with nixos-rebuild + switch or nixos-rebuild boot remain + available in the GRUB menu. + + + + + + + Build the new configuration and make it the boot default + (as with nixos-rebuild switch), but do not + activate it. That is, the system continues to run the previous + configuration until the next reboot. + + + + + + + Build and activate the new configuration, but do not add + it to the GRUB boot menu. Thus, if you reboot the system (or if + it crashes), you will automatically revert to the default + configuration (i.e. the configuration resulting from the last + call to nixos-rebuild switch or + nixos-rebuild boot). + + + + + + + Build the new configuration, but neither activate it nor + add it to the GRUB boot menu. It leaves a symlink named + result in the current directory, which + points to the output of the top-level “system” derivation. This + is essentially the same as doing + +$ nix-build /etc/nixos/nixos -A system + + Note that you do not need to be root to run + nixos-rebuild build. + + + + + + + Simply show what store paths would be built or downloaded + by any of the operations above. + + + + + + + Build a script that starts a NixOS virtual machine with + the desired configuration. It leaves a symlink + result in the current directory that points + (under + result/bin/run-hostname-vm) + at the script that starts the VM. Thus, to test a NixOS + configuration in a virtual machine, you should do the following: + +$ nixos-rebuild build-vm +$ ./result/bin/run-*-vm + + + The VM is implemented using the qemu + package. For best performance, you should load the + kvm-intel or kvm-amd + kernel modules to get hardware virtualisation. + + The VM mounts the Nix store of the host through the 9P + file system. The host Nix store is read-only, so Nix commands + that modify the Nix store will not work in the VM. This + includes commands such as nixos-rebuild; to + change the VM’s configuration, you must halt the VM and re-run + the commands above. + + + The VM has its own ext3 root file + system, which is automatically created when the VM is first + started, and is persistent across reboots of the VM. It is + stored in + ./hostname.qcow2. + + + + + + + + Like , but boots using the + regular boot loader of your configuration (e.g., GRUB 1 or 2), + rather than booting directly into the kernel and initial ramdisk + of the system. This allows you to test whether the boot loader + works correctly. However, it does not guarantee that your NixOS + configuration will boot successfully on the host hardware (i.e., + after running nixos-rebuild switch), because + the hardware and boot loader configuration in the VM are + different. The boot loader is installed on an automatically + generated virtual disk containing a /boot + partition, which is mounted read-only in the VM. + + + + + + + + + + + +Options + +This command accepts the following options: + + + + + + + Fetch the latest version of NixOS from the NixOS + channel. + + + + + + + Causes the GRUB boot loader to be (re)installed on the + device specified by the + boot.loader.grub.device configuration + option. + + + + + + + Normally, nixos-rebuild first builds + the nixUnstable attribute in Nixpkgs, and + uses the resulting instance of the Nix package manager to build + the new system configuration. This is necessary if the NixOS + modules use features not provided by the currently installed + version of Nix. This option disables building a new Nix. + + + + + + + Equivalent to + . This option is useful if you + call nixos-rebuild frequently (e.g. if you’re + hacking on a NixOS module). + + + + + + + Instead of building a new configuration as specified by + /etc/nixos/configuration.nix, roll back to + the previous configuration. (The previous configuration is + defined as the one before the “current” generation of the + profile /nix/var/nix/profiles/system.) + + + + + +In addition, nixos-rebuild accepts various +Nix-related flags, including / +, , +, and + / . See +the Nix manual for details. + + + + +Environment + + + + + NIXOS_CONFIG + + Path to the main NixOS configuration module. Defaults to + /etc/nixos/configuration.nix. + + + + + + + + +Files + + + + + /run/current-system + + A symlink to the currently active system configuration in + the Nix store. + + + + + /nix/var/nix/profiles/system + + The Nix profile that contains the current and previous + system configurations. Used to generate the GRUB boot + menu. + + + + + + + + +Bugs + +This command should be renamed to something more +descriptive. + + + + + + diff --git a/nixos/doc/manual/man-pages.xml b/nixos/doc/manual/man-pages.xml new file mode 100644 index 00000000000..7840e1b897b --- /dev/null +++ b/nixos/doc/manual/man-pages.xml @@ -0,0 +1,31 @@ + + + NixOS Reference Pages + + + + + + Eelco + Dolstra + + Author + + + + 2007 + 2008 + 2009 + Eelco Dolstra + + + + + + + + + + diff --git a/nixos/doc/manual/manual.xml b/nixos/doc/manual/manual.xml new file mode 100644 index 00000000000..7d6634bf093 --- /dev/null +++ b/nixos/doc/manual/manual.xml @@ -0,0 +1,62 @@ + + + + + NixOS Manual + + + + Eelco + Dolstra + + + + + + Nicolas + Pierron + + + + + 2007-2013 + Eelco Dolstra + + + + + + + Preface + + This manual describes how to install, use and extend NixOS, + a Linux distribution based on the purely functional package + management system Nix. + + If you encounter problems, please report them on the + nix-dev@lists.science.uu.nl + mailing list or on the + #nixos channel on Freenode. Bugs should + be reported in NixOS’ GitHub + issue tracker. + + + + + + + + + + + + List of Options + + + + diff --git a/nixos/doc/manual/options-to-docbook.xsl b/nixos/doc/manual/options-to-docbook.xsl new file mode 100644 index 00000000000..adc6c93c722 --- /dev/null +++ b/nixos/doc/manual/options-to-docbook.xsl @@ -0,0 +1,187 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + Default: + + + + + + + + + none + + + + + + + + Example: + + + + + + + + + + + + + + + + + Declared by: + + + + + + + Defined by: + + + + + + + + + + + + + + + + + + "" + + + + + + + + + + true + + + + + false + + + + + [ + + + + + ] + + + + + { + + + = + ; + + } + + + + + + + (download of ) + + + (build of ) + + + + + + + + + + + + https://github.com/NixOS/nixos/blob//modules/ + + + https://github.com/NixOS/nixops/blob//nix/ + + + file:// + + + + + + <nixos/modules/> + + + <nixops/> + + + + + + + + + + + diff --git a/nixos/doc/manual/running.xml b/nixos/doc/manual/running.xml new file mode 100644 index 00000000000..e50099707cc --- /dev/null +++ b/nixos/doc/manual/running.xml @@ -0,0 +1,369 @@ + + +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/style.css b/nixos/doc/manual/style.css new file mode 100644 index 00000000000..e2204c159e2 --- /dev/null +++ b/nixos/doc/manual/style.css @@ -0,0 +1,268 @@ +/* Copied from http://bakefile.sourceforge.net/, which appears + licensed under the GNU GPL. */ + + +/*************************************************************************** + Basic headers and text: + ***************************************************************************/ + +body +{ + font-family: "Nimbus Sans L", sans-serif; + background: white; + margin: 2em 1em 2em 1em; +} + +h1, h2, h3, h4 +{ + color: #005aa0; +} + +h1 /* title */ +{ + font-size: 200%; +} + +h2 /* chapters, appendices, subtitle */ +{ + font-size: 180%; +} + +/* Extra space between chapters, appendices. */ +div.chapter > div.titlepage h2, div.appendix > div.titlepage h2 +{ + margin-top: 1.5em; +} + +div.section > div.titlepage h2 /* sections */ +{ + font-size: 150%; + margin-top: 1.5em; +} + +h3 /* subsections */ +{ + font-size: 125%; +} + +div.simplesect h2 +{ + font-size: 110%; +} + +div.appendix h3 +{ + font-size: 150%; + margin-top: 1.5em; +} + +div.refnamediv h2, div.refsynopsisdiv h2, div.refsection h2 /* refentry parts */ +{ + margin-top: 1.4em; + font-size: 125%; +} + +div.refsection h3 +{ + font-size: 110%; +} + + +/*************************************************************************** + Examples: + ***************************************************************************/ + +div.example +{ + border: 1px solid #b0b0b0; + padding: 6px 6px; + margin-left: 1.5em; + margin-right: 1.5em; + background: #f4f4f8; + border-radius: 0.4em; + box-shadow: 0.4em 0.4em 0.5em #e0e0e0; +} + +div.example p.title +{ + margin-top: 0em; +} + +div.example pre +{ + box-shadow: none; +} + + +/*************************************************************************** + Screen dumps: + ***************************************************************************/ + +pre.screen, pre.programlisting +{ + border: 1px solid #b0b0b0; + padding: 3px 3px; + margin-left: 1.5em; + margin-right: 1.5em; + color: #600000; + background: #f4f4f8; + font-family: monospace; + border-radius: 0.4em; + box-shadow: 0.4em 0.4em 0.5em #e0e0e0; +} + +div.example pre.programlisting +{ + border: 0px; + padding: 0 0; + margin: 0 0 0 0; +} + + +/*************************************************************************** + Notes, warnings etc: + ***************************************************************************/ + +.note, .warning +{ + border: 1px solid #b0b0b0; + padding: 3px 3px; + margin-left: 1.5em; + margin-right: 1.5em; + margin-bottom: 1em; + padding: 0.3em 0.3em 0.3em 0.3em; + background: #fffff5; + border-radius: 0.4em; + box-shadow: 0.4em 0.4em 0.5em #e0e0e0; +} + +div.note, div.warning +{ + font-style: italic; +} + +div.note h3, div.warning h3 +{ + color: red; + font-size: 100%; + padding-right: 0.5em; + display: inline; +} + +div.note p, div.warning p +{ + margin-bottom: 0em; +} + +div.note h3 + p, div.warning h3 + p +{ + display: inline; +} + +div.note h3 +{ + color: blue; + font-size: 100%; +} + +div.navfooter * +{ + font-size: 90%; +} + + +/*************************************************************************** + Links colors and highlighting: + ***************************************************************************/ + +a { text-decoration: none; } +a:hover { text-decoration: underline; } +a:link { color: #0048b3; } +a:visited { color: #002a6a; } + + +/*************************************************************************** + Table of contents: + ***************************************************************************/ + +div.toc +{ + font-size: 90%; +} + +div.toc dl +{ + margin-top: 0em; + margin-bottom: 0em; +} + + +/*************************************************************************** + Special elements: + ***************************************************************************/ + +tt, code +{ + color: #400000; +} + +.term +{ + font-weight: bold; + +} + +div.variablelist dd p, div.glosslist dd p +{ + margin-top: 0em; +} + +div.variablelist dd, div.glosslist dd +{ + margin-left: 1.5em; +} + +div.glosslist dt +{ + font-style: italic; +} + +.varname +{ + color: #400000; +} + +span.command strong +{ + font-weight: normal; + color: #400000; +} + +div.calloutlist table +{ + box-shadow: none; +} + +table +{ + border-collapse: collapse; + box-shadow: 0.4em 0.4em 0.5em #e0e0e0; +} + +table.simplelist +{ + text-align: left; + color: #005aa0; + border: 0; + padding: 5px; + background: #fffff5; + font-weight: normal; + font-style: italic; + box-shadow: none; + margin-bottom: 1em; +} + +div.affiliation +{ + font-style: italic; +} \ No newline at end of file diff --git a/nixos/doc/manual/troubleshooting.xml b/nixos/doc/manual/troubleshooting.xml new file mode 100644 index 00000000000..c6e0a3a7888 --- /dev/null +++ b/nixos/doc/manual/troubleshooting.xml @@ -0,0 +1,198 @@ + + +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/ + + + + +
+ + + diff --git a/nixos/doc/manual/userconfiguration.xml b/nixos/doc/manual/userconfiguration.xml new file mode 100644 index 00000000000..7c6540caf3a --- /dev/null +++ b/nixos/doc/manual/userconfiguration.xml @@ -0,0 +1,80 @@ + + +Configuration in home directory + + + + +
+Compiz Fusion + + Compiz Fusion is just a set of plugins for Compiz. Your best interest is to have + them found both by Compiz and by Compiz Configuration Settings (also in Compiz Fusion + distribution). By default they look in Compiz installation path and in home directory. + You do not need to track /nix/store manually - everything is already in + /run/current-system/sw/share. + + + $HOME/.compiz/plugins + should contain plugins you want to load. All the installed + plugins are available in + /run/current-system/sw/share/compiz-plugins/compiz/, + so you can use symlinks to this directory. + + + $HOME/.compiz/metadata + should contain metadata (definition of configuration options) for plugins + you want to load. All the installed metadata is available in + /run/current-system/sw/share/compiz/, + so you can use symlinks to this directory. + + + + Probably a way to load GConf configuration backend by default + should be found, but if you run Compiz with + GConf configuration (default for X server job + for now), you have to link + /run/current-system/sw/share/compizconfig/backends/ + into $HOME/.compizconfig/backends directory. + + + + + To summarize the above, these are the commands you have to execute + ln -s /run/current-system/sw/share/compiz/ $HOME/.compiz/metadata + ln -s /run/current-system/sw/share/compiz-plugins/compiz/ $HOME/.compiz/plugins + ln -s /run/current-system/sw/share/compizconfig/backends/ $HOME/.compizconfig/backends + + Now you can launch ccsm and configure everything. You should select + GConf as a backend in the preferences menu of ccsm + +
+ +
+Pidgin-LaTeX + + To have pidgin-latex plugin working after installation, you need the following: + + + Symlink /run/current-system/sw/share/pidgin-latex/pidgin-latex.so + to $HOME/.purple/plugins/pidgin-latex.so + + + Enable smileys. If you do not want to, you can create + $HOME/.purple/smileys/empty/theme with the following contents: + + Name=Empty + Description=No predefined smileys + Author=Nobody + + Enabling this theme will enable smileys, but define none. + + + Enable the plugin. + + + +
+ + -- cgit 1.4.1