diff --git a/.travis.yml b/.travis.yml new file mode 100644 index 00000000000..d34a7831d65 --- /dev/null +++ b/.travis.yml @@ -0,0 +1,3 @@ +language: python +python: "3.4" +script: ./maintainers/scripts/travis-nox-review-pr.sh diff --git a/default.nix b/default.nix index c1b9bfd39f9..e0df520721c 100644 --- a/default.nix +++ b/default.nix @@ -1,6 +1,6 @@ -if ! builtins ? nixVersion || builtins.compareVersions "1.6" builtins.nixVersion == 1 then +if ! builtins ? nixVersion || builtins.compareVersions "1.7" builtins.nixVersion == 1 then - abort "This version of Nixpkgs requires Nix >= 1.6, please upgrade!" + abort "This version of Nixpkgs requires Nix >= 1.7, please upgrade!" else diff --git a/doc/language-support.xml b/doc/language-support.xml index f5e89df57fc..5e49121e695 100644 --- a/doc/language-support.xml +++ b/doc/language-support.xml @@ -233,6 +233,22 @@ twisted = buildPythonPackage { +
Ruby + For example, to package yajl-ruby package, use gem-nix: + + + $ nix-env -i gem-nix + $ gem-nix --no-user-install --nix-file=pkgs/development/interpreters/ruby/generated.nix yajl-ruby + $ nix-build -A rubyLibs.yajl-ruby + +
+ + +
Go + To extract dependency information from a Go package in automated way use go2nix. +
+ +
Java Ant-based Java packages are typically built from source as follows: @@ -314,6 +330,90 @@ Runtime) instead of the OpenJRE.
+
Lua + + + Lua packages are built by the buildLuaPackage function. This function is + implemented + in + pkgs/development/lua-modules/generic/default.nix + and works similarly to buildPerlPackage. (See + for details.) + + + + Lua packages are defined + in pkgs/top-level/lua-packages.nix. + Most of them are simple. For example: + + +fileSystem = buildLuaPackage { + name = "filesystem-1.6.2"; + src = fetchurl { + url = "https://github.com/keplerproject/luafilesystem/archive/v1_6_2.tar.gz"; + sha256 = "1n8qdwa20ypbrny99vhkmx8q04zd2jjycdb5196xdhgvqzk10abz"; + }; + meta = { + homepage = "https://github.com/keplerproject/luafilesystem"; + hydraPlatforms = stdenv.lib.platforms.linux; + maintainers = with maintainers; [ flosse ]; + }; +}; + + + + + Though, more complicated package should be placed in a seperate file in + pkgs/development/lua-modules. + + + Lua packages accept additional parameter disabled, which defines + the condition of disabling package from luaPackages. For example, if package has + disabled assigned to lua.luaversion != "5.1", + it will not be included in any luaPackages except lua51Packages, making it + only be built for lua 5.1. + + +
+ +
Coq + + Coq libraries should be installed in + $(out)/lib/coq/${coq.coq-version}/user-contrib/. + Such directories are automatically added to the + $COQPATH environment variable by the hook defined + in the Coq derivation. + + + Some libraries require OCaml and sometimes also Camlp5. The exact + versions that were used to build Coq are saved in the + coq.ocaml and coq.camlp5 + attributes. + + + Here is a simple package example. It is a pure Coq library, thus it + only depends on Coq. Its makefile has been + generated using coq_makefile so we only have to + set the $COQLIB variable at install time. + + +{stdenv, fetchurl, coq}: +stdenv.mkDerivation { + src = fetchurl { + url = http://coq.inria.fr/pylons/contribs/files/Karatsuba/v8.4/Karatsuba.tar.gz; + sha256 = "0ymfpv4v49k4fm63nq6gcl1hbnnxrvjjp7yzc4973n49b853c5b1"; + }; + + name = "coq-karatsuba"; + + buildInputs = [ coq ]; + + installFlags = "COQLIB=$(out)/lib/coq/${coq.coq-version}/"; +} + +
+ + + diff --git a/nixos/doc/manual/administration/store-corruption.xml b/nixos/doc/manual/administration/store-corruption.xml new file mode 100644 index 00000000000..0160cb45358 --- /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 00000000000..351fb188331 --- /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 00000000000..05e2c1a9b29 --- /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 64372f3bbf1..00000000000 --- 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/abstractions.xml b/nixos/doc/manual/configuration/abstractions.xml new file mode 100644 index 00000000000..cbd54bca62f --- /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 00000000000..26a572ba1fb --- /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 00000000000..e237e20c4ff --- /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 00000000000..c1789fcbc04 --- /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 00000000000..2a58ff25941 --- /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 00000000000..87847f8451e --- /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 00000000000..8fde0dc7e61 --- /dev/null +++ b/nixos/doc/manual/configuration/configuration.xml @@ -0,0 +1,32 @@ + + +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 00000000000..6ee7a95dc6f --- /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 00000000000..6de38b452e2 --- /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 00000000000..d1b324af3f1 --- /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 00000000000..87406c28c2f --- /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 00000000000..053501b1736 --- /dev/null +++ b/nixos/doc/manual/configuration/ipv4-config.xml @@ -0,0 +1,44 @@ +
+ +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.ip4 = [ { address = "192.168.1.2"; prefixLength = 24; } ]; + + +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 00000000000..592bf20e545 --- /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 00000000000..8fe2f5255df --- /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/luks-file-systems.xml b/nixos/doc/manual/configuration/luks-file-systems.xml new file mode 100644 index 00000000000..45475dbcd44 --- /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/modularity.xml b/nixos/doc/manual/configuration/modularity.xml new file mode 100644 index 00000000000..d95091bd162 --- /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 00000000000..e65060021b4 --- /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 00000000000..5f08bc1f127 --- /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 00000000000..73c1722da02 --- /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 00000000000..7c928baaf89 --- /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 00000000000..9bb5e35e16b --- /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 00000000000..40362fbbb23 --- /dev/null +++ b/nixos/doc/manual/configuration/user-mgmt.xml @@ -0,0 +1,89 @@ + + +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 = + { isNormalUser = true; + home = "/home/alice"; + description = "Alice Foobar"; + extraGroups = [ "wheel" "networkmanager" ]; + openssh.authorizedKeys.keys = [ "ssh-dss AAAAB3Nza... alice@foobar" ]; + }; + + +Note that alice is a member of the +wheel and networkmanager groups, +which allows her to use sudo to execute commands as +root and to configure the network, respectively. +Also note the SSH public key that allows remote logins with the +corresponding private key. Users created in this way do not have a +password by default, so they cannot log in via mechanisms that require +a password. However, you can use the passwd program +to set a password, which is retained across invocations of +nixos-rebuild. + +If you set 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. + +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 00000000000..373a9168cc8 --- /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 00000000000..95e66f0c70c --- /dev/null +++ b/nixos/doc/manual/configuration/x-windows.xml @@ -0,0 +1,113 @@ + + +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: + +hardware.opengl.driSupport32Bit = true; + + + + + +AMD Graphics Cards + +AMD provides a proprietary driver for its graphics cards that +has better 3D performance than the X.org drivers. It is not enabled +by default because it’s not free software. You can enable it as follows: + +services.xserver.videoDrivers = [ "ati_unfree" ]; + +You will need to reboot after enabling this driver to prevent a clash +with other kernel modules. + +On 64-bit systems, if you want full acceleration for 32-bit +programs such as Wine, you should also set the following: + +hardware.opengl.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 2530d519521..00000000000 --- 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/default.nix b/nixos/doc/manual/default.nix index f5cc33919b8..68248081af6 100644 --- a/nixos/doc/manual/default.nix +++ b/nixos/doc/manual/default.nix @@ -6,12 +6,21 @@ with pkgs.lib; let # Remove invisible and internal options. - options' = filter (opt: opt.visible && !opt.internal) (optionAttrSetToDocList options); + optionsList = filter (opt: opt.visible && !opt.internal) (optionAttrSetToDocList options); + + # Replace functions by the string + substFunction = x: + if builtins.isAttrs x then mapAttrs (name: substFunction) x + else if builtins.isList x then map substFunction x + else if builtins.isFunction x then "" + else x; # Clean up declaration sites to not refer to the NixOS source tree. - options'' = flip map options' (opt: opt // { + optionsList' = flip map optionsList (opt: opt // { declarations = map (fn: stripPrefix fn) opt.declarations; - }); + } + // optionalAttrs (opt ? example) { example = substFunction opt.example; } + // optionalAttrs (opt ? default) { default = substFunction opt.default; }); prefix = toString ../../..; @@ -21,10 +30,35 @@ let else fn; - optionsXML = builtins.toFile "options.xml" (builtins.unsafeDiscardStringContext (builtins.toXML options'')); + # Convert the list of options into an XML file and a JSON file. The builtin + # unsafeDiscardStringContext is used to prevent the realisation of the store + # paths which are used in options definitions. + optionsXML = builtins.toFile "options.xml" (builtins.unsafeDiscardStringContext (builtins.toXML optionsList')); + optionsJSON = builtins.toFile "options.json" (builtins.unsafeDiscardStringContext (builtins.toJSON optionsList')); + + # Tools-friendly version of the list of NixOS options. + options' = stdenv.mkDerivation { + name = "options"; + + buildCommand = '' + # Export list of options in different format. + dst=$out/share/doc/nixos + mkdir -p $dst + + cp ${optionsJSON} $dst/options.json + cp ${optionsXML} $dst/options.xml + + mkdir -p $out/nix-support + echo "file json $dst/options.json" >> $out/nix-support/hydra-build-products + echo "file xml $dst/options.xml" >> $out/nix-support/hydra-build-products + ''; # */ + + meta.description = "List of NixOS options in various formats."; + }; optionsDocBook = runCommand "options-db.xml" {} '' - if grep /nixpkgs/nixos/modules ${optionsXML}; then + optionsXML=${options'}/share/doc/nixos/options.xml + if grep /nixpkgs/nixos/modules $optionsXML; then echo "The manual appears to depend on the location of Nixpkgs, which is bad" echo "since this prevents sharing via the NixOS channel. This is typically" echo "caused by an option default that refers to a relative path (see above" @@ -33,7 +67,7 @@ let fi ${libxslt}/bin/xsltproc \ --stringparam revision '${revision}' \ - -o $out ${./options-to-docbook.xsl} ${optionsXML} + -o $out ${./options-to-docbook.xsl} $optionsXML ''; sources = sourceFilesBySuffices ./. [".xml"]; @@ -41,12 +75,17 @@ let copySources = '' cp -prd $sources/* . # */ + chmod -R u+w . + cp ${../../modules/services/databases/postgresql.xml} configuration/postgresql.xml ln -s ${optionsDocBook} options-db.xml echo "${version}" > version ''; in rec { + # Tools-friendly version of the list of NixOS options. + options = options'; + # Generate the NixOS manual. manual = stdenv.mkDerivation { name = "nixos-manual"; @@ -74,7 +113,7 @@ in rec { --param toc.section.depth 3 \ --stringparam admon.style "" \ --stringparam callout.graphics.extension .gif \ - --param chunk.section.depth 1 \ + --param chunk.section.depth 0 \ --param chunk.first.sections 1 \ --param use.id.as.filename 1 \ --stringparam generate.toc "book toc chapter toc appendix toc" \ @@ -88,7 +127,7 @@ in rec { mkdir -p $out/nix-support echo "nix-build out $out" >> $out/nix-support/hydra-build-products - echo "doc manual $dst manual.html" >> $out/nix-support/hydra-build-products + echo "doc manual $dst" >> $out/nix-support/hydra-build-products ''; # */ meta.description = "The NixOS manual in HTML format"; diff --git a/nixos/doc/manual/development.xml b/nixos/doc/manual/development.xml deleted file mode 100644 index 2f0c2a7aa8d..00000000000 --- a/nixos/doc/manual/development.xml +++ /dev/null @@ -1,1119 +0,0 @@ - - -Development - -This chapter describes how you can modify and extend -NixOS. - - - - -
- -Getting the sources - -By default, NixOS’s nixos-rebuild command -uses the NixOS and Nixpkgs sources provided by the -nixos-unstable channel (kept in -/nix/var/nix/profiles/per-user/root/channels/nixos). -To modify NixOS, however, you should check out the latest sources from -Git. This is done using the following command: - - -$ nixos-checkout /my/sources - - -or - - -$ mkdir -p /my/sources -$ cd /my/sources -$ nix-env -i git -$ git clone git://github.com/NixOS/nixpkgs.git - - -This will check out the latest NixOS sources to -/my/sources/nixpkgs/nixos -and the Nixpkgs sources to -/my/sources/nixpkgs. -(The NixOS source tree lives in a subdirectory of the Nixpkgs -repository.) - -It’s often inconvenient to develop directly on the master -branch, since if somebody has just committed (say) a change to GCC, -then the binary cache may not have caught up yet and you’ll have to -rebuild everything from source. So you may want to create a local -branch based on your current NixOS version: - - -$ nixos-version -14.04.273.ea1952b (Baboon) - -$ git checkout -b local ea1952b - - -Or, to base your local branch on the latest version available in the -NixOS channel: - - -$ curl -sI http://nixos.org/channels/nixos-unstable/ | grep Location -Location: http://releases.nixos.org/nixos/unstable/nixos-14.10pre43986.acaf4a6/ - -$ git checkout -b local acaf4a6 - - -You can then use git rebase to sync your local -branch with the upstream branch, and use git -cherry-pick to copy commits from your local branch to the -upstream branch. - -If you want to rebuild your system using your (modified) -sources, you need to tell nixos-rebuild about them -using the flag: - - -$ nixos-rebuild switch -I nixpkgs=/my/sources/nixpkgs - - - - -If you want nix-env to use the expressions in -/my/sources, use nix-env -f -/my/sources/nixpkgs, or change -the default by adding a symlink in -~/.nix-defexpr: - - -$ ln -s /my/sources/nixpkgs ~/.nix-defexpr/nixpkgs - - -You may want to delete the symlink -~/.nix-defexpr/channels_root to prevent root’s -NixOS channel from clashing with your own tree. - - - -
- - - - -
- -Writing NixOS modules - -NixOS has a modular system for declarative configuration. This -system combines multiple modules to produce the -full system configuration. One of the modules that constitute the -configuration is /etc/nixos/configuration.nix. -Most of the others live in the nixos/modules -subdirectory of the Nixpkgs tree. - -Each NixOS module is a file that handles one logical aspect of -the configuration, such as a specific kind of hardware, a service, or -network settings. A module configuration does not have to handle -everything from scratch; it can use the functionality provided by -other modules for its implementation. Thus a module can -declare options that can be used by other -modules, and conversely can define options -provided by other modules in its own implementation. For example, the -module pam.nix -declares the option that allows -other modules (e.g. sshd.nix) -to define PAM services; and it defines the option - (declared by etc.nix) -to cause files to be created in -/etc/pam.d. - -In , we saw the following structure -of NixOS modules: - - -{ config, pkgs, ... }: - -{ option definitions -} - - -This is actually an abbreviated form of module -that only defines options, but does not declare any. The structure of -full NixOS modules is shown in . - -Structure of NixOS modules - -{ config, pkgs, ... }: - -{ - imports = - [ paths of other modules - ]; - - options = { - option declarations - }; - - config = { - option definitions - }; -} - - -The meaning of each part is as follows. - - - - This line makes the current Nix expression a function. The - variable pkgs contains Nixpkgs, while - config contains the full system configuration. - This line can be omitted if there is no reference to - pkgs and config inside the - module. - - - - This list enumerates the paths to other NixOS modules that - should be included in the evaluation of the system configuration. - A default set of modules is defined in the file - modules/module-list.nix. These don't need to - be added in the import list. - - - - The attribute options is a nested set of - option declarations (described below). - - - - The attribute config is a nested set of - option definitions (also described - below). - - - - - - shows a module that handles -the regular update of the “locate” database, an index of all files in -the file system. This module declares two options that can be defined -by other modules (typically the user’s -configuration.nix): - (whether the database should -be updated) and (when the -update should be done). It implements its functionality by defining -two options declared by other modules: - (the set of all systemd services) -and (the list of -commands to be executed periodically by cron). - -NixOS module for the “locate” service - -{ config, lib, pkgs, ... }: - -with lib; - -let locatedb = "/var/cache/locatedb"; in - -{ - options = { - - services.locate = { - - enable = mkOption { - type = types.bool; - default = false; - description = '' - If enabled, NixOS will periodically update the database of - files used by the locate command. - ''; - }; - - period = mkOption { - type = types.str; - default = "15 02 * * *"; - description = '' - This option defines (in the format used by cron) when the - locate database is updated. The default is to update at - 02:15 at night every day. - ''; - }; - - }; - - }; - - config = { - - systemd.services.update-locatedb = - { description = "Update Locate Database"; - path = [ pkgs.su ]; - script = - '' - mkdir -m 0755 -p $(dirname ${locatedb}) - exec updatedb --localuser=nobody --output=${locatedb} --prunepaths='/tmp /var/tmp /media /run' - ''; - }; - - services.cron.systemCronJobs = optional config.services.locate.enable - "${config.services.locate.period} root ${config.systemd.package}/bin/systemctl start update-locatedb.service"; - - }; -} - - -
Option declarations - -An option declaration specifies the name, type and description -of a NixOS configuration option. It is illegal to define an option -that hasn’t been declared in any module. A option declaration -generally looks like this: - - -options = { - name = mkOption { - type = type specification; - default = default value; - example = example value; - description = "Description for use in the NixOS manual."; - }; -}; - - - - -The function mkOption accepts the following arguments. - - - - - type - - The type of the option (see below). It may be omitted, - but that’s not advisable since it may lead to errors that are - hard to diagnose. - - - - - default - - The default value used if no value is defined by any - module. A default is not required; in that case, if the option - value is ever used, an error will be thrown. - - - - - example - - An example value that will be shown in the NixOS manual. - - - - - description - - A textual description of the option, in DocBook format, - that will be included in the NixOS manual. - - - - - - - -Here is a non-exhaustive list of option types: - - - - - types.bool - - A Boolean. - - - - - types.int - - An integer. - - - - - types.str - - A string. - - - - - types.lines - - A string. If there are multiple definitions, they are - concatenated, with newline characters in between. - - - - - types.path - - A path, defined as anything that, when coerced to a - string, starts with a slash. This includes derivations. - - - - - types.listOf t - - A list of elements of type t - (e.g., types.listOf types.str is a list of - strings). Multiple definitions are concatenated together. - - - - - types.attrsOf t - - A set of elements of type t - (e.g., types.attrsOf types.int is a set of - name/value pairs, the values being integers). - - - - - types.nullOr t - - Either the value null or something of - type t. - - - - - -You can also create new types using the function -mkOptionType. See -lib/types.nix in Nixpkgs for details. - -
- - -
Option definitions - -Option definitions are generally straight-forward bindings of values to option names, like - - -config = { - services.httpd.enable = true; -}; - - -However, sometimes you need to wrap an option definition or set of -option definitions in a property to achieve -certain effects: - -Delaying conditionals - -If a set of option definitions is conditional on the value of -another option, you may need to use mkIf. -Consider, for instance: - - -config = if config.services.httpd.enable then { - environment.systemPackages = [ ... ]; - ... -} else {}; - - -This definition will cause Nix to fail with an “infinite recursion” -error. Why? Because the value of - depends on the value -being constructed here. After all, you could also write the clearly -circular and contradictory: - -config = if config.services.httpd.enable then { - services.httpd.enable = false; -} else { - services.httpd.enable = true; -}; - - -The solution is to write: - - -config = mkIf config.services.httpd.enable { - environment.systemPackages = [ ... ]; - ... -}; - - -The special function mkIf causes the evaluation of -the conditional to be “pushed down” into the individual definitions, -as if you had written: - - -config = { - environment.systemPackages = if config.services.httpd.enable then [ ... ] else []; - ... -}; - - - - - - -Setting priorities - -A module can override the definitions of an option in other -modules by setting a priority. All option -definitions that do not have the lowest priority value are discarded. -By default, option definitions have priority 1000. You can specify an -explicit priority by using mkOverride, e.g. - - -services.openssh.enable = mkOverride 10 false; - - -This definition causes all other definitions with priorities above 10 -to be discarded. The function mkForce is -equal to mkOverride 50. - - - -Merging configurations - -In conjunction with mkIf, it is sometimes -useful for a module to return multiple sets of option definitions, to -be merged together as if they were declared in separate modules. This -can be done using mkMerge: - - -config = mkMerge - [ # Unconditional stuff. - { environment.systemPackages = [ ... ]; - } - # Conditional stuff. - (mkIf config.services.bla.enable { - environment.systemPackages = [ ... ]; - }) - ]; - - - - - - -
- - -
Important options - -NixOS has many options, but some are of particular importance to -module writers. - - - - - - - This set defines files in /etc. A - typical use is: - -environment.etc."os-release".text = - '' - NAME=NixOS - ... - ''; - - which causes a file named /etc/os-release - to be created with the given contents. - - - - - - - A set of shell script fragments that must be executed - whenever the configuration is activated (i.e., at boot time, or - after running nixos-rebuild switch). For instance, - -system.activationScripts.media = - '' - mkdir -m 0755 -p /media - ''; - - causes the directory /media to be created. - Activation scripts must be idempotent. They should not start - background processes such as daemons; use - for that. - - - - - - - This is the set of systemd services. Example: - -systemd.services.dhcpcd = - { description = "DHCP Client"; - wantedBy = [ "multi-user.target" ]; - after = [ "systemd-udev-settle.service" ]; - path = [ dhcpcd pkgs.nettools pkgs.openresolv ]; - serviceConfig = - { Type = "forking"; - PIDFile = "/run/dhcpcd.pid"; - ExecStart = "${dhcpcd}/sbin/dhcpcd --config ${dhcpcdConf}"; - Restart = "always"; - }; - }; - - which creates the systemd unit - dhcpcd.service. The option - determined which other units pull this - one in; multi-user.target is the default - target of the system, so dhcpcd.service will - always be started. The option - provides the main - command for the service; it’s also possible to provide pre-start - actions, stop scripts, and so on. - - - - - - - - If your service requires special UIDs or GIDs, you can - define them with these options. See for details. - - - - - -
- - -
- - - - -
- -Building specific parts of NixOS - -With the command nix-build, you can build -specific parts of your NixOS configuration. This is done as follows: - - -$ cd /path/to/nixpkgs/nixos -$ nix-build -A config.option - -where option is a NixOS option with type -“derivation” (i.e. something that can be built). Attributes of -interest include: - - - - - system.build.toplevel - - The top-level option that builds the entire NixOS system. - Everything else in your configuration is indirectly pulled in by - this option. This is what nixos-rebuild - builds and what /run/current-system points - to afterwards. - - A shortcut to build this is: - - -$ nix-build -A system - - - - - - system.build.manual.manual - The NixOS manual. - - - - system.build.etc - A tree of symlinks that form the static parts of - /etc. - - - - system.build.initialRamdisk - system.build.kernel - - The initial ramdisk and kernel of the system. This allows - a quick way to test whether the kernel and the initial ramdisk - boot correctly, by using QEMU’s and - options: - - -$ nix-build -A config.system.build.initialRamdisk -o initrd -$ nix-build -A config.system.build.kernel -o kernel -$ qemu-system-x86_64 -kernel ./kernel/bzImage -initrd ./initrd/initrd -hda /dev/null - - - - - - - - system.build.nixos-rebuild - system.build.nixos-install - system.build.nixos-generate-config - - These build the corresponding NixOS commands. - - - - - systemd.units.unit-name.unit - - This builds the unit with the specified name. Note that - since unit names contain dots - (e.g. httpd.service), you need to put them - between quotes, like this: - - -$ nix-build -A 'config.systemd.units."httpd.service".unit' - - - You can also test individual units, without rebuilding the whole - system, by putting them in - /run/systemd/system: - - -$ cp $(nix-build -A 'config.systemd.units."httpd.service".unit')/httpd.service \ - /run/systemd/system/tmp-httpd.service -$ systemctl daemon-reload -$ systemctl start tmp-httpd.service - - - Note that the unit must not have the same name as any unit in - /etc/systemd/system since those take - precedence over /run/systemd/system. - That’s why the unit is installed as - tmp-httpd.service here. - - - - - - - -
- - - - -
- -Building your own NixOS CD - -Building a NixOS CD is as easy as configuring your own computer. The -idea is to use another module which will replace -your configuration.nix to configure the system that -would be installed on the CD. - -Default CD/DVD configurations are available -inside nixos/modules/installer/cd-dvd. To build them -you have to set NIXOS_CONFIG before -running nix-build to build the ISO. - - -$ nix-build -A config.system.build.isoImage -I nixos-config=modules/installer/cd-dvd/installation-cd-minimal.nix - - - -Before burning your CD/DVD, you can check the content of the image by mounting anywhere like -suggested by the following command: - - -$ mount -o loop -t iso9660 ./result/iso/cd.iso /mnt/iso - - - -
- - - - -
- -Testing the installer - -Building, burning, and booting from an installation CD is rather -tedious, so here is a quick way to see if the installer works -properly: - - -$ nix-build -A config.system.build.nixos-install -$ mount -t tmpfs none /mnt -$ ./result/bin/nixos-install - -To start a login shell in the new NixOS installation in -/mnt: - - -$ ./result/bin/nixos-install --chroot - - - - -
- - - - - -
- -NixOS tests - -When you add some feature to NixOS, you should write a test for -it. NixOS tests are kept in the directory nixos/tests, -and are executed (using Nix) by a testing framework that automatically -starts one or more virtual machines containing the NixOS system(s) -required for the test. - -Writing tests - -A NixOS test is a Nix expression that has the following structure: - - -import ./make-test.nix { - - # Either the configuration of a single machine: - machine = - { config, pkgs, ... }: - { configuration… - }; - - # Or a set of machines: - nodes = - { machine1 = - { config, pkgs, ... }: { … }; - machine2 = - { config, pkgs, ... }: { … }; - … - }; - - testScript = - '' - Perl code… - ''; -} - - -The attribute testScript is a bit of Perl code that -executes the test (described below). During the test, it will start -one or more virtual machines, the configuration of which is described -by the attribute machine (if you need only one -machine in your test) or by the attribute nodes (if -you need multiple machines). For instance, login.nix -only needs a single machine to test whether users can log in on the -virtual console, whether device ownership is correctly maintained when -switching between consoles, and so on. On the other hand, nfs.nix, -which tests NFS client and server functionality in the Linux kernel -(including whether locks are maintained across server crashes), -requires three machines: a server and two clients. - -There are a few special NixOS configuration options for test -VMs: - - - - - - - - The memory of the VM in - megabytes. - - - - - The virtual networks to which the VM is - connected. See nat.nix - for an example. - - - - - By default, the Nix store in the VM is not - writable. If you enable this option, a writable union file system - is mounted on top of the Nix store to make it appear - writable. This is necessary for tests that run Nix operations that - modify the store. - - - - -For more options, see the module qemu-vm.nix. - -The test script is a sequence of Perl statements that perform -various actions, such as starting VMs, executing commands in the VMs, -and so on. Each virtual machine is represented as an object stored in -the variable $name, -where name is the identifier of the machine -(which is just machine if you didn’t specify -multiple machines using the nodes attribute). For -instance, the following starts the machine, waits until it has -finished booting, then executes a command and checks that the output -is more-or-less correct: - - -$machine->start; -$machine->waitForUnit("default.target"); -$machine->succeed("uname") =~ /Linux/; - - -The first line is actually unnecessary; machines are implicitly -started when you first execute an action on them (such as -waitForUnit or succeed). If you -have multiple machines, you can speed up the test by starting them in -parallel: - - -startAll; - - - - -The following methods are available on machine objects: - - - - - start - Start the virtual machine. This method is - asynchronous — it does not wait for the machine to finish - booting. - - - - shutdown - Shut down the machine, waiting for the VM to - exit. - - - - crash - Simulate a sudden power failure, by telling the VM - to exit immediately. - - - - block - Simulate unplugging the Ethernet cable that - connects the machine to the other machines. - - - - unblock - Undo the effect of - block. - - - - screenshot - Take a picture of the display of the virtual - machine, in PNG format. The screenshot is linked from the HTML - log. - - - - sendMonitorCommand - Send a command to the QEMU monitor. This is rarely - used, but allows doing stuff such as attaching virtual USB disks - to a running machine. - - - - sendKeys - Simulate pressing keys on the virtual keyboard, - e.g., sendKeys("ctrl-alt-delete"). - - - - sendChars - Simulate typing a sequence of characters on the - virtual keyboard, e.g., sendKeys("foobar\n") - will type the string foobar followed by the - Enter key. - - - - execute - Execute a shell command, returning a list - (status, - stdout). - - - - succeed - Execute a shell command, raising an exception if - the exit status is not zero, otherwise returning the standard - output. - - - - fail - Like succeed, but raising - an exception if the command returns a zero status. - - - - waitUntilSucceeds - Repeat a shell command with 1-second intervals - until it succeeds. - - - - waitUntilFails - Repeat a shell command with 1-second intervals - until it fails. - - - - waitForUnit - Wait until the specified systemd unit has reached - the “active” state. - - - - waitForFile - Wait until the specified file - exists. - - - - waitForOpenPort - Wait until a process is listening on the given TCP - port (on localhost, at least). - - - - waitForClosedPort - Wait until nobody is listening on the given TCP - port. - - - - waitForX - Wait until the X11 server is accepting - connections. - - - - waitForWindow - Wait until an X11 window has appeared whose name - matches the given regular expression, e.g., - waitForWindow(qr/Terminal/). - - - - - - - - - -Running tests - -You can run tests using nix-build. For -example, to run the test login.nix, -you just do: - - -$ nix-build '<nixpkgs/nixos/tests/login.nix>' - - -or, if you don’t want to rely on NIX_PATH: - - -$ cd /my/nixpkgs/nixos/tests -$ nix-build login.nix -… -running the VM test script -machine: QEMU running (pid 8841) -… -6 out of 6 tests succeeded - - -After building/downloading all required dependencies, this will -perform a build that starts a QEMU/KVM virtual machine containing a -NixOS system. The virtual machine mounts the Nix store of the host; -this makes VM creation very fast, as no disk image needs to be -created. Afterwards, you can view a pretty-printed log of the test: - - -$ firefox result/log.html - - - - -It is also possible to run the test environment interactively, -allowing you to experiment with the VMs. For example: - - -$ nix-build login.nix -A driver -$ ./result/bin/nixos-run-vms - - -The script nixos-run-vms starts the virtual -machines defined by test. The root file system of the VMs is created -on the fly and kept across VM restarts in -./hostname.qcow2. - -Finally, the test itself can be run interactively. This is -particularly useful when developing or debugging a test: - - -$ nix-build tests/ -A nfs.driver -$ ./result/bin/nixos-test-driver -starting VDE switch for network 1 -> - - -You can then take any Perl statement, e.g. - - -> startAll -> $machine->succeed("touch /tmp/foo") - - -The function testScript executes the entire test -script and drops you back into the test driver command line upon its -completion. This allows you to inspect the state of the VMs after the -test (e.g. to debug the test script). - - - -
- - - diff --git a/nixos/doc/manual/development/building-nixos.xml b/nixos/doc/manual/development/building-nixos.xml new file mode 100644 index 00000000000..21c5bfe6a5b --- /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 00000000000..cb8dee039c8 --- /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 00000000000..747159c4427 --- /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 00000000000..a98da993330 --- /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 00000000000..6d93dc5c009 --- /dev/null +++ b/nixos/doc/manual/development/option-declarations.xml @@ -0,0 +1,141 @@ +
+ +Option Declarations + +An option declaration specifies the name, type and description +of a NixOS configuration option. It is illegal to define an option +that hasn’t been declared in any module. A option declaration +generally looks like this: + + +options = { + name = mkOption { + type = type specification; + default = default value; + example = example value; + description = "Description for use in the NixOS manual."; + }; +}; + + + + +The function mkOption accepts the following arguments. + + + + + type + + The type of the option (see below). It may be omitted, + but that’s not advisable since it may lead to errors that are + hard to diagnose. + + + + + default + + The default value used if no value is defined by any + module. A default is not required; in that case, if the option + value is ever used, an error will be thrown. + + + + + example + + An example value that will be shown in the NixOS manual. + + + + + description + + A textual description of the option, in DocBook format, + that will be included in the NixOS manual. + + + + + + + +Here is a non-exhaustive list of option types: + + + + + types.bool + + A Boolean. + + + + + types.int + + An integer. + + + + + types.str + + A string. + + + + + types.lines + + A string. If there are multiple definitions, they are + concatenated, with newline characters in between. + + + + + types.path + + A path, defined as anything that, when coerced to a + string, starts with a slash. This includes derivations. + + + + + types.listOf t + + A list of elements of type t + (e.g., types.listOf types.str is a list of + strings). Multiple definitions are concatenated together. + + + + + types.attrsOf t + + A set of elements of type t + (e.g., types.attrsOf types.int is a set of + name/value pairs, the values being integers). + + + + + types.nullOr t + + Either the value null or something of + type t. + + + + + +You can also create new types using the function +mkOptionType. See +lib/types.nix in Nixpkgs for details. + +
\ No newline at end of file diff --git a/nixos/doc/manual/development/option-def.xml b/nixos/doc/manual/development/option-def.xml new file mode 100644 index 00000000000..4e267ecfd1e --- /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 00000000000..d9be761eb01 --- /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 00000000000..992a07af981 --- /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 00000000000..87e40e32617 --- /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 00000000000..9cf29e5dc57 --- /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 00000000000..bbb655eed2a --- /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 4cbfcc229fa..00000000000 --- 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 00000000000..aa31742434e --- /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 00000000000..ee61bedc418 --- /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 00000000000..dbd5606c4a5 --- /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 00000000000..97e3d2eaa1c --- /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 00000000000..b140c56fbee --- /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 00000000000..ceeeb5c0ac0 --- /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 00000000000..ed71a7e23a3 --- /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/man-nixos-option.xml b/nixos/doc/manual/man-nixos-option.xml index 7952847d4db..2875336c67e 100644 --- a/nixos/doc/manual/man-nixos-option.xml +++ b/nixos/doc/manual/man-nixos-option.xml @@ -17,11 +17,6 @@ nixos-option - - - - - option.name @@ -31,50 +26,13 @@ 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. +of the option name given as argument. When the option name is not an option, the command prints the list of attributes contained in the attribute set. -Options - -This command accepts the following options: - - - - - , - - 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 @@ -103,27 +61,21 @@ grub initScript $ nixos-option boot.loader.grub.enable -true +Value: +true -Prints option information: +Default: +true -$ 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). +Whether to enable the GNU GRUB boot loader. -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 + "/nix/var/nix/profiles/per-user/root/channels/nixos/nixpkgs/nixos/modules/system/boot/loader/grub/grub.nix" Defined by: - /path/to/nixpkgs/nixos/modules/system/boot/kernel.nix - /path/to/nixpkgs/nixos/modules/hardware/network/rt73.nix - /path/to/nixpkgs/nixos/modules/hardware/network/intel-3945abg.nix - /path/to/nixpkgs/nixos/modules/hardware/network/intel-2200bg.nix + "/nix/var/nix/profiles/per-user/root/channels/nixos/nixpkgs/nixos/modules/system/boot/loader/grub/grub.nix" + diff --git a/nixos/doc/manual/manual.xml b/nixos/doc/manual/manual.xml index f51a04cdf25..a3ad76209ac 100644 --- a/nixos/doc/manual/manual.xml +++ b/nixos/doc/manual/manual.xml @@ -1,15 +1,14 @@ - + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="NixOSManual"> + - NixOS Manual Version - - Preface @@ -29,19 +28,14 @@ - - - - + + + - - - - - + - Configuration options + Configuration Options diff --git a/nixos/doc/manual/release-notes/release-notes.xml b/nixos/doc/manual/release-notes/release-notes.xml new file mode 100644 index 00000000000..fb82d5adcef --- /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 00000000000..234fb5a643f --- /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 52e88bb4c86..74af1ed1274 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 00000000000..09da15ce236 --- /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 e1a358df2aa..00000000000 --- 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 c7d65112b64..00000000000 --- 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/ - - - - -
- - - diff --git a/nixos/lib/build-vms.nix b/nixos/lib/build-vms.nix index 498c0a37783..50b3b424166 100644 --- a/nixos/lib/build-vms.nix +++ b/nixos/lib/build-vms.nix @@ -48,10 +48,11 @@ rec { let interfacesNumbered = zipTwoLists config.virtualisation.vlans (range 1 255); interfaces = flip map interfacesNumbered ({ first, second }: - nameValuePair "eth${toString second}" - { ipAddress = "192.168.${toString first}.${toString m.second}"; - subnetMask = "255.255.255.0"; - }); + nameValuePair "eth${toString second}" { ip4 = + [ { address = "192.168.${toString first}.${toString m.second}"; + prefixLength = 24; + } ]; + }); in { key = "ip-address"; config = @@ -60,7 +61,7 @@ rec { networking.interfaces = listToAttrs interfaces; networking.primaryIPAddress = - optionalString (interfaces != []) (head interfaces).value.ipAddress; + optionalString (interfaces != []) (head (head interfaces).value.ip4).address; # Put the IP addresses of all VMs in this machine's # /etc/hosts file. If a machine has multiple diff --git a/nixos/lib/make-system-tarball.nix b/nixos/lib/make-system-tarball.nix index 8fed9a34882..3bd891fdbc2 100644 --- a/nixos/lib/make-system-tarball.nix +++ b/nixos/lib/make-system-tarball.nix @@ -15,6 +15,9 @@ # store path whose closure will be copied, and `symlink' is a # symlink to `object' that will be added to the tarball. storeContents ? [] + + # Extra tar arguments +, extraArgs ? "" }: stdenv.mkDerivation { @@ -22,7 +25,7 @@ stdenv.mkDerivation { builder = ./make-system-tarball.sh; buildInputs = [perl xz]; - inherit fileName pathsFromGraph; + inherit fileName pathsFromGraph extraArgs; # !!! should use XML. sources = map (x: x.source) contents; diff --git a/nixos/lib/make-system-tarball.sh b/nixos/lib/make-system-tarball.sh index 096d96ac1c8..2eb668115a6 100644 --- a/nixos/lib/make-system-tarball.sh +++ b/nixos/lib/make-system-tarball.sh @@ -50,7 +50,7 @@ done mkdir -p $out/tarball -tar cvJf $out/tarball/$fileName.tar.xz * +tar cvJf $out/tarball/$fileName.tar.xz * $extraArgs mkdir -p $out/nix-support echo $system > $out/nix-support/system diff --git a/nixos/lib/test-driver/Machine.pm b/nixos/lib/test-driver/Machine.pm index e2bd3393d87..85c2bfa88e1 100644 --- a/nixos/lib/test-driver/Machine.pm +++ b/nixos/lib/test-driver/Machine.pm @@ -482,7 +482,7 @@ sub screenshot { my $name = basename($filename); $self->nest("making screenshot ‘$name’", sub { $self->sendMonitorCommand("screendump $tmp"); - system("convert $tmp ${filename}") == 0 + system("pnmtopng $tmp > ${filename}") == 0 or die "cannot convert screenshot"; unlink $tmp; }, { image => $name } ); diff --git a/nixos/lib/test-driver/log2html.xsl b/nixos/lib/test-driver/log2html.xsl index ce8a9c6de2b..0485412b4c8 100644 --- a/nixos/lib/test-driver/log2html.xsl +++ b/nixos/lib/test-driver/log2html.xsl @@ -9,8 +9,8 @@ - - + +