Vars System Overview

The vars system is clan's declarative solution for managing generated files, secrets, and dynamic configuration in your NixOS deployments. It eliminates the manual steps of generating credentials, certificates, and other dynamic values by automating these processes within your infrastructure-as-code workflow.

What Problems Does Vars Solve?

Before Vars: Manual Secret Management

Traditional NixOS deployments require manual steps for secrets and generated files:

# Generate password hash manually
mkpasswd -m sha-512 > /tmp/root-password-hash
# Copy hash into configuration
users.users.root.hashedPasswordFile = "/tmp/root-password-hash";

This approach has several problems:

• Not reproducible: Manual steps vary between team members

• Hard to maintain: Updating secrets requires remembering manual commands

• Deployment friction: Secrets must be managed outside of your configuration

• Team collaboration issues: Sharing credentials securely is complex

After Vars: Declarative Generation

With vars, the same process becomes declarative and automated:

clan.core.vars.generators.root-password = {
  prompts.password.description = "Root password";
  prompts.password.type = "hidden";
  files.hash.secret = false;
  script = "mkpasswd -m sha-512 < $prompts/password > $out/hash";
  runtimeInputs = [ pkgs.mkpasswd ];
};

users.users.root.hashedPasswordFile = 
  config.clan.core.vars.generators.root-password.files.hash.path;

Core Benefits

• 🔄 Reproducible: Same inputs always produce the same outputs
• 📝 Declarative: Defined alongside your NixOS configuration
• 🔐 Secure: Automatic secret storage and encrypted deployment
• 👥 Collaborative: Built-in sharing for team environments
• 🚀 Automated: No manual intervention required for deployments
• 🔗 Integrated: Works seamlessly with clan's deployment workflow

How It Works

graph TB
    A[Generator Declaration] --> B[clan vars generate]
    B --> C{Prompts User}
    C --> D[Execute Script]
    D --> E[Output Files]
    E --> F{Secret?}
    F -->|Yes| G[Encrypted Storage]
    F -->|No| H[Git Repository]
    G --> I[Deploy to Machine]
    H --> I
    I --> J[Available in NixOS]

1. Declare generators in your NixOS configuration
2. Generate values using clan vars generate (or automatically during deployment)
3. Store securely in encrypted backends or version control
4. Deploy seamlessly to your machines where they're accessible as file paths

Common Use Cases

Architecture Overview

The vars system has three main components:

1. Generators

Define how to create files from inputs:

• Prompts: Values requested from users

• Scripts: Generation logic

• Dependencies: Other generators this depends on

• Outputs: Files that get created

2. Storage Backends

Handle secret storage and deployment:

• sops: Encrypted files in git (recommended)

• password-store: GPG/age-based secret storage

Quick Start Example

Here's a complete example showing password generation and usage:

# generator.nix
{ config, pkgs, ... }: {
  clan.core.vars.generators.user-password = {
    prompts.password = {
      description = "User password";
      type = "hidden";
    };
    files.hash = { secret = false; };
    script = ''
      mkpasswd -m sha-512 < $prompts/password > $out/hash
    '';
    runtimeInputs = [ pkgs.mkpasswd ];
  };

  users.users.myuser = {
    hashedPasswordFile = 
      config.clan.core.vars.generators.user-password.files.hash.path;
  };
}

# Generate the password
clan vars generate my-machine

# Deploy to machine
clan machines update my-machine

Migration from Facts

If you're currently using the legacy facts system, see our Migration Guide for step-by-step instructions on upgrading to vars.