Skip to content

Latest commit

 

History

History
114 lines (92 loc) · 4.47 KB

quickstart.org

File metadata and controls

114 lines (92 loc) · 4.47 KB

Obtain the tools

We need age for key generation, sillysecrets for secret management and optionally the Aquaris Deployer for remote installation.

nix shell nixpkgs#age github:42LoCo42/sillysecrets github:42LoCo42/aquaris#deploy

Create a configuration

This repo provides an example configuration. Get it via

nix flake new -t github:42loco42/aquaris config
cd config
nix flake update

Create a machine

Create the file machines/<machineName>/default.nix; adapt it from the example.

Generate the required ID and key:

dbus-uuidgen # machine ID -> put in your machine file
age-keygen -o "keys/<machineName>.key" # prints public key -> copy for later

Adapt the filesystem configuration and other stuff to your requirements. We will generate a hardware configuration later.

Set up the secrets storage

Secrets are stored in the sesi.yaml file at the toplevel of your config.

I recommend creating separate admin, machine and user groups, where admins contain the machines for which they should be able to define secrets and machines contain their user accounts (whose groups therefore don’t need a key).

Don’t forget to remove the example secrets from the file!

Create a user

The global config is a good place to put user accounts shared over multiple machines (and was originally only designed for this). For one-off accounts, you can skip it and just define them directly in the machine config file.

In any case, make sure you have at least one admin on your machine. I like to set the admin option locally, but if you want, you can put in in your global user config too.

Finally, set the user’s password:

mkpasswd -S "$(mkpasswd)" # twice for verification
# copy the resulting hash...
sesi edit user:<userName>.password # and paste it

Installation

Standard

Boot a recent NixOS live ISO on your target machine, preferably one with flakes enabled by default (like this one).

Obtain the hardware configuration:

nixos-generate-config --show-hardware-config --no-filesystems

Write it to your config at machines/<machineName>/hardware.nix. Don’t forget to git add that file when using Git (as you should)!

Copy/clone your configuration onto the live system; make sure to also copy keys/<machineName>.key somewhere!

Run the installer:

nix run .#machineName -f -m -i # format, mount, install

You can pass the option -k <path> to specify where the machine key is. By default, keys/<machineName>.key is used relative to where the installer runs.

Remote deployment

If you want to deploy your configuration from a different machine, either just for convenience or because you can’t physically access your target, try out this method instead!

Inspired by nixos-anywhere, it supports replacing whatever old system is running on your target with a NixOS kexec image, which is like a stripped-down live ISO that lives in the RAM! This of course requires kexec support, but not much else other than basic Linux shell utilities (tested on Alpine, so even Busybox works!)

Use it like this:

deploy --show-hwconf --key "keys/<machineName>.key" user@host .#machineName

The specified user requires root access for this process! Both sudo and doas are supported. If you need to pass custom SSH options, you can do so via ~/.ssh/config. Please don’t forcefully request a TTY; the deployer chooses when to do this.

If the current target is not already a NixOS live system, a kexec image is downloaded & executed. The URL for this can be set via --kexec-url <url>. Running the kexec step can be forced via --force-kexec.

After booting into the kexec environment, --show-hwconf prints the hardware configuration and pauses the deployment, allowing you to add it to your local configuration.

You can skip certain steps of the installation process using. --dont-format, --dont-mount and --dont-reboot.

Everything is built on the target in order to support other CPU architectures. A local build mode might be added in the future.