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):
-
System configuration (default settings) — Not configurable by the end user.
-
Account configuration — Settings that are used for all users of the same account. Configurable by end users through the nixbuild.net shell.
-
SSH key configuration — Settings that are used for a specific SSH key. Configurable by end users through the nixbuild.net shell.
-
SSH environment configuration — Settings used for a specific SSH session. Configurable by end users through their SSH client configuration.
-
Nix derivation configuration — Settings used for a specific build. Configurable by end users by setting special attributes in their Nix derivations.
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.