* Documented some of the sharing mechanisms.

7 files changed, 144 insertions, 5 deletions

diff --git a/doc/manual/Makefile.am b/doc/manual/Makefile.am
index 20c9e1beec4f..392a6d71ddc8 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 fdfbaf59ab2b..d6ebbf654761 100644
--- a/doc/manual/env-common.xml
+++ b/doc/manual/env-common.xml
@@ -274,6 +274,27 @@ $ mount -o bind /mnt/otherdisk/nix /nix</screen>
 </varlistentry>
 
     
+<varlistentry xml:id="envar-other-stores"><term><envar>NIX_OTHER_STORES</envar></term>
+
+  <listitem><para>This variable contains the paths of remote Nix
+  installations from whichs paths can be copied, separated by colons.
+  See <xref linkend="sec-sharing-packages" /> for details.  Each path
+  should be the <filename>/nix</filename> directory of a remote Nix
+  installation (i.e., not the <filename>/nix/store</filename>
+  directory).  The paths are subject to globbing, so you can set it so
+  something like <literal>/var/run/nix/remote-stores/*/nix</literal>
+  and mount multiple remote filesystems in
+  <literal>/var/run/nix/remote-stores</literal>.</para>
+
+  <para>Note that if you’re building through the <link
+  linkend="sec-nix-worker">Nix daemon</link>, the only setting for
+  this variable that matters is the one that the
+  <command>nix-worker</command> process uses.  So if you want to
+  change it, you have to restart the daemon.</para></listitem>
+
+</varlistentry>
+
+    
 </variablelist>
 
 
diff --git a/doc/manual/installation.xml b/doc/manual/installation.xml
index b13be1363f70..7adf00cb6aa3 100644
--- a/doc/manual/installation.xml
+++ b/doc/manual/installation.xml
@@ -336,8 +336,8 @@ $ chown -R root /nix/store /nix/var/nix</screen>
 
 </para>
 
-<para>The Nix daemon should be started as follows (as
-<literal>root</literal>):
+<para>The <link linkend="sec-nix-worker">Nix daemon</link> should be
+started as follows (as <literal>root</literal>):
 
 <screen>
 $ nix-worker --daemon</screen>
diff --git a/doc/manual/manual.xml b/doc/manual/manual.xml
index 22e9f6afd84d..e1dd5d48540b 100644
--- a/doc/manual/manual.xml
+++ b/doc/manual/manual.xml
@@ -28,7 +28,7 @@
       <holder>Eelco Dolstra</holder>
     </copyright>
 
-    <date>June 2008</date>
+    <date>November 2008</date>
     
   </info>
 
@@ -101,6 +101,10 @@
         <title>nix-push</title>
         <xi:include href="nix-push.xml" />
       </section>
+      <section xml:id="sec-nix-worker">
+        <title>nix-worker</title>
+        <xi:include href="nix-worker.xml" />
+      </section>
     </section>
     
   </appendix>
diff --git a/doc/manual/nix-copy-closure.xml b/doc/manual/nix-copy-closure.xml
index fcb6be2343c7..ddbd8e6944cc 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
 <para>Copy Firefox with all its dependencies to a remote machine:
 
 <screen>
-$ nix-copy-closure alice@itchy.labs $(type -tP firefox)</screen>
+$ nix-copy-closure --to alice@itchy.labs $(type -tP firefox)</screen>
 
 </para>
 
diff --git a/doc/manual/nix-worker.xml b/doc/manual/nix-worker.xml
new file mode 100644
index 000000000000..a14ee574e0cc
--- /dev/null
+++ b/doc/manual/nix-worker.xml
@@ -0,0 +1,34 @@
+<refentry xmlns="http://docbook.org/ns/docbook"
+          xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:xi="http://www.w3.org/2001/XInclude">
+
+<refmeta>
+  <refentrytitle>nix-worker</refentrytitle>
+  <manvolnum>8</manvolnum>
+  <refmiscinfo class="source">Nix</refmiscinfo>
+  <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo>
+</refmeta>
+
+<refnamediv>
+  <refname>nix-worker</refname>
+  <refpurpose>Nix multi-user support daemon</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+  <cmdsynopsis>
+    <command>nix-worker</command>
+    <arg choice="plain"><option>--daemon</option></arg>
+  </cmdsynopsis>
+</refsynopsisdiv>
+
+
+<refsection><title>Description</title>
+
+<para>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.</para>
+
+
+</refsection>
+
+</refentry>
diff --git a/doc/manual/package-management.xml b/doc/manual/package-management.xml
index be0d5f21bf1c..c22273ebe31d 100644
--- a/doc/manual/package-management.xml
+++ b/doc/manual/package-management.xml
@@ -528,4 +528,82 @@ linkend='sec-nix-install-package' /> for details.</para>
 </section>
 
 
+<section xml:id="sec-sharing-packages"><title>Sharing packages between machines</title>
+
+<para>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.</para>
+
+<para>The command <command
+linkend="sec-nix-copy-closure">nix-copy-closure</command> 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:
+
+<screen>
+$ nix-copy-closure --to alice@itchy.example.org $(type -p firefox)</screen>
+
+See <xref linkend='sec-nix-copy-closure' /> for details.</para>
+
+<para>With <command linkend='refsec-nix-store-export'>nix-store
+--export</command> and <command
+linkend='refsec-nix-store-import'>nix-store --import</command> 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,
+
+<screen>
+$ nix-store --export $(type -p firefox) > firefox.closure</screen>
+
+writes the closure of Firefox to a file.  You can then copy this file
+to another machine and install the closure:
+
+<screen>
+$ nix-store --import &lt; firefox.closure</screen>
+
+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:
+
+<screen>
+$ nix-store --export $(type -p firefox) | bzip2 | \
+    ssh alice@itchy.example.org "bunzip2 | nix-store --import"</screen>
+
+But note that <command>nix-copy-closure</command> is generally more
+efficient in this example because it only copies paths that are not
+already present in the target Nix store.</para>
+
+<para>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 <emphasis>on demand</emphasis>.  For instance,
+suppose that you mount a remote machine containing a Nix store via
+<command
+xlink:href="http://fuse.sourceforge.net/sshfs.html">sshfs</command>:
+
+<screen>
+$ sshfs alice@itchy.example.org:/ /mnt</screen>
+
+You should then set the <envar>NIX_OTHER_STORES</envar> environment
+variable to tell Nix about this remote Nix store:
+
+<screen>
+$ export NIX_OTHER_STORES=/mnt/nix</screen>
+
+Then if you do any Nix operation, e.g.
+
+<screen>
+$ nix-env -i firefox</screen>
+
+and Nix has to build a path that it sees is already present in
+<filename>/mnt/nix</filename>, then it will just copy from there
+instead of building it from source.</para>
+ 
+
+</section>
+
+
 </chapter>