From 60d794147557e5910e857d900e865125bdfb25c7 Mon Sep 17 00:00:00 2001 From: Johannes Kirschbauer Date: Tue, 7 Jan 2025 09:14:03 +0100 Subject: [PATCH] Docs/drafts: remove unused drafts, {HardwareInstallation,SecretCLI} --- docs/site/drafts/install-iso.md | 146 -------------- docs/site/drafts/secret-cli.md | 324 -------------------------------- 2 files changed, 470 deletions(-) delete mode 100644 docs/site/drafts/install-iso.md delete mode 100644 docs/site/drafts/secret-cli.md diff --git a/docs/site/drafts/install-iso.md b/docs/site/drafts/install-iso.md deleted file mode 100644 index 188b21292..000000000 --- a/docs/site/drafts/install-iso.md +++ /dev/null @@ -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 - ``` - - 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@ - ``` - - Use the root password displayed on your screen as login. - ---- - -# What's next? - -- Deploy a clan machine-configuration on your prepared machine - ---- diff --git a/docs/site/drafts/secret-cli.md b/docs/site/drafts/secret-cli.md deleted file mode 100644 index 1fbc473c7..000000000 --- a/docs/site/drafts/secret-cli.md +++ /dev/null @@ -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 --machine --user --user -``` - -#### 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/`. 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 -``` - -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 -``` - -!!! 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 - │ └── -> ../../../users/ - ``` - -#### remove-user - -TODO - -#### add-machine - -TODO - -#### remove-machine - -TODO - -#### add-secret - -```bash -clan secrets groups add-secret -``` - -#### 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 -│ └── users/ -│ └── / -``` - -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 | 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 -``` - -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..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. = { };` unless you need to specify more options for the secret like owner/group of the secret file.