# PXE Server Quick Start Guide

This is a condensed guide for getting the PXE boot server running quickly.

## Prerequisites

- NixOS server
- Root access
- Network connectivity to bare-metal servers

## 5-Minute Setup

### 1. Run Setup Script

```bash
cd baremetal/pxe-server
sudo ./setup.sh --install --download --validate
```

### 2. Configure NixOS

Add to `/etc/nixos/configuration.nix`:

```nix
imports = [ /path/to/baremetal/pxe-server/nixos-module.nix ];

services.centra-pxe-server = {
  enable = true;
  interface = "eth0";               # YOUR NETWORK INTERFACE
  serverAddress = "10.0.100.10";   # YOUR PXE SERVER IP

  dhcp = {
    subnet = "10.0.100.0";         # YOUR SUBNET
    netmask = "255.255.255.0";
    broadcast = "10.0.100.255";
    range = {
      start = "10.0.100.100";      # DHCP RANGE START
      end = "10.0.100.200";        # DHCP RANGE END
    };
    router = "10.0.100.1";         # YOUR GATEWAY
  };
};
```

### 3. Deploy

```bash
sudo nixos-rebuild switch
```

### 4. Verify

```bash
sudo ./setup.sh --test
```

You should see:
- TFTP server running
- HTTP server running
- DHCP server running

### 5. Boot a Server

1. Configure server BIOS for PXE boot
2. Connect to same network
3. Power on
4. Watch for boot menu

## Adding Nodes

### Quick Add (No Auto-Selection)

Just boot the server and select profile from menu.

### With Auto-Selection

1. Get MAC address from server
2. Edit `ipxe/boot.ipxe`, add line:
   ```ipxe
   iseq ${mac} AA:BB:CC:DD:EE:FF && set profile worker && set hostname worker-05 && goto boot ||
   ```
3. Optionally add to `dhcp/dhcpd.conf`:
   ```conf
   host worker-05 {
       hardware ethernet AA:BB:CC:DD:EE:FF;
       fixed-address 10.0.100.65;
       option host-name "worker-05";
   }
   ```
4. Restart DHCP: `sudo systemctl restart dhcpd4`

## Troubleshooting

### Server doesn't get IP

```bash
sudo tcpdump -i eth0 port 67 or port 68
sudo journalctl -u dhcpd4 -f
```

Check:
- DHCP server running on correct interface
- Network connectivity
- Firewall allows UDP 67/68

### Server gets IP but no bootloader

```bash
sudo tcpdump -i eth0 port 69
sudo journalctl -u atftpd -f
```

Check:
- TFTP server running
- Bootloaders exist: `ls /var/lib/tftpboot/`
- Firewall allows UDP 69

### iPXE loads but can't get boot script

```bash
curl http://localhost/boot/ipxe/boot.ipxe
sudo tail -f /var/log/nginx/access.log
```

Check:
- Nginx running
- boot.ipxe exists: `ls /var/lib/pxe-boot/ipxe/`
- Firewall allows TCP 80

### Boot script loads but can't get kernel

This is expected until T032.S3 (Image Builder) is complete.

Check: `ls /var/lib/pxe-boot/nixos/`

Should have:
- bzImage
- initrd

These will be generated by the image builder.

## Common Commands

```bash
# Check all services
sudo systemctl status dhcpd4 atftpd nginx

# View logs
sudo journalctl -u dhcpd4 -u atftpd -u nginx -f

# Test connectivity
curl http://localhost/health
tftp localhost -c get undionly.kpxe /tmp/test.kpxe

# Restart services
sudo systemctl restart dhcpd4 atftpd nginx

# Check firewall
sudo iptables -L -n | grep -E "67|68|69|80"
```

## Boot Profiles

- **control-plane**: All services (FlareDB, IAM, PlasmaVMC, K8sHost, etc.)
- **worker**: Compute services (K8sHost, PlasmaVMC, ChainFire)
- **all-in-one**: Everything on one node (testing/homelab)

## Next Steps

- Add more nodes (see "Adding Nodes" above)
- Wait for T032.S3 to generate NixOS boot images
- Configure monitoring for boot activity
- Set up DHCP relay for multi-segment networks

## Full Documentation

See [README.md](README.md) for complete documentation.