From 2142f47c0606aac6f0b66bc3fe25fe79fc85e7d8 Mon Sep 17 00:00:00 2001 From: Eelco Dolstra Date: Sun, 14 Dec 2014 03:19:15 +0100 Subject: [PATCH] Add section on SSH substituter --- doc/manual/expressions/simple-expression.xml | 4 +- doc/manual/packages/copy-closure.xml | 50 ++++++++++++++ doc/manual/packages/sharing-packages.xml | 43 +----------- doc/manual/packages/ssh-substituter.xml | 73 ++++++++++++++++++++ 4 files changed, 127 insertions(+), 43 deletions(-) create mode 100644 doc/manual/packages/copy-closure.xml create mode 100644 doc/manual/packages/ssh-substituter.xml diff --git a/doc/manual/expressions/simple-expression.xml b/doc/manual/expressions/simple-expression.xml index a8eb96f5a..29fd872ee 100644 --- a/doc/manual/expressions/simple-expression.xml +++ b/doc/manual/expressions/simple-expression.xml @@ -4,7 +4,7 @@ version="5.0" xml:id="ch-simple-expression"> -Simple Nix Expression Use-Case +A Simple Nix Expression This section shows how to add and test the GNU Hello @@ -44,4 +44,4 @@ need to do three things: - \ No newline at end of file + diff --git a/doc/manual/packages/copy-closure.xml b/doc/manual/packages/copy-closure.xml new file mode 100644 index 000000000..5ec7896d8 --- /dev/null +++ b/doc/manual/packages/copy-closure.xml @@ -0,0 +1,50 @@ +
+ +Copying Closures + +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 $(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/packages/sharing-packages.xml b/doc/manual/packages/sharing-packages.xml index 8fab15f7e..586363b03 100644 --- a/doc/manual/packages/sharing-packages.xml +++ b/doc/manual/packages/sharing-packages.xml @@ -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. -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 $(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" - -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. - + + diff --git a/doc/manual/packages/ssh-substituter.xml b/doc/manual/packages/ssh-substituter.xml new file mode 100644 index 000000000..f24f354c4 --- /dev/null +++ b/doc/manual/packages/ssh-substituter.xml @@ -0,0 +1,73 @@ +
+ +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: + + +$ nix-env -i firefox --option ssh-substituter-hosts 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. + +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. + + +$ nix-store -r /nix/store/m85bxg…-firefox-34.0.5 --option ssh-substituter-hosts alice@avalon + + +This is essentially equivalent to doing + + +$ 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.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. + +