docs: add Arch install guide (LUKS + TPM2) and network cheatsheet

This commit is contained in:
Filip Suchy 2026-10-11 00:41:59 +02:00
parent 8e439a9bd2
commit 4173d16685
Signed by: nevim42
GPG Key ID: DA63EE05A1AB736C
2 changed files with 338 additions and 0 deletions

277
docs/install.md Normal file
View File

@ -0,0 +1,277 @@
# Arch Linux Installation
I need only a minimalistic Arch installation and then I run my bootstrap
script that installs [Ansible](https://www.ansible.com/) and runs the magic
show...
## 1. Partition the disk
To check connected disks and partitions, you can use simple `lsblk`.
Now you can create partitions on disk using `cfdisk`, which is a more
user-friendly TUI utility, or you can use `gdisk`, which is also easy, but
less "clickable"...
To use EFI, we need to create a GPT table on the disk.
Usually I'm using only two partitions - one for the EFI and the second one for
the BTRFS partition. EFI partition is typically **512MB** of size and it's
marked as **EFI System**. To create file systems, use the following commands
(assume the disk is on `sda` - on NVMe it is `nvme0n1` instead)
```shell
mkfs.fat -F32 /dev/sda1
mkfs.btrfs -L ArchLinux /dev/sda2
```
**Optional: full-disk encryption.** If you want encryption, put the BTRFS
partition into a LUKS2 container first and create the filesystem on the
mapped device:
```shell
cryptsetup luksFormat /dev/sda2
cryptsetup open /dev/sda2 relic
mkfs.btrfs -L ArchLinux /dev/mapper/relic
```
Then use `/dev/mapper/relic` instead of `/dev/sda2` in every command below
(mounts and UUID lookups). The name is arbitrary - just keep it consistent
with the GRUB command line in section 4. The rest of the install is the
same, with two extra steps marked in section 4. The passphrase is not
recoverable - keep it in a password manager.
The BTRFS partition is never used directly, so you have to create at least the
root subvolume. To create subvolumes, mount the BTRFS partition.
```shell
mount /dev/sda2 /mnt
cd /mnt
```
Now you can create your subvolumes. Subvolume names start with `@` and the
**root** subvolume is just `@`
```shell
btrfs subvolume create @
btrfs subvolume create @home
btrfs subvolume create @snapshots
```
After you create all desired subvolumes, unmount `/mnt` and mount all
partitions and subvolumes
```shell
cd /
umount /mnt
mount -o noatime,compress=zstd,discard=async,subvol=@ /dev/sda2 /mnt
mkdir -p /mnt/{boot,home,snapshots}
mount -o noatime,compress=zstd,discard=async,subvol=@home /dev/sda2 /mnt/home
mount -o noatime,compress=zstd,discard=async,subvol=@snapshots /dev/sda2 /mnt/snapshots
mount /dev/sda1 /mnt/boot
```
Alright, the disk is ready and we can pacstrap Arch Linux...
## 2. Pacstrap Arch Linux
Pacstrap Arch Linux with some useful packages
```shell
pacstrap /mnt base base-devel linux linux-firmware linux-headers grub grub-btrfs efibootmgr btrfs-progs sudo fish xdg-utils xdg-user-dirs networkmanager wpa_supplicant wget neovim tmux
```
Microcode (`amd-ucode` / `intel-ucode`) is hardware-specific and installed
later by the bootstrap/Ansible based on the detected CPU.
Generate **fstab** and check it
```shell
genfstab -U -p /mnt >> /mnt/etc/fstab
cat /mnt/etc/fstab
```
## 3. Set locale, create user, ...
Now we can "chroot" to the system and set up some basic stuff like the
timezone
```shell
arch-chroot /mnt
ln -sf /usr/share/zoneinfo/Europe/Prague /etc/localtime
hwclock --systohc --utc
```
Check if the time is correct using the `date` command. Use **neovim** to
uncomment the `en_US.UTF-8` line in `/etc/locale.gen` and then run
`locale-gen`
```shell
nvim /etc/locale.gen
echo LANG=en_US.UTF-8 > /etc/locale.conf
locale-gen
```
Set the hostname and edit the **hosts** file (use the machine's actual
hostname)
```shell
echo <hostname> > /etc/hostname
nvim /etc/hosts
```
The **hosts** file should look like this
```
# Static table lookup for hostnames.
# See hosts(5) for details.
# <ip-address> <hostname>
127.0.0.1 localhost
::1 localhost
127.0.0.1 <hostname>
::1 <hostname>
# End of file
```
Create the user and add him to the `wheel` group to enable `sudo`
```shell
useradd -mG wheel -s /bin/fish nevim42
passwd nevim42
EDITOR=nvim visudo
```
Uncomment the line `%wheel ALL=(ALL:ALL) ALL`
Enable colors for pacman (and yay)
```shell
nvim /etc/pacman.conf
```
And uncomment the `Color` line under `Misc options`. Also some packages are
in the multilib repository, so uncomment the following lines
```
# [multilib]
# Include = /etc/pacman.d/mirrorlist
```
Now we can also enable some services like networking - just NetworkManager.
It takes care of DHCP, ethernet, WiFi (via wpa_supplicant) and VPN on its
own; nothing else needs to be enabled. Basic commands are in
[network.md](network.md).
```shell
systemctl enable NetworkManager
```
## 4. Bootloader/GRUB
Because we are using BTRFS, we have to add it to the modules in the
**initcpio**
```shell
nvim /etc/mkinitcpio.conf
```
and add `btrfs` to the modules
```
MODULES=(btrfs)
```
**With encryption**, the initramfs must unlock the LUKS container before the
root filesystem can be mounted. Switch to the systemd-based hooks (they also
handle the TPM2 unlock later):
```
HOOKS=(base systemd autodetect microcode modconf kms keyboard sd-vconsole block sd-encrypt filesystems fsck)
```
Now rebuild the initramfs
```shell
mkinitcpio -p linux
```
Install GRUB
```shell
grub-install --target=x86_64-efi --efi-directory=/boot --bootloader-id=GRUB
```
**With encryption**, tell the initramfs where the container is. First get the
UUID of the LUKS partition (not the BTRFS filesystem)
```shell
blkid -s UUID -o value /dev/sda2 # <LUKS-UUID>
```
and put it into `/etc/default/grub`
```
GRUB_CMDLINE_LINUX="rd.luks.name=<LUKS-UUID>=relic root=/dev/mapper/relic"
```
Finally generate the configuration - the same command with and without
encryption
```shell
grub-mkconfig -o /boot/grub/grub.cfg
```
Some motherboards have a problem recognizing the GRUB bootloader on the EFI
partition, so if you can't see the boot entry in your BIOS, try to rename
these
```shell
mv /boot/EFI/GRUB /boot/EFI/BOOT
mv /boot/EFI/BOOT/grubx64.efi /boot/EFI/BOOT/BOOTX64.EFI
```
You can also check the boot entry with `efibootmgr`
```shell
efibootmgr | cut -f 1
```
## 5. It's done...
Now it's done and we can finally reboot to the installed system. With
encryption you will be asked for the LUKS passphrase before the system boots.
Nothing else is needed in the live environment - the optional TPM2 auto-unlock
is set up after the first boot, on the installed system (see section 6).
```shell
exit
cd /
umount -a
reboot
```
## 6. Optional: TPM2 auto-unlock (after first boot)
With a TPM 2.0 chip the disk can unlock itself at boot - no passphrase typing.
Run this on the installed system, after the first boot (not in the live
environment). The existing passphrase slot stays in the LUKS header as a
fallback, so this only adds another way to unlock:
```shell
sudo pacman -S tpm2-tss
sudo systemd-cryptenroll --tpm2-device=auto /dev/sda2
```
Notes:
- Without Secure Boot the TPM binding is machine-bound only - it protects
against a casual boot of the machine, not against a targeted attacker with
physical access.
- After a firmware change (BIOS update, motherboard swap) the TPM unlock stops
working - unlock with the passphrase and enroll again.
- Don't run `systemd-cryptenroll --wipe-slot=password` - it would remove the
passphrase fallback.

61
docs/network.md Normal file
View File

@ -0,0 +1,61 @@
# Network
Day-to-day network management on Arch, all through **NetworkManager** — one
tool for ethernet, WiFi, DHCP and VPN. If you ever forget the commands,
`nmtui` gives you a text UI for the same thing.
## Status
```shell
nmcli device status # interfaces and what they are doing
nmcli general status # overall NM state + connectivity check
nmcli connection show # saved connections
ip -brief address # IP addresses (iproute2, part of base)
```
## Ethernet
Wired connections are picked up automatically (DHCP). If a cable is connected
but the interface stays disconnected:
```shell
nmcli device connect eno1
```
## WiFi
```shell
nmcli radio wifi # is the WiFi radio on?
nmcli radio wifi on # turn it on if needed
nmcli device wifi list # visible networks (--rescan yes to refresh)
nmcli device wifi connect "MyNet" --ask # connect, ask for password
nmcli device wifi connect "MyNet" password "secret" # or inline
nmcli device wifi connect "MyNet" hidden yes # hidden network
```
Managing the connection afterwards:
```shell
nmcli connection show # saved connections
nmcli connection up "MyNet" # connect again
nmcli device disconnect wlan0 # disconnect
nmcli connection delete "MyNet" # forget it
```
NetworkManager remembers networks and reconnects to them automatically.
## Checking what I have
```shell
nmcli device show wlan0 # details for one interface (IP, gateway, DNS)
nmcli -f IP4.ADDRESS,IP4.GATEWAY,IP4.DNS device show
ping archlinux.org # is it actually working?
```
## Tips
- `nmtui` — full text UI when you don't remember the nmcli syntax.
- Interface names: `eno1` (ethernet), `wlan0` (WiFi) — check `nmcli device status`.
- The WiFi backend is `wpa_supplicant`, managed by NetworkManager — it is
never started or configured separately.