Settings Reference

There are a number of settings available that can impact how nixbuild.net behaves when you use the service. The settings are represented as a flat list of key-value pairs. All settings have reasonable default values so you don't need to change anything, but it is recommended to read through this page to get a feeling for what is possible.

Some settings are named the same as standard Nix settings. These settings should have the same meaning in nixbuild.net as they have in Nix. Other settings are unique to nixbuild.net.

Settings can be configured on the following levels, in order of significance (settings defined later in this list overrides earlier settings):

1. System configuration (default settings) — Not configurable by the end user.

2. Account configuration — Settings that are used for all users of the same account. Configurable by end users through the nixbuild.net shell.

3. SSH key configuration — Settings that are used for a specific SSH key. Configurable by end users through the nixbuild.net shell.

4. SSH environment configuration — Settings used for a specific SSH session. Configurable by end users through their SSH client configuration. You must have set settings-from-ssh-env to true, otherwise the SSH environment settings are ignored. By default, settings-from-ssh-env is true.

5. Nix derivation configuration — Settings used for a specific build. Configurable by end users by setting special attributes in their Nix derivations. You must have set settings-from-drv-env to true, otherwise the derivation settings are ignored. By default, settings-from-drv-env is false.

6. Nix client settings — Nix allows some settings to be specified directly on the command line when running a build. Some of these settings will be passed on to remote builders. Unfortunately, very few of the available Nix settings are passed on, and it also varies depending how you run your build (if you use ssh:// or ssh-ng://, remote builds or remote stores). nixbuild.net tries to make the best of the situation and picks up any settings passed on to it. There are improvements needed in this area, both in Nix and nixbuild.net.

Configuration

Account

See the nixbuild.net shell documentation for instructions on how to configure account-wide settings.

SSH Key

You can override account settings for specific SSH keys. See the nixbuild.net shell documentation for instructions on how to configure key-specific overrides.

SSH Environment

Only used if settings-from-ssh-env is true (which is the default).

You can use the SetEnv option of OpenSSH to configure nixbuild.net via your SSH session. Each setting needs to capitalized, prepended with NIXBUILDNET_ and hyphens should be replace with underscores. This is an example of how your SSH client config could look like:

Host eu.nixbuild.net
  SetEnv NIXBUILDNET_KEEP_BUILDS_RUNNING=true NIXBUILDNET_REUSE_BUILD_FAILURES=false

Boolean true values are encoded with true or 1. False values are encoded with false, 0 or an empty string. For list settings (like substituters, caches etc) entries should be separated by a space or a comma.

You can make use of host aliases in you ssh configuration to create "virtual" builders that configure nixbuild.net in different ways.

The SetEnv option was added in OpenSSH 7.8. If you use an older version you can look into the SendEnv option, which works slightly differently.

Nix Derivation

Only used if settings-from-drv-env is true (which is not the default).

Use derivation attributes to use specific settings for individual builds:

mkDerivation {
  name = "...";
  src = ...;

  NIXBUILDNET_KEEP_BUILDS_RUNNING = true;
}

The variable names use the same format as the ssh environment does.

Available Settings

access-tokens

List of access tokens, default empty.

Defines tokens that are used to access private resources. This works much in the same way as the identically named Nix setting.

Currently, the only kind of token supported is Cachix per-cache auth tokens. These are used when uploading store paths directly from nixbuild.net to Cachix (see the caches setting).

The format used for storing Cachix auth tokens in the access-tokens setting is cachix://<CACHE>=<TOKEN>. So, to add an auth token for the Cachix cache mycache you would run:

nixbuild.net> settings access-tokens --add cachix://mycache=<TOKEN>

To remove an access token, use --remove and leave out the actual token, like this:

nixbuild.net> settings access-tokens --remove cachix://mycache

The tokens you add are stored for your account in nixbuild.net. You should take care and try to use tokens with limited capabilities and short expiration times. An even better approach is to not store the tokens in the account settings or SSH key setting at all, but instead use the SSH environment. That way, the tokens will disappear from nixbuild.net when your SSH session ends. To pass access tokens in the SSH environment configure SSH like this:

SetEnv NIXBUILDNET_ACCESS_TOKENS=cachix://mycache=<TOKEN>

Multiple tokens can be separated by spaces or commas.

always-substitute

Boolean, default true

If enabled, nixbuild.net will ignore the builders-use-substitutes setting reported by your Nix client, and always try to perform substitution from the binary caches configured for your account.

caches

List of URLs, default empty.

The caches setting defines external caches that should be populated automatically by nixbuild.net during builds.

If assigned, nixbuild.net will upload the transitive closures of all inputs and outputs for every build that is executed, to all caches listed. nixbuild.net will perform upload of build inputs in parallel with running the build, to save time.

Currently, only Cachix caches are supported. You need to use a cache where the signing key is managed by Cachix, and have a write per-cache token for your cache. The token must be added to the access-tokens setting.

The format used for storing Cachix caches in the caches settings is cachix://<CACHE>. So, to add a Cachix cache named mycache, and its auth token you would run:

nixbuild.net> settings caches --add cachix://mycache
nixbuild.net> settings access-tokens --add cachix://mycache=<TOKEN>

If you would like to see support for other types of caches in addition to Cachix, please contact [email protected].

See also ignore-cache-failures.

default-permissions

List of permissions, defaults to all permissions.

The default-permissions setting specifies what permissions are authorized when connecting to an auth token when connecting to nixbuild.net, the default-permissions nixbuild.net without using an auth token. If you are using an auth token this setting will be ignored.

If you don't need the control and flexibility that auth tokens provide, default-permissions offers a simple way to restrict SSH keys to some operations. A typical use case is to only allow a specific SSH key to be used to make administrative changes to your nixbuild.net account. To achieve this, run the following shell commands:

nixbuild.net> settings default-permissions --remove account:read --remove account-write
nixbuild.net> settings default-permissions --ssh-key my-admin-key --add account:read --add account-write

The first command removes the account:read and account:write permissions from the account (that is, all current and future SSH keys). The second command re-adds those permissions to the SSH key with id my-admin-key.

ignore-cache-failures

Boolean, default false

If ignore-cache-failures is false, any failure in uploading build inputs or outputs to the configured caches will fail the build. If set to true, upload failures will be ignored. Note, if a build is failed due to cache upload issues, this will not happen until after the build has finished. This means that if you fix the cache issue and retry the same build, the already produced build result will be used, instead of running the build again.

inject-fs-randomness

Boolean, default false

If enabled, the filesystem within the build sandbox will exhibit random behavior. Currently, this will cause directory entries to be read in a random order, but this feature might be expanded in the future to inject more metadata randomness.

This setting is useful for detecting non-determinism in builds (using the repeat and enforce-determinism options in Nix).

keep-builds-running

Boolean, default false

If enabled, active builds will keep running even if you stop your Nix client or in any other way disconnect from nixbuild.net. The builds will keep running until they are done (or fail). If you re-request a build of such a "disconnected build" nixbuild.net will simply wait for the running build to finish and then deliver the resulting build for your new request.

Please note that disconnected builds incur costs in the same way as normal builds.

max-cpu-hours-per-month

Integer, default 2000

This setting defines how many CPU hours your account can use per month. The setting can be used if you want to set an upper limit for your monthly charges.

If you, for whatever reason, haven't been billed for more than one month, the CPU hour limit set will cover the whole period since the last invoice. So when you set this limit you can always be sure that your next invoice will not exceed it (running builds might still cause the limit to be exceeded, see below).

This setting can only be set on the account level or the SSH key level, not through the SSH environment or Nix derivation.

Note, the limit is about your account's total monthly usage. So you can configure a lower (or higher) limit for a specific SSH key, and as soon as the account's total montly usage has passed that limit, you will not be a able to run any new builds with that particular SSH key. It doesn't matter which SSH keys that have generated the usage.

Running builds will not be terminated if the limit is exceeded, only new builds are affected.

reuse-build-failures

Boolean, default true

When enabled, nixbuild.net will not rebuild a derivation that already has failed for your own or any other account. The derivations (and the content hashes of their inputs) must match exactly in order to be re-used. Only non-transient errors will be re-used.

reuse-build-timeouts

Boolean, default false

If enabled, nixbuild.net will check if any previous build (performed by any account) of the exact same derivation took longer time than the timeout specified (by your Nix client) for the new build. If so, nixbuild.net will not run the build, but instead serve back a timed out build status.

sandbox

Possible values: true, relaxed or false. Defaults to true.

This setting can be used to disable or enable the Nix build sandbox.

Note: This setting is only about the sandboxing used by Nix during the build. Even if the Nix sandbox is disabled, the complete build will run inside a virtual machine that fully isolates builds from each other. This also means that it is impossible for a build to read any files other than the inputs defined in its derivation. However, when the Nix sandbox is disabled, it will be possible for the build to access the network.

If this setting is set to true, only fixed-output derivations will be able to access the network. If set to false, all builds will be able access the network. If set to relaxed, only derivations with the attribute __noChroot set to true (and fixed-output derivations) will have network access. This behaviour is described closer in the documentation of the corresponding setting in Nix.

It is highly recommended to keep this setting on true or relaxed (to be able to opt-in network access for specific builds with __noChroot). Builds that run with network access enabled will not be considered in some cases when nixbuild.net tries to find existing build results that can safely be re-used for new builds. Therefore, setting sandbox to false will slightly limit reusability of your build results. Additionally, having network access enabled also increases the risk of introducing impurities and reproducibility issues in your builds.

substituters

List of URLs, default https://cache.nixos.org/

Defines the list of substituters nixbuild.net should fetch from when running your builds. To disable substitution, remove all entries of this list. This setting is similar to the identically named Nix setting.

Remember that when adding new substituters you also need to add their public keys using the trusted-public-keys setting. If you don't add the trusted public key of the cache, nixbuild.net will not be able to use any fetched closures in your builds, since it only allows using signed and trusted paths.

nixbuild.net only supports substituting from publicly available HTTP caches. If you need support for using private substituters, please contact [email protected].

You can use public Cachix caches for substitution. Simply add a substituter with an URL on the form https://<cache name>.cachix.org. You see the public key of a cache if you visit https://<cache name>.cachix.org in your browser.

This is an example on how to add the nix-community public cache to your list of substituters:

nixbuild.net> settings substituters --add https://nix-community.cachix.org
nixbuild.net> settings trusted-public-keys --add nix-community.cachix.org-1:mB9FSh9qf2dCimDSUo8Zy7bkq5CX+/rkCWyvRCYg3Fs=

You can use different substituter lists depending on which SSH key you use or even depending on your SSH environment.

trusted-public-keys

List of public keys, default cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY=.

Defines which signing keys you want to trust.

The key that is used for signing your builds on nixbuild.net is internally managed by nixbuild.net and implicitly trusted. It is not part of the trusted-public-keys setting.

You should usually make sure that the trusted-public-keys matches the substituters you have configured.

You can use different trusted public key lists depending on which SSH key you use or even depending on your SSH environment. This effectively gives you a way to operate on a subset of the paths available to you in nixbuild.net. If a path is signed by a key not listed in your current list of trusted public keys, that path will be invisible to your Nix client.

settings-from-drv-env

Boolean, default false.

This setting must be set to true in order for Nix derivation configuration to used.

settings-from-ssh-env

Boolean, default true.

This setting must be set to true in order for SSH environment configuration to used.