Getting Started
The clan vars subcommand is a powerful tool for managing machine-specific variables in a declarative and reproducible way. This guide will walk you through its usage, from setting up a generator to sharing and updating variables across machines.
For a detailed API reference, see the vars module documentation.
In this guide, you will learn how to:
- Declare a
generatorin the machine's NixOS configuration. - Inspect the status of variables using the Clan CLI.
- Generate variables interactively.
- Observe the changes made to your repository.
- Update the machine configuration.
- Share the root password between multiple machines.
- Change the root password when needed.
By the end of this guide, you will have a clear understanding of how to use clan vars to manage sensitive data, such as passwords, in a secure and efficient manner.
Declare the generator
In this example, a vars generator is used to:
- prompt the user for the password
- run the required
mkpasswdcommand to generate the hash - store the hash in a file
- expose the file path to the nixos configuration
Create a new nix file root-password.nix with the following content and import it into your configuration.nix
{config, pkgs, ...}: {
clan.core.vars.generators.root-password = {
# prompt the user for a password
# (`password-input` being an arbitrary name)
prompts.password-input.description = "the root user's password";
prompts.password-input.type = "hidden";
# don't store the prompted password itself
prompts.password-input.persist = false;
# define an output file for storing the hash
files.password-hash.secret = false;
# define the logic for generating the hash
script = ''
cat $prompts/password-input | mkpasswd -m sha-512 > $out/password-hash
'';
# the tools required by the script
runtimeInputs = [ pkgs.mkpasswd ];
};
# ensure users are immutable (otherwise the following config might be ignored)
users.mutableUsers = false;
# set the root password to the file containing the hash
users.users.root.hashedPasswordFile =
# clan will make sure, this path exists
config.clan.core.vars.generators.root-password.files.password-hash.path;
}
Inspect the status
Executing clan vars list, you should see the following:
...indicating that the value password-hash for the generator root-password is not set yet.
Generate the values
This step is not strictly necessary, as deploying the machine via clan machines update would trigger the generator as well.
To run the generator, execute clan vars generate for your machine
After entering the value, the updated status is reported:
Observe the changes
With the last step, a new file was created in your repository:
vars/per-machine/my-machine/root-password/password-hash/value
If the repository is a git repository, a commit was created automatically:
$ git log -n1
commit ... (HEAD -> master)
Author: ...
Date: ...
Update vars via generator root-password for machine grmpf-nix
Update the machine
Share root password between machines
If we just imported the root-password.nix from above into more machines, clan would ask for a new password for each additional machine.
If the root password instead should only be entered once and shared across all machines, the generator defined above needs to be declared as shared, by adding share = true to it:
Importing that shared generator into each machine, will ensure that the password is only asked once the first machine gets updated and then re-used for all subsequent machines.
Change the root password
Changing the password can be done via this command.
Replace my-machine with your machine.
If the password is shared, just pick any machine that has the generator declared.