Deployment Options

You are currently reading the unstable version of the Colmena Manual, built against the tip of the development branch.

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: