Skip to content

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.

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

Some settings can only be configured on some of the levels, this is documented below.

You can limit how settings can be overriden by using the allow-override setting.

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

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_CACHE_BUILD_FAILURES=false

Boolean true values are encoded with true or 1. False values are encoded with false, 0 or an empty string.

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

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

allow-build

Boolean, default true

Enables or disables building on nixbuild.net. This setting can be used if you want to set up SSH keys that only have access to the nixbuild.net shell and can't be used for building Nix derivations.

Also see the related allow-shell setting.

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

allow-override

Boolean, default true

If set to false, settings will be locked and cannot be changed on a lower level.

For example, if you set allow-override = false in your account settings, it is no longer possible to override any settings through SSH key settings, SSH environment settings or Nix derivation settings. Only the settings configured on the account level will be used.

This setting can be used to create locked-down SSH keys for specific scenarios like for example CI builds. To do that, you should add a new SSH key to your account, then disable settings overrides for that key with the following shell command (while still allowing overrides in your account settings):

nixbuild.net> ssh-keys set <KEY_NAME> allow-override false

Then, set any other settings that you want the key to use (either by setting account settings or SSH key settings for that key). If you're setting up a CI account, it could be good to disable shell access. Finally configure the Nix client that you want to lock down to use the specific SSH key. Now you can be sure that any builds run by that Nix client can't use any other settings than the one you've configured.

It is also possible to set allow-override = false in your SSH environment, this will disable settings overrides from the lowest level, Nix derivations.

Note, allow-override disables or enables overrides of all settings. It is currently not possibly to let some settings be overriden.

allow-shell

Boolean, default true

Enables or disables access to the nixbuild.net shell. Anyone with access to the nixbuild.net shell can make any changes to your account (like adding/removing SSH keys, changing settings etc), so in a multi-user setup it could be wise to restrict shell access to selected SSH keys.

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

You can set allow-shell = false on the account level, and then set allow-shell = true for specific SSH keys, or you can do it the other way around (account-wide allow, deny specific keys).

NOTE Be careful not to lock yourself out from the shell! Before exiting your shell session, double-check that allow-shell is set up properly and will leave shell access open for at least one SSH key that you control. If you lock yourself out, contact [email protected] to recover access.

always-substitute

Boolean, default false

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.

cache-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.

cache-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.

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.

never-substitute

Boolean, default false

If enabled, nixbuild.net will ignore both the always-substitute setting and the builders-use-substitutes setting reported by your Nix client, and never perform substitution from binary caches.