From 7509d70f9ddec7d28911e6b6f2145bc50a923e9f Mon Sep 17 00:00:00 2001 From: Eelco Dolstra Date: Wed, 19 Nov 2008 15:20:46 +0000 Subject: [PATCH] * Documented some of the sharing mechanisms. --- doc/manual/Makefile.am | 4 +- doc/manual/env-common.xml | 21 +++++++++ doc/manual/installation.xml | 4 +- doc/manual/manual.xml | 6 ++- doc/manual/nix-copy-closure.xml | 2 +- doc/manual/nix-worker.xml | 34 ++++++++++++++ doc/manual/package-management.xml | 78 +++++++++++++++++++++++++++++++ 7 files changed, 144 insertions(+), 5 deletions(-) create mode 100644 doc/manual/nix-worker.xml diff --git a/doc/manual/Makefile.am b/doc/manual/Makefile.am index 20c9e1bee..392a6d71d 100644 --- a/doc/manual/Makefile.am +++ b/doc/manual/Makefile.am @@ -16,12 +16,14 @@ man1_MANS = nix-env.1 nix-build.1 nix-store.1 nix-instantiate.1 \ nix-prefetch-url.1 nix-channel.1 \ nix-install-package.1 nix-hash.1 nix-copy-closure.1 +man8_MANS = nix-worker.8 + FIGURES = figures/user-environments.png MANUAL_SRCS = manual.xml introduction.xml installation.xml \ package-management.xml writing-nix-expressions.xml builtins.xml \ build-farm.xml \ - $(man1_MANS:.1=.xml) \ + $(man1_MANS:.1=.xml) $(man8_MANS:.8=.xml) \ troubleshooting.xml bugs.xml opt-common.xml opt-common-syn.xml \ env-common.xml quick-start.xml nix-lang-ref.xml glossary.xml \ conf-file.xml release-notes.xml \ diff --git a/doc/manual/env-common.xml b/doc/manual/env-common.xml index fdfbaf59a..d6ebbf654 100644 --- a/doc/manual/env-common.xml +++ b/doc/manual/env-common.xml @@ -274,6 +274,27 @@ $ mount -o bind /mnt/otherdisk/nix /nix +NIX_OTHER_STORES + + This variable contains the paths of remote Nix + installations from whichs paths can be copied, separated by colons. + See for details. Each path + should be the /nix directory of a remote Nix + installation (i.e., not the /nix/store + directory). The paths are subject to globbing, so you can set it so + something like /var/run/nix/remote-stores/*/nix + and mount multiple remote filesystems in + /var/run/nix/remote-stores. + + Note that if you’re building through the Nix daemon, the only setting for + this variable that matters is the one that the + nix-worker process uses. So if you want to + change it, you have to restart the daemon. + + + + diff --git a/doc/manual/installation.xml b/doc/manual/installation.xml index b13be1363..7adf00cb6 100644 --- a/doc/manual/installation.xml +++ b/doc/manual/installation.xml @@ -336,8 +336,8 @@ $ chown -R root /nix/store /nix/var/nix -The Nix daemon should be started as follows (as -root): +The Nix daemon should be +started as follows (as root): $ nix-worker --daemon diff --git a/doc/manual/manual.xml b/doc/manual/manual.xml index 22e9f6afd..e1dd5d485 100644 --- a/doc/manual/manual.xml +++ b/doc/manual/manual.xml @@ -28,7 +28,7 @@ Eelco Dolstra - June 2008 + November 2008 @@ -101,6 +101,10 @@ nix-push +
+ nix-worker + +
diff --git a/doc/manual/nix-copy-closure.xml b/doc/manual/nix-copy-closure.xml index fcb6be234..ddbd8e694 100644 --- a/doc/manual/nix-copy-closure.xml +++ b/doc/manual/nix-copy-closure.xml @@ -128,7 +128,7 @@ those paths. If this bothers you, use Copy Firefox with all its dependencies to a remote machine: -$ nix-copy-closure alice@itchy.labs $(type -tP firefox) +$ nix-copy-closure --to alice@itchy.labs $(type -tP firefox) diff --git a/doc/manual/nix-worker.xml b/doc/manual/nix-worker.xml new file mode 100644 index 000000000..a14ee574e --- /dev/null +++ b/doc/manual/nix-worker.xml @@ -0,0 +1,34 @@ + + + + nix-worker + 8 + Nix + + + + + nix-worker + Nix multi-user support daemon + + + + + nix-worker + + + + + +Description + +The Nix daemon is necessary in multi-user Nix installations. It +performs build actions and other operations on the Nix store on behalf +of unprivileged users. + + + + + diff --git a/doc/manual/package-management.xml b/doc/manual/package-management.xml index be0d5f21b..c22273ebe 100644 --- a/doc/manual/package-management.xml +++ b/doc/manual/package-management.xml @@ -528,4 +528,82 @@ linkend='sec-nix-install-package' /> for details.
+
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. + +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 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 $(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 $(type -p firefox) | bzip2 | \ + ssh alice@itchy.example.org "bunzip2 | nix-store --import" + +But note that nix-copy-closure is generally more +efficient in this example because it only copies paths that are not +already present in the target Nix store. + +Finally, if you can mount the Nix store of a remote machine in +your local filesystem, Nix can copy paths from the remote Nix store to +the local Nix store on demand. For instance, +suppose that you mount a remote machine containing a Nix store via +sshfs: + + +$ sshfs alice@itchy.example.org:/ /mnt + +You should then set the NIX_OTHER_STORES environment +variable to tell Nix about this remote Nix store: + + +$ export NIX_OTHER_STORES=/mnt/nix + +Then if you do any Nix operation, e.g. + + +$ nix-env -i firefox + +and Nix has to build a path that it sees is already present in +/mnt/nix, then it will just copy from there +instead of building it from source. + + +
+ +