diff --git a/doc/manual/configuration.xml b/doc/manual/configuration.xml
index 41f010d10b3e..daee0248e88c 100644
--- a/doc/manual/configuration.xml
+++ b/doc/manual/configuration.xml
@@ -11,6 +11,300 @@ NixOS machine through the configuration file
effect after you run nixos-rebuild.
+
+
+Package management
+
+This section describes how to add additional packages to your
+system. NixOS has two distinct styles of package management:
+
+
+
+ Declarative, where you declare
+ what packages you want in your
+ configuration.nix. Every time you run
+ nixos-rebuild, NixOS will ensure that you get a
+ consistent set of binaries corresponding to your
+ specification.
+
+ Ad hoc, where you install,
+ upgrade and uninstall packages via the nix-env
+ command. This style allows mixing packages from different Nixpkgs
+ versions. It’s the only choice for non-root
+ users.
+
+
+
+
+
+The next two sections describe these two styles.
+
+
+Declarative package management
+
+With declarative package management, you specify which packages
+you want on your system by setting the option
+. For instance, adding the
+following line to configuration.nix enables the
+Mozilla Thunderbird email application:
+
+
+environment.systemPackages = [ pkgs.thunderbird ];
+
+
+The effect of this specification is that the Thunderbird package from
+Nixpkgs will be built or downloaded as part of the system when you run
+nixos-rebuild switch.
+
+You can get a list of the available packages as follows:
+
+$ nix-env -qaP '*' --description
+nixos.pkgs.firefox firefox-23.0 Mozilla Firefox - the browser, reloaded
+...
+
+
+The first column in the output is the attribute
+name, such as
+nixos.pkgs.thunderbird. (The
+nixos prefix allows distinguishing between
+different channels that you might have.)
+
+To “uninstall” a package, simply remove it from
+ and run
+nixos-rebuild switch.
+
+
+Customising packages
+
+Some packages in Nixpkgs have options to enable or disable
+optional functionality or change other aspects of the package. For
+instance, the Firefox wrapper package (which provides Firefox with a
+set of plugins such as the Adobe Flash player) has an option to enable
+the Google Talk plugin. It can be set in
+configuration.nix as follows:
+
+
+nixpkgs.config.firefox.enableGoogleTalkPlugin = true;
+
+
+
+Unfortunately, Nixpkgs currently lacks a way to query
+available configuration options.
+
+Apart from high-level options, it’s possible to tweak a package
+in almost arbitrary ways, such as changing or disabling dependencies
+of a package. For instance, the Emacs package in Nixpkgs by default
+has a dependency on GTK+ 2. If you want to build it against GTK+ 3,
+you can specify that as follows:
+
+
+environment.systemPackages = [ (pkgs.emacs.override { gtk = pkgs.gtk3; }) ];
+
+
+The function override performs the call to the Nix
+function that produces Emacs, with the original arguments amended by
+the set of arguments specified by you. So here the function argument
+gtk gets the value pkgs.gtk3,
+causing Emacs to depend on GTK+ 3. (The parentheses are necessary
+because in Nix, function application binds more weakly than list
+construction, so without them,
+environment.systemPackages would be a list with two
+elements.)
+
+Even greater customisation is possible using the function
+overrideDerivation. While the
+override mechanism above overrides the arguments of
+a package function, overrideDerivation allows
+changing the result of the function. This
+permits changing any aspect of the package, such as the source code.
+For instance, if you want to override the source code of Emacs, you
+can say:
+
+
+environment.systemPackages =
+ [ (pkgs.lib.overrideDerivation pkgs.emacs (attrs: {
+ name = "emacs-25.0-pre";
+ src = /path/to/my/emacs/tree;
+ }))
+ ];
+
+
+Here, overrideDerivation takes the Nix derivation
+specified by pkgs.emacs and produces a new
+derivation in which the original’s name and
+src attribute have been replaced by the given
+values. The original attributes are accessible via
+attrs.
+
+The overrides shown above are not global. They do not affect
+the original package; other packages in Nixpkgs continue to depend on
+the original rather than the customised package. This means that if
+another package in your system depends on the original package, you
+end up with two instances of the package. If you want to have
+everything depend on your customised instance, you can apply a
+global override as follows:
+
+
+nixpkgs.config.packageOverrides = pkgs:
+ { emacs = pkgs.emacs.override { gtk = pkgs.gtk3; };
+ };
+
+
+The effect of this definition is essentially equivalent to modifying
+the emacs attribute in the Nixpkgs source tree.
+Any package in Nixpkgs that depends on emacs will
+be passed your customised instance. (However, the value
+pkgs.emacs in
+nixpkgs.config.packageOverrides refers to the
+original rather than overriden instance, to prevent an infinite
+recursion.)
+
+
+
+Adding custom packages
+
+It’s possible that a package you need is not available in NixOS.
+In that case, you can do two things. First, you can clone the Nixpkgs
+repository, add the package to your clone, and (optionally) submit a
+patch or pull request to have it accepted into the main Nixpkgs
+repository. This is described in detail in the Nixpkgs
+manual. In short, you clone Nixpkgs:
+
+
+$ git clone git://github.com/NixOS/nixpkgs.git
+$ cd nixpkgs
+
+
+Then you write and test the package as described in the Nixpkgs
+manual. Finally, you add it to
+environment.systemPackages, e.g.
+
+
+environment.systemPackages = [ pkgs.my-package ];
+
+
+and you run nixos-rebuild, specifying your own
+Nixpkgs tree:
+
+
+$ nixos-rebuild switch -I nixpkgs=/path/to/my/nixpkgs
+
+
+
+The second possibility is to add the package outside of the
+Nixpkgs tree. For instance, here is how you specify a build of the
+GNU Hello
+package directly in configuration.nix:
+
+
+environment.systemPackages =
+ let
+ my-hello = with pkgs; stdenv.mkDerivation rec {
+ name = "hello-2.8";
+ src = fetchurl {
+ url = "mirror://gnu/hello/${name}.tar.gz";
+ sha256 = "0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6";
+ };
+ };
+ in
+ [ my-hello ];
+
+
+Of course, you can also move the definition of
+my-hello into a separate Nix expression, e.g.
+
+environment.systemPackages = [ (import ./my-hello.nix) ];
+
+where my-hello.nix contains:
+
+with <nixpkgs> {}; # bring all of Nixpkgs into scope
+
+stdenv.mkDerivation rec {
+ name = "hello-2.8";
+ src = fetchurl {
+ url = "mirror://gnu/hello/${name}.tar.gz";
+ sha256 = "0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6";
+ };
+}
+
+
+This allows testing the package easily:
+
+$ nix-build my-hello.nix
+$ ./result/bin/hello
+Hello, world!
+
+
+
+
+
+
+
+
+
+Ad hoc package management
+
+With the command nix-env, you can install and
+uninstall packages from the command line. For instance, to install
+Mozilla Thunderbird:
+
+
+$ nix-env -iA nixos.pkgs.thunderbird
+
+If you invoke this as root, the package is installed in the Nix
+profile /nix/var/nix/profiles/default and visible
+to all users of the system; otherwise, the package ends up in
+/nix/var/nix/profiles/per-user/username/profile
+and is not visible to other users. The flag
+specifies the package by its attribute name; without it, the package
+is installed by matching against its package name
+(e.g. thunderbird). The latter is slower because
+it requires matching against all available Nix packages, and is
+ambiguous if there are multiple matching packages.
+
+Packages come from the NixOS channel. You typically upgrade a
+package by updating to the latest version of the NixOS channel:
+
+$ nix-channel --update nixos
+
+and then running nix-env -i again. Other packages
+in the profile are not affected; this is the
+crucial difference with the declarative style of package management,
+where running nixos-rebuild switch causes all
+packages to be updated to their current versions in the NixOS channel.
+You can however upgrade all packages for which there is a newer
+version by doing:
+
+$ nix-env -u '*'
+
+
+
+A package can be unstalled 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.
+
+
+
+
+
+
+
Networking
diff --git a/doc/manual/installation.xml b/doc/manual/installation.xml
index 40a2efa1405a..3068fa5cb944 100644
--- a/doc/manual/installation.xml
+++ b/doc/manual/installation.xml
@@ -307,7 +307,7 @@ available.
-
+Upgrading NixOS