yadunut/clan-core
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

docs: vars ai fixups

Browse Source
This commit is contained in:
Qubasa
2025-09-09 22:39:03 +02:00
parent 79d44f7c30
commit ef66c9b5be
4 changed files with 207 additions and 147 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
docs/mkdocs.yml
View File

@@ -63,19 +63,17 @@ nav:
- ClanServices: guides/clanServices.md - ClanServices: guides/clanServices.md
- Backup & Restore: guides/backups.md - Backup & Restore: guides/backups.md
- Disk Encryption: guides/disk-encryption.md - Disk Encryption: guides/disk-encryption.md
- Mesh VPN: guides/mesh-vpn.md
- Backup & Restore: guides/backups.md
- Vars: - Vars:
- Overview: guides/vars-overview.md
- Getting Started: guides/vars-backend.md - Getting Started: guides/vars-backend.md
- Concepts: guides/vars-concepts.md - Concepts: guides/vars-concepts.md
- Advanced Examples: guides/vars-advanced-examples.md - Advanced Examples: guides/vars-advanced-examples.md
- Troubleshooting: guides/vars-troubleshooting.md - Troubleshooting: guides/vars-troubleshooting.md
- Facts Backend: guides/secrets.md - Age Plugins: guides/age-plugins.md
- Adding more machines: guides/more-machines.md - Secrets management: guides/secrets.md
- Target Host: guides/target-host.md - Networking: guides/networking.md
- Inventory: - Zerotier VPN: guides/mesh-vpn.md
- Inventory: guides/inventory.md - How to disable Secure Boot: guides/secure-boot.md
- Secure Boot: guides/secure-boot.md
- Flake-parts: guides/flake-parts.md - Flake-parts: guides/flake-parts.md
- macOS: guides/macos.md - macOS: guides/macos.md
- Contributing: - Contributing:

167
docs/site/concepts/generators.md
View File

@@ -1,152 +1,45 @@
# Generators # Generators
Defining a linux user's password via the nixos configuration previously required running `mkpasswd ...` and then copying the hash back into the nix configuration. Generators are the core mechanism of the clan vars system for automating the creation and management of generated files, especially secrets, in your NixOS configurations.
In this example, we will guide you through automating that interaction using clan `vars`. ## What are Generators?
For architectural concepts and design principles, see the [Concepts guide](vars-concepts.md). For the complete API reference, see the [vars module documentation](../reference/clan.core/vars.md). Generators solve a common problem: instead of manually running commands like `mkpasswd` to create password hashes and copying them into your configuration, generators automate this process declaratively.
This guide assumes A generator defines:
- Clan is set up already (see [Getting Started](../guides/getting-started/index.md))
- a machine has been added to the clan (see [Adding Machines](../guides/getting-started/add-machines.md))
This section will walk you through the following steps: - **Input prompts**: Values to request from users (passwords, names, etc.)
- **Generation script**: Logic to transform inputs into outputs
- **Output files**: Generated files that can be secrets or public data
- **Dependencies**: Other generators this one depends on
- **Runtime inputs**: Tools and packages needed by the script
1. declare a `generator` in the machine's nixos configuration ## Key Benefits
2. inspect the status via the Clan CLI
3. generate the vars
4. observe the changes
5. update the machine
6. share the root password between machines
7. change the password
## Declare a generator - **Reproducible**: Same inputs produce same outputs across machines
- **Declarative**: Defined in your NixOS configuration alongside usage
- **Secure**: Automatic handling of secrets storage and deployment
- **Collaborative**: Shared generators work across team environments
- **Automated**: No manual copy-paste of generated values
In this example, a `vars` `generator` is used to: ## Common Use Cases
- prompt the user for the password - **Password hashing**: Generate secure password hashes for user accounts
- run the required `mkpasswd` command to generate the hash - **SSH keys**: Create and manage SSH host and user keys
- store the hash in a file - **Certificates**: Generate TLS certificates and certificate authorities
- expose the file path to the nixos configuration - **API tokens**: Create secure random tokens for services
- **Configuration files**: Generate config files that depend on secrets
Create a new nix file `root-password.nix` with the following content and import it into your `configuration.nix` ## Learning Path
```nix
{config, pkgs, ...}: {
clan.core.vars.generators.root-password = { 1. **Start here**: [Vars Getting Started Guide](../guides/vars-backend.md) - Hands-on tutorial with practical examples
# prompt the user for a password 2. **Understand the architecture**: [Vars Concepts Guide](../guides/vars-concepts.md) - Deep dive into design principles and patterns
# (`password-input` being an arbitrary name) 3. **Explore complex scenarios**: [Advanced Examples](../guides/vars-advanced-examples.md) - Real-world patterns and best practices
prompts.password-input.description = "the root user's password"; 4. **Troubleshoot issues**: [Troubleshooting Guide](../guides/vars-troubleshooting.md) - Common problems and solutions
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) ## API Reference
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 For complete configuration options and technical details, see:
Executing `clan vars list`, you should see the following: - [Vars NixOS Module Reference](../reference/clan.core/vars.md) - All configuration options
```shellSession - [Vars CLI Reference](../reference/cli/vars.md) - Command-line interface
$ clan vars list my_machine
root-password/password-hash: <not set>
```
...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
```shellSession
$ clan vars generate my_machine
Enter the value for root-password/password-input (hidden):
```
After entering the value, the updated status is reported:
```shellSession
Updated var root-password/password-hash
old: <not set>
new: $6$RMats/YMeypFtcYX$DUi...
```
## 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:
```shellSession
$ git log -n1
commit ... (HEAD -> master)
Author: ...
Date: ...
Update vars via generator root-password for machine grmpf-nix
```
## Update the machine
```shell
clan machines update my_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:
```nix
{config, pkgs, ...}: {
clan.vars.generators.root-password = {
share = true;
# ...
}
}
```
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.
```shellSession
$ clan vars generate my-machine --generator root-password --regenerate
...
Enter the value for root-password/password-input (hidden):
Input received. Processing...
...
Updated var root-password/password-hash
old: $6$tb27m6EOdff.X9TM$19N...
new: $6$OyoQtDVzeemgh8EQ$zRK...
```
## Further Reading
- [Understanding Vars Concepts](vars-concepts.md) - Learn about the architecture and core concepts
- [Advanced Examples](vars-advanced-examples.md) - Complex real-world examples including certificates, SSH keys, and more
- [Troubleshooting Guide](vars-troubleshooting.md) - Common issues and solutions
- [Migration Guide](migrations/migration-facts-vars.md) - Migrate from legacy facts system
- [Reference Documentation for `clan.core.vars` NixOS options](../reference/clan.core/vars.md)
- [Reference Documentation for the `clan vars` CLI command](../reference/cli/vars.md)

4
docs/site/guides/vars-backend.md
View File

@@ -11,7 +11,7 @@ For architectural concepts and design principles, see the [Concepts guide](vars-
This guide assumes This guide assumes
- Clan is set up already (see [Getting Started](../guides/getting-started/index.md)) - Clan is set up already (see [Getting Started](../guides/getting-started/index.md))
- a machine has been added to the clan (see [Adding Machines](./more-machines.md)) - a machine has been added to the clan (see [Adding Machines](getting-started/add-machines.md))
This section will walk you through the following steps: This section will walk you through the following steps:
@@ -117,7 +117,7 @@ If we just imported the `root-password.nix` from above into more machines, clan
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: 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:
```nix ```nix
{config, pkgs, ...}: { {config, pkgs, ...}: {
clan.vars.generators.root-password = { clan.core.vars.generators.root-password = {
share = true; share = true;
# ... # ...
} }

169
docs/site/guides/vars-overview.md Normal file
View File

@@ -0,0 +1,169 @@
# 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:
```bash
# 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:
```nix
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
```mermaid
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
| Use Case | What Gets Generated | Benefits |
|----------|-------------------|----------|
| **User passwords** | Password hashes | No plaintext in config |
| **SSH keys** | Host/user keypairs | Automated key rotation |
| **TLS certificates** | Certificates + private keys | Automated PKI |
| **Database credentials** | Passwords + connection strings | Secure service communication |
| **API tokens** | Random tokens | Service authentication |
| **Configuration files** | Complex configs with secrets | Dynamic config generation |
## 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
- **vm**: For development/testing
### 3. **Integration**
Seamless NixOS integration:
- File paths available at build time
- Automatic deployment to machines
- Service restarts on changes
## Learning Path
Ready to get started? Follow this recommended path:
### 1. **🚀 Hands-On Tutorial**
[Vars Getting Started Guide](vars-backend.md)
Start here for a practical walkthrough with password generation.
### 2. **🏗️ Understand the Design**
[Vars Concepts & Architecture](vars-concepts.md)
Deep dive into design principles and advanced patterns.
### 3. **💡 Real-World Examples**
[Advanced Examples](vars-advanced-examples.md)
Complex scenarios including certificates, SSH keys, and databases.
### 4. **🔧 Troubleshooting**
[Troubleshooting Guide](vars-troubleshooting.md)
Solutions for common issues and debugging techniques.
### 5. **📚 Complete Reference**
- [NixOS Module Options](../reference/clan.core/vars.md)
- [CLI Commands](../reference/cli/vars.md)
## Quick Start Example
Here's a complete example showing password generation and usage:
```nix
# 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;
};
}
```
```bash
# 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](migrations/migration-facts-vars.md) for step-by-step instructions on upgrading to vars.
---
**Ready to start?** Head to the [Getting Started Guide](vars-backend.md) for your first hands-on experience with the vars system.