lix-project/lix
20
57
Fork 31
Code Issues 349 Code Review (Gerrit) Projects 3 Releases Wiki Activity

Add section on SSH substituter

Browse source
This commit is contained in:
Eelco Dolstra 2014-12-14 03:19:15 +01:00
parent 4e0607369e
commit 2142f47c06
4 changed files with 127 additions and 43 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
doc/manual/expressions/simple-expression.xml
View file

@ -4,7 +4,7 @@
version="5.0"
xml:id="ch-simple-expression">
<title>Simple Nix Expression Use-Case</title>
<title>A Simple Nix Expression</title>
<para>This section shows how to add and test the <link
xlink:href='http://www.gnu.org/software/hello/hello.html'>GNU Hello
@ -44,4 +44,4 @@ need to do three things:
<xi:include href="simple-building-testing.xml" />
<xi:include href="generic-builder.xml" />
</chapter>
</chapter>

50
doc/manual/packages/copy-closure.xml Normal file
View file

@ -0,0 +1,50 @@
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="ssec-copy-closure">
<title>Copying Closures</title>
<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 $(nix-store -qR $(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 $(nix-store -qR $(type -p firefox)) | bzip2 | \
ssh alice@itchy.example.org "bunzip2 | nix-store --import"</screen>
However, <command>nix-copy-closure</command> is generally more
efficient because it only copies paths that are not already present in
the target Nix store.</para>
</section>

43
doc/manual/packages/sharing-packages.xml
View file

@ -12,46 +12,7 @@ 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 $(nix-store -qR $(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 $(nix-store -qR $(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>
<xi:include href="copy-closure.xml" />
<xi:include href="ssh-substituter.xml" />
</chapter>

73
doc/manual/packages/ssh-substituter.xml Normal file
View file

@ -0,0 +1,73 @@
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="ssec-ssh-substituter">
<title>Serving a Nix store via SSH</title>
<para>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 <literal>avalon</literal>:
<screen>
$ nix-env -i firefox --option ssh-substituter-hosts alice@avalon
</screen>
This works similar to the binary cache substituter that Nix usually
uses, only using SSH instead of HTTP: if a store path
<literal>P</literal> is needed, Nix will first check if it’s available
in the Nix store on <literal>avalon</literal>. If not, it will fall
back to using the binary cache substituter, and then to building from
source.</para>
<note><para>The SSH substituter currently does not allow you to enter
an SSH passphrase interactively. Therefore, you should use
<command>ssh-add</command> to load the decrypted private key into
<command>ssh-agent</command>.</para></note>
<para>You can also copy the closure of some store path, without
installing it into your profile, e.g.
<screen>
$ nix-store -r /nix/store/m85bxg…-firefox-34.0.5 --option ssh-substituter-hosts alice@avalon
</screen>
This is essentially equivalent to doing
<screen>
$ nix-copy-closure --from alice@avalon /nix/store/m85bxg…-firefox-34.0.5
</screen>
</para>
<para>You can use SSH’s <emphasis>forced command</emphasis> 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 <filename>sshd_config</filename>
to restrict the user <literal>nix-ssh</literal>:
<programlisting>
Match User nix-ssh
AllowAgentForwarding no
AllowTcpForwarding no
PermitTTY no
PermitTunnel no
X11Forwarding no
ForceCommand nix-store --serve
Match All
</programlisting>
On NixOS, you can accomplish the same by adding the following to your
<filename>configuration.nix</filename>:
<programlisting>
nix.sshServe.enable = true;
nix.sshServe.keys = [ "ssh-dss AAAAB3NzaC1k... bob@example.org" ];
</programlisting>
where the latter line lists the public keys of users that are allowed
to connect.</para>
</section>