Skip to content

Understanding Clan Vars - Concepts & Architecture

This guide explains the architecture and design principles behind the vars system. For a hands-on tutorial, see the Getting Started guide.

Architecture Overview

The vars system provides a declarative, reproducible way to manage generated files (especially secrets) in NixOS configurations.

Data Flow

graph LR
    A[Generator Script] --> B[Output Files]
    C[User Prompts] --> A
    D[Dependencies] --> A
    B --> E[Secret Storage<br/>sops/password-store]
    B --> F[Nix Store<br/>public files]
    E --> G[Machine Deployment]
    F --> G

Key Design Principles

1. Declarative Generation

Unlike imperative secret management, vars are declared in your NixOS configuration and generated deterministically. This ensures reproducibility across deployments.

2. Separation of Concerns

  • Generation logic: Defined in generator scripts
  • Storage: Handled by pluggable backends (sops, password-store, etc.)
  • Deployment: Managed by NixOS activation scripts
  • Access control: Enforced through file permissions and ownership

3. Composability Through Dependencies

Generators can depend on outputs from other generators, enabling complex workflows:

# Dependencies create a directed acyclic graph (DAG)
A → B → C
    ↓
    D

This allows building sophisticated systems like certificate authorities where intermediate certificates depend on root certificates.

4. Type Safety

The vars system distinguishes between: - Secret files: Only accessible via .path, deployed to /run/secrets/ - Public files: Accessible via .value, stored in nix store

This prevents accidental exposure of secrets in the nix store.

Storage Backend Architecture

The vars system uses pluggable storage backends:

  • sops (default): Integrates with clan's existing sops encryption
  • password-store: For users already using pass

Each backend handles encryption/decryption transparently, allowing the same generator definitions to work across different security models.

Timing and Lifecycle

Generation Phases

  1. Pre-deployment: clan vars generate creates vars before deployment
  2. During deployment: Missing vars are generated automatically
  3. Regeneration: Explicit regeneration with --regenerate flag

The neededFor Option

Control when vars are available during system activation:

files."early-secret" = {
  secret = true;
  neededFor = [ "users" "groups" ];  # Available early in activation
};

Advanced Patterns

Multi-Machine Coordination

The share option enables cross-machine secret sharing:

graph LR
    A[Shared Generator] --> B[Machine 1]
    A --> C[Machine 2]
    A --> D[Machine 3]

This is useful for: - Shared certificate authorities - Mesh VPN pre-shared keys - Cluster join tokens

Generator Composition

Complex systems can be built by composing simple generators:

root-ca → intermediate-ca → service-cert
         ↓
     ocsp-responder

Each generator focuses on one task, making the system modular and testable.

Key Advantages

Compared to manual secret management, vars provides:

  • Declarative configuration: Define once, generate consistently
  • Dependency management: Build complex systems with generator dependencies
  • Type safety: Separate handling of secret and public files
  • User prompts: Gather input when needed
  • Easy regeneration: Update secrets with a single command

Next Steps