# 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.

```shell
sudo -i
```

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

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

- Set the correct keyboard map.

```shell
# Arch:
loadkeys uk

# Debian:
dpkg-reconfigure keyboard-configuration
setupcon
```

- Check the system time is correct.

```shell
timedatectl
```

- **[Arch]** Use `iwctl` to connect to WiFi if necessary.

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

- **[Debian]** Use `wpa_supplicant` to connect to WiFi if necessary.

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

- Check network connectivity.

```shell
ping archlinux.org
```

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

```shell
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.

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

- Encrypt the main partition with LUKS2 then open it.

```shell
cryptsetup luksFormat /dev/nvme0n1p2
cryptsetup open /dev/nvme0n1p2 cryptroot
```

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

```shell
pvcreate /dev/mapper/cryptroot
vgcreate vgroot /dev/mapper/cryptroot
```

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

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

- Create filesystems on each partition.

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

- Create a FAT32 filesystem on the boot partition.

```shell
mkfs.fat -F 32 /dev/nvme0n1p1
```

### System Install

- Mount the boot partition and LVM volumes under `/mnt`.

```shell
# 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.

```shell
# 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.

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

- Change-root into the new system.

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

- **[Debian]** Install core packages.

```shell
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.

```shell
# 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.

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

- Persist the keyboard layout change.

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

- Set a root password.

```shell
passwd
```

### Boot Setup

These steps set up the system to build a [universal kernel image (UKI)][uki] using [Dracut][dracut] then boot into it with [systemd-boot][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:

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

- Clean up any old boot images.

```shell
rm -rf /efi/*
```

- Configure a minimal [Dracut][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.

```shell
dracut --force --regenerate-all
```

- Configure systemd-boot.

```shell
bootctl install
```

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

```shell
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.

```shell
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.

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

## Post-Install

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

[ansible]: https://gitea.tatsu.casa/tatsu-deploy/ansible
[dracut]: https://wiki.archlinux.org/title/Dracut
[systemd-boot]: https://wiki.archlinux.org/title/Systemd-boot
[uki]: https://wiki.archlinux.org/title/Unified_kernel_image