pxe_boot_alma/docs/replication.md

# Replication Guide

This document describes how to reproduce the AlmaLinux PXE + Kickstart environment on a fresh `server1`.

## Topology

- `server1`: PXE services
  - runs `dnsmasq`
  - serves TFTP boot files
  - serves Alma install tree and Kickstarts over HTTP
- `server2`: install target
  - configured to network boot first

Example addresses:

- `server1`: `192.168.10.10`
- `server2`: DHCP client on the same VLAN/subnet

Replace these with your real values everywhere below.

## Services

You need these on `server1`:

- `dnsmasq`
- an HTTP server such as `nginx`, `httpd`, or `caddy`
- TFTP root directory

Common paths used in this repo:

- TFTP root: `/srv/tftp`
- HTTP root: `/srv/www`
- Alma install tree: `/srv/www/alma/10/BaseOS/x86_64/os`
- Kickstarts: `/srv/www/kickstarts`

## 1. Install Packages On Server 1

Example for AlmaLinux or RHEL-family hosts:

```bash
sudo dnf install -y dnsmasq nginx syslinux-tftpboot grub2-efi-x64 shim-x64
```

Example for Debian or Ubuntu:

```bash
sudo apt-get update
sudo apt-get install -y dnsmasq nginx pxelinux syslinux-common grub-efi-amd64-bin shim-signed
```

Package names vary slightly by distro. Adjust as needed for your host.

## 2. Prepare HTTP And TFTP Paths

```bash
sudo mkdir -p /srv/tftp/pxelinux.cfg
sudo mkdir -p /srv/tftp/EFI/BOOT
sudo mkdir -p /srv/www/alma/10/BaseOS/x86_64/os
sudo mkdir -p /srv/www/kickstarts
```

## 3. Copy AlmaLinux ISO Contents To HTTP Root

Place the ISO in this repo, then run:

```bash
./scripts/sync_alma_tree.sh \
  --iso ./AlmaLinux-10.1-x86_64-minimal.iso \
  --http-root /srv/www/alma/10/BaseOS/x86_64/os
```

This mounts the ISO read-only and copies the contents into the HTTP install tree.

## 4. Copy PXE Boot Files

From the extracted Alma tree, copy:

- `images/pxeboot/vmlinuz`
- `images/pxeboot/initrd.img`

Example:

```bash
sudo cp /srv/www/alma/10/BaseOS/x86_64/os/images/pxeboot/vmlinuz /srv/tftp/vmlinuz-alma10
sudo cp /srv/www/alma/10/BaseOS/x86_64/os/images/pxeboot/initrd.img /srv/tftp/initrd-alma10.img
```

For BIOS clients, also copy PXELINUX assets:

```bash
sudo cp /usr/share/syslinux/pxelinux.0 /srv/tftp/
sudo cp /usr/share/syslinux/menu.c32 /srv/tftp/
sudo cp /usr/share/syslinux/libutil.c32 /srv/tftp/
```

For UEFI clients, install or copy the GRUB EFI loader that matches your distro packaging.

Typical examples:

- `/boot/efi/EFI/almalinux/grubx64.efi`
- `/usr/lib/grub/x86_64-efi-signed/grubnetx64.efi.signed`
- `/usr/share/shim/BOOTX64.EFI`

## 5. Publish Kickstart Files

Copy the Kickstart file into the HTTP root:

```bash
sudo cp kickstarts/alma10-auto.ks /srv/www/kickstarts/alma10-auto.ks
sudo cp scripts/post-install-bootstrap.sh /srv/www/kickstarts/post-install-bootstrap.sh
```

The sample Kickstart expects to be reachable at:

```text
http://192.168.10.10/kickstarts/alma10-auto.ks
```

Adjust the IP or hostname in:

- `kickstarts/alma10-auto.ks`
- `kickstarts/post-install-bootstrap.sh`
- `boot/grub2/grub.cfg`
- `boot/pxelinux.cfg/default`

## 6. Install dnsmasq Config

Use [`dnsmasq/dnsmasq.conf.example`](/usr/local/valherun/pxe_boot_alma/dnsmasq/dnsmasq.conf.example) as the base.

Important fields to customize:

- interface name
- DHCP range
- router and DNS values
- `dhcp-boot`
- `enable-tftp`
- `tftp-root`

Then install and restart:

```bash
sudo cp dnsmasq/dnsmasq.conf.example /etc/dnsmasq.d/pxe-alma.conf
sudo systemctl enable --now dnsmasq
sudo systemctl restart dnsmasq
```

## 7. Install PXE Menu Files

BIOS:

```bash
sudo cp boot/pxelinux.cfg/default /srv/tftp/pxelinux.cfg/default
```

UEFI:

```bash
sudo cp boot/grub2/grub.cfg /srv/tftp/grub.cfg
```

Some UEFI layouts expect the config under:

- `/srv/tftp/EFI/BOOT/grub.cfg`
- `/srv/tftp/grub/grub.cfg`

Use the location expected by your GRUB EFI binary.

## 8. Make Sure HTTP Is Serving The Tree

Verify from another host:

```bash
curl -I http://192.168.10.10/alma/10/BaseOS/x86_64/os/
curl -I http://192.168.10.10/kickstarts/alma10-auto.ks
```

## 9. Boot Server 2

Set `server2` to:

- UEFI PXE boot, or BIOS PXE boot depending on hardware
- network boot ahead of disk boot

When PXE works correctly:

1. `server2` gets an IP from `dnsmasq`
2. it downloads the bootloader from TFTP
3. it loads kernel + initrd
4. installer fetches the install tree from HTTP
5. Kickstart runs unattended

## 10. Post-Install Bootstrap

The sample Kickstart calls [`scripts/post-install-bootstrap.sh`](/usr/local/valherun/pxe_boot_alma/scripts/post-install-bootstrap.sh) during `%post`.

That script:

1. installs `git`, `curl`, `sudo`, and related basics if missing
2. clones your `kickstart` repo to `/usr/local/valherun/kickstart`
3. clones your `tools` repo to `/usr/local/valherun/tools`
4. optionally runs:
   - `kickstart/bin/create_valherun.sh`
   - `kickstart/bash_profiles.sh --adduser`
   - `tools/bin/install_codex_access.sh`
   - `tools/bin/update_sshd_config.sh`

This gives you a second-stage bootstrap after the base OS install is complete.

## Notes About Your Existing kickstart.sh

Your current [`kickstart.sh`](/usr/local/valherun/kickstart/kickstart.sh) is useful for interactive host bootstrap, but it is not ideal for unattended Kickstart `%post` as-is because:

- it prompts by default
- `--all` re-enables the Unraid path internally

For unattended Alma installs, this repo uses the reusable sub-scripts directly instead.

## Validation Checklist

Before attempting install:

- `dnsmasq --test`
- `curl -I` against the Alma tree
- `curl -I` against the Kickstart file
- confirm `vmlinuz` and `initrd.img` exist in TFTP root
- confirm `server2` can PXE on the intended NIC and VLAN

## Suggested Next Improvements

- add a host-specific Kickstart per target machine
- add static DHCP reservation for `server2`
- add UEFI HTTP Boot if the hardware supports it
- add a wrapper to sync repo files directly into `/srv/tftp` and `/srv/www`