Configuration and Administration¶

The nixbuild.net Shell¶

nixbuild.net does not have a web frontend for administrating your account. Instead all administration and configuration is done through a terminal-based shell accessible over SSH like this:

ssh eu.nixbuild.net shell

By default, the SSH key you used when registering is used both for performing Nix builds and for accessing the administration shell. You can, however, add more SSH keys to your account and give the keys different permissions within your account. It doesn't matter what user name you connect with, only your SSH key will be checked. This also means that the same SSH keys can't be added to multiple nixbuild.net accounts.

The nixbuild.net shell doesn't yet have support for command history or many other features that you could expect from a proper shell. However, you can use the rlwrap program to mitigate this:

rlwrap ssh eu.nixbuild.net shell

This will make things like Up/Down arrow keys and CTRL-R work as you would expect.

The greeting screen showed each time you log in to the shell also includes a list of all top-level commands, and instructions on how the help system works:

••••••••••••••••••••••••••••
••••••• nixbuild.net •••••••
••••••••••••••••••••••••••••

Welcome to nixbuild.net!

This shell allows you to administer your account
and retrieve information about your nix builds.

Account id: IIERI7
Unbilled CPU hours: 0
Free build time left: 49:59:59

Available shell commands:

  help         Show help
  settings     Configure account or SSH key
               settings
  usage        Show resource usage
  ssh-keys     Manage your public SSH keys
  billing      Billing activation and info
  signing-keys Manage Nix signing keys
  tokens       Manage auth tokens
  builds       Manage builds

Run 'help COMMAND' for help on individual shell commands.
For help on subcommands run 'COMMAND SUBCOMMAND --help'.
For more documentation, see:
https://docs.nixbuild.net/configuration

Account Usage¶

To see how much you've been using nixbuild.net, run the usage command:

nixbuild.net> usage

Resources used since 2021-03-01
--------------------
Build count       : 51
Successful builds : 51
Wall time         : 5.79 s
CPU time          : 6.26 s

The usage metrics only includes non-discarded builds and includes any free build time consumed.
To find out your currently accumulated cost, or see past invoices, use the 'billing info' command.

By default, the usage command will show your usage during the current month. You can also show the previous month's usage with the -l option and the total usage with the -t option:

nixbuild.net> usage -h
usage - Show resource usage

Usage: usage [(-t|--total) | (-l|--last-month) | (-m|--this-month)]

Available options:
  -t,--total               Show total usage
  -l,--last-month          Show last month's usage
  -m,--this-month          Show this month's usage (default)
  -h,--help                Show this help text

To get information on how much money you've spent on builds, use the billing commands.

Settings¶

You can manage your nixbuild.net settings with the settings command.

Show all account settings by running settings --show:

nixbuild.net> settings --show
Account settings
----------------
  access-tokens             <no entries>
  always-substitute         true
  caches                    <no entries>
  inject-fs-randomness      false
+ keep-builds-running       true
  max-cpu-hours-per-month   2000
  reuse-build-failures      true
  reuse-build-timeouts      false
  substituters              https://cache.nixos.org
  trusted-public-keys       cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY=
  settings-from-drv-env false
  settings-from-ssh-env true

Settings with a '+' sign have been assigned a value, others are using system defaults.

Set, get and reset individual settings with settings <SETTING>:

nixbuild.net> settings keep-builds-running --set true

nixbuild.net> settings keep-builds-running --show
keep-builds-running true

nixbuild.net> settings keep-builds-running --reset

nixbuild.net> settings keep-builds-running --show
keep-builds-running false

Complex settings like lists have the options --add and --remove instead of --set.

You can define settings that is only used when a specific SSH key is used for accessing nixbuild.net. Those settings will then override the account-level settings. To set key-specific settings add the option --ssh-key <key id> to the settings commands. The you can list your SSH key ids with the ssh-keys list command (the key id is the last column).

You can revert all account settings by running settings --reset. Note that this doesn't revert any of the settings you might have configured for individual SSH keys. To revert key-specific settings, run settings --ssh-key <key id> --reset.

SSH Keys¶

You can list, add and remove ssh keys associated with your account using the ssh-keys command:

Usage: ssh-keys COMMAND

  Manage your public SSH keys

Available options:
  -h,--help                Show this help text

Available commands:
  list                     List the public SSH keys identifying your
                           account
  add                      Add a public SSH key to your account
  remove                   Remove a public SSH key from your account

NOTE: Settings for SSH keys are no longer configured here, use the
'settings' commands with the '--ssh-key' option instead.

Binary Caches¶

Substitution¶

nixbuild.net supports fetching build dependencies from binary caches. This can make builds a lot faster, especially if your network upload speed is poor.

By default nixbuild.net uses cache.nixos.org to perform substitution, just like an ordinary Nix installation does. You can disable substitution by setting substituters to an empty list. You can also add other substituters that you want nixbuild.net to use when it runs your builds. Remember that when adding new substituters you also need to add their public keys using the trusted-public-keys setting. The substituters and trusted-public-keys settings work the same in nixbuild.net as they do for a local Nix installation.

nixbuild.net only supports substituting from publicly available HTTP caches. If you need support for using private substituters, 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.

Uploading to external caches¶

nixbuild.net also supports uploading store paths to external caches. Any cache added to the caches setting will be populated with the transitive closure of the build's inputs and outputs. Uploading of a build's inputs happens in parallel to running the build, and the outputs are uploaded as soon as the build finishes.

Utilizing nixbuild.net for performing cache uploads means that you don't have to do that yourself as an extra step after the build is done. If also combined with remote store building, you can cut down network traffic to a minimum which can really improve performance in some cases.

Currently, nixbuild.net only supports uploading to Cachix caches. See the documentation of the caches setting for instruction on how to configure Cachix caches. If you would like to see support for additional cache types in nixbuild.net, please contact [email protected].

Using nixbuild.net as a substituter¶

You can set up Nix to use nixbuild.net as a substituter on your local machine or CI builder. This can improve performance in some situtations, and it is very useful in custom CI setups where you want to integrate nixbuild.net. Note that even if you set up nixbuild.net as a substituter, you still need to use an SSH key to access it.

To set up nixbuild.net as a substituter, first fetch your public signing key through the shell:

nixbuild.net> signing-keys account-keys
nixbuild.net/bob-1:8tJU22/XxyINhP+wM65gwSIlg0rrQrmWhFf5+8u8F/s=

Then add the substituter and signing key to your existing configuration in nix.conf:

substituters = ... ssh://eu.nixbuild.net
trusted-public-keys = ... nixbuild.net/bob-1:8tJU22/XxyINhP+wM65gwSIlg0rrQrmWhFf5+8u8F/s=

You can use trusted-substituters instead of substituters to not use nixbuild.net as a substituter by default, but make it available for selection on the command line.

Billing¶

The billing commands let you manage billing for your account:

nixbuild.net> billing --help
billing - Billing activation and info

Usage: billing SUBCOMMAND

Available options:
  -h,--help                Show this help text

Available subcommands:
  activate                 Enable non-free usage
  edit                     Edit your credit card details
  info                     Display billing details

To be able to use nixbuild.net beyond the initial free build hours you need to enable billing by running billing activate. You can do this at any time, and as soon as you've done it your account will be able to run non-free builds. If you run out of free build hours before you have activated billing, you will not be able to run any more builds. As soon as you activate billing, you will be able to run builds again.

When activating billing, you will be directed to a Stripe-hosted web page where you can enter your billing address and credit card details. When running billing activate you need to provide your company name or full name (for personal accounts) like this:

nixbuild.net> billing activate Acme LLC

Billing has been activated for your account.
You will now be able to use nixbuild.net beyond your free CPU hours.
If you still have free CPU hours left, you will not be charged until they have been used up.

IMPORTANT: Visit the time-limited url below to enter your credit card details and billing address.

https://billing.stripe.com/session/_J7U1XtINfG0dMoQayAJegz3kcfSsryu

If you want to change your payment method after the above url has expired, use the command 'billing edit'.
If you need to make any other billing changes, please contact [email protected].
If you fail to provide valid billing details your account may be locked.

If you need to change your credit card details at any time, you can use the billing edit command. If you need to change any other billing details, you must contact [email protected].

The billing info command lets you see the amount of the upcoming invoice, as well as past invoices.

List Builds¶

Use the command builds list -r to list your currently running builds:

nixbuild.net> builds list -r
70196 2020-08-23 21:05:10Z 3.21 s 1 CPU [In queue]
      /nix/store/ky3fzyaw0hibjpkpyx8s89fhaprxhrba-zlib-1.2.11.drv

70195 2020-08-23 21:05:10Z 3.66 s 1 CPU [In queue]
      /nix/store/k8ir9nqbqhlriqs6r97vi19im5rn9nkd-xz-5.2.5.drv

70194 2020-08-23 21:05:09Z 3.40 s 4 CPUs [Running]
      /nix/store/5k1i3j15dzqkf8rcga0ap7fjk1q7xj9a-perl-5.30.3.drv

70193 2020-08-23 21:05:08Z 4.18 s 2 CPUs [Running]
      /nix/store/7cgb9m0dm9facpzqbyfkz1i0snd2n1y7-gnum4-1.4.18.drv

Remove the -r option to also show historic builds. By default, at most 500 builds are listed, but that can be adjusted with the -l option.