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:

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

Example for Debian or Ubuntu:

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

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:

./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:

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:

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:

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:

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 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:

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:

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

UEFI:

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:

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