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

Merge pull request 'Docs/drafts: remove unused drafts, {HardwareInstallation,SecretCLI}' (#2691) from hsjobeki/clan-core:hsjobeki-main into main

Browse Source
This commit is contained in:
clan-bot
2025-01-07 08:18:26 +00:00
parent b9a00f3adc 60d7941475
commit 4cd28f257a
2 changed files with 0 additions and 470 deletions
Download Patch File Download Diff File Expand all files Collapse all files

146
docs/site/drafts/install-iso.md
View File

@@ -1,146 +0,0 @@
# Hardware Installation
For installations on physical hardware, create a NixOS installer image and transfer it to a bootable USB drive as described below.
## Creating a Bootable USB Drive on Linux
To create a bootable USB flash drive with the NixOS installer:
### Download the install iso
Either with wget:
```shellSession
wget https://github.com/nix-community/nixos-images/releases/download/nixos-unstable/nixos-installer-x86_64-linux.iso
```
or with curl:
```shellSession
curl -L https://github.com/nix-community/nixos-images/releases/download/nixos-unstable/nixos-installer-x86_64-linux.iso -o nixos-installer-x86_64-linux.iso
```
### Prepare the USB Flash Drive
1. Insert your USB flash drive into your computer.
2. Identify your flash drive with `lsblk`.
```shellSession
lsblk
NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINTS
sdb 8:0 1 117,2G 0 disk
└─sdb1 8:1 1 117,2G 0 part /run/media/qubasa/INTENSO
nvme0n1 259:0 0 1,8T 0 disk
├─nvme0n1p1 259:1 0 512M 0 part /boot
└─nvme0n1p2 259:2 0 1,8T 0 part
└─luks-f7600028-9d83-4967-84bc-dd2f498bc486 254:0 0 1,8T 0 crypt /nix/store
```
In this case it's `sdb`
3. Ensure all partitions on the drive are unmounted. Replace `sdX` in the command below with your device identifier (like `sdb`, etc.):
```shellSession
sudo umount /dev/sdb1
```
### Write the Image to the USB Drive
Use the `dd` utility to write the NixOS installer image to your USB drive:
```shellSession
sudo dd bs=4M conv=fsync oflag=direct status=progress if=./nixos-installer-x86_64-linux.iso of=/dev/sd<X>
```
In this case, the USB device is `sdb` use `of=/dev/sdb`
### Boot and Connect
After writing the installer to the USB drive, use it to boot the target machine.
1. For this secure boot needs to be disabled. Go into your UEFI / Bios settings by pressing one of the keys outlined below while booting:
- **Dell**: F2/Del (BIOS Setup)
- **HP**: Esc (Startup Menu)
- **Lenovo**: F2/Fn+F2/Novo Button (IdeaPad Boot Menu/BIOS Setup)
- **Acer**: F2/Del (BIOS Setup)
- **Asus**: F2/Del (BIOS Setup)
- **Toshiba**: Esc then F12 (Alternate Method)
- **Sony**: F11
- **Samsung**: F2 (BIOS Setup)
- **MSI**: Del (BIOS Setup)
- **Apple**: Option (Alt) Key (Boot Menu for Mac)
- If your hardware was not listed read the manufacturers instructions how to enter the boot Menu/BIOS Setup.
2. Inside the UEFI/Bios Menu go to `Security->Secure Boot` and disable secure boot
3. Save your settings. Put in the USB stick and reboot.
4. Press one of keys outlined below to go into the Boot Menu
- **Dell**: F12 (Boot Menu)
- **HP**: F9 (Boot Menu)
- **Lenovo**: F12 (ThinkPad Boot Menu)
- **Acer**: F12 (Boot Menu)
- **Asus**: F8/Esc (Boot Menu)
- **Toshiba**: F12/F2 (Boot Menu)
- **Sony**: F11
- **Samsung**: F2/F12/Esc (Boot Menu)
- **MSI**: F11
- **Apple**: Option (Alt) Key (Boot Menu for Mac)
- If your hardware was not listed read the manufacturers instructions how to enter the boot Menu/BIOS Setup.
5. Select `NixOS` to boot into the clan installer
6. The installer will display an IP address and a root password, which you can use to connect via SSH.
Alternatively you can also use the displayed QR code.
7. Set your keyboard language (i.e. `de` for German keyboards, default is English). Important for writing passwords correctly.
```shellSession
loadkeys de
```
8. If you only have Wifi available, execute:
1. Bring up the `iwd` shell
```shellSession
iwctl
```
2. List available networks. Double press tab after station for autocompleting your wlan device. In this case `wlan0`
```shellSession
[iwd] station wlan0 get-networks
```
3. Connect to a Wifi network. Replace `SSID` with the wlan network name.
```shellSession
[iwd] station wlan0 connect SSID
```
9. Now that you have internet re-execute the init script by pressing `Ctrl+D` or by executing:
```shellSession
bash
```
10. Connect to the machine over ssh
```shellSession
ssh-copy-id -o PreferredAuthentications=password root@<ip>
```
Use the root password displayed on your screen as login.
---
# What's next?
- Deploy a clan machine-configuration on your prepared machine
---

324
docs/site/drafts/secret-cli.md
View File

@@ -1,324 +0,0 @@
## Secrets (CLI Reference)
#### Adding Secrets (set)
```bash
clan secrets set mysecret
> Paste your secret:
```
!!! note
As you type your secret won't be displayed. Press Enter to save the secret.
#### List all Secrets (list)
```bash
clan secrets list
```
#### Assigning Access (set)
By default, secrets are encrypted for your key. To specify which users and machines can access a secret:
```bash
clan secrets set --machine <machine1> --machine <machine2> --user <user1> --user <user2> <secret_name>
```
#### Displaying Secrets (get)
```bash
clan secrets get mysecret
```
#### Rename
TODO
#### Remove
TODO
#### import-sops
TODO
### Users (Reference)
Learn how to manage users and allowing access to existing secrets.
#### list user
Lists all added users
```bash
clan secrets user list
```
``` {.console, title="Example output", .no-copy}
jon
sara
```
!!! Question "Who can execute this command?"
Everyone - completely public.
#### add user
add a user
```bash
clan secrets users add {username} {public-key}
```
!!! Note
Changes can be trusted by maintainer review in version control.
#### get user
get a user public key
```bash
clan secrets users get {username}
```
``` {.console, title="Example output", .no-copy}
age1zk8uzrte55wkg9lkqxu5x6twsj2ja4lehegks0cw4mkg6jv37d9qsjpt44
```
#### remove user
remove a user
```bash
clan secrets users remove {username}
```
!!! Note
Changes can be trusted by maintainer review in version control.
#### add-secret user
Grants the user (`username`) access to the secret (`secret_name`)
```bash
clan secrets users add-secret {username} {secret_name}
```
!!! Note
Requires the executor of the command to have access to the secret (`secret_name`).
#### remove-secret user
remove the user (`username`) from accessing the secret (`secret_name`)
!!! Danger "Make sure at least one person has access."
It might still be possible for the machine to access the secret. (See [machines](#machines))
We highly recommend to use version control such as `git` which allows you to rollback secrets in case anything gets messed up.
```bash
clan secrets users remove-secret {username} {secret_name}
```
!!! Question "Who can execute this command?"
Requires the executor of the command to have access to the secret (`secret_name`).
### Machines (Reference)
- [list](): list machines
- [add](): add a machine
- [get](): get a machine public key
- [remove](): remove a machine
- [add-secret](): allow a machine to access a secret
- [remove-secret](): remove a machine's access to a secret
#### List machine
New machines in Clan come with age keys stored in `./sops/machines/<machine_name>`. To list these machines:
```bash
clan secrets machines list
```
#### Add machine
For clan machines the machine key is generated automatically on demand if none exists.
```bash
clan secrets machines add <machine_name> <age_key>
```
If you already have a device key and want to add it manually, see: [How to obtain a remote key](#obtain-remote-keys-manually)
#### get machine
TODO
#### remove machine
TODO
#### add-secret machine
TODO
#### remove-secret machine
TODO
### Groups (Reference)
The Clan-CLI makes it easy to manage access by allowing you to create groups.
- [list](): list groups
- [add-user](): add a user to group
- [remove-user](): remove a user from group
- [add-machine](): add a machine to group
- [remove-machine](): remove a machine from group
- [add-secret](): allow a user to access a secret
- [remove-secret](): remove a group's access to a secret
#### List Groups
```bash
clan secrets groups list
```
#### add-user
Assign users to a new group, e.g., `admins`:
```bash
clan secrets groups add-user admins <username>
```
!!! info
The group is created if no such group existed before.
The user must exist in beforehand (See: [users](#users-reference))
```{.console, .no-copy}
.
├── flake.nix
. ...
└── sops
├── groups
│ └── admins
│ └── users
│ └── <username> -> ../../../users/<username>
```
#### remove-user
TODO
#### add-machine
TODO
#### remove-machine
TODO
#### add-secret
```bash
clan secrets groups add-secret <group_name> <secret_name>
```
#### remove-secret
TODO
### Key (Reference)
- [generate]() generate age key
- [show]() show age public key
- [update]() re-encrypt all secrets with current keys (useful when changing keys)
#### generate
TODO
#### show
TODO
#### update
TODO
## Further
Secrets in the repository follow this structure:
```{.console, .no-copy}
sops/
├── secrets/
│ └── <secret_name>/
│ ├── secret
│ └── users/
│ └── <your_username>/
```
The content of the secret is stored encrypted inside the `secret` file under `mysecret`.
By default, secrets are encrypted with your key to ensure readability.
### Obtain remote keys manually
To fetch a **SSH host key** from a preinstalled system:
```bash
ssh-keyscan <domain_name> | nix shell nixpkgs#ssh-to-age -c ssh-to-age
```
!!! Success
This command converts the SSH key into an age key on the fly. Since this is the format used by the clan secrets backend.
Once added the **SSH host key** enables seamless integration of existing machines with clan.
Then add the key by executing:
```bash
clan secrets machines add <machine_name> <age_key>
```
See also: [Machine reference](#machines-reference)
### NixOS integration
A NixOS machine will automatically import all secrets that are encrypted for the
current machine. At runtime it will use the host key to decrypt all secrets into
an in-memory, non-persistent filesystem using [sops-nix](https://github.com/Mic92/sops-nix).
In your nixos configuration you can get a path to secrets like this `config.sops.secrets.<name>.path`. For example:
```nix
{ config, ...}: {
sops.secrets.my-password.neededForUsers = true;
users.users.mic92 = {
isNormalUser = true;
passwordFile = config.sops.secrets.my-password.path;
};
}
```
See the [readme](https://github.com/Mic92/sops-nix) of sops-nix for more
examples.
### Migration: Importing existing sops-based keys / sops-nix
`clan secrets` stores each secret in a single file, whereas [sops](https://github.com/Mic92/sops-nix) commonly allows to put all secrets in a yaml or json document.
If you already happened to use sops-nix, you can migrate by using the `clan secrets import-sops` command by importing these files:
```bash
% clan secrets import-sops --prefix matchbox- --group admins --machine matchbox nixos/matchbox/secrets/secrets.yaml
```
This will create secrets for each secret found in `nixos/matchbox/secrets/secrets.yaml` in a `./sops` folder of your repository.
Each member of the group `admins` in this case will be able to decrypt the secrets with their respective key.
Since our clan secret module will auto-import secrets that are encrypted for a particular nixos machine,
you can now remove `sops.secrets.<secrets> = { };` unless you need to specify more options for the secret like owner/group of the secret file.