Introduction

Colmena is a simple, stateless NixOS deployment tool modeled after NixOps and morph, written in Rust. It's a thin wrapper over Nix commands like nix-instantiate and nix-copy-closure, and supports parallel deployment.

Interested? Get started here!

$ colmena apply --on @tag-a [INFO ] Enumerating nodes... [INFO ] Selected 7 out of 45 hosts. (...) ✅ 0s Build successful sigma 🕗 7s copying path '/nix/store/h6qpk8rwm3dh3zsl1wlj1jharzf8aw9f-unit-haigha-agent.service' to 'ssh://root@sigma.redacted'... theta ✅ 7s Activation successful gamma 🕘 8s Starting... alpha ✅ 1s Activation successful epsilon 🕗 7s copying path '/nix/store/fhh4rfixny8b21l6jqzk7nqwxva5k20h-nixos-system-epsilon-20.09pre-git' to 'ssh://root@epsilon.redacted'... beta 🕗 7s removing obsolete file /boot/kernels/z28ayg10kpnlrz0s2qrb9pzv82lc20s2-initrd-linux-5.4.89-initrd kappa ✅ 2s Activation successful

You are currently reading version 0.4 of the Colmena Manual, built against version 0.4.0.

Tutorial

Installation

colmena is included in Nixpkgs beginning with 21.11.

For this tutorial, use the following command to enter an ephemeral environment with the colmena command:

nix-shell -p colmena

If you are interested in trying out the bleeding-edge version of Colmena, Read the unstable version of the Manual for instructions.

Basic Configuration

If you use Nix Flakes, follow the Flake version here.

Colmena should work with your existing NixOps and morph configurations with minimal modification (see Migrating from NixOps/morph).

Here is a sample hive.nix with two nodes, with some common configurations applied to both nodes:

{
  meta = {
    # Override to pin the Nixpkgs version (recommended). This option
    # accepts one of the following:
    # - A path to a Nixpkgs checkout
    # - The Nixpkgs lambda (e.g., import <nixpkgs>)
    # - An initialized Nixpkgs attribute set
    nixpkgs = <nixpkgs>;

    # You can also override Nixpkgs by node!
    nodeNixpkgs = {
      node-b = ./another-nixos-checkout;
    };

    # If your Colmena host has nix configured to allow for remote builds
    # (for nix-daemon, your user being included in trusted-users)
    # you can set a machines file that will be passed to the underlying
    # nix-store command during derivation realization as a builders option.
    # For example, if you support multiple orginizations each with their own
    # build machine(s) you can ensure that builds only take place on your
    # local machine and/or the machines specified in this file.
    # machinesFile = ./machines.client-a;
  };

  defaults = { pkgs, ... }: {
    # This module will be imported by all hosts
    environment.systemPackages = with pkgs; [
      vim wget curl
    ];

    # By default, Colmena will replace unknown remote profile
    # (unknown means the profile isn't in the nix store on the
    # host running Colmena) during apply (with the default goal,
    # boot, and switch).
    # If you share a hive with others, or use multiple machines,
    # and are not careful to always commit/push/pull changes
    # you can accidentaly overwrite a remote profile so in those
    # scenarios you might want to change this default to false.
    # deployment.replaceUnknownProfiles = true;
  };

  host-a = { name, nodes, ... }: {
    # The name and nodes parameters are supported in Colmena,
    # allowing you to reference configurations in other nodes.
    networking.hostName = name;
    time.timeZone = nodes.host-b.config.time.timeZone;

    boot.loader.grub.device = "/dev/sda";
    fileSystems."/" = {
      device = "/dev/sda1";
      fsType = "ext4";
    };
  };

  host-b = {
    # Like NixOps and Morph, Colmena will attempt to connect to
    # the remote host using the attribute name by default. You
    # can override it like:
    deployment.targetHost = "host-b.mydomain.tld";

    # It's also possible to override the target SSH port.
    # For further customization, use the SSH_CONFIG_FILE
    # environment variable to specify a ssh_config file.
    deployment.targetPort = 1234;

    # Override the default for this target host
    deployment.replaceUnknownProfiles = false;

    # You can filter hosts by tags with --on @tag-a,@tag-b.
    # In this example, you can deploy to hosts with the "web" tag using:
    #    colmena apply --on @web
    # You can use globs in tag matching as well:
    #    colmena apply --on '@infra-*'
    deployment.tags = [ "web" "infra-lax" ];

    time.timeZone = "America/Los_Angeles";

    boot.loader.grub.device = "/dev/sda";
    fileSystems."/" = {
      device = "/dev/sda1";
      fsType = "ext4";
    };
  };
}

The full set of deployment options can be found here.

Now you are ready to use Colmena! To build the configuration:

colmena build

To build and deploy to all nodes:

colmena apply

Next Steps

  • Head to the Features section to see what else Colmena can do.
  • Read more about options available in Colmena in the Reference section.

Usage with Flakes

Installation

colmena is included in Nixpkgs beginning with 21.11.

For this tutorial, use the following command to enter an ephemeral environment with the colmena command:

nix shell nixpkgs#colmena

If you are interested in trying out the bleeding-edge version of Colmena, Read the unstable version of the Manual for instructions.

Basic Configuration

Colmena reads the colmena output in your Flake.

Here is a short example:

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
  };
  outputs = { nixpkgs, ... }: {
    colmena = {
      meta = {
        nixpkgs = import nixpkgs {
          system = "x86_64-linux";
          overlays = [];
        };
      };

      host-a = { name, nodes, pkgs, ... }: {
        boot.isContainer = true;
        time.timeZone = nodes.host-b.config.time.timeZone;
      };
      host-b = {
        deployment = {
          targetHost = "somehost.tld";
          targetPort = 1234;
          targetUser = "luser";
        };
        boot.isContainer = true;
        time.timeZone = "America/Los_Angeles";
      };
    };
  };
}

The full set of deployment options can be found here. You can also check out the example in the main tutorial for some inspiration.

Now you are ready to use Colmena! To build the configuration:

colmena build

To build and deploy to all nodes:

colmena apply

Next Steps

  • Head to the Features section to see what else Colmena can do.
  • Read more about options available in Colmena in the Reference section.

Migrating from NixOps/morph

Colmena should work with existing NixOps and morph configurations with minimal modification. That said, there are a few things to look out for:

Colmena deploys to existing NixOS hosts

Unlike NixOps which can be configured to manage the entire lifecycles of NixOS machines (e.g., spinning up AWS EC2 instances), Colmena can only deploy to hosts already running NixOS.

network vs meta

Colmena accepts a set of options to configure the deployment itself as meta. For NixOps compatibility, it also accepts network as an alias so you don't have to change your existing configuration.

Pinning Nixpkgs

You can pin the nixpkgs version by setting meta.nixpkgs (or network.nixpkgs if you use the alias). This is required if you use Flakes. The options accepts one of the following:

  • Path to a Nixpkgs checkout (not supported in Flakes)
    • Example: ./nixpkgs
  • The Nixpkgs lambda returned by importing its default.nix (not supported in Flakes)
    • Example: import ./nixpkgs
  • A fully initialized Nixpkgs attribute set
    • Example: import ./nixpkgs { system = "x86_64-linux"; }

Features

This section introduces the main features in Colmena:

  • Node Tagging - Deploying to a subset of tagged nodes
  • Local Deployment - Deploying to the host running Colmena itself
  • Secrets - Deploying sensitive files separate from the main configuration
  • Ad Hoc Evaluation - Evaluating a Nix expression with access to your configuration
  • Parallelism - Controlling how Colmena parallelizes the deployment process
  • Remote Builds - Building system profiles on remote machines

Node Tagging

With node tags, you can quickly select a subset of nodes for deployment. You can specify tags using the deployment.tags option:

{
  alpha = { pkgs, ... }: {
    deployment.tags = [ "web" "infra-lax" ];

    # ... Rest of configuration ...
  };
  beta = { pkgs, ... }: {
    deployment.tags = [ "infra-sfo" ];

    # ... Rest of configuration ...
  };
}

You can filter hosts by tags or names with --on, which accepts a comma-separated list of node names or @tags.

To select all nodes with web:

$ colmena apply --on @web

Wildcards are supported as well. To select all nodes with a tag beginning with infra-:

$ colmena apply --on '@infra-*'

(Note the quotes around the argument)

Local Deployment

For some machines, you may still want to stick with the manual nixos-rebuild-type of workflow. Colmena allows you to build and activate configurations on the host running Colmena itself, provided that:

  1. The node must be running NixOS.
  2. The node must have deployment.allowLocalDeployment set to true.
  3. The node's attribute name must match the hostname of the machine.

If you invoke apply-local with --sudo, Colmena will attempt to elevate privileges with sudo if it's not run as root. You may also find it helpful to set deployment.targetHost to null if you don't intend to deploy to the host via SSH.

As an example, the following hive.nix includes a node (laptop) that is meant to be only deployed with apply-local:

{
  meta = {
    nixpkgs = ./deps/nixpkgs-stable;

    # I'd like to use the unstable version of Nixpkgs on
    # my desktop machines.
    nodeNixpkgs = {
      laptop = ./deps/nixpkgs-unstable;
    };
  };

  # This attribute name must match the output of `hostname` on your machine
  laptop = { name, nodes, ... }: {
    networking.hostName = "laptop";

    deployment = {
      # Allow local deployment with `colmena apply-local`
      allowLocalDeployment = true;

      # Disable SSH deployment. This node will be skipped in a
      # normal`colmena apply`.
      targetHost = null;
    };

    # ... Rest of configuration ...
  };

  server-a = { pkgs, ... }: {
    # This node will use the default Nixpkgs checkout specified
    # in `meta.nixpkgs`.

    # ... Rest of configuration ...
  };
}

On laptop, run colmena apply-local --sudo to activate the configuration.

Secrets

Colmena allows you to upload secret files that will not be stored in the Nix store to nodes. It implements a subset of the deployment.keys options supported by NixOps.

For example, to deploy DNS-01 credentials for use with security.acme:

{
  shared-box = {
    security.acme.certs."my-site.tld".credentialsFile = "/run/keys/acme-credentials.secret";
    deployment.keys."acme-credentials.secret" = {
      # Alternatively, `text` (string) or `keyFile` (path to file)
      # may be specified.
      keyCommand = [ "vault" "read" "-field=env" "secret/dns01" ];

      destDir = "/run/keys";       # Default: /run/keys
      user = "acme";               # Default: root
      group = "nginx";             # Default: root
      permissions = "0640";        # Default: 0600

      uploadAt = "pre-activation"; # Default: pre-activation, Alternative: post-activation
    };
    # Rest of configuration...
  };
}

Take note that if you use the default path (/run/keys), the secret files are only stored in-memory and will not survive reboots. To upload your secrets without performing a full deployment, use colmena upload-keys.

Key Services

For each secret file deployed using deployment.keys, a systemd service with the name of ${name}-key.service is created (acme-credentials.secret-key.service for the example above). This unit is only active when the corresponding file is present, allowing you to set up dependencies for services requiring secret files to function.

Key Permissions

The /run/keys directory is owned by the keys group. If you are using a systemd service running as a non-root user, you will likely need to add:

SupplementaryGroups = [ "keys" ];

to your service configuration.

Flakes

If you are using flakes, Nix will copy the entire flake (everything tracked by git) into the Nix store during evaluation. This means that all files as checked out by git are world-readable, including the ones managed by filter-based encryption tools like git-crypt. To use deployment.keys.<name>.keyFile with flakes without having the secrets copied to the Nix store, a quoted absolute path can be used.

Ad Hoc Evaluation

Sometimes you may want to extract values from your Hive configuration for consumption in another program (e.g., OctoDNS). To do that, create a .nix file with a lambda:

{ nodes, pkgs, lib, ... }:
# Feels like a NixOS module - But you can return any JSON-serializable value
lib.attrsets.mapAttrs (k: v: v.config.deployment.targetHost) nodes

Then you can obtain a JSON output with:

$ colmena eval target-hosts.nix
{"alpha":"fd12:3456::1","beta":"fd12:3456::2"}

You can also specify an expression directly on the command line:

$ colmena eval -E '{ nodes, pkgs, lib, ... }: ...'

Instantiation

You may directly instantiate an expression that evaluates to a derivation:

$ colmena eval --instantiate -E '{ nodes, ... }: nodes.alpha.config.boot.kernelPackages.kernel'
/nix/store/7ggmhnwvywrqcd1z2sdpan8afz55sw7z-linux-5.14.14.drv

Interactive REPL

To explore the configurations interactively, start a REPL session with colmena repl:

$ colmena repl
[INFO ] Using flake: git+file:///home/user/cluster
Welcome to Nix 2.10.3. Type :? for help.

Loading installable ''...
Added 3 variables.
nix-repl> nodes.alpha.config.deployment.targetHost
"fd12:3456::1"

Parallelism

Colmena is built from the ground up to support parallel deployments. Evaluation, build, and deployment of node configurations can happen at the same time.

Configuration

The parallelism of Colmena can be controlled through two flags:

--limit <number>

Number of hosts to deploy at once in the final step (pushing closures and activating new profiles). The default value is 10.

--eval-node-limit <number>

By default, Colmena will automatically determine the maximum number of nodes to evaluate at the same time according to available RAM. This flag allows you to set the limit to a predetermined value.

Parallel Evaluation (Experimental)

By default, Colmena evaluates nodes in batches according to available RAM using Nix's built-in single-threaded evaluator. Experimental support is available for using nix-eval-jobs as the evaluator.

When nix-eval-jobs is enabled via --evaluator streaming, evaluation is parallelized with deployment processes kicked off as individual nodes finish evaluating.

Remote Builds

If the host running Colmena is not powerful enough, consider offloading the actual builds to remote machines. Colmena supports two ways to achieve this:

Using Colmena's deployment.buildOnTarget

If you set deployment.buildOnTarget = true; for a node, then the actual build process will be initiated on the node itself. Colmena will evaluate the configuration locally before copying the derivations to the target node. You can temporarily enable this for all nodes by passing --build-on-target on the command line, or disable it with --no-build-on-target.

This is most useful in scenarios where the machine running Colmena is bandwidth-constrained, or it's inconvenient to configure designated builders beforehand. With this method, the build results will not be copied back to the local machine or otherwise shared across the target nodes. If you have custom packages used on multiple nodes, the work required to build those packages will be duplicated across the nodes.

Using the native distributed build feature in Nix

When distributed build is enabled, Nix will transparently forward builds to the configured builders. After the builds are done, Nix will copy the results back to the local machine.

Builders can either be configured globally or in your configuration with meta.machinesFile.

Examples

This section contains examples of setups people commonly use:

Multi-Architecture Deployments

You can deploy to hosts running different architectures with a single configuration. There are two ways to achieve this:

Using binfmt Emulation

On Linux hosts, you can run builds through transparent binary emulation using QEMU and binfmt-misc.

This following example sets up binfmt, allowing an X86-64 host (laptop) to build derivations for an AArch64 host (rpi) through QEMU:

{
  # The NixOS machine you are running Colmena on (x86_64-linux)
  laptop = { pkgs, ... }: {
    # Enable binfmt emulation for aarch64-linux
    boot.binfmt.emulatedSystems = [ "aarch64-linux" ];

    # ... Rest of configuration ...
  };

  # The remote machine running a foreign architecture (aarch64-linux)
  rpi = { pkgs, ... }: {
    # Override nixpkgs architecture
    nixpkgs.system = "aarch64-linux";

    # ... Rest of configuration ...
  };
}

(For Flake users, the above attribute set is the value of outputs.colmena)

First, deploy the local configuration with colmena apply-local --sudo. For more information on what is required on the local system, see Local Deployment.

After the new configuration is activated, binfmt emulation will be set up on the local machine. You can then deploy to the rpi node with colmena apply --on rpi.

Building Remotely

If the remote nodes are powerful enough, you may also execute builds on them directly. See Remote Builds for more details.

Reference

This section contains detailed listings of options and parameters accepted by Colmena:

Deployment Options

Colmena adds a set of extra options that can be used in your NixOS configurations under the deployment prefix.

deployment.allowLocalDeployment

Allow the configuration to be applied locally on the host running Colmena.

For local deployment to work, all of the following must be true:

  • The node must be running NixOS.
  • The node must have deployment.allowLocalDeployment set to true.
  • The node’s networking.hostName must match the hostname.

To apply the configurations locally, run colmena apply-local. You can also set deployment.targetHost to null if the nost is not accessible over SSH (only local deployment will be possible).

Type: boolean

Default: false

deployment.buildOnTarget

Whether to build the system profiles on the target node itself.

When enabled, Colmena will copy the derivation to the target node and initiate the build there. This avoids copying back the build results involved with the native distributed build feature. Furthermore, the build goal will be equivalent to the push goal. Since builds happen on the target node, the results are automatically “pushed” and won’t exist in the local Nix store.

You can temporarily override per-node settings by passing --build-on-target (enable for all nodes) or --no-build-on-target (disable for all nodes) on the command line.

Type: boolean

Default: false

deployment.keys

A set of secrets to be deployed to the node.

Secrets are transferred to the node out-of-band and never ends up in the Nix store.

Type: attribute set of (submodule)

Default: { }

deployment.keys.<name>.destDir

Destination directory on the host.

Type: path

Default: "/run/keys"

deployment.keys.<name>.group

The group that will own the file.

Type: string

Default: "root"

deployment.keys.<name>.keyCommand

Command to run to generate the key. One of text, keyCommand and keyFile must be set.

Type: null or (list of string)

Default: null

deployment.keys.<name>.keyFile

Path of the local file to read the key from. One of text, keyCommand and keyFile must be set.

Type: null or path

Default: null

deployment.keys.<name>.name

File name of the key.

Type: string

Default: "‹name›"

deployment.keys.<name>.permissions

Permissions to set for the file.

Type: string

Default: "0600"

deployment.keys.<name>.text

Content of the key. One of text, keyCommand and keyFile must be set.

Type: null or string

Default: null

deployment.keys.<name>.uploadAt

When to upload the keys.

  • pre-activation (default): Upload the keys before activating the new system profile.
  • post-activation: Upload the keys after successfully activating the new system profile.

For colmena upload-keys, all keys are uploaded at the same time regardless of the configuration here.

Type: one of “pre-activation”, “post-activation”

Default: "pre-activation"

deployment.keys.<name>.user

The group that will own the file.

Type: string

Default: "root"

deployment.privilegeEscalationCommand

Command to use to elevate privileges when activating the new profiles on SSH hosts.

This is used on SSH hosts when deployment.targetUser is not root. The user must be allowed to use the command non-interactively.

Type: list of string

Default:

[
  "sudo"
  "-H"
  "--"
]

deployment.replaceUnknownProfiles

Allow a configuration to be applied to a host running a profile we have no knowledge of. By setting this option to false, you reduce the likelyhood of rolling back changes made via another Colmena user.

Unknown profiles are usually the result of either:

  • The node had a profile applied, locally or by another Colmena.
  • The host running Colmena garbage-collecting the profile.

To force profile replacement on all targeted nodes during apply, use the flag --force-replace-unknown-profiles.

Type: boolean

Default: true

deployment.tags

A list of tags for the node.

Can be used to select a group of nodes for deployment.

Type: list of string

Default: [ ]

deployment.targetHost

The target SSH node for deployment.

By default, the node’s attribute name will be used. If set to null, only local deployment will be supported.

Type: null or string

Default: "nixos"

deployment.targetPort

The target SSH port for deployment.

By default, the port is the standard port (22) or taken from your ssh_config.

Type: null or unsigned integer, meaning >=0

Default: null

deployment.targetUser

The user to use to log into the remote node. If set to null, the target user will not be specified in SSH invocations.

Type: null or string

Default: "root"

Meta Options

The following is a list of options that can be added to the meta attribute set.

For compatibility with NixOps, you may name it network instead of meta. However, you cannot specify both at the same time.

allowApplyAll

Whether to allow deployments without a node filter set.

If set to false, a node filter must be specified with --on when deploying.

It helps prevent accidental deployments to the entire cluster when tags are used (e.g., @production and @staging).

Type: boolean

Default: true

description

A short description for the configuration.

Type: string

Default: "A Colmena Hive"

machinesFile

Use the machines listed in this file when building this hive configuration.

If your Colmena host has nix configured to allow for remote builds (for nix-daemon, your user being included in trusted-users) you can set a machines file that will be passed to the underlying nix-store command during derivation realization as a builders option. For example, if you support multiple orginizations each with their own build machine(s) you can ensure that builds only take place on your local machine and/or the machines specified in this file.

See https://nixos.org/manual/nix/stable/#chap-distributed-builds for the machine specification format.

This option is ignored when builds are initiated on the remote nodes themselves via deployment.buildOnTarget or --build-on-target. To still use the Nix distributed build functionality, configure the builders on the target nodes with nix.buildMachines.

Type: null or path

Default: null

name

The name of the configuration.

Type: string

Default: "hive"

nixpkgs

The pinned Nixpkgs package set. Accepts one of the following:

  • A path to a Nixpkgs checkout
  • The Nixpkgs lambda (e.g., import <nixpkgs>)
  • An initialized Nixpkgs attribute set

This option must be specified when using Flakes.

Type: unspecified value

Default: null

nodeNixpkgs

Node-specific Nixpkgs pins.

Type: attribute set of unspecified value

Default: { }

nodeSpecialArgs

Node-specific special args.

Type: attribute set of unspecified value

Default: { }

specialArgs

A set of special arguments to be passed to NixOS modules.

This will be merged into the specialArgs used to evaluate the NixOS configurations.

Type: attribute set of unspecified value

Default: { }

Command Line Options

The following are the help messages that will be printed when you invoke any sub-command with --help:

colmena

NixOS deployment tool Colmena helps you deploy to multiple hosts running NixOS. For more details, read the manual at <https://colmena.cli.rs/0.4>. Usage: colmena [OPTIONS] [COMMAND] Commands: apply Apply configurations on remote machines apply-local Apply configurations on the local machine build Build configurations but not push to remote machines eval Evaluate an expression using the complete configuration upload-keys Upload keys to remote hosts exec Run a command on remote machines repl Start an interactive REPL with the complete configuration nix-info Show information about the current Nix installation help Print this message or the help of the given subcommand(s) Options: --show-trace Passes --show-trace to Nix commands --impure Passes --impure to Nix commands --nix-option <NAME> <VALUE> Passes arbitrary options to Nix commands This only works when building locally. -f, --config <CONFIG> If this argument is not specified, Colmena will search upwards from the current working directory for a file named "flake.nix" or "hive.nix". This behavior is disabled if --config/-f is given explicitly. For a sample configuration, check the manual at <https://colmena.cli.rs/0.4>. [default: hive.nix] -h, --help Print help (see a summary with '-h') -V, --version Print version --color <WHEN> When to colorize the output. By default, Colmena enables colorized output when the terminal supports it. It's also possible to specify the preference using environment variables. See <https://bixense.com/clicolors>. [default: auto] [possible values: auto, always, never]

colmena apply

Apply configurations on remote machines Usage: colmena apply [OPTIONS] [goal] Arguments: [goal] The goal of the deployment. Same as the targets for switch-to-configuration, with the following extra pseudo-goals: - build: Only build the system profiles - push: Only copy the closures to remote nodes - keys: Only upload the keys to the remote nodes `switch` is the default goal unless `--reboot` is passed, in which case `boot` is the default. [default: switch] [possible values: build, push, switch, boot, test, dry-activate, keys] Options: --eval-node-limit <LIMIT> Limits the maximum number of hosts to be evaluated at once. The evaluation process is RAM-intensive. The default behavior is to limit the maximum number of host evaluated at the same time based on naive heuristics. Set to 0 to disable the limit. [default: auto] -p, --parallel <LIMIT> Limits the maximum number of hosts to be deployed in parallel. Set to 0 to disable parallemism limit. [default: 10] --show-trace Passes --show-trace to Nix commands --impure Passes --impure to Nix commands --keep-result Create GC roots for built profiles. The built system profiles will be added as GC roots so that they will not be removed by the garbage collector. The links will be created under .gcroots in the directory the Hive configuration is located. --nix-option <NAME> <VALUE> Passes arbitrary options to Nix commands This only works when building locally. -v, --verbose Deactivates the progress spinner and prints every line of output. --no-keys Do not upload secret keys set in `deployment.keys`. By default, Colmena will upload keys set in `deployment.keys` before deploying the new profile on a node. To upload keys without building or deploying the rest of the configuration, use `colmena upload-keys`. --reboot Reboots nodes after activation and waits for them to come back up. --no-substitute Disables the use of substituters when copying closures to the remote host. --no-gzip Disables the use of gzip when copying closures to the remote host. --build-on-target Build the system profiles on the target nodes themselves. If enabled, the system profiles will be built on the target nodes themselves, not on the host running Colmena itself. This overrides per-node perferences set in `deployment.buildOnTarget`. To temporarily disable remote build on all nodes, use `--no-build-on-target`. --force-replace-unknown-profiles If `deployment.replaceUnknownProfiles` is set for a target, using this switch will treat deployment.replaceUnknownProfiles as though it was set true and perform unknown profile replacement. --evaluator <evaluator> If set to `chunked` (default), evaluation of nodes will happen in batches. If set to `streaming`, the experimental streaming evaluator (nix-eval-jobs) will be used and nodes will be evaluated in parallel. This is an experimental feature. [default: chunked] [possible values: chunked, streaming] --on <NODES> Select a list of nodes to deploy to. The list is comma-separated and globs are supported. To match tags, prepend the filter by @. Valid examples: - host1,host2,host3 - edge-* - edge-*,core-* - @a-tag,@tags-can-have-* -f, --config <CONFIG> If this argument is not specified, Colmena will search upwards from the current working directory for a file named "flake.nix" or "hive.nix". This behavior is disabled if --config/-f is given explicitly. For a sample configuration, check the manual at <https://colmena.cli.rs/0.4>. [default: hive.nix] -h, --help Print help (see a summary with '-h') --color <WHEN> When to colorize the output. By default, Colmena enables colorized output when the terminal supports it. It's also possible to specify the preference using environment variables. See <https://bixense.com/clicolors>. [default: auto] [possible values: auto, always, never]

colmena apply-local

Apply configurations on the local machine Usage: colmena apply-local [OPTIONS] [goal] Arguments: [goal] Same as the targets for switch-to-configuration. "push" is noop in apply-local. [default: switch] [possible values: push, switch, boot, test, dry-activate, keys] Options: --sudo Attempt to escalate privileges if not run as root --show-trace Passes --show-trace to Nix commands -v, --verbose Deactivates the progress spinner and prints every line of output. --impure Passes --impure to Nix commands --no-keys Do not deploy secret keys set in `deployment.keys`. By default, Colmena will deploy keys set in `deployment.keys` before activating the profile on this host. --nix-option <NAME> <VALUE> Passes arbitrary options to Nix commands This only works when building locally. --node <NODE> Override the node name to use -f, --config <CONFIG> If this argument is not specified, Colmena will search upwards from the current working directory for a file named "flake.nix" or "hive.nix". This behavior is disabled if --config/-f is given explicitly. For a sample configuration, check the manual at <https://colmena.cli.rs/0.4>. [default: hive.nix] -h, --help Print help (see a summary with '-h') --color <WHEN> When to colorize the output. By default, Colmena enables colorized output when the terminal supports it. It's also possible to specify the preference using environment variables. See <https://bixense.com/clicolors>. [default: auto] [possible values: auto, always, never]

colmena build

Build configurations but not push to remote machines This subcommand behaves as if you invoked `apply` with the `build` goal. Usage: colmena build [OPTIONS] Options: --eval-node-limit <LIMIT> Limits the maximum number of hosts to be evaluated at once. The evaluation process is RAM-intensive. The default behavior is to limit the maximum number of host evaluated at the same time based on naive heuristics. Set to 0 to disable the limit. [default: auto] -p, --parallel <LIMIT> Limits the maximum number of hosts to be deployed in parallel. Set to 0 to disable parallemism limit. [default: 10] --show-trace Passes --show-trace to Nix commands --impure Passes --impure to Nix commands --keep-result Create GC roots for built profiles. The built system profiles will be added as GC roots so that they will not be removed by the garbage collector. The links will be created under .gcroots in the directory the Hive configuration is located. --nix-option <NAME> <VALUE> Passes arbitrary options to Nix commands This only works when building locally. -v, --verbose Deactivates the progress spinner and prints every line of output. --no-keys Do not upload secret keys set in `deployment.keys`. By default, Colmena will upload keys set in `deployment.keys` before deploying the new profile on a node. To upload keys without building or deploying the rest of the configuration, use `colmena upload-keys`. --reboot Reboots nodes after activation and waits for them to come back up. --no-substitute Disables the use of substituters when copying closures to the remote host. --no-gzip Disables the use of gzip when copying closures to the remote host. --build-on-target Build the system profiles on the target nodes themselves. If enabled, the system profiles will be built on the target nodes themselves, not on the host running Colmena itself. This overrides per-node perferences set in `deployment.buildOnTarget`. To temporarily disable remote build on all nodes, use `--no-build-on-target`. --force-replace-unknown-profiles If `deployment.replaceUnknownProfiles` is set for a target, using this switch will treat deployment.replaceUnknownProfiles as though it was set true and perform unknown profile replacement. --evaluator <evaluator> If set to `chunked` (default), evaluation of nodes will happen in batches. If set to `streaming`, the experimental streaming evaluator (nix-eval-jobs) will be used and nodes will be evaluated in parallel. This is an experimental feature. [default: chunked] [possible values: chunked, streaming] --on <NODES> Select a list of nodes to deploy to. The list is comma-separated and globs are supported. To match tags, prepend the filter by @. Valid examples: - host1,host2,host3 - edge-* - edge-*,core-* - @a-tag,@tags-can-have-* -f, --config <CONFIG> If this argument is not specified, Colmena will search upwards from the current working directory for a file named "flake.nix" or "hive.nix". This behavior is disabled if --config/-f is given explicitly. For a sample configuration, check the manual at <https://colmena.cli.rs/0.4>. [default: hive.nix] -h, --help Print help (see a summary with '-h') --color <WHEN> When to colorize the output. By default, Colmena enables colorized output when the terminal supports it. It's also possible to specify the preference using environment variables. See <https://bixense.com/clicolors>. [default: auto] [possible values: auto, always, never]

colmena upload-keys

Upload keys to remote hosts This subcommand behaves as if you invoked `apply` with the pseudo `keys` goal. Usage: colmena upload-keys [OPTIONS] Options: --eval-node-limit <LIMIT> Limits the maximum number of hosts to be evaluated at once. The evaluation process is RAM-intensive. The default behavior is to limit the maximum number of host evaluated at the same time based on naive heuristics. Set to 0 to disable the limit. [default: auto] -p, --parallel <LIMIT> Limits the maximum number of hosts to be deployed in parallel. Set to 0 to disable parallemism limit. [default: 10] --show-trace Passes --show-trace to Nix commands --impure Passes --impure to Nix commands --keep-result Create GC roots for built profiles. The built system profiles will be added as GC roots so that they will not be removed by the garbage collector. The links will be created under .gcroots in the directory the Hive configuration is located. --nix-option <NAME> <VALUE> Passes arbitrary options to Nix commands This only works when building locally. -v, --verbose Deactivates the progress spinner and prints every line of output. --no-keys Do not upload secret keys set in `deployment.keys`. By default, Colmena will upload keys set in `deployment.keys` before deploying the new profile on a node. To upload keys without building or deploying the rest of the configuration, use `colmena upload-keys`. --reboot Reboots nodes after activation and waits for them to come back up. --no-substitute Disables the use of substituters when copying closures to the remote host. --no-gzip Disables the use of gzip when copying closures to the remote host. --build-on-target Build the system profiles on the target nodes themselves. If enabled, the system profiles will be built on the target nodes themselves, not on the host running Colmena itself. This overrides per-node perferences set in `deployment.buildOnTarget`. To temporarily disable remote build on all nodes, use `--no-build-on-target`. --force-replace-unknown-profiles If `deployment.replaceUnknownProfiles` is set for a target, using this switch will treat deployment.replaceUnknownProfiles as though it was set true and perform unknown profile replacement. --evaluator <evaluator> If set to `chunked` (default), evaluation of nodes will happen in batches. If set to `streaming`, the experimental streaming evaluator (nix-eval-jobs) will be used and nodes will be evaluated in parallel. This is an experimental feature. [default: chunked] [possible values: chunked, streaming] --on <NODES> Select a list of nodes to deploy to. The list is comma-separated and globs are supported. To match tags, prepend the filter by @. Valid examples: - host1,host2,host3 - edge-* - edge-*,core-* - @a-tag,@tags-can-have-* -f, --config <CONFIG> If this argument is not specified, Colmena will search upwards from the current working directory for a file named "flake.nix" or "hive.nix". This behavior is disabled if --config/-f is given explicitly. For a sample configuration, check the manual at <https://colmena.cli.rs/0.4>. [default: hive.nix] -h, --help Print help (see a summary with '-h') --color <WHEN> When to colorize the output. By default, Colmena enables colorized output when the terminal supports it. It's also possible to specify the preference using environment variables. See <https://bixense.com/clicolors>. [default: auto] [possible values: auto, always, never]

colmena eval

Evaluate an expression using the complete configuration Your expression should take an attribute set with keys `pkgs`, `lib` and `nodes` (like a NixOS module) and return a JSON-serializable value. For example, to retrieve the configuration of one node, you may write something like: { nodes, ... }: nodes.node-a.config.networking.hostName Usage: colmena eval [OPTIONS] [FILE] Arguments: [FILE] The .nix file containing the expression Options: -E <EXPRESSION> The Nix expression --instantiate Actually instantiate the expression --show-trace Passes --show-trace to Nix commands --impure Passes --impure to Nix commands --nix-option <NAME> <VALUE> Passes arbitrary options to Nix commands This only works when building locally. -f, --config <CONFIG> If this argument is not specified, Colmena will search upwards from the current working directory for a file named "flake.nix" or "hive.nix". This behavior is disabled if --config/-f is given explicitly. For a sample configuration, check the manual at <https://colmena.cli.rs/0.4>. [default: hive.nix] -h, --help Print help (see a summary with '-h') --color <WHEN> When to colorize the output. By default, Colmena enables colorized output when the terminal supports it. It's also possible to specify the preference using environment variables. See <https://bixense.com/clicolors>. [default: auto] [possible values: auto, always, never]

colmena exec

Run a command on remote machines Usage: colmena exec [OPTIONS] <COMMAND>... Arguments: <COMMAND>... Command to run It's recommended to use -- to separate Colmena options from the command to run. For example: colmena exec --on @routers -- tcpdump -vni any ip[9] == 89 Options: -p, --parallel <LIMIT> Limits the maximum number of hosts to run the command in parallel. In `colmena exec`, the parallelism limit is disabled (0) by default. [default: 0] --show-trace Passes --show-trace to Nix commands -v, --verbose Deactivates the progress spinner and prints every line of output. --impure Passes --impure to Nix commands --on <NODES> Select a list of nodes to deploy to. The list is comma-separated and globs are supported. To match tags, prepend the filter by @. Valid examples: - host1,host2,host3 - edge-* - edge-*,core-* - @a-tag,@tags-can-have-* --nix-option <NAME> <VALUE> Passes arbitrary options to Nix commands This only works when building locally. -f, --config <CONFIG> If this argument is not specified, Colmena will search upwards from the current working directory for a file named "flake.nix" or "hive.nix". This behavior is disabled if --config/-f is given explicitly. For a sample configuration, check the manual at <https://colmena.cli.rs/0.4>. [default: hive.nix] -h, --help Print help (see a summary with '-h') --color <WHEN> When to colorize the output. By default, Colmena enables colorized output when the terminal supports it. It's also possible to specify the preference using environment variables. See <https://bixense.com/clicolors>. [default: auto] [possible values: auto, always, never]

colmena nix-info

Show information about the current Nix installation Usage: colmena nix-info [OPTIONS] Options: --show-trace Passes --show-trace to Nix commands --impure Passes --impure to Nix commands --nix-option <NAME> <VALUE> Passes arbitrary options to Nix commands This only works when building locally. -f, --config <CONFIG> If this argument is not specified, Colmena will search upwards from the current working directory for a file named "flake.nix" or "hive.nix". This behavior is disabled if --config/-f is given explicitly. For a sample configuration, check the manual at <https://colmena.cli.rs/0.4>. [default: hive.nix] -h, --help Print help (see a summary with '-h') --color <WHEN> When to colorize the output. By default, Colmena enables colorized output when the terminal supports it. It's also possible to specify the preference using environment variables. See <https://bixense.com/clicolors>. [default: auto] [possible values: auto, always, never]

colmena repl

Start an interactive REPL with the complete configuration In the REPL, you can inspect the configuration interactively with tab completion. The node configurations are accessible under the `nodes` attribute set. Usage: colmena repl [OPTIONS] Options: --show-trace Passes --show-trace to Nix commands --impure Passes --impure to Nix commands --nix-option <NAME> <VALUE> Passes arbitrary options to Nix commands This only works when building locally. -f, --config <CONFIG> If this argument is not specified, Colmena will search upwards from the current working directory for a file named "flake.nix" or "hive.nix". This behavior is disabled if --config/-f is given explicitly. For a sample configuration, check the manual at <https://colmena.cli.rs/0.4>. [default: hive.nix] -h, --help Print help (see a summary with '-h') --color <WHEN> When to colorize the output. By default, Colmena enables colorized output when the terminal supports it. It's also possible to specify the preference using environment variables. See <https://bixense.com/clicolors>. [default: auto] [possible values: auto, always, never]

Release Notes

Release 0.4.0 (2023/05/14)

  • Flake evaluation is now actually pure by default. To enable impure expressions, pass --impure.
  • --reboot is added to trigger a reboot and wait for the node to come back up.
  • The target user is no longer explicitly set when deployment.targetUser is null (#91).
  • In apply-local, we now only escalate privileges during activation (#85).
  • Impure overlays are no longer imported by default if a path is specified in meta.nixpkgs (#39)
  • GC roots are now created right after the builds are complete, as opposed to after activation.
  • The meta.allowApplyAll option has been added. If set to false, deployments without a node filter (--on) are disallowed (#95).
  • The --no-substitutes option under the apply subcommand has been renamed to --no-substitute (#59).
  • The meta.nodeSpecialArgs option has been added. It allows specifying node-specific specialArgs passed to NixOS modules (#100).
  • The repl subcommand has been added. It allows you to start an interactive REPL with access to the complete node configurations.
  • The default goal for colmena apply is now boot if --reboot is specified, and switch otherwise (#113).
  • Post-activation keys are now uploaded after the reboot if --reboot is specified (#113).
  • Flake-enabled deployments now use the new SSH store protocol (ssh-ng://).

Release 0.3.2 (2022/09/29)

Release 0.3.1 (2022/08/18)

  • Fixed: Streaming evaluation fails for node names containing periods (#92)
  • Fixed: Streaming evaluation fails in non-flake deployments with relative paths (#107)
  • Fixed: colmena apply-local returning non-zero exit code when successful (#111)

Release 0.3.0 (2022/04/27)

  • Remote builds are now supported (#33).
  • Streaming evaluation powered by nix-eval-jobs is now available as an experimental feature (--evaluator streaming).
  • Colmena can now run on macOS to deploy to NixOS hosts using remote building.
  • It's now possible to configure output colorization via the CLI and environment variables. Colmena follows the clicolors standard.
  • A systemd unit (${name}-key.service) is now created for each secret file deployed using deployment.keys (#48).
  • Node enumeration is now faster if you do not filter against tags with --on @tag-name.
  • The main deployment logic has been rewritten to be cleaner and easier to follow.
  • There are now end-to-end tests to ensure that the development branch is actually functional as a whole at all times.

Release 0.2.2 (2022/03/08)

This bugfix release fixes NixOS detection so apply-local works with the latest changes in nixos-unstable (#63). Additionally, --no-keys was fixed in apply-local.

Release 0.2.1 (2022/01/26)

This bugfix release fixes the issue (#50) where sandboxed documentation builds fail when using the unstable Nixpkgs channel.

Release 0.2.0 (2021/11/18)

This is release 0.2.0, the first stable release of Colmena!

Colmena is a simple, stateless NixOS deployment tool modeled after NixOps and morph, built from the ground up to support parallel deployments.

This release contains the following features:

  • Node Tagging
  • Local Deployment
  • Secrets
  • Ad Hoc Evaluation
  • Nix Flakes Support
  • Parallelism

We now have a User Manual at https://colmena.cli.rs/0.2 containing tutorials, sample configurations as well as a complete listing of supported deployment options.

Contributing

Contributions are welcome!

Code

You can checkout the source code and submit pull requests at the GitHub repo.

By contributing code to Colmena, you agree that your contributions will be available under the MIT License.

Issues & Feature Requests

Bumped into a problem? We would like to fix it! Please open a new issue at the GitHub repo.