Merge pull request 'Improve backup documentation' (#5272) from Qubasa/clan-core:docs_fix2 into main
Reviewed-on: https://git.clan.lol/clan/clan-core/pulls/5272
This commit is contained in:
Luis Hebendanz
@@ -54,7 +54,7 @@
|
||||
authorizedKeys = [ (builtins.readFile (borgbackupIpMachinePath machineName)) ];
|
||||
# };
|
||||
# }) machinesWithKey;
|
||||
}) roles.client.machines;
|
||||
}) (roles.client.machines or { });
|
||||
in
|
||||
hosts;
|
||||
};
|
||||
@@ -187,7 +187,7 @@
|
||||
config.clan.core.vars.generators.borgbackup.files."borgbackup.ssh".path
|
||||
} -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null -o IdentitiesOnly=Yes";
|
||||
};
|
||||
}) (builtins.attrNames roles.server.machines);
|
||||
}) (builtins.attrNames (roles.server.machines or { }));
|
||||
in
|
||||
(builtins.listToAttrs destinations);
|
||||
|
||||
|
||||
@@ -63,7 +63,6 @@ nav:
|
||||
- Inventory:
|
||||
- Introduction to Inventory: guides/inventory/inventory.md
|
||||
- File Autoincludes: guides/inventory/autoincludes.md
|
||||
|
||||
- Clan Services:
|
||||
- Inventory Guide: guides/inventory/clanServices.md
|
||||
- Author Your Own Service: guides/services/community.md
|
||||
@@ -76,24 +75,26 @@ nav:
|
||||
- Sops Backend:
|
||||
- Yubikeys & Age Plugins: guides/vars/sops/age-plugins.md
|
||||
- Managing Users (OLD): guides/secrets.md
|
||||
- Backups:
|
||||
- Introduction to Backups: guides/backups/backup-intro.md
|
||||
- Minimal Example: guides/backups/minimal-example.md
|
||||
- Digging Deeper: guides/backups/digging-deeper.md
|
||||
- Advanced Example: guides/backups/advanced-example.md
|
||||
- Networking:
|
||||
- Introduction to Networking: guides/networking/networking.md
|
||||
- Zerotier VPN: guides/networking/mesh-vpn.md
|
||||
- Nixpkgs Flake Input: guides/nixpkgs-flake-input/index.md
|
||||
- Disko Templates:
|
||||
- Community Disko Templates: guides/disko-templates/community.md
|
||||
- Backups:
|
||||
- Introduction to Backups: guides/backups.md
|
||||
- Flake-parts: guides/flake-parts.md
|
||||
- NixOS Rebuild: guides/nixos-rebuild.md
|
||||
- macOS:
|
||||
- Managing macOS Machines: guides/macos.md
|
||||
- macOS: guides/macos.md
|
||||
# Should be part of the respective sections above
|
||||
# machines, disko, clan
|
||||
- Templates: concepts/templates.md
|
||||
- Templates:
|
||||
- Introduction to Templates: concepts/templates.md
|
||||
- Community Disko Templates: guides/disko-templates/community.md
|
||||
- Migrations:
|
||||
- clan modules --> clan services: guides/migrations/migrate-inventory-services.md
|
||||
- Facts --> Vars: guides/migrations/migration-facts-vars.md
|
||||
- clan modules to clan services: guides/migrations/migrate-inventory-services.md
|
||||
- Facts to Vars: guides/migrations/migration-facts-vars.md
|
||||
- Disk id: guides/migrations/disk-id.md
|
||||
- Disk Encryption: guides/disk-encryption.md
|
||||
- Disable Secure Boot: guides/secure-boot.md
|
||||
|
||||
@@ -1,195 +0,0 @@
|
||||
This guide explains how to set up and manage
|
||||
[BorgBackup](https://borgbackup.readthedocs.io/) for secure, efficient backups
|
||||
in a clan network. BorgBackup provides:
|
||||
|
||||
- Space efficient storage of backups with deduplication
|
||||
- Secure, authenticated encryption
|
||||
- Compression: lz4, zstd, zlib, lzma or none
|
||||
- Mountable backups with FUSE
|
||||
- Easy installation on multiple platforms: Linux, macOS, BSD, …
|
||||
- Free software (BSD license).
|
||||
- Backed by a large and active open-source community.
|
||||
|
||||
## Borgbackup Example
|
||||
|
||||
```nix
|
||||
inventory.instances = {
|
||||
borgbackup = {
|
||||
module = {
|
||||
name = "borgbackup";
|
||||
input = "clan-core";
|
||||
};
|
||||
roles.client.machines."jon".settings = {
|
||||
destinations."storagebox" = {
|
||||
repo = "username@$hostname:/./borgbackup";
|
||||
rsh = ''ssh -oPort=23 -i /run/secrets/vars/borgbackup/borgbackup.ssh'';
|
||||
};
|
||||
};
|
||||
roles.server.machines = { };
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
The input should be named according to your flake input. Jon is configured as a
|
||||
client machine with a destination pointing to a Hetzner Storage Box.
|
||||
|
||||
To see a list of all possible options go to [borgbackup clan service](../reference/clanServices/borgbackup.md)
|
||||
|
||||
## Roles
|
||||
|
||||
A Clan Service can have multiple roles, each role applies different nix config to the machine.
|
||||
|
||||
### 1. Client
|
||||
|
||||
Clients are machines that create and send backups to various destinations. Each
|
||||
client can have multiple backup destinations configured.
|
||||
|
||||
### 2. Server
|
||||
|
||||
Servers act as backup repositories, receiving and storing backups from client
|
||||
machines. They can be dedicated backup servers within your clan network.
|
||||
|
||||
## Backup destinations
|
||||
|
||||
This service allows you to perform backups to multiple `destinations`.
|
||||
Destinations can be:
|
||||
|
||||
- **Local**: Local disk storage
|
||||
- **Server**: Your own borgbackup server (using the `server` role)
|
||||
- **Third-party services**: Such as Hetzner's Storage Box
|
||||
|
||||
## State management
|
||||
|
||||
Backups are based on [states](../reference/clan.core/state.md). A state
|
||||
defines which files should be backed up and how these files are obtained through
|
||||
pre/post backup and restore scripts.
|
||||
|
||||
Here's an example for a user application `linkding`:
|
||||
|
||||
In this example:
|
||||
|
||||
- `/data/podman/linkding` is the application's data directory
|
||||
- `/var/backup/linkding` is the staging directory where data is copied for
|
||||
backup
|
||||
|
||||
```nix
|
||||
clan.core.state.linkding = {
|
||||
folders = [ "/var/backup/linkding" ];
|
||||
|
||||
preBackupScript = ''
|
||||
export PATH=${
|
||||
lib.makeBinPath [
|
||||
config.systemd.package
|
||||
pkgs.coreutils
|
||||
pkgs.rsync
|
||||
]
|
||||
}
|
||||
|
||||
service_status=$(systemctl is-active podman-linkding)
|
||||
|
||||
if [ "$service_status" = "active" ]; then
|
||||
systemctl stop podman-linkding
|
||||
rsync -avH --delete --numeric-ids "/data/podman/linkding/" /var/backup/linkding/
|
||||
systemctl start podman-linkding
|
||||
fi
|
||||
'';
|
||||
|
||||
postRestoreScript = ''
|
||||
export PATH=${
|
||||
lib.makeBinPath [
|
||||
config.systemd.package
|
||||
pkgs.coreutils
|
||||
pkgs.rsync
|
||||
]
|
||||
}
|
||||
|
||||
service_status="$(systemctl is-active podman-linkding)"
|
||||
|
||||
if [ "$service_status" = "active" ]; then
|
||||
systemctl stop podman-linkding
|
||||
|
||||
# Backup locally current linkding data
|
||||
cp -rp "/data/podman/linkding" "/data/podman/linkding.bak"
|
||||
|
||||
# Restore from borgbackup
|
||||
rsync -avH --delete --numeric-ids /var/backup/linkding/ "/data/podman/linkding/"
|
||||
|
||||
systemctl start podman-linkding
|
||||
fi
|
||||
'';
|
||||
};
|
||||
```
|
||||
|
||||
## Managing backups
|
||||
|
||||
In this section we go over how to manage your collection of backups with the clan command.
|
||||
|
||||
### Listing states
|
||||
|
||||
To see which files (`states`) will be backed up on a specific machine, use:
|
||||
|
||||
```bash
|
||||
clan state list jon
|
||||
```
|
||||
|
||||
This will show all configured states for the machine `jon`, for example:
|
||||
|
||||
```text
|
||||
· service: linkding
|
||||
folders:
|
||||
- /var/backup/linkding
|
||||
preBackupCommand: pre-backup-linkding
|
||||
postRestoreCommand: post-restore-linkding
|
||||
|
||||
· service: zerotier
|
||||
folders:
|
||||
- /var/lib/zerotier-one
|
||||
```
|
||||
|
||||
### Creating backups
|
||||
|
||||
To create a backup of a machine (e.g., `jon`), run:
|
||||
|
||||
```bash
|
||||
clan backups create jon
|
||||
```
|
||||
|
||||
This will backup all configured states (`zerotier` and `linkding` in this
|
||||
example) from the machine `jon`.
|
||||
|
||||
### Listing available backups
|
||||
|
||||
To see all available backups, use:
|
||||
|
||||
```bash
|
||||
clan backups list
|
||||
```
|
||||
|
||||
This will display all backups with their timestamps:
|
||||
|
||||
```text
|
||||
storagebox::username@username.your-storagebox.de:/./borgbackup::jon-jon-2025-07-22T19:40:10
|
||||
storagebox::username@username.your-storagebox.de:/./borgbackup::jon-jon-2025-07-23T01:00:00
|
||||
storagebox::username@username.your-storagebox.de:/./borgbackup::jon-storagebox-2025-07-24T01:00:00
|
||||
storagebox::username@username.your-storagebox.de:/./borgbackup::jon-storagebox-2025-07-24T06:02:35
|
||||
```
|
||||
|
||||
### Restoring backups
|
||||
|
||||
For restoring a backup you have two options.
|
||||
|
||||
#### Full restoration
|
||||
|
||||
To restore all services from a backup:
|
||||
|
||||
```bash
|
||||
clan backups restore jon borgbackup storagebox::u444061@u444061.your-storagebox.de:/./borgbackup::jon-storagebox-2025-07-24T06:02:35
|
||||
```
|
||||
|
||||
#### Partial restoration
|
||||
|
||||
To restore only a specific service (e.g., `linkding`):
|
||||
|
||||
```bash
|
||||
clan backups restore --service linkding jon borgbackup storagebox::u444061@u444061.your-storagebox.de:/./borgbackup::jon-storagebox-2025-07-24T06:02:35
|
||||
```
|
||||
71
docs/site/guides/backups/advanced-example.md
Normal file
71
docs/site/guides/backups/advanced-example.md
Normal file
@@ -0,0 +1,71 @@
|
||||
This guide explains how to set up a [Hetzner Storage Box](https://docs.hetzner.com/storage/storage-box/general) as a backup destination instead of using an internal Clan backup server. Follow the steps below to configure and verify the setup.
|
||||
|
||||
### Step 1: Create a Hetzner Storage Box
|
||||
|
||||
Begin by [creating a Hetzner Storage Box account](https://docs.hetzner.com/storage/storage-box/getting-started/creating-a-storage-box).
|
||||
|
||||
### Step 2: Create a Sub-Account
|
||||
|
||||
Set up a sub-account for your `jon` machine. Save the SSH password for this account in your password manager for future reference.
|
||||
|
||||
### Step 3: Configure BorgBackup in `clan.nix`
|
||||
|
||||
Add the BorgBackup service to your `clan.nix` configuration. In this example, the `jon` machine will back up to `user-sub1@user-sub1.your-storagebox.de` in the `borgbackup` folder:
|
||||
|
||||
```nix hl_lines="9"
|
||||
inventory.instances = {
|
||||
borgbackup = {
|
||||
module = {
|
||||
name = "borgbackup";
|
||||
input = "clan-core";
|
||||
};
|
||||
roles.client.machines."jon".settings = {
|
||||
destinations."storagebox" = {
|
||||
repo = "user-sub1@user-sub1.your-storagebox.de:/./borgbackup";
|
||||
rsh = ''ssh -p 23 -oStrictHostKeyChecking=accept-new -i /run/secrets/vars/borgbackup/borgbackup.ssh'';
|
||||
};
|
||||
};
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
### Step 4: Generate SSH Keys
|
||||
|
||||
Run the following command to generate the SSH private keys:
|
||||
|
||||
```bash
|
||||
clan vars generate
|
||||
```
|
||||
|
||||
### Step 5: Add the Public Key to the Sub-Account
|
||||
|
||||
Add the generated SSH public key to the `user-sub1` account by running:
|
||||
|
||||
```bash
|
||||
clan vars get jon borgbackup/borgbackup.ssh.pub | ssh -p23 user-sub1@user-sub1.your-storagebox.de install-ssh-key
|
||||
```
|
||||
|
||||
### Step 6: Deploy the Configuration
|
||||
|
||||
Apply the changes to your Clan setup by executing:
|
||||
|
||||
```bash
|
||||
clan machines update
|
||||
```
|
||||
|
||||
### Step 7: Verify the Setup
|
||||
|
||||
Check if the configuration works by starting the BorgBackup service on the `jon` machine:
|
||||
|
||||
```bash
|
||||
systemctl start borgbackup-job-storagebox.service &
|
||||
```
|
||||
|
||||
Then, inspect the service logs to ensure everything is functioning correctly:
|
||||
|
||||
```bash
|
||||
journalctl -u borgbackup-job-storagebox.service
|
||||
```
|
||||
|
||||
|
||||
|
||||
89
docs/site/guides/backups/backup-intro.md
Normal file
89
docs/site/guides/backups/backup-intro.md
Normal file
@@ -0,0 +1,89 @@
|
||||
# Introduction to Clan Backups
|
||||
|
||||
This guide explains how to use the Clan backup and state management interface to configure, manage, and restore backups for your services and machines. By the end of this guide, you will understand how to define backup states, manage backups, and restore data.
|
||||
|
||||
## State Management
|
||||
|
||||
Clan backups are based on the concept of [states](../../reference/clan.core/state.md). A state is a Nix attribute set, defined as `clan.core.state.<name> = {};`, which specifies the files or directories to back up.
|
||||
|
||||
For example, if you have a clan service called `linkding`, you can define the folders to back up as follows:
|
||||
|
||||
```nix hl_lines="2"
|
||||
clan.core.state.linkding = {
|
||||
folders = [ "/var/backup/linkding" ];
|
||||
};
|
||||
```
|
||||
|
||||
In this example:
|
||||
|
||||
- `/var/backup/linkding` is the staging directory where data is prepared for backup.
|
||||
|
||||
This simple configuration ensures that all critical data for the `linkding` service is included in the backup process.
|
||||
|
||||
|
||||
## Custom Pre and Post Backup Hooks
|
||||
|
||||
The state interface allows you to run custom scripts before creating a backup and after restoring one. These scripts are defined using the `preBackupScript` and `postRestoreScript` options. This can be useful for tasks like stopping services, syncing data, or performing cleanup operations.
|
||||
|
||||
### Example: Pre and Post Backup Scripts for the `linkding` Service
|
||||
|
||||
In the following example, we configure the `linkding` service to:
|
||||
|
||||
1. Stop the service before backing up its data.
|
||||
2. Sync the data to a staging directory.
|
||||
3. Restore the data and restart the service after restoration.
|
||||
|
||||
```nix hl_lines="5 26"
|
||||
clan.core.state.linkding = {
|
||||
folders = [ "/var/backup/linkding" ];
|
||||
|
||||
# Script to run before creating a backup
|
||||
preBackupScript = ''
|
||||
export PATH=${
|
||||
lib.makeBinPath [
|
||||
config.systemd.package
|
||||
pkgs.coreutils
|
||||
pkgs.rsync
|
||||
]
|
||||
}
|
||||
|
||||
# Check if the service is running
|
||||
service_status=$(systemctl is-active podman-linkding)
|
||||
|
||||
if [ "$service_status" = "active" ]; then
|
||||
# Stop the service and sync data to the backup directory
|
||||
systemctl stop podman-linkding
|
||||
rsync -avH --delete --numeric-ids "/data/podman/linkding/" /var/backup/linkding/
|
||||
systemctl start podman-linkding
|
||||
fi
|
||||
'';
|
||||
|
||||
# Script to run after restoring a backup
|
||||
postRestoreScript = ''
|
||||
export PATH=${
|
||||
lib.makeBinPath [
|
||||
config.systemd.package
|
||||
pkgs.coreutils
|
||||
pkgs.rsync
|
||||
]
|
||||
}
|
||||
|
||||
# Check if the service is running
|
||||
service_status="$(systemctl is-active podman-linkding)"
|
||||
|
||||
if [ "$service_status" = "active" ]; then
|
||||
# Stop the service
|
||||
systemctl stop podman-linkding
|
||||
|
||||
# Backup current data locally
|
||||
cp -rp "/data/podman/linkding" "/data/podman/linkding.bak"
|
||||
|
||||
# Restore data from the backup directory
|
||||
rsync -avH --delete --numeric-ids /var/backup/linkding/ "/data/podman/linkding/"
|
||||
|
||||
# Restart the service
|
||||
systemctl start podman-linkding
|
||||
fi
|
||||
'';
|
||||
};
|
||||
```
|
||||
75
docs/site/guides/backups/digging-deeper.md
Normal file
75
docs/site/guides/backups/digging-deeper.md
Normal file
@@ -0,0 +1,75 @@
|
||||
|
||||
|
||||
In this section we go over how to manage your collection of backups with the clan command.
|
||||
|
||||
### Listing states
|
||||
|
||||
To see which files (`states`) will be backed up on a specific machine, use:
|
||||
|
||||
```bash
|
||||
clan state list jon
|
||||
```
|
||||
|
||||
This will show all configured states for the machine `jon`, for example:
|
||||
|
||||
```text
|
||||
· service: linkding
|
||||
folders:
|
||||
- /var/backup/linkding
|
||||
preBackupCommand: pre-backup-linkding
|
||||
postRestoreCommand: post-restore-linkding
|
||||
|
||||
· service: zerotier
|
||||
folders:
|
||||
- /var/lib/zerotier-one
|
||||
```
|
||||
|
||||
### Creating backups
|
||||
|
||||
To create a backup of a machine (e.g., `jon`), run:
|
||||
|
||||
```bash
|
||||
clan backups create jon
|
||||
```
|
||||
|
||||
This will backup all configured states (`zerotier` and `linkding` in this
|
||||
example) from the machine `jon`.
|
||||
|
||||
### Listing available backups
|
||||
|
||||
To see all available backups, use:
|
||||
|
||||
```bash
|
||||
clan backups list
|
||||
```
|
||||
|
||||
This will display all backups with their timestamps:
|
||||
|
||||
```text
|
||||
storagebox::username@username.your-storagebox.de:/./borgbackup::jon-jon-2025-07-22T19:40:10
|
||||
storagebox::username@username.your-storagebox.de:/./borgbackup::jon-jon-2025-07-23T01:00:00
|
||||
storagebox::username@username.your-storagebox.de:/./borgbackup::jon-storagebox-2025-07-24T01:00:00
|
||||
storagebox::username@username.your-storagebox.de:/./borgbackup::jon-storagebox-2025-07-24T06:02:35
|
||||
```
|
||||
|
||||
### Restoring backups
|
||||
|
||||
For restoring a backup you have two options.
|
||||
|
||||
#### Full restoration
|
||||
|
||||
To restore all services from a backup:
|
||||
|
||||
```bash
|
||||
clan backups restore jon borgbackup storagebox::u444061@u444061.your-storagebox.de:/./borgbackup::jon-storagebox-2025-07-24T06:02:35
|
||||
```
|
||||
|
||||
#### Partial restoration
|
||||
|
||||
To restore only a specific service (e.g., `linkding`):
|
||||
|
||||
```bash
|
||||
clan backups restore --service linkding jon borgbackup storagebox::u444061@u444061.your-storagebox.de:/./borgbackup::jon-storagebox-2025-07-24T06:02:35
|
||||
```
|
||||
|
||||
|
||||
63
docs/site/guides/backups/minimal-example.md
Normal file
63
docs/site/guides/backups/minimal-example.md
Normal file
@@ -0,0 +1,63 @@
|
||||
In this guide we will explain how to install a simple peer-to-peer backup system through the inventory. Such that machines will backup it's state to other machines in the clan, ensuring redundancy and data safety.
|
||||
|
||||
|
||||
### What is BorgBackup?
|
||||
|
||||
BorgBackup is a powerful and efficient backup solution designed for secure and space-efficient backups. It offers features such as:
|
||||
|
||||
- **Deduplication**: Saves storage space by avoiding duplicate data.
|
||||
- **Encryption**: Ensures backups are secure and authenticated.
|
||||
- **Compression**: Supports multiple compression algorithms like lz4, zstd, zlib, and more.
|
||||
- **FUSE Mounting**: Allows backups to be mounted as a file system.
|
||||
- **Cross-Platform**: Works on Linux, macOS, BSD, and more.
|
||||
- **Open Source**: Licensed under BSD and supported by an active community.
|
||||
|
||||
|
||||
While this guide uses BorgBackup, you can also use other backup services supported by Clan, depending on your requirements.
|
||||
|
||||
|
||||
### Example Setup
|
||||
|
||||
In this example, we configure a backup system with three machines: `bob`, `jon`, and `alice`. The `bob` and `jon` machines will periodically back up their state folders to `alice`. The backups are encrypted for security.
|
||||
|
||||
|
||||
|
||||
```nix
|
||||
inventory.instances = {
|
||||
borgbackup = {
|
||||
module = {
|
||||
name = "borgbackup";
|
||||
input = "clan-core";
|
||||
};
|
||||
roles.client.machines = {
|
||||
"bob" = { };
|
||||
"jon" = { };
|
||||
};
|
||||
roles.server.machines = {
|
||||
"alice" = { };
|
||||
};
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
|
||||
## Roles
|
||||
|
||||
In a Clan Service, roles define how machines participate in the backup system. Each role applies specific Nix configurations to the machine, enabling flexibility and scalability in your backup setup.
|
||||
|
||||
- **Client**: These machines create backups and send them to designated destinations. Clients can be configured to back up to multiple destinations, ensuring redundancy and reliability.
|
||||
|
||||
- **Server**: These machines act as repositories, receiving and securely storing backups from client machines. Servers can be dedicated backup nodes within your clan network, providing centralized storage for all backups.
|
||||
|
||||
|
||||
## Backup destinations
|
||||
|
||||
This service allows you to perform backups to multiple `destinations`.
|
||||
Destinations can be:
|
||||
|
||||
- **Local**: Local disk storage
|
||||
- **Server**: Your own borgbackup server (using the `server` role)
|
||||
- **Third-party services**: Such as Hetzner's Storage Box
|
||||
|
||||
|
||||
However, if BorgBackup does not meet your needs, you can implement your own backup clan service.
|
||||
@@ -1,33 +1,29 @@
|
||||
Clan supports integration with [flake-parts](https://flake.parts/), a framework for constructing your `flake.nix` using modules. Follow these steps to integrate Clan with flake-parts:
|
||||
|
||||
Clan supports integration with [flake-parts](https://flake.parts/), a framework for constructing your `flake.nix` using modules.
|
||||
## Step 1: Update Your Flake Inputs
|
||||
|
||||
To construct your Clan using flake-parts, follow these steps:
|
||||
|
||||
## Update Your Flake Inputs
|
||||
|
||||
To begin, you'll need to add `flake-parts` as a new dependency in your flake's inputs. This is alongside the already existing dependencies, such as `clan-core` and `nixpkgs`. Here's how you can update your `flake.nix` file:
|
||||
Add `flake-parts` as a dependency in your `flake.nix` file alongside existing dependencies like `clan-core` and `nixpkgs`. Here's an example:
|
||||
|
||||
```nix
|
||||
# flake.nix
|
||||
inputs = {
|
||||
nixpkgs.url = "github:NixOS/nixpkgs?ref=nixos-unstable";
|
||||
|
||||
# New flake-parts input
|
||||
# Add flake-parts
|
||||
flake-parts.url = "github:hercules-ci/flake-parts";
|
||||
flake-parts.inputs.nixpkgs-lib.follows = "nixpkgs";
|
||||
|
||||
clan-core = {
|
||||
url = "https://git.clan.lol/clan/clan-core/archive/main.tar.gz";
|
||||
inputs.nixpkgs.follows = "nixpkgs"; # Don't do this if your machines are on nixpkgs stable.
|
||||
# New
|
||||
inputs.flake-parts.follows = "flake-parts";
|
||||
inputs.nixpkgs.follows = "nixpkgs"; # Avoid this if using nixpkgs stable.
|
||||
inputs.flake-parts.follows = "flake-parts"; # New
|
||||
};
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
## Import the Clan flake-parts Module
|
||||
## Step 2: Import the Clan flake-parts Module
|
||||
|
||||
After updating your flake inputs, the next step is to import the Clan flake-parts module. This will make the [Clan options](/options) available within `mkFlake`.
|
||||
Next, import the Clan flake-parts module to make the [Clan options](/options) available within `mkFlake`:
|
||||
|
||||
```nix
|
||||
{
|
||||
@@ -43,9 +39,9 @@ After updating your flake inputs, the next step is to import the Clan flake-part
|
||||
}
|
||||
```
|
||||
|
||||
## Configure Clan Settings and Define Machines
|
||||
## Step 3: Configure Clan Settings and Define Machines
|
||||
|
||||
Next you'll need to configure Clan wide settings and define machines, here's an example of how `flake.nix` should look:
|
||||
Configure Clan-wide settings and define machines. Here's an example `flake.nix`:
|
||||
|
||||
```nix
|
||||
{
|
||||
@@ -62,24 +58,22 @@ Next you'll need to configure Clan wide settings and define machines, here's an
|
||||
];
|
||||
|
||||
# Define your Clan
|
||||
# See: https://docs.clan.lol/reference/nix-api/clan/
|
||||
clan = {
|
||||
# Clan wide settings
|
||||
meta.name = ""; # This is required and must be unique
|
||||
meta.name = ""; # Required and must be unique
|
||||
|
||||
machines = {
|
||||
jon = {
|
||||
imports = [
|
||||
./modules/firefox.nix
|
||||
# ... more modules
|
||||
# Add more modules as needed
|
||||
];
|
||||
|
||||
nixpkgs.hostPlatform = "x86_64-linux";
|
||||
|
||||
# Set this for Clan commands to work remotely over SSH like `clan machines update`
|
||||
# Enable remote Clan commands over SSH
|
||||
clan.core.networking.targetHost = "root@jon";
|
||||
|
||||
# remote> lsblk --output NAME,ID-LINK,FSTYPE,SIZE,MOUNTPOINT
|
||||
# Disk configuration
|
||||
disko.devices.disk.main = {
|
||||
device = "/dev/disk/by-id/nvme-eui.e8238fa6bf530001001b448b4aec2929";
|
||||
};
|
||||
@@ -90,7 +84,4 @@ Next you'll need to configure Clan wide settings and define machines, here's an
|
||||
}
|
||||
```
|
||||
|
||||
For detailed information about configuring `flake-parts` and the available options within Clan,
|
||||
refer to the [Clan module](https://git.clan.lol/clan/clan-core/src/branch/main/flakeModules/clan.nix) documentation.
|
||||
|
||||
---
|
||||
For more details on configuring `flake-parts` and available Clan options, refer to the [Clan module documentation](https://git.clan.lol/clan/clan-core/src/branch/main/flakeModules/clan.nix).
|
||||
|
||||
@@ -1,98 +1,99 @@
|
||||
**Q**: How should I choose the nixpkgs input for my flake when using clan-core?
|
||||
**Q**: How should I choose the `nixpkgs` input for my flake when using `clan-core`?
|
||||
|
||||
**A**: In general, you should pin your flake to a recent nixpkgs version.
|
||||
There are two common ways to do this, each with its own trade-offs:
|
||||
**A**: Pin your flake to a recent `nixpkgs` version. Here are two common approaches, each with its trade-offs:
|
||||
|
||||
## Follow clan-core
|
||||
## Option 1: Follow `clan-core`
|
||||
|
||||
- (+) Recommended for most people.
|
||||
- (+) Verified by our CI and widely used by others
|
||||
- (-) Coupling to version bumps in clan-core,
|
||||
- Upstream features and packages may take longer to land.
|
||||
- **Pros**:
|
||||
- Recommended for most users.
|
||||
- Verified by our CI and widely used by others.
|
||||
- **Cons**:
|
||||
- Coupled to version bumps in `clan-core`.
|
||||
- Upstream features and packages may take longer to land.
|
||||
|
||||
Example:
|
||||
|
||||
```nix
|
||||
inputs = {
|
||||
clan-core.url = "https://git.clan.lol/clan/clan-core/archive/main.tar.gz";
|
||||
# Uses the nixpkgs version that was locked in clan-core
|
||||
nixpkgs.follows = "clan-core/nixpkgs";
|
||||
}
|
||||
clan-core.url = "https://git.clan.lol/clan/clan-core/archive/main.tar.gz";
|
||||
# Use the `nixpkgs` version locked in `clan-core`
|
||||
nixpkgs.follows = "clan-core/nixpkgs";
|
||||
};
|
||||
```
|
||||
|
||||
## Use your own nixpkgs version
|
||||
## Option 2: Use Your Own `nixpkgs` Version
|
||||
|
||||
- (+) Faster access to new upstream features and packages
|
||||
- (-) Recommended for advanced usage.
|
||||
- (-) Not covered by our CI — you’re on the frontier
|
||||
- **Pros**:
|
||||
- Faster access to new upstream features and packages.
|
||||
- **Cons**:
|
||||
- Recommended for advanced users.
|
||||
- Not covered by our CI — you’re on the frontier.
|
||||
|
||||
Example:
|
||||
|
||||
```nix
|
||||
inputs = {
|
||||
# Use your own version here.
|
||||
nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
|
||||
# Specify your own `nixpkgs` version
|
||||
nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
|
||||
|
||||
clan-core.url = "https://git.clan.lol/clan/clan-core/archive/main.tar.gz";
|
||||
# Uses the nixpkgs version of your own flake in clan-core
|
||||
clan-core.inputs.nixpkgs.follows = "nixpkgs";
|
||||
clan-core.url = "https://git.clan.lol/clan/clan-core/archive/main.tar.gz";
|
||||
# Ensure `clan-core` uses your `nixpkgs` version
|
||||
clan-core.inputs.nixpkgs.follows = "nixpkgs";
|
||||
};
|
||||
```
|
||||
|
||||
## Recommended: Avoid Duplicate `nixpkgs` Entries
|
||||
|
||||
To prevent ambiguity or compatibility issues, check your `flake.lock` for duplicate `nixpkgs` entries. Duplicate entries indicate a missing `follows` directive in one of your flake inputs.
|
||||
|
||||
Example of duplicate entries in `flake.lock`:
|
||||
|
||||
```json
|
||||
"nixpkgs": {
|
||||
"locked": {
|
||||
"lastModified": 315532800,
|
||||
"narHash": "sha256-1tUpklZsKzMGI3gjo/dWD+hS8cf+5Jji8TF5Cfz7i3I=",
|
||||
"rev": "08b8f92ac6354983f5382124fef6006cade4a1c1",
|
||||
"type": "tarball",
|
||||
"url": "https://releases.nixos.org/nixpkgs/nixpkgs-25.11pre862603.08b8f92ac635/nixexprs.tar.xz"
|
||||
},
|
||||
"original": {
|
||||
"type": "tarball",
|
||||
"url": "https://nixos.org/channels/nixpkgs-unstable/nixexprs.tar.xz"
|
||||
}
|
||||
},
|
||||
"nixpkgs_2": {
|
||||
"locked": {
|
||||
"lastModified": 1758346548,
|
||||
"narHash": "sha256-afXE7AJ7MY6wY1pg/Y6UPHNYPy5GtUKeBkrZZ/gC71E=",
|
||||
"owner": "nixos",
|
||||
"repo": "nixpkgs",
|
||||
"rev": "b2a3852bd078e68dd2b3dfa8c00c67af1f0a7d20",
|
||||
"type": "github"
|
||||
},
|
||||
"original": {
|
||||
"owner": "nixos",
|
||||
"ref": "nixos-25.05",
|
||||
"repo": "nixpkgs",
|
||||
"type": "github"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Recommended
|
||||
|
||||
To avoid ambiguity or incompatibility issues, it’s a good idea to check your `flake.lock` for duplicate `nixpkgs` entries.
|
||||
This usually indicates that one of your flake inputs is missing a `follows` directive.
|
||||
|
||||
If you see something like this, it means you have multiple versions of `nixpkgs`:
|
||||
To locate the source of duplicate entries, grep your `flake.lock` file. For example, if `home-manager` is referencing `nixpkgs_2` instead of the main `nixpkgs`:
|
||||
|
||||
```json
|
||||
"nixpkgs": {
|
||||
"locked": {
|
||||
"lastModified": 315532800,
|
||||
"narHash": "sha256-1tUpklZsKzMGI3gjo/dWD+hS8cf+5Jji8TF5Cfz7i3I=",
|
||||
"rev": "08b8f92ac6354983f5382124fef6006cade4a1c1",
|
||||
"type": "tarball",
|
||||
"url": "https://releases.nixos.org/nixpkgs/nixpkgs-25.11pre862603.08b8f92ac635/nixexprs.tar.xz"
|
||||
},
|
||||
"original": {
|
||||
"type": "tarball",
|
||||
"url": "https://nixos.org/channels/nixpkgs-unstable/nixexprs.tar.xz"
|
||||
}
|
||||
},
|
||||
"nixpkgs_2": {
|
||||
"locked": {
|
||||
"lastModified": 1758346548,
|
||||
"narHash": "sha256-afXE7AJ7MY6wY1pg/Y6UPHNYPy5GtUKeBkrZZ/gC71E=",
|
||||
"owner": "nixos",
|
||||
"repo": "nixpkgs",
|
||||
"rev": "b2a3852bd078e68dd2b3dfa8c00c67af1f0a7d20",
|
||||
"type": "github"
|
||||
},
|
||||
"original": {
|
||||
"owner": "nixos",
|
||||
"ref": "nixos-25.05",
|
||||
"repo": "nixpkgs",
|
||||
"type": "github"
|
||||
}
|
||||
},
|
||||
"home-manager": {
|
||||
"inputs": {
|
||||
"nixpkgs": "nixpkgs_2"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
You can grep through your lock file to locate which inputs are referencing the wrong nixpkgs.
|
||||
|
||||
In this example, `home-manager` is pointing to `nixpkgs_2` instead of the main `nixpkgs`
|
||||
|
||||
```json
|
||||
// ...
|
||||
"home-manager": {
|
||||
"inputs": {
|
||||
"nixpkgs": "nixpkgs_2"
|
||||
}
|
||||
// ...
|
||||
```
|
||||
|
||||
To fix this add the following line to your flake.nix inputs:
|
||||
Fix this by adding the following line to your `flake.nix` inputs:
|
||||
|
||||
```nix
|
||||
home-manager.inputs.nixpkgs.follows = "nixpkgs";
|
||||
```
|
||||
|
||||
Repeat this process until all duplicate `nixpkgs` entries are eliminated.
|
||||
|
||||
This helps prevent cross-version conflicts and ensures all inputs use the same `nixpkgs` source.
|
||||
Repeat this process until all duplicate `nixpkgs` entries are resolved. This ensures all inputs use the same `nixpkgs` source, preventing cross-version conflicts.
|
||||
|
||||
@@ -74,7 +74,7 @@ hide:
|
||||
<input type="checkbox" id="clan-readmore" class="clamp-toggle" />
|
||||
<div class="clamp-content">
|
||||
<p><a href="https://clan.lol/">Clan</a> is a peer-to-peer computer management framework that empowers you to selfhost in a reliable and scalable way</strong>.</p>
|
||||
<p>Built on NixOS, Clan provides a declarative interface for managing machines</strong> with automated <a href="./guides/secrets.md">secret management</a>, easy <a href="./guides/mesh-vpn.md">mesh VPN connectivity</a>, and <a href="./guides/backups.md">automated backups</a>.</p>
|
||||
<p>Built on NixOS, Clan provides a declarative interface for managing machines</strong> with automated <a href="./guides/secrets.md">secret management</a>, easy <a href="./guides/mesh-vpn.md">mesh VPN connectivity</a>, and <a href="./guides/backups/backup-intro.md">automated backups</a>.</p>
|
||||
<p>Whether you're running a homelab or maintaining critical computing infrastructure, Clan will help reduce maintenance burden</strong> by allowing a git repository to define your whole network</strong> of computers.</p>
|
||||
<p>In combination with <a href="https://github.com/Mic92/sops-nix">sops-nix</a>, <a href="https://github.com/nix-community/nixos-anywhere">nixos-anywhere</a> and <a href="https://github.com/nix-community/disko">disko</a>, Clan makes it possible to have collaborative infrastructure</strong>.</p>
|
||||
<p>At the heart of Clan are <a href="./reference/clanServices/index.md">Clan Services</a> - the core concept that enables you to add functionality across multiple machines in your network. While Clan ships with essential core services, you can <a href="./guides/inventory/clanServices.md">create custom services</a> tailored to your specific needs.</p>
|
||||
|
||||
@@ -160,7 +160,7 @@ Examples:
|
||||
The backup to restore for the machine [MACHINE] with the configured [PROVIDER]
|
||||
with the name [NAME].
|
||||
|
||||
For more detailed information visit: {help_hyperlink("backups", "https://docs.clan.lol/guides/backups")}.
|
||||
For more detailed information visit: {help_hyperlink("backups", "https://docs.clan.lol/guides/backups/backup-intro")}.
|
||||
"""
|
||||
),
|
||||
formatter_class=argparse.RawTextHelpFormatter,
|
||||
@@ -510,7 +510,7 @@ Examples:
|
||||
$ clan state list [MACHINE]
|
||||
List state of the machines managed by Clan.
|
||||
|
||||
For more detailed information, visit: {help_hyperlink("getting-started", "https://docs.clan.lol/guides/backups")}
|
||||
For more detailed information, visit: {help_hyperlink("getting-started", "https://docs.clan.lol/guides/backups/backup-intro")}
|
||||
"""
|
||||
),
|
||||
formatter_class=argparse.RawTextHelpFormatter,
|
||||
|
||||
Reference in New Issue
Block a user