forked from lix-project/lix
142 lines
5.4 KiB
Markdown
142 lines
5.4 KiB
Markdown
# Remote Builds
|
||
|
||
Nix supports remote builds, where a local Nix installation can forward
|
||
Nix builds to other machines. This allows multiple builds to be
|
||
performed in parallel and allows Nix to perform multi-platform builds in
|
||
a semi-transparent way. For instance, if you perform a build for a
|
||
`x86_64-darwin` on an `i686-linux` machine, Nix can automatically
|
||
forward the build to a `x86_64-darwin` machine, if available.
|
||
|
||
To forward a build to a remote machine, it’s required that the remote
|
||
machine is accessible via SSH and that it has Nix installed. You can
|
||
test whether connecting to the remote Nix instance works, e.g.
|
||
|
||
$ nix ping-store --store ssh://mac
|
||
|
||
will try to connect to the machine named `mac`. It is possible to
|
||
specify an SSH identity file as part of the remote store URI, e.g.
|
||
|
||
$ nix ping-store --store ssh://mac?ssh-key=/home/alice/my-key
|
||
|
||
Since builds should be non-interactive, the key should not have a
|
||
passphrase. Alternatively, you can load identities ahead of time into
|
||
`ssh-agent` or `gpg-agent`.
|
||
|
||
If you get the error
|
||
|
||
bash: nix-store: command not found
|
||
error: cannot connect to 'mac'
|
||
|
||
then you need to ensure that the `PATH` of non-interactive login shells
|
||
contains Nix.
|
||
|
||
> **Warning**
|
||
>
|
||
> If you are building via the Nix daemon, it is the Nix daemon user
|
||
> account (that is, `root`) that should have SSH access to the remote
|
||
> machine. If you can’t or don’t want to configure `root` to be able to
|
||
> access to remote machine, you can use a private Nix store instead by
|
||
> passing e.g. `--store ~/my-nix`.
|
||
|
||
The list of remote machines can be specified on the command line or in
|
||
the Nix configuration file. The former is convenient for testing. For
|
||
example, the following command allows you to build a derivation for
|
||
`x86_64-darwin` on a Linux machine:
|
||
|
||
$ uname
|
||
Linux
|
||
|
||
$ nix build \
|
||
'(with import <nixpkgs> { system = "x86_64-darwin"; }; runCommand "foo" {} "uname > $out")' \
|
||
--builders 'ssh://mac x86_64-darwin'
|
||
[1/0/1 built, 0.0 MiB DL] building foo on ssh://mac
|
||
|
||
$ cat ./result
|
||
Darwin
|
||
|
||
It is possible to specify multiple builders separated by a semicolon or
|
||
a newline, e.g.
|
||
|
||
```
|
||
--builders 'ssh://mac x86_64-darwin ; ssh://beastie x86_64-freebsd'
|
||
```
|
||
|
||
Each machine specification consists of the following elements, separated
|
||
by spaces. Only the first element is required. To leave a field at its
|
||
default, set it to `-`.
|
||
|
||
1. The URI of the remote store in the format
|
||
`ssh://[username@]hostname`, e.g. `ssh://nix@mac` or `ssh://mac`.
|
||
For backward compatibility, `ssh://` may be omitted. The hostname
|
||
may be an alias defined in your `~/.ssh/config`.
|
||
|
||
2. A comma-separated list of Nix platform type identifiers, such as
|
||
`x86_64-darwin`. It is possible for a machine to support multiple
|
||
platform types, e.g., `i686-linux,x86_64-linux`. If omitted, this
|
||
defaults to the local platform type.
|
||
|
||
3. The SSH identity file to be used to log in to the remote machine. If
|
||
omitted, SSH will use its regular identities.
|
||
|
||
4. The maximum number of builds that Nix will execute in parallel on
|
||
the machine. Typically this should be equal to the number of CPU
|
||
cores. For instance, the machine `itchy` in the example will execute
|
||
up to 8 builds in parallel.
|
||
|
||
5. The “speed factor”, indicating the relative speed of the machine. If
|
||
there are multiple machines of the right type, Nix will prefer the
|
||
fastest, taking load into account.
|
||
|
||
6. A comma-separated list of *supported features*. If a derivation has
|
||
the `requiredSystemFeatures` attribute, then Nix will only perform
|
||
the derivation on a machine that has the specified features. For
|
||
instance, the attribute
|
||
|
||
requiredSystemFeatures = [ "kvm" ];
|
||
|
||
will cause the build to be performed on a machine that has the `kvm`
|
||
feature.
|
||
|
||
7. A comma-separated list of *mandatory features*. A machine will only
|
||
be used to build a derivation if all of the machine’s mandatory
|
||
features appear in the derivation’s `requiredSystemFeatures`
|
||
attribute..
|
||
|
||
For example, the machine specification
|
||
|
||
nix@scratchy.labs.cs.uu.nl i686-linux /home/nix/.ssh/id_scratchy_auto 8 1 kvm
|
||
nix@itchy.labs.cs.uu.nl i686-linux /home/nix/.ssh/id_scratchy_auto 8 2
|
||
nix@poochie.labs.cs.uu.nl i686-linux /home/nix/.ssh/id_scratchy_auto 1 2 kvm benchmark
|
||
|
||
specifies several machines that can perform `i686-linux` builds.
|
||
However, `poochie` will only do builds that have the attribute
|
||
|
||
requiredSystemFeatures = [ "benchmark" ];
|
||
|
||
or
|
||
|
||
requiredSystemFeatures = [ "benchmark" "kvm" ];
|
||
|
||
`itchy` cannot do builds that require `kvm`, but `scratchy` does support
|
||
such builds. For regular builds, `itchy` will be preferred over
|
||
`scratchy` because it has a higher speed factor.
|
||
|
||
Remote builders can also be configured in `nix.conf`, e.g.
|
||
|
||
builders = ssh://mac x86_64-darwin ; ssh://beastie x86_64-freebsd
|
||
|
||
Finally, remote builders can be configured in a separate configuration
|
||
file included in `builders` via the syntax `@file`. For example,
|
||
|
||
builders = @/etc/nix/machines
|
||
|
||
causes the list of machines in `/etc/nix/machines` to be included. (This
|
||
is the default.)
|
||
|
||
If you want the builders to use caches, you likely want to set the
|
||
option [`builders-use-substitutes`](#conf-builders-use-substitutes) in
|
||
your local `nix.conf`.
|
||
|
||
To build only on remote builders and disable building on the local
|
||
machine, you can use the option `--max-jobs 0`.
|