From 036cd710e1e037f5669363fd7e26fb6c121a5504 Mon Sep 17 00:00:00 2001 From: Qubasa Date: Fri, 20 Sep 2024 16:52:52 +0200 Subject: [PATCH] docs: Rename guides to manual, Rename reference to options, add secure boot chapter to manual. Add secrets chapter to manual. --- clanModules/borgbackup-static/README.md | 2 +- docs/mkdocs.yml | 18 +- docs/nix/render_options/__init__.py | 6 +- docs/site/getting-started/installer.md | 46 ++- docs/site/getting-started/secrets.md | 262 +----------------- docs/site/guides/index.md | 7 - .../contributing.md => manual/contribute.md} | 0 .../include-machines.md} | 4 +- docs/site/manual/index.md | 11 + docs/site/{guides => manual}/inventory.md | 2 +- docs/site/manual/secrets.md | 251 +++++++++++++++++ docs/site/manual/secure-boot.md | 49 ++++ docs/site/reference/index.md | 12 +- 13 files changed, 351 insertions(+), 319 deletions(-) delete mode 100644 docs/site/guides/index.md rename docs/site/{contributing/contributing.md => manual/contribute.md} (100%) rename docs/site/{guides/add-machines.md => manual/include-machines.md} (93%) create mode 100644 docs/site/manual/index.md rename docs/site/{guides => manual}/inventory.md (98%) create mode 100644 docs/site/manual/secrets.md create mode 100644 docs/site/manual/secure-boot.md diff --git a/clanModules/borgbackup-static/README.md b/clanModules/borgbackup-static/README.md index a0dda99da..1bdf32a69 100644 --- a/clanModules/borgbackup-static/README.md +++ b/clanModules/borgbackup-static/README.md @@ -4,7 +4,7 @@ description = "Statically configure borgbackup with sane defaults." !!! Danger "Deprecated" Use [borgbackup](borgbackup.md) instead. - Don't use borgbackup-static through [inventory](../../guides/inventory.md). + Don't use borgbackup-static through [inventory](../../manual/inventory.md). This module implements the `borgbackup` backend and implements sane defaults for backup management through `borgbackup` for members of the clan. diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index b83d45a8f..936a20331 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -39,7 +39,7 @@ exclude_docs: | /drafts/ nav: - - Getting started: + - Get Started: - index.md - Installer: getting-started/installer.md - Configure: getting-started/configure.md @@ -49,12 +49,15 @@ nav: - Mesh VPN: getting-started/mesh-vpn.md - Backup & Restore: getting-started/backups.md - Flake-parts: getting-started/flake-parts.md - - Guides: - - guides/index.md - - Adding Machines: guides/add-machines.md - - Inventory: guides/inventory.md - - Reference: - - reference/index.md + - Manual: + - Overview: manual/index.md + - Include Machines: manual/include-machines.md + - Inventory: manual/inventory.md + - Secrets: manual/secrets.md + - Secure Boot: manual/secure-boot.md + - Contribute: manual/contribute.md + - Options: + - Overview: reference/index.md - Clan Modules: - reference/clanModules/index.md - reference/clanModules/admin.md @@ -117,7 +120,6 @@ nav: - reference/nix-api/index.md - buildClan: reference/nix-api/buildclan.md - Inventory: reference/nix-api/inventory.md - - Contributing: contributing/contributing.md - Blog: - blog/index.md diff --git a/docs/nix/render_options/__init__.py b/docs/nix/render_options/__init__.py index 272990d0d..bd1325e08 100644 --- a/docs/nix/render_options/__init__.py +++ b/docs/nix/render_options/__init__.py @@ -205,15 +205,15 @@ Predefined roles {roles_list} -For more information, see the [inventory guide](../../guides/inventory.md). +For more information, see the [inventory guide](../../manual/inventory.md). """ return "" clan_modules_descr = """Clan modules are [NixOS modules](https://wiki.nixos.org/wiki/NixOS_modules) which have been enhanced with additional features provided by Clan, with certain option types restricted to enable configuration through a graphical interface. -!!! note "🔹 = [inventory](../../guides/inventory.md) supported - Modules with this indicator support the [inventory](../../guides/inventory.md) feature. +!!! note "🔹 = [inventory](../../manual/inventory.md) supported + Modules with this indicator support the [inventory](../../manual/inventory.md) feature. """ diff --git a/docs/site/getting-started/installer.md b/docs/site/getting-started/installer.md index 5e21aa2c3..30839a055 100644 --- a/docs/site/getting-started/installer.md +++ b/docs/site/getting-started/installer.md @@ -53,27 +53,34 @@ sudo umount /dev/sdb1 --disk main /dev/sd \ flash-installer ``` - - Replace `$HOME/.ssh/id_ed25519.pub` with a path to your SSH public key. - If you do not have an ssh key yet, you can generate one with `ssh-keygen -t ed25519` command. + !!! Note + Replace `$HOME/.ssh/id_ed25519.pub` with a path to your SSH public key. + Replace `/dev/sd` with the drive path you want to flash !!! Danger "Specifying the wrong device can lead to unrecoverable data loss." The `clan flash` utility will erase the disk. Make sure to specify the correct device - !!! Note + - **SSH-Pubkey Option**: + To add an ssh public key into the installer image append the option: + ``` + --ssh-pubkey + ``` + If you do not have an ssh key yet, you can generate one with `ssh-keygen -t ed25519` command. + + - **Wifi Option**: To add wifi credentials into the installer image append the option: ``` - --wifi + --wifi ``` - !!! Note + - **List Keymaps**: You can get a list of all keymaps with the following command: ``` clan flash list keymaps ``` - !!! Note + - **List Languages**: You can get a list of all languages with the following command: ``` clan flash list languages @@ -89,7 +96,7 @@ sudo umount /dev/sdb1 wget https://github.com/nix-community/nixos-images/releases/download/nixos-unstable/nixos-installer-x86_64-linux.iso ``` - ### Step 3. Flash the Installer to the USB Drive + ### Step 2.5 Flash the Installer to the USB Drive !!! Danger "Specifying the wrong device can lead to unrecoverable data loss." @@ -105,28 +112,9 @@ sudo umount /dev/sdb1 sudo dd bs=4M conv=fsync oflag=direct status=progress if=./nixos-installer-x86_64-linux.iso of=/dev/sd ``` -### Step 4. Boot and Connect to your network -After writing the installer to the USB drive, use it to boot the target machine. -To do this plug the USB drive into the target machine and select the USB drive as a temporary boot device. - -??? tip "Here you can find the key combinations for selection used by most vendors." - - **Dell**: F12 (Boot Menu), F2/Del (BIOS Setup) - - **HP**: F9 (Boot Menu), Esc (Startup Menu) - - **Lenovo**: F12 (ThinkPad Boot Menu), F2/Fn+F2/Novo Button (IdeaPad Boot Menu/BIOS Setup) - - **Acer**: F12 (Boot Menu), F2/Del (BIOS Setup) - - **Asus**: F8/Esc (Boot Menu), F2/Del (BIOS Setup) - - **Toshiba**: F12/F2 (Boot Menu), Esc then F12 (Alternate Method) - - **Sony**: F11/Assist Button (Boot Menu/Recovery Options) - - **Samsung**: F2/F12/Esc (Boot Menu), F2 (BIOS Setup) - - **MSI**: F11 (Boot Menu), 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. - - -**After Booting** - -Now you can deploy your clan configuration onto the machine +### Step 3: Boot From USB Stick +- To use, boot from the Clan USB drive with **secure boot turned off**. For step by step instructions go to [Disabling Secure Boot](../manual/secure-boot.md) ## (Optional) Connect to Wifi Manually diff --git a/docs/site/getting-started/secrets.md b/docs/site/getting-started/secrets.md index 5f3be52c9..65cfec8e3 100644 --- a/docs/site/getting-started/secrets.md +++ b/docs/site/getting-started/secrets.md @@ -60,265 +60,5 @@ If you followed the quickstart tutorial all necessary secrets are initialized at ## Whats next? - [Deployment](deploy.md): How to remotely deploy your machine +- [Advanced Secrets](../manual/secrets.md) If you want to know more about how to save and share passwords in your clan ---- - -## More on Secrets - -If you want to know more about how to save and share passwords in your clan read further! - -### Adding a Secret - -```shellSession -clan secrets set mysecret -Paste your secret: -``` - -### Retrieving a Stored Secret - -```bash -clan secrets get mysecret -``` - -### List all Secrets - -```bash -clan secrets list -``` - -### 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; - }; -} -``` - -### Assigning Access - -When using `clan secrets set ` without arguments, secrets are encrypted for the key of the user named like your current $USER. - -To add machines/users to an existing secret use: - -```bash - clan secrets machines add-secret -``` - -Alternatively specify users and machines while creating a secret: - -```bash -clan secrets set --machine --machine --user --user -``` - -## Advanced - -In this section we go into more advanced secret management topics. - -### Groups - -Clan CLI makes it easy to manage access by allowing you to create groups. - -All users within a group inherit access to all secrets of the group. - -This feature eases the process of handling permissions for multiple users. - -Here's how to get started: - -1. **Creating Groups**: - - Assign users to a new group, e.g., `admins`: - - ```bash - clan secrets groups add admins - ``` - -2. **Listing Groups**: - - ```bash - clan secrets groups list - ``` - -3. **Assigning Secrets to Groups**: - - ```bash - clan secrets groups add-secret - ``` - -### Adding Machine Keys - -New machines in Clan come with age keys stored in `./sops/machines/`. To list these machines: - -```bash - clan secrets machines list -``` - -For existing machines, add their keys: - -```bash - clan secrets machines add -``` - -To fetch an age key from an SSH host key: - -```bash - ssh-keyscan | nix shell nixpkgs#ssh-to-age -c ssh-to-age -``` - -### 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. - - -## Indepth Explanation - - -The secrets system conceptually knows two different entities: - -- **Machine**: consumes secrets -- **User**: manages access to secrets - -**A Users** Can add or revoke machines' access to secrets. - -**A machine** Can decrypt secrets that where encrypted specifically for that machine. - -!!! Danger - **Always make sure at least one _User_ has access to a secret**. Otherwise you could lock yourself out from accessing the secret. - -### Inherited implications - -By default clan uses [sops](https://github.com/getsops/sops) through [sops-nix](https://github.com/Mic92/sops-nix) for managing its secrets which inherits some implications that are important to understand: - -- **Public/Private keys**: Entities are identified via their public keys. Each Entity can use their respective private key to decrypt a secret. -- **Public keys are stored**: All Public keys are stored inside the repository -- **Secrets are stored Encrypted**: secrets are stored inside the repository encrypted with the respective public keys -- **Secrets are deployed encrypted**: Fully encrypted secrets are deployed to machines at deployment time. -- **Secrets are decrypted by sops on-demand**: Each machine decrypts its secrets at runtime and stores them at an ephemeral location. -- **Machine key-pairs are auto-generated**: When a machine is created **no user-interaction is required** to setup public/private key-pairs. -- **secrets are re-encrypted**: In case machines, users or groups are modified secrets get re-encrypted on demand. - - !!! Important - After revoking access to a secret you should also change the underlying secret. i.e. change the API key, or the password. - ---- - -### Machine and user keys - -The following diagrams illustrates how a user can provide a secret (i.e. a Password). - -- By using the **Clan CLI** a user encrypts the password with both the **User public-key** and the **machine's public-key** - -- The *Machine* can decrypt the password with its private-key on demand. - -- The *User* is able to decrypt the password to make changes to it. - -```plantuml -@startuml -!include C4_Container.puml - -Person(user, "User", "Someone who manages secrets") -ContainerDb(secret, "Secret") -Container(machine, "Machine", "A Machine. i.e. Needs the Secret for a given Service." ) - -Rel_R(user, secret, "Encrypt", "", "Pubkeys: User, Machine") -Rel_L(secret, user, "Decrypt", "", "user privkey") -Rel_R(secret, machine, "Decrypt", "", "machine privkey" ) - -@enduml -``` - - -#### User groups - -Here we illustrate how machine groups work. - -Common use cases: - -- **Shared Management**: Access among multiple users. I.e. a subset of secrets/machines that have two admins - -```plantuml -@startuml -!include C4_Container.puml - -System_Boundary(c1, "Group") { - Person(user1, "User A", "has access") - Person(user2, "User B", "has access") -} - -ContainerDb(secret, "Secret") -Container(machine, "Machine", "A Machine. i.e. Needs the Secret for a given Service." ) - -Rel_R(c1, secret, "Encrypt", "", "Pubkeys: User A, User B, Machine") -Rel_R(secret, machine, "Decrypt", "", "machine privkey" ) - - -@enduml -``` - - - ---- - -#### Machine groups - -Here we illustrate how machine groups work. - -Common use cases: - -- **Shared secrets**: Among multiple machines such as Wifi passwords - -```plantuml -@startuml -!include C4_Container.puml -!include C4_Deployment.puml - -Person(user, "User", "Someone who manages secrets") -ContainerDb(secret, "Secret") -System_Boundary(c1, "Group") { - Container(machine1, "Machine A", "Both machines need the same secret" ) - Container(machine2, "Machine B", "Both machines need the same secret" ) -} - -Rel_R(user, secret, "Encrypt", "", "Pubkeys: machine A, machine B, User") -Rel(secret, c1, "Decrypt", "", "Both machine A or B can decrypt using their private key" ) - - -@enduml -``` - - - - - -See the [readme](https://github.com/Mic92/sops-nix) of sops-nix for more -examples. - - ---- - -## Whats next? - -- [Deployment](deploy.md): How to remotely deploy your machine - ---- diff --git a/docs/site/guides/index.md b/docs/site/guides/index.md deleted file mode 100644 index 2623b7fdf..000000000 --- a/docs/site/guides/index.md +++ /dev/null @@ -1,7 +0,0 @@ -# Guides - -Detailed guides into the following subtopics: - -- [Getting Started](../index.md): Getting started with clan. -- [Adding Machines](./add-machines.md): How to add machines. -- [Inventory](./inventory.md): Configuring Services across machine boundaries diff --git a/docs/site/contributing/contributing.md b/docs/site/manual/contribute.md similarity index 100% rename from docs/site/contributing/contributing.md rename to docs/site/manual/contribute.md diff --git a/docs/site/guides/add-machines.md b/docs/site/manual/include-machines.md similarity index 93% rename from docs/site/guides/add-machines.md rename to docs/site/manual/include-machines.md index 1aa089ab2..79761c9bb 100644 --- a/docs/site/guides/add-machines.md +++ b/docs/site/manual/include-machines.md @@ -1,4 +1,4 @@ -# How to add machines +# Include Machines Clan has two general methods of adding machines @@ -17,7 +17,7 @@ Automatically imported: ## Manual declaration -Machines can also be added manually under `buildClan`, `clan.*` in flake-parts or via [`inventory`](../guides/inventory.md). +Machines can also be added manually under `buildClan`, `clan.*` in flake-parts or via [`inventory`](../manual/inventory.md). !!! Note It is possible to use `inventory` and `buildClan` together at the same time. diff --git a/docs/site/manual/index.md b/docs/site/manual/index.md new file mode 100644 index 000000000..089f490e4 --- /dev/null +++ b/docs/site/manual/index.md @@ -0,0 +1,11 @@ +# Manual + +Explore the Clan Framework in detail with comprehensive information on specific topics: + +- [Include Machines](./include-machines.md): Learn how Clan automatically includes machines and Nix files. + +- [Secrets](./secrets.md): Learn how you can manage secrets + +- [Inventory](./inventory.md): Access a distributed and editable version of the NixOS module system. + +- [Contribute](./contribute.md): Discover how to set up a development environment to contribute to Clan! \ No newline at end of file diff --git a/docs/site/guides/inventory.md b/docs/site/manual/inventory.md similarity index 98% rename from docs/site/guides/inventory.md rename to docs/site/manual/inventory.md index 3d4a2b219..83e6f510f 100644 --- a/docs/site/guides/inventory.md +++ b/docs/site/manual/inventory.md @@ -14,7 +14,7 @@ This guide will walk you through setting up a backup service, where the inventor ## Prerequisites -- [x] [Add machines](./add-machines.md) to your clan. +- [x] [Add machines](./include-machines.md) to your clan. ## Services diff --git a/docs/site/manual/secrets.md b/docs/site/manual/secrets.md new file mode 100644 index 000000000..1632e402b --- /dev/null +++ b/docs/site/manual/secrets.md @@ -0,0 +1,251 @@ +If you want to know more about how to save and share passwords in your clan read further! + +### Adding a Secret + +```shellSession +clan secrets set mysecret +Paste your secret: +``` + +### Retrieving a Stored Secret + +```bash +clan secrets get mysecret +``` + +### List all Secrets + +```bash +clan secrets list +``` + +### 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; + }; +} +``` + +### Assigning Access + +When using `clan secrets set ` without arguments, secrets are encrypted for the key of the user named like your current $USER. + +To add machines/users to an existing secret use: + +```bash + clan secrets machines add-secret +``` + +Alternatively specify users and machines while creating a secret: + +```bash +clan secrets set --machine --machine --user --user +``` + +## Advanced + +In this section we go into more advanced secret management topics. + +### Groups + +Clan CLI makes it easy to manage access by allowing you to create groups. + +All users within a group inherit access to all secrets of the group. + +This feature eases the process of handling permissions for multiple users. + +Here's how to get started: + +1. **Creating Groups**: + + Assign users to a new group, e.g., `admins`: + + ```bash + clan secrets groups add admins + ``` + +2. **Listing Groups**: + + ```bash + clan secrets groups list + ``` + +3. **Assigning Secrets to Groups**: + + ```bash + clan secrets groups add-secret + ``` + +### Adding Machine Keys + +New machines in Clan come with age keys stored in `./sops/machines/`. To list these machines: + +```bash + clan secrets machines list +``` + +For existing machines, add their keys: + +```bash + clan secrets machines add +``` + +To fetch an age key from an SSH host key: + +```bash + ssh-keyscan | nix shell nixpkgs#ssh-to-age -c ssh-to-age +``` + +### 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. + + +## Indepth Explanation + + +The secrets system conceptually knows two different entities: + +- **Machine**: consumes secrets +- **User**: manages access to secrets + +**A Users** Can add or revoke machines' access to secrets. + +**A machine** Can decrypt secrets that where encrypted specifically for that machine. + +!!! Danger + **Always make sure at least one _User_ has access to a secret**. Otherwise you could lock yourself out from accessing the secret. + +### Inherited implications + +By default clan uses [sops](https://github.com/getsops/sops) through [sops-nix](https://github.com/Mic92/sops-nix) for managing its secrets which inherits some implications that are important to understand: + +- **Public/Private keys**: Entities are identified via their public keys. Each Entity can use their respective private key to decrypt a secret. +- **Public keys are stored**: All Public keys are stored inside the repository +- **Secrets are stored Encrypted**: secrets are stored inside the repository encrypted with the respective public keys +- **Secrets are deployed encrypted**: Fully encrypted secrets are deployed to machines at deployment time. +- **Secrets are decrypted by sops on-demand**: Each machine decrypts its secrets at runtime and stores them at an ephemeral location. +- **Machine key-pairs are auto-generated**: When a machine is created **no user-interaction is required** to setup public/private key-pairs. +- **secrets are re-encrypted**: In case machines, users or groups are modified secrets get re-encrypted on demand. + + !!! Important + After revoking access to a secret you should also change the underlying secret. i.e. change the API key, or the password. + +--- + +### Machine and user keys + +The following diagrams illustrates how a user can provide a secret (i.e. a Password). + +- By using the **Clan CLI** a user encrypts the password with both the **User public-key** and the **machine's public-key** + +- The *Machine* can decrypt the password with its private-key on demand. + +- The *User* is able to decrypt the password to make changes to it. + +```plantuml +@startuml +!include C4_Container.puml + +Person(user, "User", "Someone who manages secrets") +ContainerDb(secret, "Secret") +Container(machine, "Machine", "A Machine. i.e. Needs the Secret for a given Service." ) + +Rel_R(user, secret, "Encrypt", "", "Pubkeys: User, Machine") +Rel_L(secret, user, "Decrypt", "", "user privkey") +Rel_R(secret, machine, "Decrypt", "", "machine privkey" ) + +@enduml +``` + + +#### User groups + +Here we illustrate how machine groups work. + +Common use cases: + +- **Shared Management**: Access among multiple users. I.e. a subset of secrets/machines that have two admins + +```plantuml +@startuml +!include C4_Container.puml + +System_Boundary(c1, "Group") { + Person(user1, "User A", "has access") + Person(user2, "User B", "has access") +} + +ContainerDb(secret, "Secret") +Container(machine, "Machine", "A Machine. i.e. Needs the Secret for a given Service." ) + +Rel_R(c1, secret, "Encrypt", "", "Pubkeys: User A, User B, Machine") +Rel_R(secret, machine, "Decrypt", "", "machine privkey" ) + + +@enduml +``` + + + +--- + +#### Machine groups + +Here we illustrate how machine groups work. + +Common use cases: + +- **Shared secrets**: Among multiple machines such as Wifi passwords + +```plantuml +@startuml +!include C4_Container.puml +!include C4_Deployment.puml + +Person(user, "User", "Someone who manages secrets") +ContainerDb(secret, "Secret") +System_Boundary(c1, "Group") { + Container(machine1, "Machine A", "Both machines need the same secret" ) + Container(machine2, "Machine B", "Both machines need the same secret" ) +} + +Rel_R(user, secret, "Encrypt", "", "Pubkeys: machine A, machine B, User") +Rel(secret, c1, "Decrypt", "", "Both machine A or B can decrypt using their private key" ) + + +@enduml +``` + + + + + +See the [readme](https://github.com/Mic92/sops-nix) of sops-nix for more +examples. + + + diff --git a/docs/site/manual/secure-boot.md b/docs/site/manual/secure-boot.md new file mode 100644 index 000000000..9514ec580 --- /dev/null +++ b/docs/site/manual/secure-boot.md @@ -0,0 +1,49 @@ +At the moment, NixOS/Clan does not support [Secure Boot](https://wiki.gentoo.org/wiki/Secure_Boot). Therefore, you need to disable it in the BIOS. You can watch this [video guide](https://www.youtube.com/watch?v=BKVShiMUePc) or follow the instructions below: + +### Step 1: Insert the USB Stick +- Begin by inserting the USB stick into a USB port on your computer. + +### Step 2: Access the UEFI/BIOS Menu +- Restart your computer. +- As your computer restarts, press the appropriate key to enter the UEFI/BIOS settings. +??? tip "The key depends on your laptop or motherboard manufacturer. Click to see a reference list:" + + | Manufacturer | UEFI/BIOS Key(s) | + |--------------------|---------------------------| + | ASUS | `Del`, `F2` | + | MSI | `Del`, `F2` | + | Gigabyte | `Del`, `F2` | + | ASRock | `Del`, `F2` | + | Lenovo | `F1`, `F2`, `Enter` (alternatively `Fn + F2`) | + | HP | `Esc`, `F10` | + | Dell | `F2`, `Fn + F2`, `Esc` | + | Acer | `F2`, `Del` | + | Samsung | `F2`, `F10` | + | Toshiba | `F2`, `Esc` | + | Sony | `F2`, `Assist` button | + | Fujitsu | `F2` | + | Microsoft Surface | `Volume Up` + `Power` | + | IBM/Lenovo ThinkPad| `Enter`, `F1`, `F12` | + | Biostar | `Del` | + | Zotac | `Del`, `F2` | + | EVGA | `Del` | + | Origin PC | `F2`, `Delete` | + + !!! Note + Pressing the key quickly and repeatedly is sometimes necessary to access the UEFI/BIOS menu, as the window to enter this mode is brief. + +### Step 3: Access Advanced Mode (Optional) +- If your UEFI/BIOS has a `Simple` or `Easy` mode interface, look for an option labeled `Advanced Mode` (often found in the lower right corner). +- Click on `Advanced Mode` to access more settings. This step is optional, as your boot settings might be available in the basic view. + +### Step 4: Disable Secure Boot +- Locate the `Secure Boot` option in your UEFI/BIOS settings. This is typically found under a `Security` tab, `Boot` tab, or a similarly named section. +- Set the `Secure Boot` option to `Disabled`. + +### Step 5: Change Boot Order +- Find the option to adjust the boot order—often labeled `Boot Order`, `Boot Sequence`, or `Boot Priority`. +- Ensure that your USB device is set as the first boot option. This allows your computer to boot from the USB stick. + +### Step 6: Save and Exit +- Save your changes before exiting the UEFI/BIOS menu. Look for a `Save & Exit` option or press the corresponding function key (often `F10`). +- Your computer should now restart and boot from the USB stick. diff --git a/docs/site/reference/index.md b/docs/site/reference/index.md index d9e1b00fd..191b394c4 100644 --- a/docs/site/reference/index.md +++ b/docs/site/reference/index.md @@ -1,8 +1,6 @@ -# Documentation +This section of the site provides an automatically generated overview of the available options and commands within the Clan Framework. -This section of the site contains information about the following topics: - -- How to use the [Clan CLI](./cli/index.md) -- Available services and application [modules](./clanModules/index.md) -- [Configuration options](./clan-core/index.md) controlling the essential features -- Descriptions of the [Nix interfaces](./nix-api/index.md) for defining a Clan +- Learn how to use the [Clan CLI](./cli/index.md) +- Explore available services and application [modules](./clanModules/index.md) +- Discover [configuration options](./clan-core/index.md) that manage essential features +- Find descriptions of the [Nix interfaces](./nix-api/index.md) for defining a Clan \ No newline at end of file