krops is a lightweight toolkit to deploy NixOS systems, remotely or locally.

• store your secrets in password store or passage
• build your systems remotely
• minimal overhead (it's basically just nixos-rebuild switch!)
• run from custom nixpkgs branch/checkout/fork

Create a file named krops.nix (name doesn't matter) with following content:

let
  krops = (import <nixpkgs> {}).fetchgit {
    url = https://cgit.krebsco.de/krops/;
    rev = "v1.25.0";
    sha256 = "07mg3iaqjf1w49vmwfchi7b1w55bh7rvsbgicp2m47gnj9alwdb6";
  };

  lib = import "${krops}/lib";
  pkgs = import "${krops}/pkgs" {};

  source = lib.evalSource [{
    nixpkgs.git = {
      clean.exclude = ["/.version-suffix"];
      ref = "4b4bbce199d3b3a8001ee93495604289b01aaad3";
      url = https://github.com/NixOS/nixpkgs;
    };
    nixos-config.file = toString (pkgs.writeText "nixos-config" ''
      { pkgs, ... }: {
        fileSystems."/" = { device = "/dev/sda1"; };
        boot.loader.systemd-boot.enable = true;
        services.openssh.enable = true;
        environment.systemPackages = [ pkgs.git ];
        users.users.root.openssh.authorizedKeys.keys = [
          "ssh-rsa ADD_YOUR_OWN_PUBLIC_KEY_HERE user@localhost"
        ];
      }
    '');
  }];
in
  pkgs.krops.writeDeploy "deploy" {
    source = source;
    target = "root@YOUR_IP_ADDRESS_OR_HOST_NAME_HERE";
  }

and run $(nix-build --no-out-link krops.nix) to deploy the target machine. krops exports some funtions under krops. namely:

This will make the sources available on the target machine below /var/src, and execute nixos-rebuild switch -I /var/src.

The target attribute to writeDeploy can either be a string or an attribute set, specifying where to make the sources available, as well as where to run the deployment.

If specified as string, the format could be described as:

[[USER]@]HOST[:PORT][/SOME/PATH]

Portions in square brackets are optional.

If the USER is the empty string, as in e.g. @somehost, then the username will be obtained by ssh from its configuration files.

If the target attribute is an attribute set, then it can specify the attributes extraOptions, host, path, port, sudo, and user. The extraOptions is a list of strings that get passed to ssh as additional arguments. The sudo attribute is a boolean and if set to true, then it's possible to to deploy to targets that disallow sshing in as root, but allow (preferably passwordless) sudo. Example:

pkgs.krops.writeDeploy "deploy" {
  source = /* ... */;
  target = lib.mkTarget "user@host/path" // {
    extraOptions = [
      "-o" "LogLevel=DEBUG"
    ];
    sudo = true;
  };
}

For more details about the target attribute, please check the mkTarget function in lib/default.nix.

Backup all paths specified in source before syncing new sources.

If set the evaluation and build of the system will be executed on this host. buildTarget takes the same arguments as target. Sources will be synced to both buildTarget and target. Built packages will be uploaded from the buildTarget to target directly This requires the building machine to have ssh access to the target. To build the system on the same machine, that runs the krops command, set up a local ssh service and set the build host to localhost.

Use this option if target host architecture is not the same as the build host architecture as set by buildHost i.e. deploying to aarch64 from a x86_64 machine. Setting this option will disable building & running nix in the wrong architecture when running nixos-rebuild on the deploying machine. It is required to set nixpkgs.localSystem.system in the NixOS configuration to the architecture of the target host. This option is only useful if the build host also has remote builders that are capable of producing artifacts for the deploy architecture.

Run nixos-rebuild immediately without building the system in a dedicated nix build step.

Create the sentinel file (/var/src/.populate) before syncing the new source.

Specifies which nixos-rebuild operation to perform.

Specifies when to pipe nixos-rebuild's output to nom.

Supported values:

• "opportunistic" (default) - Use nom only if it is present on the target machine.

• "optimistic" - Use nom, assuming it is present on the target machine.

• "pessimistic" - Use nom via nix-shell on the target machine.

• true - Use nom. If it is not present on the target machine, then use it via nix-shell.

• false - Don't use nom

Very similiar to writeDeploy, but just builds the system on the target without activating it.

This basically makes the sources available on the target machine below /var/src, and executes NIX_PATH=/var/src nix-build -A system '<nixpkgs/nixos>'.

see writeDeploy

see writeDeploy

see writeDeploy

run nix-build with --show-trace

This can be used to run other commands than nixos-rebuild or pre/post build hooks.

A function which takes the targetPath as an attribute. Example to activate/deactivate a swapfile before/after build:

pkgs.krops.writeCommand "deploy-with-swap" {
  source = source;
  target = "root@YOUR_IP_ADDRESS_OR_HOST_NAME_HERE";
  command = targetPath: ''
    swapon /var/swapfile
    nixos-rebuild -I ${targetPath} switch
    swapoff /var/swapfile
  '';
}

see writeDeploy

see writeDeploy

see writeDeploy

whether the ssh session should do a pseudo-terminal allocation. sets -t on the ssh command.

Nix expression to be built at the target machine.

Supported attributes:

• text - Nix expression to be built.

The file source type transfers local files (and folders) to the target using rsync.

Supported attributes:

• path - absolute path to files that should by transferred.

• useChecksum (optional) - boolean that controls whether file contents should be checked to decide whether a file has changed. This is useful when path points at files with mangled timestamps, e.g. the Nix store.

  The default value is true if path is a derivation, and false otherwise.

• filters (optional) List of filters that should be passed to rsync. Filters are specified as attribute sets with the attributes type and pattern. Supported filter types are include and exclude. Checkout the filter rules section in the rsync manual for further information.

• deleteExcluded (optional) boolean that controls whether the excluded directories should be deleted if they exist on the target. This is passed to the --delete-excluded option of rsync. Defaults to true.

Git sources that will be fetched on the target machine.

Supported attributes:

• url - URL of the Git repository that should be fetched.

• ref - Branch / tag / commit that should be fetched.

• clean.exclude - List of patterns that should be excluded from Git cleaning.

• shallow (optional) boolean that controls whether only the requested commit ref. should be fetched instead of the whole history, to save disk space and bandwith. Defaults to false.

The pass source type transfers contents from a local password store to the target machine.

Supported attributes:

• dir - absolute path to the password store.

• name - sub-directory in the password store.

The passage source type decrypts files from a local passage store and transfers them to the target using rsync.

Supported attributes:

• dir - Path to the passage store. For a partial transfer, this may point to a subdirectory. Example: ~/.passage/store/hosts/MYHOSTNAME

• identities_file (optional) - Path to the identities file. Defaults to ~/.passage/identities.

• age (optional) - Path of the age binary. Defaults to age (absolute path gets resolved using passage's search path.)

Executes a local command, capture its stdout, and send that as a file to the target machine.

Supported attributes:

• command - The (shell) command to run.

Symlink to create at the target, relative to the target directory. This can be used to reference files in other sources.

Supported attributes:

• target - Content of the symlink. This is typically a relative path.

• In-depth example by Ingolf Wagner

Comments, questions, pull-requests and patches, etc. are very welcome, and can be directed at:

• IRC: #krebs at hackint
• Mail: [email protected]
• Github: https://github.com/krebs/krops/