diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index a40b4e69a..2787d32bf 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -61,8 +61,6 @@ nav: - Continuous Integration: guides/getting-started/flake-check.md - Convert Existing NixOS Config: guides/getting-started/convert-flake.md - ClanServices: guides/clanServices.md - - Backup & Restore: guides/backups.md - - Disk Encryption: guides/disk-encryption.md - Vars: - Overview: guides/vars-overview.md - Getting Started: guides/vars-backend.md @@ -70,6 +68,8 @@ nav: - Advanced Examples: guides/vars-advanced-examples.md - Troubleshooting: guides/vars-troubleshooting.md - Age Plugins: guides/age-plugins.md + - Backup & Restore: guides/backups.md + - Disk Encryption: guides/disk-encryption.md - Secrets management: guides/secrets.md - Networking: guides/networking.md - Zerotier VPN: guides/mesh-vpn.md @@ -89,7 +89,6 @@ nav: - Disk id: guides/migrations/disk-id.md - Concepts: - Inventory: concepts/inventory.md - - Generators: concepts/generators.md - Autoincludes: concepts/autoincludes.md - Templates: concepts/templates.md - Reference: diff --git a/docs/site/concepts/generators.md b/docs/site/concepts/generators.md deleted file mode 100644 index 107e6fc42..000000000 --- a/docs/site/concepts/generators.md +++ /dev/null @@ -1,45 +0,0 @@ -# Generators - -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. - -## What are Generators? - -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. - -A generator defines: - -- **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 - -## Key Benefits - -- **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 - -## Common Use Cases - -- **Password hashing**: Generate secure password hashes for user accounts -- **SSH keys**: Create and manage SSH host and user keys -- **Certificates**: Generate TLS certificates and certificate authorities -- **API tokens**: Create secure random tokens for services -- **Configuration files**: Generate config files that depend on secrets - -## Learning Path - -1. **Start here**: [Vars Getting Started Guide](../guides/vars-backend.md) - Hands-on tutorial with practical examples -2. **Understand the architecture**: [Vars Concepts Guide](../guides/vars-concepts.md) - Deep dive into design principles and patterns -3. **Explore complex scenarios**: [Advanced Examples](../guides/vars-advanced-examples.md) - Real-world patterns and best practices -4. **Troubleshoot issues**: [Troubleshooting Guide](../guides/vars-troubleshooting.md) - Common problems and solutions - -## API Reference - -For complete configuration options and technical details, see: - -- [Vars NixOS Module Reference](../reference/clan.core/vars.md) - All configuration options -- [Vars CLI Reference](../reference/cli/vars.md) - Command-line interface \ No newline at end of file diff --git a/docs/site/guides/vars-advanced-examples.md b/docs/site/guides/vars-advanced-examples.md index 9cbe40fbb..9729dd8f8 100644 --- a/docs/site/guides/vars-advanced-examples.md +++ b/docs/site/guides/vars-advanced-examples.md @@ -1,6 +1,7 @@ # Advanced Vars Examples -This guide demonstrates complex, real-world patterns for the vars system. For basic usage, see the [Getting Started guide](vars-backend.md). +This guide demonstrates complex, real-world patterns for the vars system. + ## Certificate Authority with Intermediate Certificates diff --git a/docs/site/guides/vars-backend.md b/docs/site/guides/vars-backend.md index bf6c076a0..9050d9d86 100644 --- a/docs/site/guides/vars-backend.md +++ b/docs/site/guides/vars-backend.md @@ -1,27 +1,19 @@ +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. -!!! Note - This guide demonstrates the vars system for managing secrets and generated files +For a detailed API reference, see the [vars module documentation](../reference/clan.core/vars.md). +In this guide, you will learn how to: -Defining a linux user's password via the nixos configuration previously required running `mkpasswd ...` and then copying the hash back into the nix configuration. +1. Declare a `generator` in the machine's NixOS configuration. +2. Inspect the status of variables using the Clan CLI. +3. Generate variables interactively. +4. Observe the changes made to your repository. +5. Update the machine configuration. +6. Share the root password between multiple machines. +7. Change the root password when needed. -In this example, we will guide you through automating that interaction using clan `vars`. +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. -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). - -This guide assumes -- Clan is set up already (see [Getting Started](../guides/getting-started/index.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: - -1. declare a `generator` in the machine's nixos configuration -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 the generator @@ -144,12 +136,3 @@ Updated var root-password/password-hash 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) diff --git a/docs/site/guides/vars-concepts.md b/docs/site/guides/vars-concepts.md index eb742219f..62b61d109 100644 --- a/docs/site/guides/vars-concepts.md +++ b/docs/site/guides/vars-concepts.md @@ -1,6 +1,6 @@ # 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](vars-backend.md). +This guide explains the architecture and design principles behind the vars system. ## Architecture Overview @@ -121,9 +121,3 @@ Compared to manual secret management, vars provides: - **User prompts**: Gather input when needed - **Easy regeneration**: Update secrets with a single command -## Next Steps - -- [Practical Tutorial](vars-backend.md) - Step-by-step guide -- [Advanced Examples](vars-advanced-examples.md) - Real-world patterns -- [Troubleshooting](vars-troubleshooting.md) - Common issues -- [Reference](../reference/clan.core/vars.md) - Complete API diff --git a/docs/site/guides/vars-overview.md b/docs/site/guides/vars-overview.md index 7cf60a6d3..73582ef67 100644 --- a/docs/site/guides/vars-overview.md +++ b/docs/site/guides/vars-overview.md @@ -16,9 +16,13 @@ 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 @@ -85,46 +89,21 @@ 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 @@ -164,6 +143,3 @@ clan machines update my-machine 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. \ No newline at end of file diff --git a/docs/site/guides/vars-troubleshooting.md b/docs/site/guides/vars-troubleshooting.md index b35e4a827..98a23fd67 100644 --- a/docs/site/guides/vars-troubleshooting.md +++ b/docs/site/guides/vars-troubleshooting.md @@ -1,6 +1,6 @@ # Troubleshooting Vars -Quick reference for diagnosing and fixing vars issues. For basic usage, see the [Getting Started guide](vars-backend.md). +Quick reference for diagnosing and fixing vars issues. ## Common Issues @@ -240,8 +240,11 @@ clan vars list my-machine **Solution**: Ensure your user/machine has the correct age keys configured. Clan manages encryption keys automatically based on the configured users and machines in your flake. Check that: + 1. Your machine is properly configured in the flake + 2. Your user has access to the machine's secrets + 3. The age key is available in the expected location ### Password Store Issues @@ -261,6 +264,9 @@ If these solutions don't resolve your issue: 1. Check the [clan-core issue tracker](https://git.clan.lol/clan/clan-core/issues) 2. Ask in the Clan community channels 3. Provide: - - The generator configuration - - The exact error message - - Output of `clan --debug vars generate` \ No newline at end of file + + - The generator configuration + + - The exact error message + + - Output of `clan --debug vars generate` \ No newline at end of file