a0da5be8fc
Translate 8 documentation files from German to English: - docs/index.md (complete) - docs/getting-started/first-install.md (complete) - docs/getting-started/new-client.md (complete) - docs/getting-started/reinstall.md (complete) - docs/getting-started/sd-image.md (complete) - docs/deployment/dns.md (PTR, Hetzner, checklist sections) - docs/services/tailscale.md (code comments) - docs/services/forgejo.md (placeholder names)
184 lines
4.1 KiB
Markdown
184 lines
4.1 KiB
Markdown
# Reinstallation
|
|
|
|
This guide describes the **reinstallation** of an existing host, e.g. after a hardware change or in case of issues.
|
|
|
|
## Difference from Initial Installation
|
|
|
|
| Aspect | Initial Installation | Reinstallation |
|
|
|--------|----------------------|----------------|
|
|
| SOPS Secrets | Not yet present | Already configured |
|
|
| SSH Host Key | Newly generated | **Must be restored!** |
|
|
| Disk IDs | Newly determined | Often changed (new hardware) |
|
|
| secrets.yaml | Will be created | Already exists |
|
|
|
|
## Important: SSH Host Key Issue
|
|
|
|
During a reinstallation, a **new SSH host key** is generated. This key will no longer match the age key in `.sops.yaml`!
|
|
|
|
### Possible Solutions
|
|
|
|
**Option A: Back up and restore the old host key** (recommended)
|
|
|
|
**Option B: Generate a new key and update SOPS**
|
|
|
|
## Prerequisites
|
|
|
|
- Backup of the old SSH host key (if using Option A)
|
|
- Access to `.sops.yaml` and the admin age keys
|
|
- Bootable NixOS ISO
|
|
|
|
## Step 1: Preparation (before the installation)
|
|
|
|
### 1.1 Back Up the Old SSH Host Key (Option A)
|
|
|
|
If the old host is still running:
|
|
|
|
```bash
|
|
# On the old host
|
|
sudo cat /etc/ssh/ssh_host_ed25519_key > ~/ssh_host_ed25519_key.backup
|
|
sudo cat /etc/ssh/ssh_host_ed25519_key.pub > ~/ssh_host_ed25519_key.pub.backup
|
|
```
|
|
|
|
Copy the files securely to the development machine.
|
|
|
|
### 1.2 Determine Disk IDs
|
|
|
|
**With new hardware**, the disk IDs will change!
|
|
|
|
```bash
|
|
# In the NixOS live system
|
|
lsblk -o NAME,SIZE,MODEL,SERIAL
|
|
ls -la /dev/disk/by-id/
|
|
```
|
|
|
|
Enter the new disk ID in `hosts/<hostname>/disks.sh` or `disks.nix`:
|
|
|
|
```bash
|
|
# Example disks.sh
|
|
DISK="/dev/disk/by-id/nvme-Samsung_SSD_970_EVO_Plus_XXXXX"
|
|
```
|
|
|
|
## Step 2: Perform the Installation
|
|
|
|
### 2.1 Boot the NixOS ISO
|
|
|
|
Boot from USB/CD, set a root password, and connect via SSH.
|
|
|
|
### 2.2 Clone the Repository
|
|
|
|
```bash
|
|
sudo -i
|
|
nix-shell -p git
|
|
git clone <GIT_REPO_URL> /tmp/nixos
|
|
cd /tmp/nixos
|
|
```
|
|
|
|
### 2.3 Verify the Disk Configuration
|
|
|
|
```bash
|
|
# Display current disk IDs
|
|
ls -la /dev/disk/by-id/
|
|
|
|
# Compare with the configuration
|
|
cat hosts/<hostname>/disks.sh | grep DISK
|
|
```
|
|
|
|
**If necessary:** Update the disk ID in the configuration.
|
|
|
|
### 2.4 Run the Install Script
|
|
|
|
```bash
|
|
bash scripts/install.sh -n <hostname>
|
|
```
|
|
|
|
### 2.5 Restore the SSH Host Key (Option A)
|
|
|
|
**Before rebooting!**
|
|
|
|
```bash
|
|
# Restore the host key from backup
|
|
cp /path/to/ssh_host_ed25519_key.backup /mnt/etc/ssh/ssh_host_ed25519_key
|
|
cp /path/to/ssh_host_ed25519_key.pub.backup /mnt/etc/ssh/ssh_host_ed25519_key.pub
|
|
chmod 600 /mnt/etc/ssh/ssh_host_ed25519_key
|
|
chmod 644 /mnt/etc/ssh/ssh_host_ed25519_key.pub
|
|
```
|
|
|
|
### 2.6 Reboot
|
|
|
|
```bash
|
|
umount -Rl /mnt
|
|
reboot
|
|
```
|
|
|
|
## Step 3: After the Reboot
|
|
|
|
### Option A (Key Restored)
|
|
|
|
SOPS secrets should work automatically. Verify:
|
|
|
|
```bash
|
|
sudo cat /run/secrets/tailscale/auth-key
|
|
```
|
|
|
|
### Option B (New Key)
|
|
|
|
The host cannot decrypt the secrets. Configure the new key:
|
|
|
|
```bash
|
|
# Determine the new age key
|
|
nix-shell -p ssh-to-age --run 'cat /etc/ssh/ssh_host_ed25519_key.pub | ssh-to-age'
|
|
```
|
|
|
|
On the development machine:
|
|
|
|
```bash
|
|
# Update .sops.yaml with the new key
|
|
vim .sops.yaml
|
|
|
|
# Re-encrypt secrets with the new key
|
|
sops updatekeys hosts/<hostname>/secrets.yaml
|
|
```
|
|
|
|
Then redeploy the configuration:
|
|
|
|
```bash
|
|
NIX_SSHOPTS="-p 2299" nixos-rebuild switch --flake .#<hostname> \
|
|
--target-host <user>@<IP> --sudo --ask-sudo-password
|
|
```
|
|
|
|
## Common Issues
|
|
|
|
### "No secret key available"
|
|
|
|
SOPS cannot decrypt the secrets. Cause:
|
|
- SSH host key does not match the age key in `.sops.yaml`
|
|
|
|
Solution: Follow Option B (configure the new key).
|
|
|
|
### "Device not found" during partitioning
|
|
|
|
The disk ID in `disks.sh`/`disks.nix` is incorrect.
|
|
|
|
```bash
|
|
# Find the correct ID
|
|
ls -la /dev/disk/by-id/
|
|
```
|
|
|
|
### Outdated Hardware Config
|
|
|
|
With new hardware, `hardware.nix` must be regenerated:
|
|
|
|
```bash
|
|
# The install script regenerates automatically if the file is missing
|
|
rm hosts/<hostname>/hardware.nix
|
|
bash scripts/install.sh -n <hostname>
|
|
```
|
|
|
|
## Checklist
|
|
|
|
- [ ] Old SSH host key backed up (if possible)
|
|
- [ ] Disk IDs in configuration verified/updated
|
|
- [ ] Installation completed
|
|
- [ ] SSH host key restored OR new key configured in SOPS
|
|
- [ ] Secrets are functional (`sudo cat /run/secrets/...`)
|
|
- [ ] Tailscale connected (`tailscale status`)
|