Description¶
NixOps is a tool for deploying NixOS machines in a network or cloud.
Common options¶
--state
;-s
Path to the state file that contains the deployments. It defaults to the value of the NIXOPS_STATE environment variable, or
~/.nixops/deployments.nixops
if that one is not defined. It must have extension.nixops
. The state file is actually a SQLite database that can be inspected using thesqlite3
command (for example,sqlite3 deployments.nixops .dump
). If it does not exist, it is created automatically.--deployment
;-d
UUID or symbolic name of the deployment on which to operate. Defaults to the value of the NIXOPS_DEPLOYMENT environment variable.
--confirm
Automatically confirm “dangerous” actions, such as terminating EC2 instances or deleting EBS volumes. Without this option, you will be asked to confirm each dangerous action interactively.
--debug
Turn on debugging output. In particular, this causes NixOps to print a Python stack trace if an unhandled exception occurs.
--help
Print a brief summary of NixOps’s command line syntax.
--version
Print NixOps’s version number.
Common options passed along to Nix¶
-I
Append a directory to the Nix search path.
--max-jobs
Set maximum number of concurrent Nix builds.
--cores
Sets the value of the NIX_BUILD_CORES environment variable in the invocation of builders
--keep-going
Keep going after failed builds.
--keep-failed
Keep temporary directories of failed builds.
--show-trace
Print a Nix stack trace if evaluation fails.
--fallback
Fall back on installation from source.
--option
Set a Nix option.
--read-only-mode
Run Nix evaluations in read-only mode.
Environment variables¶
- NIXOPS_STATE
The location of the state file if
--state
is not used. It defaults to~/.nixops/deployments.nixops
.- NIXOPS_DEPLOYMENT
UUID or symbolic name of the deployment on which to operate. Can be overridden using the
-d
option.- EC2_ACCESS_KEY; AWS_ACCESS_KEY_ID
AWS Access Key ID used to communicate with the Amazon EC2 cloud. Used if
deployment.ec2.accessKeyId
is not set in an EC2 machine’s configuration.- EC2_SECRET_KEY; AWS_SECRET_ACCESS_KEY
AWS Secret Access Key used to communicate with the Amazon EC2 cloud. It is only used if no secret key corresponding to the AWS Access Key ID is defined in
~/.ec2-keys
or~/.aws/credentials
.- AWS_SHARED_CREDENTIALS_FILE
Alternative path to the the shared credentials file, which is located in
~/.aws/credentials
by default.- HETZNER_ROBOT_USER; HETZNER_ROBOT_PASS
Username and password used to access the Robot for Hetzner deployments.
- GCE_PROJECT
GCE Project which should own the resources in the Google Compute Engine deployment. Used if
deployment.gce.project
is not set in a GCE machine configuration and ifresources.$TYPE.$NAME.project
is not set in a GCE resource specification.- GCE_SERVICE_ACCOUNT; ACCESS_KEY_PATH
GCE Service Account ID and the path to the corresponding private key in .pem format which should be used to manage the Google Compute Engine deployment. Used if
deployment.gce.serviceAccount
anddeployment.gce.accessKey
are not set in a GCE machine configuration and ifresources.$TYPE.$NAME.serviceAccount
andresources.$TYPE.$NAME.accessKey
are not set in a GCE resource specification.
Files¶
~/.ec2-keys
This file maps AWS Access Key IDs to their corresponding Secret Access Keys. Each line must consist of an Access Key IDs, a Secret Access Keys and an optional symbolic identifier, separated by whitespace. Comments starting with
#
are stripped. An example:AKIABOGUSACCESSKEY BOGUSSECRETACCESSKEY dev # AWS development account AKIABOGUSPRODACCESSKEY BOGUSPRODSECRETACCESSKEY prod # AWS production account
The identifier can be used instead of actual Access Key IDs in
deployment.ec2.accessKeyId
, e.g.deployment.ec2.accessKeyId = "prod";
This is useful if you have an AWS account with multiple user accounts and you don’t want to hard-code an Access Key ID in a NixOps specification.
~/.aws/credentials
This file pairs AWS Access Key IDs with their corresponding Secret Access Keys under symbolic profile names. It consists of sections marked by profile names. Sections contain newline-separated “assignments” of “variables”
aws_access_key_id
andaws_secret_access_key
to a desired Access Key ID and a Secret Access Key, respectively, e.g.:[dev] aws_access_key_id = AKIABOGUSACCESSKEY aws_secret_access_key = BOGUSSECRETACCESSKEY [prod] aws_access_key_id = AKIABOGUSPRODACCESSKEY aws_secret_access_key = BOGUSPRODSECRETACCESSKEY
Symbolic profile names are specified in
deployment.ec2.accessKeyId
, e.g.:deployment.ec2.accessKeyId = "prod";
If an actual Access Key IDs is used in
deployment.ec2.accessKeyId
its corresponding Secret Access Key is looked up under[default]
profile name. Location of credentials file can be customized by setting the AWS_SHARED_CREDENTIALS_FILE environment variable.
Command nixops create
¶
Synopsis¶
nixops create nixexprs -I path Description ———–
This command creates a new deployment state record in NixOps’s database. The paths of the Nix expressions that specify the desired deployment (nixexprs) are stored in the state file. The UUID of the new deployment is printed on standard output.
Options¶
-I
pathAdd path to the Nix expression search path for all future evaluations of the deployment specification. NixOps stores path in the state file. This option may be given multiple times. See the description of the
-I
option in nix-instantiate1 for details.--deployment
;-d
Set the symbolic name of the new deployment to the given string. The name can be used to refer to the deployment by passing the option
-d name
or the environment variableNIXOPS_DEPLOYMENT=name
to subsequent NixOps invocations. This is typically more convenient than using the deployment’s UUID. However, names are not required to be unique; if you create multiple deployments with the same name, NixOps will complain.
Examples¶
To create a deployment with symbolic name foo
, and then perform the
actual deployment:
$ nixops create expr1.nix expr2.nix -d foo
created deployment ‘32b06868-d27c-11e2-a055-81d7beb7925e’
$ nixops deploy -d foo
Command nixops modify
¶
Synopsis¶
nixops modify nixexprs –name -n name -I path Description ———–
This command modifies an existing deployment. The options are the same
as for nixops create
. The symbolic name of the deployment can be
changed using the --name
flag.
Examples¶
To change the Nix expressions specifying the deployment, and rename it
from foo
to bar
:
$ nixops modify -d foo -n bar expr3.nix expr4.nix
Note that -d
identifies the existing deployment, while -n
specifies its new name.
Command nixops clone
¶
Synopsis¶
nixops clone –name -n name Description ———–
This command clones an existing deployment; that is, it creates a new
deployment that has the same deployment specification and parameters,
but a different UUID and (optionally) name. Note that nixops clone
does not currently clone the state of the machines in the existing
deployment. Thus, when you first run nixops deploy
on the cloned
deployment, NixOps will create new instances from scratch.
Examples¶
To create a new deployment bar
by cloning the deployment foo
:
$ nixops clone -d foo -n bar
Command nixops delete
¶
Synopsis¶
nixops delete –all –force Description ———–
This command deletes a deployment from the state file. NixOps will
normally refuse to delete the deployment if any resources belonging to
the deployment (such as virtual machines) still exist. You must run
nixops destroy
first to get rid of any such resources. However, if
you pass --force
, NixOps will forget about any still-existing
resources; this should be used with caution.
If the --all
flag is given, all deployments in the state file are
deleted.
Examples¶
To delete the deployment named foo
:
$ nixops delete -d foo
Command nixops deploy
¶
Synopsis¶
nixops deploy –kill-obsolete -k –dry-run –repair –create-only –build-only –copy-only –check –allow-reboot –force-reboot –allow-recreate –include machine-name –exclude machine-name -I path –max-concurrent-copy N Description ———–
This command deploys a set of machines on the basis of the specification
described by the Nix expressions given in the preceding
nixops create
call. It creates missing virtual machines, builds each
machine configuration, copies the closure of each configuration to the
corresponding machine, uploads any keys described in
deployment.keys
, and activates the new configuration.
Options¶
--kill-obsolete
;-k
Destroy (terminate) virtual machines that were previously created as part of this deployment, but are obsolete because they are no longer mentioned in the deployment specification. This happens if you remove a machine from the specification after having run
nixops deploy
to create it. Without this flag, such obsolete machines are left untouched.--dry-run
Dry run; show what would be done by this command without actually doing it.
--repair
Use –repair when calling nix-build. This is useful for repairing the nix store when some inconsistency is found and nix-copy-closure is failing as a result. Note that this option only works in nix setups that run without the nix daemon.
--create-only
Exit after creating any missing machines. Nothing is built and no existing machines are touched.
--build-only
Just build the configuration locally; don’t create or deploy any machines. Note that this may fail if the configuration refers to information only known after machines have been created (such as IP addresses).
--copy-only
Exit after creating missing machines, building the configuration and copying closures to the target machines; i.e., do everything except activate the new configuration.
--check
Normally, NixOps assumes that the deployment state of machines doesn’t change behind its back. For instance, it assumes that a VirtualBox VM, once started, will continue to run unless you run
nixops destroy
to terminate it. If this is not the case, e.g., because you shut down or destroyed a machine through other means, you should pass the--check
option to tell NixOps to verify its current knowledge.--allow-reboot
Allow NixOps to reboot the instance if necessary. For instance, if you change the type of an EC2 instance, NixOps must stop, modify and restart the instance to effectuate this change.
--force-reboot
Reboot the machine to activate the new configuration (using
nixos-rebuild boot
).--allow-recreate
Recreate resources that have disappeared (e.g. destroyed through mechanisms outside of NixOps). Without this flag, NixOps will print an error if a resource that should exist no longer does.
--include
machine-name…Only operate on the machines explicitly mentioned here, excluding other machines.
--exclude
machine-name…Only operate on the machines that are not mentioned here.
-I
pathAdd path to the Nix expression search path. This option may be given multiple times and takes precedence over the
-I
flags used in the precedingnixops create
invocation. See the description of the-I
option in nix-instantiate1 for details.--max-concurrent-copy
NUse at most N concurrent
nix-copy-closure
processes to deploy closures to the target machines. N defaults to 5.
Examples¶
To deploy all machines:
$ nixops deploy
To deploy only the logical machines foo
and bar
, checking
whether their recorded deployment state is correct:
$ nixops deploy --check --include foo bar
To create any missing machines (except foo
) without doing anything
else:
$ nixops deploy --create-only --exclude foo
Command nixops destroy
¶
Synopsis¶
nixops destroy –all –include machine-name –exclude machine-name Description ———–
This command destroys (terminates) all virtual machines previously
created as part of this deployment, and similarly deletes all disk
volumes if they’re marked as “delete on termination”. Unless you pass
the --confirm
option, you will be asked to approve every machine
destruction.
This command has no effect on machines that cannot be destroyed
automatically; for instance, machines in the none
target environment
(such as physical machines, or virtual machines not created by NixOps).
Options¶
--all
Destroy all deployments.
--include
machine-name…Only destroy the machines listed here.
--exclude
machine-name…Destroy all machines except the ones listed here.
Examples¶
To destroy all machines:
$ nixops destroy
To destroy the machine named foo
:
$ nixops destroy --include foo
Command nixops stop
¶
Synopsis¶
nixops stop –include machine-name –exclude machine-name Description ———–
This command stops (shuts down) all non-obsolete machines that can be
automatically started. This includes EC2 and VirtualBox machines, but
not machines using the none
backend (because NixOps doesn’t know how
to start them automatically).
Options¶
--include
machine-name…Only stop the machines listed here.
--exclude
machine-name…Stop all machines except the ones listed here.
Examples¶
To stop all machines that support being stopped:
$ nixops stop
Command nixops start
¶
Synopsis¶
nixops start –include machine-name –exclude machine-name Description ———–
This command starts all non-obsolete machines previously stopped using
nixops stop
.
Options¶
--include
machine-name…Only start the machines listed here.
--exclude
machine-name…Start all machines except the ones listed here.
Examples¶
To start all machines that were previously stopped:
$ nixops start
Command nixops list
¶
Synopsis¶
nixops list Description ———–
This command prints information about all deployments in the database: the UUID, the name, the description, the number of running or stopped machines, and the types of those machines.
Examples¶
$ nixops list
+--------------------------------------+------------------------+------------------------+------------+------------+
| UUID | Name | Description | # Machines | Type |
+--------------------------------------+------------------------+------------------------+------------+------------+
| 80dc8e11-287d-11e2-b05a-a810fd2f513f | test | Test network | 4 | ec2 |
| 79fe0e26-d1ec-11e1-8ba3-a1d56c8a5447 | nixos-systemd-test | Unnamed NixOps network | 1 | virtualbox |
| 742c2a4f-0817-11e2-9889-49d70558c59e | xorg-test | NixOS X11 Updates Test | 0 | |
+--------------------------------------+------------------------+------------------------+------------+------------+
Command nixops info
¶
Synopsis¶
nixops info –all –plain –no-eval Description ———–
This command prints some information about the current state of the deployment. For each machine, it prints:
The logical name of the machine.
Its state, which is one of
New
(not deployed yet),Up
(created and up to date),Outdated
(created but not up to date with the current configuration, e.g. due to use of the--exclude
option tonixops deploy
) andObsolete
(created but no longer present in the configuration).The type of the machine (i.e. the value of
deployment.targetEnv
, such asec2
). For EC2 machines, it also shows the machine’s region or availability zone.The virtual machine identifier, if applicable. For EC2 machines, this is the instance ID. For VirtualBox VMs, it’s the virtual machine name.
The IP address of the machine. This is its public IP address, if it has one, or its private IP address otherwise. (For instance, VirtualBox machines only have a private IP address.)
Options¶
--all
Print information about all resources in all known deployments, rather than in a specific deployment.
--plain
Print the information in a more easily parsed format where columns are separated by tab characters and there are no column headers.
--no-eval
Do not evaluate the deployment specification. Note that as a consequence the “Status” field in the output will show all machines as “Obsolete” (since the effective deployment specification is empty).
Examples¶
$ nixops info -d foo
Network name: test
Network UUID: 80dc8e11-287d-11e2-b05a-a810fd2f513f
Network description: Test network
Nix expressions: /home/alice/test-network.nix
+----------+-----------------+------------------------------+------------+-----------------+
| Name | Status | Type | VM Id | IP address |
+----------+-----------------+------------------------------+------------+-----------------+
| backend0 | Up / Outdated | ec2 [us-east-1b; m2.2xlarge] | i-905e9def | 23.23.12.249 |
| backend1 | Up / Outdated | ec2 [us-east-1b; m2.2xlarge] | i-925e9ded | 184.73.128.122 |
| backend2 | Up / Obsolete | ec2 [us-east-1b; m2.2xlarge] | i-885e9df7 | 204.236.192.216 |
| frontend | Up / Up-to-date | ec2 [us-east-1c; m1.large] | i-945e9deb | 23.23.161.169 |
+----------+-----------------+------------------------------+------------+-----------------+
Command nixops check
¶
Synopsis¶
nixops check –all Description ———–
This command checks and prints the status of each machine in the deployment. For instance, for an EC2 machine, it will ask EC2 whether the machine is running or stopped. If a machine is supposed to be up, NixOps will try to connect to the machine via SSH and get the current load average statistics.
Options¶
--all
Check all machines in all known deployments, rather than in a specific deployment.
Examples¶
For a running VirtualBox instance, NixOps will print something like:
$ nixops check
machine> VM state is ‘running’
machine> pinging SSH... up [1.03 0.34 0.12]
For a stopped EC2 instance, NixOps might show:
machine> instance state is ‘stopped’
Command nixops ssh
¶
Synopsis¶
nixops ssh username @ machine command args Description ———–
This command opens an SSH connection to the specified machine and
executes the specified command. If no command is specified, an
interactive shell is started. If no user is specified, the machines
deployment.targetUser
is used.
Options¶
--include-keys
Include the public SSH host keys into .ssh/known_hosts for all machines in the imported network.
Examples¶
To start a shell on machine foo
:
$ nixops ssh foo
To run Emacs on machine bar
:
$ nixops ssh bar -- -X emacs
Passes -X
(“enable X11 forwarding”) to SSH.
Command nixops ssh-for-each
¶
Synopsis¶
nixops ssh-for-each –parallel -p –include machine-name –exclude machine-name command args Description ———–
This operation executes the specified shell command on all non-obsolete machines.
Options¶
--parallel
Execute the command on each machine in parallel. The default is to do each machine sequentially.
--include
machine-name…Execute the command only on the machines listed here.
--exclude
machine-name…Execute the command on all machines except the ones listed here.
Examples¶
To reboot all machines in parallel:
$ nixops ssh-for-each -p reboot
Command nixops mount
¶
Synopsis¶
nixops mount –option -o option username @ machine : remote local Description ———–
This command mounts the directory remote in the file system of the
specified machine onto the directory local in the local file system. If
:remote
is omitted, the entire remote file system is mounted. If you
specify an empty path (i.e. :
), then the home directory of the
specified user is mounted. If no user is specified, the machines
deployment.targetUser
is used.
This command is implemented using sshfs
, so you must have sshfs
installed and the fuse
kernel module loaded.
Options¶
--option
/-o
optPass additional options to
sshfs
. See sshfs1 for details.
Examples¶
To mount the entire file system of machine foo
onto the local
directory ~/mnt
:
$ nixops mount foo ~/mnt
$ ls -l ~/mnt
total 72
drwxr-xr-x 1 root root 4096 Jan 15 11:44 bin
drwx------ 1 root root 4096 Jan 14 17:15 boot
…
To mount the home directory of user alice
:
$ nixops mount alice@foo: ~/mnt
To mount a specific directory, passing the option transform_symlinks
to ensure that absolute symlinks in the remote file system work
properly:
$ nixops mount foo:/data ~/mnt -o transform_symlinks
Command nixops reboot
¶
Synopsis¶
nixops reboot –include machine-name –exclude machine-name –no-wait command args Description ———–
This command reboots all non-obsolete machines in parallel.
Options¶
--include
machine-name…Only reboot the machines listed here.
--exclude
machine-name…Reboot all machines except the ones listed here.
--no-wait
Do not wait until the machines have finished rebooting.
Examples¶
To reboot all machines except foo
and wait until they’re up again,
that is, are reachable via SSH again:
$ nixops reboot --exclude foo
Command nixops backup
¶
Synopsis¶
nixops backup –include machine-name –exclude machine-name Description ———–
This command makes a backup of all persistent disks of all machines. Currently this is only implemented for EC2 EBS instances/volumes.
Options¶
--include
machine-name…Only backup the persistent disks of the machines listed here.
--exclude
machine-name…Backup the persistent disks of all machines except the ones listed here.
Examples¶
To backup the persistent disks of all machines:
$ nixops backup
Command nixops restore
¶
Synopsis¶
nixops restore –include machine-name –exclude machine-name –backup-id backup-id Description ———–
This command restores a machine to a backup.
Options¶
--include
machine-name…Only backup the persistent disks of the machines listed here.
--exclude
machine-name…Restore the persistent disks of all machines to a given backup except the ones listed here.
--devices
device-name…Restore only the persistent disks which are mapped to the specified device names.
--backup-id
backup-idRestore the persistent disks of all machines to a given backup except the ones listed here.
Examples¶
To list the available backups and restore the persistent disks of all machines to a given backup:
$ nixops backup-status
$ nixops restore --backup-id 20120803151302
Restore the persistent disks at device /dev/xvdf of all machines to a given backup:
$ nixops restore --devices /dev/xvdf --backup-id 20120803151302
Command nixops show-option
¶
Synopsis¶
nixops show-option –xml machine option Description ———–
This command prints the value of the specified NixOS configuration option for the specified machine.
Examples¶
$ nixops show-option machine services.xserver.enable
false
$ nixops show-option --xml machine boot.initrd.availableKernelModules
<?xml version='1.0' encoding='utf-8'?>
<expr>
<list>
<string value="md_mod" />
<string value="raid0" />
…
</list>
</expr>
Command nixops set-args
¶
Synopsis¶
nixops set-args –arg name value –argstr name value –unset name Description ———–
This command persistently sets arguments to be passed to the deployment specification.
Options¶
--arg
name valueSet the function argument name to value, where the latter is an arbitrary Nix expression.
--argstr
name valueLike
--arg
, but the value is a literal string rather than a Nix expression. Thus,--argstr name value
is equivalent to--arg name \"value\"
.--unset
nameRemove a previously set function argument.
Examples¶
Consider the following deployment specification (servers.nix
):
{ nrMachines, active }:
with import <nixpkgs/lib>;
let
makeMachine = n: nameValuePair "webserver-${toString n}"
({ config, pkgs, ... }:
{ deployment.targetEnv = "virtualbox";
services.httpd.enable = active;
services.httpd.adminAddr = "foo@example.org";
});
in listToAttrs (map makeMachine (range 1 nrMachines))
This specifies a network of nrMachines identical VirtualBox VMs that run the Apache web server if active is set. To create 10 machines without Apache:
$ nixops create servers.nix
$ nixops set-args --arg nrMachines 10 --arg active false
$ nixops deploy
Next we can enable Apache on the existing machines:
$ nixops set-args --arg active true
$ nixops deploy
or provision additional machines:
$ nixops set-args --arg nrMachines 20
$ nixops deploy
Command nixops show-console-output
¶
Synopsis¶
nixops show-console-output machine Description ———–
This command prints the console output of the specified machine, if available. Currently this is only supported for the EC2 backend.
Examples¶
$ nixops show-console-output machine
Xen Minimal OS!
[ 0.000000] Initializing cgroup subsys cpuset
[ 0.000000] Initializing cgroup subsys cpu
[ 0.000000] Linux version 3.2.36 (nixbld@) (gcc version 4.6.3 (GCC) ) #1 SMP Fri Jan 4 16:07:14 UTC 2013
…
Command nixops export
¶
Synopsis¶
nixops export –all Description ———–
This command exports the state of the specified deployment, or all
deployments if --all
is given, as a JSON representation to standard
output. The deployment(s) can be imported into another state file using
nixops import
.
Examples¶
To export a specific deployment, and import it into the state file
other.nixops
:
$ nixops export -d foo > foo.json
$ nixops import -s other.nixops < foo.json
added deployment ‘2bbaddca-01cb-11e2-88b2-19d91ca51c50’
If desired, you can then remove the deployment from the old state file:
$ nixops delete -d foo --force
To export all deployments:
$ nixops export --all > all.json
Command nixops import
¶
Synopsis¶
nixops import –include-keys Description ———–
This command creates deployments from the state data exported by
nixops export
. The state is read from standard input. See
nixops export
for examples.
Command nixops send-keys
¶
Synopsis¶
nixops send-keys –include machine-name –exclude machine-name Description ———–
This command uploads the keys described in deployment.keys
to remote
machines in the /run/keys/
directory.
Keys are not persisted across reboots by default. If a machine reboot
is triggered from outside nixops
, it will need nixops send-keys
to repopulate its keys.
Note that nixops deploy
does an implicit send-keys
where
appropriate, so manually sending keys is only necessary after unattended
reboots.
Options¶
--include
machine-name…Only operate on the machines explicitly mentioned here, excluding other machines.
--exclude
machine-name…Only operate on the machines that are not mentioned here.