OS Install Notes

This page documents the process of installing and configuring a new Arch or Debian host. It is a summarised version of the official guides combined with the decisions made for our installs.

Some steps are labelled as Arch- or Debian-specific. Where not labelled, steps should be performed as-is on both systems.

Initial Install

Boot from USB and into the live environment.
[Debian] Switch to root.

sudo -i

Verify the machine is booted in UFEI mode on a 64-bit platform.

cat /sys/firmware/efi/fw_platform_size
# The result should be 64

Set the correct keyboard map.

# Arch:
loadkeys uk

# Debian:
dpkg-reconfigure keyboard-configuration
setupcon

Check the system time is correct.

timedatectl

[Arch] Use iwctl to connect to WiFi if necessary.

iwctl
# station wlxxx scan
# station wlxxx connect "Network Name"

[Debian] Use wpa_supplicant to connect to WiFi if necessary.

wpa_passphrase 'Network Name' 'Password' > /etc/wpa_supplicant.conf
wpa_supplicant -c /etc/wpa_supplicant.conf -i wlxxx -B
dhclient wlxxx

Check network connectivity.

ping archlinux.org

[Debian] Install utilities that will be needed during the install:

apt update
apt install --no-install-recommends gdisk cryptsetup dosfstools debootstrap arch-install-scripts

Disk Setup

The steps below will set up the system disk with the following structure:

Phsyical disk
├─ EFI boot partition (1GB, FAT32)
└─ LUKS encrypted container
   └─ LVM volume group
      ├─ Root OS volume (64GB, EXT4)
      ├─ Home volume (128GB, EXT4)
      └─ ... other volumes as required

Identify disks with lsblk. The rest of these notes assume the main disk is /dev/nvme0n1.
Use gdisk /dev/nvme0n1 to set up the disk as follows:
- o to create a GPT table.
- n to create a new partition - this will be the boot partition.
  - Partition number: 1
  - First sector: default
  - Last sector: +1G
  - Hex code: ef00 (EFI system partition)
- n to create a new partition - this will be the encrypted LVM partition.
  - Partition number: 2
  - First sector: default
  - Last sector: default
  - Hex code: 8300 (Linux filesystem)
- w to write changes and exit.
Verify that lsblk outputs something like this:

NAME        MAJ:MIN  RM  SIZE    RO TYPE MOUNTPOINT
nvme0n1     259:0    0   1000G   0  disk
├─nvme0n1p1 259:1    0      1G   0  part
└─nvme0n1p2 259:2    0    999G   0  part

Unless the disk was previously encrypted, overwrite the whole partition with random noise.

dd if=/dev/urandom of=/dev/nvme0n1p2 bs=1M status=progress

Encrypt the main partition with LUKS2 then open it.

cryptsetup luksFormat /dev/nvme0n1p2
cryptsetup open /dev/nvme0n1p2 cryptroot

Create a physical volume within LVM then assign it to a volume group.

pvcreate /dev/mapper/cryptroot
vgcreate vgroot /dev/mapper/cryptroot

Create the root and home partitions, plus any others that are required.

lvcreate -L 64G vgroot -n root
lvcreate -L 128G vgroot -n home

Create filesystems on each partition.

mkfs.ext4 /dev/mapper/vgroot-root
mkfs.ext4 /dev/mapper/vgroot-home

Create a FAT32 filesystem on the boot partition.

mkfs.fat -F 32 /dev/nvme0n1p1

System Install

Mount the boot partition and LVM volumes under /mnt.

# LVM volumes:
mount --mkdir /dev/mapper/vgroot-root /mnt
mount --mkdir /dev/mapper/vgroot-home /mnt/home

# EFI partition:
mount --mkdir /dev/nvme0n1p1 -o uid=0,gid=0,fmask=0077,dmask=0077 /mnt/efi

Bootstrap the OS. For Arch we can bootstrap install core packages in one step; for Debian we will bootstrap now and install core packages later.

# Arch:
pacstrap -K /mnt base linux linux-firmware linux-headers intel-ucode vim wget lvm2 cryptsetup openssh dracut binutils

# Debian:
debootstrap bookworm /mnt

Create an initial fstab file.

genfstab -U /mnt >> /mnt/etc/fstab

Change-root into the new system.

# Yes, this works on Arch and Debian
arch-chroot /mnt

[Debian] Install core packages.

apt update
apt install --no-install-recommends linux-image-amd64 zstd vim wget ca-certificates lvm2 cryptsetup openssh-server locales dracut binutils systemd-boot systemd-resolved tpm2-tools

Core OS Setup

Set the system timezone.

# Debian:
rm /etc/localtime

# All OSes, user devices:
ln -s /usr/share/zoneinfo/Europe/London /etc/localtime

# All OSes, servers:
ln -s /usr/share/zoneinfo/Etc/UTC /etc/localtime

Set and generate locale files.

echo "en_GB.UTF-8 UTF-8" > /etc/locale.gen
locale-gen

Persist the keyboard layout change.

echo "KEYMAP=uk" > /etc/vconsole.conf

Set a root password.

passwd

Boot Setup

These steps set up the system to build a universal kernel image (UKI) using Dracut then boot into it with systemd-boot. The generated UKI is configured to decrypt the encrypted root disk during boot.

Run blkid to get the UUID of the LUKS container partition (it will be the entry with type="crypto_LUKS").
[Arch] Remove the default boot image builder:

pacman -Rsn mkinitcpio
rm -rf /etc/mkinitcpio*

Clean up any old boot images.

rm -rf /efi/*

Configure a minimal Dracut config in /etc/dracut.conf.d/dracut.conf. It will be replaced with the full config by Ansible.

uefi="yes"
hostonly="yes"
add_dracutmodules+=" systemd "
kernel_cmdline="rd.luks.name=LUKS_CONTAINER_UUID_GOES_HERE=cryptroot root=/dev/vgroot/root"

Build the UKI.

dracut --force --regenerate-all

Configure systemd-boot.

bootctl install

Optionally, set systemd-boot options to show the boot menu before loading the OS.

echo "timeout 3" > /efi/loader/loader.conf

Networking

Warning

The setup described below is insecure and unfit for long-term use; it is intended only for use during initial setup.

Create a basic catch-all network setup to get the system online.

cat <<EOF > /etc/systemd/network/default.network
[Match]
Name = *

[Network]
DHCP = yes
EOF

systemctl enable systemd-networkd
systemctl enable systemd-resolved

Allow the root user to log in via SSH, then enable SSH to continue the setup remotely.

sed -i 's/.*PermitRoot.*/PermitRootLogin yes/g' /etc/ssh/sshd_config

Post-Install

After exiting chroot and rebooting, use the setup script from Ansible to get the system ready for Ansible management, then apply playbooks as required.