Merge pull request #5212 from mkenigs/auto-uid-allocation

Merge master into #3600

11 files changed, 748 insertions, 0 deletions

diff --git a/doc/manual/src/package-management/basic-package-mgmt.md b/doc/manual/src/package-management/basic-package-mgmt.md
new file mode 100644
index 000000000..9702a29eb
--- /dev/null
+++ b/doc/manual/src/package-management/basic-package-mgmt.md
@@ -0,0 +1,172 @@
+# Basic Package Management
+
+The main command for package management is
+[`nix-env`](../command-ref/nix-env.md).  You can use it to install,
+upgrade, and erase packages, and to query what packages are installed
+or are available for installation.
+
+In Nix, different users can have different “views” on the set of
+installed applications. That is, there might be lots of applications
+present on the system (possibly in many different versions), but users
+can have a specific selection of those active — where “active” just
+means that it appears in a directory in the user’s `PATH`. Such a view
+on the set of installed applications is called a *user environment*,
+which is just a directory tree consisting of symlinks to the files of
+the active applications.
+
+Components are installed from a set of *Nix expressions* that tell Nix
+how to build those packages, including, if necessary, their
+dependencies. There is a collection of Nix expressions called the
+Nixpkgs package collection that contains packages ranging from basic
+development stuff such as GCC and Glibc, to end-user applications like
+Mozilla Firefox. (Nix is however not tied to the Nixpkgs package
+collection; you could write your own Nix expressions based on Nixpkgs,
+or completely new ones.)
+
+You can manually download the latest version of Nixpkgs from
+<http://nixos.org/nixpkgs/download.html>. However, it’s much more
+convenient to use the Nixpkgs [*channel*](channels.md), since it makes
+it easy to stay up to date with new versions of Nixpkgs. Nixpkgs is
+automatically added to your list of “subscribed” channels when you
+install Nix. If this is not the case for some reason, you can add it
+as follows:
+
+```console
+$ nix-channel --add https://nixos.org/channels/nixpkgs-unstable
+$ nix-channel --update
+```
+
+> **Note**
+> 
+> On NixOS, you’re automatically subscribed to a NixOS channel
+> corresponding to your NixOS major release (e.g.
+> <http://nixos.org/channels/nixos-14.12>). A NixOS channel is identical
+> to the Nixpkgs channel, except that it contains only Linux binaries
+> and is updated only if a set of regression tests succeed.
+
+You can view the set of available packages in Nixpkgs:
+
+```console
+$ nix-env -qa
+aterm-2.2
+bash-3.0
+binutils-2.15
+bison-1.875d
+blackdown-1.4.2
+bzip2-1.0.2
+…
+```
+
+The flag `-q` specifies a query operation, and `-a` means that you want
+to show the “available” (i.e., installable) packages, as opposed to the
+installed packages. If you downloaded Nixpkgs yourself, or if you
+checked it out from GitHub, then you need to pass the path to your
+Nixpkgs tree using the `-f` flag:
+
+```console
+$ nix-env -qaf /path/to/nixpkgs
+```
+
+where */path/to/nixpkgs* is where you’ve unpacked or checked out
+Nixpkgs.
+
+You can select specific packages by name:
+
+```console
+$ nix-env -qa firefox
+firefox-34.0.5
+firefox-with-plugins-34.0.5
+```
+
+and using regular expressions:
+
+```console
+$ nix-env -qa 'firefox.*'
+```
+
+It is also possible to see the *status* of available packages, i.e.,
+whether they are installed into the user environment and/or present in
+the system:
+
+```console
+$ nix-env -qas
+…
+-PS bash-3.0
+--S binutils-2.15
+IPS bison-1.875d
+…
+```
+
+The first character (`I`) indicates whether the package is installed in
+your current user environment. The second (`P`) indicates whether it is
+present on your system (in which case installing it into your user
+environment would be a very quick operation). The last one (`S`)
+indicates whether there is a so-called *substitute* for the package,
+which is Nix’s mechanism for doing binary deployment. It just means that
+Nix knows that it can fetch a pre-built package from somewhere
+(typically a network server) instead of building it locally.
+
+You can install a package using `nix-env -i`. For instance,
+
+```console
+$ nix-env -i subversion
+```
+
+will install the package called `subversion` (which is, of course, the
+[Subversion version management system](http://subversion.tigris.org/)).
+
+> **Note**
+> 
+> When you ask Nix to install a package, it will first try to get it in
+> pre-compiled form from a *binary cache*. By default, Nix will use the
+> binary cache <https://cache.nixos.org>; it contains binaries for most
+> packages in Nixpkgs. Only if no binary is available in the binary
+> cache, Nix will build the package from source. So if `nix-env
+> -i subversion` results in Nix building stuff from source, then either
+> the package is not built for your platform by the Nixpkgs build
+> servers, or your version of Nixpkgs is too old or too new. For
+> instance, if you have a very recent checkout of Nixpkgs, then the
+> Nixpkgs build servers may not have had a chance to build everything
+> and upload the resulting binaries to <https://cache.nixos.org>. The
+> Nixpkgs channel is only updated after all binaries have been uploaded
+> to the cache, so if you stick to the Nixpkgs channel (rather than
+> using a Git checkout of the Nixpkgs tree), you will get binaries for
+> most packages.
+
+Naturally, packages can also be uninstalled:
+
+```console
+$ nix-env -e subversion
+```
+
+Upgrading to a new version is just as easy. If you have a new release of
+Nix Packages, you can do:
+
+```console
+$ nix-env -u subversion
+```
+
+This will *only* upgrade Subversion if there is a “newer” version in the
+new set of Nix expressions, as defined by some pretty arbitrary rules
+regarding ordering of version numbers (which generally do what you’d
+expect of them). To just unconditionally replace Subversion with
+whatever version is in the Nix expressions, use `-i` instead of `-u`;
+`-i` will remove whatever version is already installed.
+
+You can also upgrade all packages for which there are newer versions:
+
+```console
+$ nix-env -u
+```
+
+Sometimes it’s useful to be able to ask what `nix-env` would do, without
+actually doing it. For instance, to find out what packages would be
+upgraded by `nix-env -u`, you can do
+
+```console
+$ nix-env -u --dry-run
+(dry run; not doing anything)
+upgrading `libxslt-1.1.0' to `libxslt-1.1.10'
+upgrading `graphviz-1.10' to `graphviz-1.12'
+upgrading `coreutils-5.0' to `coreutils-5.2.1'
+```
diff --git a/doc/manual/src/package-management/binary-cache-substituter.md b/doc/manual/src/package-management/binary-cache-substituter.md
new file mode 100644
index 000000000..bdc5038fc
--- /dev/null
+++ b/doc/manual/src/package-management/binary-cache-substituter.md
@@ -0,0 +1,50 @@
+# Serving a Nix store via HTTP
+
+You can easily share the Nix store of a machine via HTTP. This allows
+other machines to fetch store paths from that machine to speed up
+installations. It uses the same *binary cache* mechanism that Nix
+usually uses to fetch pre-built binaries from <https://cache.nixos.org>.
+
+The daemon that handles binary cache requests via HTTP, `nix-serve`, is
+not part of the Nix distribution, but you can install it from Nixpkgs:
+
+```console
+$ nix-env -i nix-serve
+```
+
+You can then start the server, listening for HTTP connections on
+whatever port you like:
+
+```console
+$ nix-serve -p 8080
+```
+
+To check whether it works, try the following on the client:
+
+```console
+$ curl http://avalon:8080/nix-cache-info
+```
+
+which should print something like:
+
+    StoreDir: /nix/store
+    WantMassQuery: 1
+    Priority: 30
+
+On the client side, you can tell Nix to use your binary cache using
+`--option extra-binary-caches`, e.g.:
+
+```console
+$ nix-env -i firefox --option extra-binary-caches http://avalon:8080/
+```
+
+The option `extra-binary-caches` tells Nix to use this binary cache in
+addition to your default caches, such as <https://cache.nixos.org>.
+Thus, for any path in the closure of Firefox, Nix will first check if
+the path is available on the server `avalon` or another binary caches.
+If not, it will fall back to building from source.
+
+You can also tell Nix to always use your binary cache by adding a line
+to the `nix.conf` configuration file like this:
+
+    binary-caches = http://avalon:8080/ https://cache.nixos.org/
diff --git a/doc/manual/src/package-management/channels.md b/doc/manual/src/package-management/channels.md
new file mode 100644
index 000000000..93c8b41a6
--- /dev/null
+++ b/doc/manual/src/package-management/channels.md
@@ -0,0 +1,50 @@
+# Channels
+
+If you want to stay up to date with a set of packages, it’s not very
+convenient to manually download the latest set of Nix expressions for
+those packages and upgrade using `nix-env`. Fortunately, there’s a
+better way: *Nix channels*.
+
+A Nix channel is just a URL that points to a place that contains a set
+of Nix expressions and a manifest. Using the command
+[`nix-channel`](../command-ref/nix-channel.md) you can automatically
+stay up to date with whatever is available at that URL.
+
+To see the list of official NixOS channels, visit
+<https://nixos.org/channels>.
+
+You can “subscribe” to a channel using `nix-channel --add`, e.g.,
+
+```console
+$ nix-channel --add https://nixos.org/channels/nixpkgs-unstable
+```
+
+subscribes you to a channel that always contains that latest version of
+the Nix Packages collection. (Subscribing really just means that the URL
+is added to the file `~/.nix-channels`, where it is read by subsequent
+calls to `nix-channel
+--update`.) You can “unsubscribe” using `nix-channel
+--remove`:
+
+```console
+$ nix-channel --remove nixpkgs
+```
+
+To obtain the latest Nix expressions available in a channel, do
+
+```console
+$ nix-channel --update
+```
+
+This downloads and unpacks the Nix expressions in every channel
+(downloaded from `url/nixexprs.tar.bz2`). It also makes the union of
+each channel’s Nix expressions available by default to `nix-env`
+operations (via the symlink `~/.nix-defexpr/channels`). Consequently,
+you can then say
+
+```console
+$ nix-env -u
+```
+
+to upgrade all packages in your profile to the latest versions available
+in the subscribed channels.
diff --git a/doc/manual/src/package-management/copy-closure.md b/doc/manual/src/package-management/copy-closure.md
new file mode 100644
index 000000000..d3fac4d76
--- /dev/null
+++ b/doc/manual/src/package-management/copy-closure.md
@@ -0,0 +1,34 @@
+# Copying Closures via SSH
+
+The command `nix-copy-closure` copies a Nix store path along with all
+its dependencies to or from another machine via the SSH protocol. It
+doesn’t copy store paths that are already present on the target machine.
+For example, the following command copies Firefox with all its
+dependencies:
+
+    $ nix-copy-closure --to alice@itchy.example.org $(type -p firefox)
+
+See the [manpage for `nix-copy-closure`](../command-ref/nix-copy-closure.md) for details.
+
+With `nix-store
+--export` and `nix-store --import` you can write the closure of a store
+path (that is, the path and all its dependencies) to a file, and then
+unpack that file into another Nix store. For example,
+
+    $ nix-store --export $(nix-store -qR $(type -p firefox)) > firefox.closure
+
+writes the closure of Firefox to a file. You can then copy this file to
+another machine and install the closure:
+
+    $ nix-store --import < firefox.closure
+
+Any store paths in the closure that are already present in the target
+store are ignored. It is also possible to pipe the export into another
+command, e.g. to copy and install a closure directly to/on another
+machine:
+
+    $ nix-store --export $(nix-store -qR $(type -p firefox)) | bzip2 | \
+        ssh alice@itchy.example.org "bunzip2 | nix-store --import"
+
+However, `nix-copy-closure` is generally more efficient because it only
+copies paths that are not already present in the target Nix store.
diff --git a/doc/manual/src/package-management/garbage-collection.md b/doc/manual/src/package-management/garbage-collection.md
new file mode 100644
index 000000000..fecb30fd6
--- /dev/null
+++ b/doc/manual/src/package-management/garbage-collection.md
@@ -0,0 +1,73 @@
+# Garbage Collection
+
+`nix-env` operations such as upgrades (`-u`) and uninstall (`-e`) never
+actually delete packages from the system. All they do (as shown above)
+is to create a new user environment that no longer contains symlinks to
+the “deleted” packages.
+
+Of course, since disk space is not infinite, unused packages should be
+removed at some point. You can do this by running the Nix garbage
+collector. It will remove from the Nix store any package not used
+(directly or indirectly) by any generation of any profile.
+
+Note however that as long as old generations reference a package, it
+will not be deleted. After all, we wouldn’t be able to do a rollback
+otherwise. So in order for garbage collection to be effective, you
+should also delete (some) old generations. Of course, this should only
+be done if you are certain that you will not need to roll back.
+
+To delete all old (non-current) generations of your current profile:
+
+```console
+$ nix-env --delete-generations old
+```
+
+Instead of `old` you can also specify a list of generations, e.g.,
+
+```console
+$ nix-env --delete-generations 10 11 14
+```
+
+To delete all generations older than a specified number of days (except
+the current generation), use the `d` suffix. For example,
+
+```console
+$ nix-env --delete-generations 14d
+```
+
+deletes all generations older than two weeks.
+
+After removing appropriate old generations you can run the garbage
+collector as follows:
+
+```console
+$ nix-store --gc
+```
+
+The behaviour of the gargage collector is affected by the
+`keep-derivations` (default: true) and `keep-outputs` (default: false)
+options in the Nix configuration file. The defaults will ensure that all
+derivations that are build-time dependencies of garbage collector roots
+will be kept and that all output paths that are runtime dependencies
+will be kept as well. All other derivations or paths will be collected.
+(This is usually what you want, but while you are developing it may make
+sense to keep outputs to ensure that rebuild times are quick.) If you
+are feeling uncertain, you can also first view what files would be
+deleted:
+
+```console
+$ nix-store --gc --print-dead
+```
+
+Likewise, the option `--print-live` will show the paths that *won’t* be
+deleted.
+
+There is also a convenient little utility `nix-collect-garbage`, which
+when invoked with the `-d` (`--delete-old`) switch deletes all old
+generations of all profiles in `/nix/var/nix/profiles`. So
+
+```console
+$ nix-collect-garbage -d
+```
+
+is a quick and easy way to clean up your system.
diff --git a/doc/manual/src/package-management/garbage-collector-roots.md b/doc/manual/src/package-management/garbage-collector-roots.md
new file mode 100644
index 000000000..30c5b7f8d
--- /dev/null
+++ b/doc/manual/src/package-management/garbage-collector-roots.md
@@ -0,0 +1,18 @@
+# Garbage Collector Roots
+
+The roots of the garbage collector are all store paths to which there
+are symlinks in the directory `prefix/nix/var/nix/gcroots`. For
+instance, the following command makes the path
+`/nix/store/d718ef...-foo` a root of the collector:
+
+```console
+$ ln -s /nix/store/d718ef...-foo /nix/var/nix/gcroots/bar
+```
+
+That is, after this command, the garbage collector will not remove
+`/nix/store/d718ef...-foo` or any of its dependencies.
+
+Subdirectories of `prefix/nix/var/nix/gcroots` are also searched for
+symlinks. Symlinks to non-store paths are followed and searched for
+roots, but symlinks to non-store paths *inside* the paths reached in
+that way are not followed to prevent infinite recursion.
diff --git a/doc/manual/src/package-management/package-management.md b/doc/manual/src/package-management/package-management.md
new file mode 100644
index 000000000..bd26a09ab
--- /dev/null
+++ b/doc/manual/src/package-management/package-management.md
@@ -0,0 +1,5 @@
+This chapter discusses how to do package management with Nix, i.e.,
+how to obtain, install, upgrade, and erase packages. This is the
+“user’s” perspective of the Nix system — people who want to *create*
+packages should consult the [chapter on writing Nix
+expressions](../expressions/writing-nix-expressions.md).
diff --git a/doc/manual/src/package-management/profiles.md b/doc/manual/src/package-management/profiles.md
new file mode 100644
index 000000000..fbbfb7320
--- /dev/null
+++ b/doc/manual/src/package-management/profiles.md
@@ -0,0 +1,133 @@
+# Profiles
+
+Profiles and user environments are Nix’s mechanism for implementing the
+ability to allow different users to have different configurations, and
+to do atomic upgrades and rollbacks. To understand how they work, it’s
+useful to know a bit about how Nix works. In Nix, packages are stored in
+unique locations in the *Nix store* (typically, `/nix/store`). For
+instance, a particular version of the Subversion package might be stored
+in a directory
+`/nix/store/dpmvp969yhdqs7lm2r1a3gng7pyq6vy4-subversion-1.1.3/`, while
+another version might be stored in
+`/nix/store/5mq2jcn36ldlmh93yj1n8s9c95pj7c5s-subversion-1.1.2`. The long
+strings prefixed to the directory names are cryptographic hashes (to be
+precise, 160-bit truncations of SHA-256 hashes encoded in a base-32
+notation) of *all* inputs involved in building the package — sources,
+dependencies, compiler flags, and so on. So if two packages differ in
+any way, they end up in different locations in the file system, so they
+don’t interfere with each other. Here is what a part of a typical Nix
+store looks like:
+
+![](../figures/user-environments.png)
+
+Of course, you wouldn’t want to type
+
+```console
+$ /nix/store/dpmvp969yhdq...-subversion-1.1.3/bin/svn
+```
+
+every time you want to run Subversion. Of course we could set up the
+`PATH` environment variable to include the `bin` directory of every
+package we want to use, but this is not very convenient since changing
+`PATH` doesn’t take effect for already existing processes. The solution
+Nix uses is to create directory trees of symlinks to *activated*
+packages. These are called *user environments* and they are packages
+themselves (though automatically generated by `nix-env`), so they too
+reside in the Nix store. For instance, in the figure above, the user
+environment `/nix/store/0c1p5z4kda11...-user-env` contains a symlink to
+just Subversion 1.1.2 (arrows in the figure indicate symlinks). This
+would be what we would obtain if we had done
+
+```console
+$ nix-env -i subversion
+```
+
+on a set of Nix expressions that contained Subversion 1.1.2.
+
+This doesn’t in itself solve the problem, of course; you wouldn’t want
+to type `/nix/store/0c1p5z4kda11...-user-env/bin/svn` either. That’s why
+there are symlinks outside of the store that point to the user
+environments in the store; for instance, the symlinks `default-42-link`
+and `default-43-link` in the example. These are called *generations*
+since every time you perform a `nix-env` operation, a new user
+environment is generated based on the current one. For instance,
+generation 43 was created from generation 42 when we did
+
+```console
+$ nix-env -i subversion firefox
+```
+
+on a set of Nix expressions that contained Firefox and a new version of
+Subversion.
+
+Generations are grouped together into *profiles* so that different users
+don’t interfere with each other if they don’t want to. For example:
+
+```console
+$ ls -l /nix/var/nix/profiles/
+...
+lrwxrwxrwx  1 eelco ... default-42-link -> /nix/store/0c1p5z4kda11...-user-env
+lrwxrwxrwx  1 eelco ... default-43-link -> /nix/store/3aw2pdyx2jfc...-user-env
+lrwxrwxrwx  1 eelco ... default -> default-43-link
+```
+
+This shows a profile called `default`. The file `default` itself is
+actually a symlink that points to the current generation. When we do a
+`nix-env` operation, a new user environment and generation link are
+created based on the current one, and finally the `default` symlink is
+made to point at the new generation. This last step is atomic on Unix,
+which explains how we can do atomic upgrades. (Note that the
+building/installing of new packages doesn’t interfere in any way with
+old packages, since they are stored in different locations in the Nix
+store.)
+
+If you find that you want to undo a `nix-env` operation, you can just do
+
+```console
+$ nix-env --rollback
+```
+
+which will just make the current generation link point at the previous
+link. E.g., `default` would be made to point at `default-42-link`. You
+can also switch to a specific generation:
+
+```console
+$ nix-env --switch-generation 43
+```
+
+which in this example would roll forward to generation 43 again. You can
+also see all available generations:
+
+```console
+$ nix-env --list-generations
+```
+
+You generally wouldn’t have `/nix/var/nix/profiles/some-profile/bin` in
+your `PATH`. Rather, there is a symlink `~/.nix-profile` that points to
+your current profile. This means that you should put
+`~/.nix-profile/bin` in your `PATH` (and indeed, that’s what the
+initialisation script `/nix/etc/profile.d/nix.sh` does). This makes it
+easier to switch to a different profile. You can do that using the
+command `nix-env --switch-profile`:
+
+```console
+$ nix-env --switch-profile /nix/var/nix/profiles/my-profile
+
+$ nix-env --switch-profile /nix/var/nix/profiles/default
+```
+
+These commands switch to the `my-profile` and default profile,
+respectively. If the profile doesn’t exist, it will be created
+automatically. You should be careful about storing a profile in another
+location than the `profiles` directory, since otherwise it might not be
+used as a root of the [garbage collector](garbage-collection.md).
+
+All `nix-env` operations work on the profile pointed to by
+`~/.nix-profile`, but you can override this using the `--profile` option
+(abbreviation `-p`):
+
+```console
+$ nix-env -p /nix/var/nix/profiles/other-profile -i subversion
+```
+
+This will *not* change the `~/.nix-profile` symlink.
diff --git a/doc/manual/src/package-management/s3-substituter.md b/doc/manual/src/package-management/s3-substituter.md
new file mode 100644
index 000000000..30f2b2e11
--- /dev/null
+++ b/doc/manual/src/package-management/s3-substituter.md
@@ -0,0 +1,145 @@
+# Serving a Nix store via S3
+
+Nix has built-in support for storing and fetching store paths from
+Amazon S3 and S3-compatible services. This uses the same *binary*
+cache mechanism that Nix usually uses to fetch prebuilt binaries from
+[cache.nixos.org](https://cache.nixos.org/).
+
+The following options can be specified as URL parameters to the S3 URL:
+
+  - `profile`\
+    The name of the AWS configuration profile to use. By default Nix
+    will use the `default` profile.
+
+  - `region`\
+    The region of the S3 bucket. `us–east-1` by default.
+    
+    If your bucket is not in `us–east-1`, you should always explicitly
+    specify the region parameter.
+
+  - `endpoint`\
+    The URL to your S3-compatible service, for when not using Amazon S3.
+    Do not specify this value if you're using Amazon S3.
+    
+    > **Note**
+    > 
+    > This endpoint must support HTTPS and will use path-based
+    > addressing instead of virtual host based addressing.
+
+  - `scheme`\
+    The scheme used for S3 requests, `https` (default) or `http`. This
+    option allows you to disable HTTPS for binary caches which don't
+    support it.
+    
+    > **Note**
+    > 
+    > HTTPS should be used if the cache might contain sensitive
+    > information.
+
+In this example we will use the bucket named `example-nix-cache`.
+
+## Anonymous Reads to your S3-compatible binary cache
+
+If your binary cache is publicly accessible and does not require
+authentication, the simplest and easiest way to use Nix with your S3
+compatible binary cache is to use the HTTP URL for that cache.
+
+For AWS S3 the binary cache URL for example bucket will be exactly
+<https://example-nix-cache.s3.amazonaws.com> or
+<s3://example-nix-cache>. For S3 compatible binary caches, consult that
+cache's documentation.
+
+Your bucket will need the following bucket policy:
+
+```json
+{
+    "Id": "DirectReads",
+    "Version": "2012-10-17",
+    "Statement": [
+        {
+            "Sid": "AllowDirectReads",
+            "Action": [
+                "s3:GetObject",
+                "s3:GetBucketLocation"
+            ],
+            "Effect": "Allow",
+            "Resource": [
+                "arn:aws:s3:::example-nix-cache",
+                "arn:aws:s3:::example-nix-cache/*"
+            ],
+            "Principal": "*"
+        }
+    ]
+}
+```
+
+## Authenticated Reads to your S3 binary cache
+
+For AWS S3 the binary cache URL for example bucket will be exactly
+<s3://example-nix-cache>.
+
+Nix will use the [default credential provider
+chain](https://docs.aws.amazon.com/sdk-for-cpp/v1/developer-guide/credentials.html)
+for authenticating requests to Amazon S3.
+
+Nix supports authenticated reads from Amazon S3 and S3 compatible binary
+caches.
+
+Your bucket will need a bucket policy allowing the desired users to
+perform the `s3:GetObject` and `s3:GetBucketLocation` action on all
+objects in the bucket. The [anonymous policy given
+above](#anonymous-reads-to-your-s3-compatible-binary-cache) can be
+updated to have a restricted `Principal` to support this.
+
+## Authenticated Writes to your S3-compatible binary cache
+
+Nix support fully supports writing to Amazon S3 and S3 compatible
+buckets. The binary cache URL for our example bucket will be
+<s3://example-nix-cache>.
+
+Nix will use the [default credential provider
+chain](https://docs.aws.amazon.com/sdk-for-cpp/v1/developer-guide/credentials.html)
+for authenticating requests to Amazon S3.
+
+Your account will need the following IAM policy to upload to the cache:
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Sid": "UploadToCache",
+      "Effect": "Allow",
+      "Action": [
+        "s3:AbortMultipartUpload",
+        "s3:GetBucketLocation",
+        "s3:GetObject",
+        "s3:ListBucket",
+        "s3:ListBucketMultipartUploads",
+        "s3:ListMultipartUploadParts",
+        "s3:PutObject"
+      ],
+      "Resource": [
+        "arn:aws:s3:::example-nix-cache",
+        "arn:aws:s3:::example-nix-cache/*"
+      ]
+    }
+  ]
+}
+```
+
+## Examples
+
+To upload with a specific credential profile for Amazon S3:
+
+```console
+$ nix copy nixpkgs.hello \
+  --to 's3://example-nix-cache?profile=cache-upload&region=eu-west-2'
+```
+
+To upload to an S3-compatible binary cache:
+
+```console
+$ nix copy nixpkgs.hello --to \
+  's3://example-nix-cache?profile=cache-upload&scheme=https&endpoint=minio.example.com'
+```
diff --git a/doc/manual/src/package-management/sharing-packages.md b/doc/manual/src/package-management/sharing-packages.md
new file mode 100644
index 000000000..846ca6934
--- /dev/null
+++ b/doc/manual/src/package-management/sharing-packages.md
@@ -0,0 +1,6 @@
+# Sharing Packages Between Machines
+
+Sometimes you want to copy a package from one machine to another. Or,
+you want to install some packages and you know that another machine
+already has some or all of those packages or their dependencies. In that
+case there are mechanisms to quickly copy packages between machines.
diff --git a/doc/manual/src/package-management/ssh-substituter.md b/doc/manual/src/package-management/ssh-substituter.md
new file mode 100644
index 000000000..6e5e258bc
--- /dev/null
+++ b/doc/manual/src/package-management/ssh-substituter.md
@@ -0,0 +1,62 @@
+# Serving a Nix store via SSH
+
+You can tell Nix to automatically fetch needed binaries from a remote
+Nix store via SSH. For example, the following installs Firefox,
+automatically fetching any store paths in Firefox’s closure if they are
+available on the server `avalon`:
+
+```console
+$ nix-env -i firefox --substituters ssh://alice@avalon
+```
+
+This works similar to the binary cache substituter that Nix usually
+uses, only using SSH instead of HTTP: if a store path `P` is needed, Nix
+will first check if it’s available in the Nix store on `avalon`. If not,
+it will fall back to using the binary cache substituter, and then to
+building from source.
+
+> **Note**
+> 
+> The SSH substituter currently does not allow you to enter an SSH
+> passphrase interactively. Therefore, you should use `ssh-add` to load
+> the decrypted private key into `ssh-agent`.
+
+You can also copy the closure of some store path, without installing it
+into your profile, e.g.
+
+```console
+$ nix-store -r /nix/store/m85bxg…-firefox-34.0.5 --substituters
+ssh://alice@avalon
+```
+
+This is essentially equivalent to doing
+
+```console
+$ nix-copy-closure --from alice@avalon
+/nix/store/m85bxg…-firefox-34.0.5
+```
+
+You can use SSH’s *forced command* feature to set up a restricted user
+account for SSH substituter access, allowing read-only access to the
+local Nix store, but nothing more. For example, add the following lines
+to `sshd_config` to restrict the user `nix-ssh`:
+
+    Match User nix-ssh
+      AllowAgentForwarding no
+      AllowTcpForwarding no
+      PermitTTY no
+      PermitTunnel no
+      X11Forwarding no
+      ForceCommand nix-store --serve
+    Match All
+
+On NixOS, you can accomplish the same by adding the following to your
+`configuration.nix`:
+
+```nix
+nix.sshServe.enable = true;
+nix.sshServe.keys = [ "ssh-dss AAAAB3NzaC1k... bob@example.org" ];
+```
+
+where the latter line lists the public keys of users that are allowed to
+connect.