homelab-agents/sys-apps-session-summary.md

# Homelab Agents Session Summary - sys-apps
**Date:** 2025-11-30
**VPS:** sys-apps
**Repository:** homelab-agents (shared agent repository)
**Session Type:** NetBox DHCP pool configuration

## Session Overview

This session focused on configuring NetBox to properly mark DHCP pool IP ranges as reserved, preventing them from showing as "available" for static assignment. Created automation scripts to set up DHCP pool ranges across all VLANs.

## Problem Statement

User noticed that NetBox showed IPs in the DHCP pool range (.100-.150) as "available" for static assignment. This created confusion about which IPs could actually be assigned statically vs. which were reserved for DHCP dynamic assignment.

**Issue:** NetBox was showing 133 "available" IPs in VLAN 20, but most of those (.100-.150) were actually in the DHCP pool.

## Solution Implemented

### Two-Step Approach:

1. **Create IP Ranges** - Logical grouping of DHCP pool
2. **Reserve Individual IPs** - Mark each IP .100-.150 as "Reserved" status

## Scripts Created

### 1. sys-apps-netbox-dhcp-setup.py
**Purpose:** Create IP Range objects for DHCP pools

**What it does:**
- Connects to NetBox via API
- Fetches all IPv4 prefixes
- Creates IP Range for .100-.150 in each subnet
- Status: Active
- Description: "DHCP Pool - Dynamic Assignment Range (.100-.150)"

**Results:**
- Created/verified 6 IP ranges
- Ranges: 192.168.0.100-150, 192.168.2.100-150, 192.168.20.100-150, 192.168.30.100-150, 192.168.40.100-150, 192.168.50.100-150

### 2. sys-apps-netbox-reserve-dhcp-ips.py
**Purpose:** Create individual IP objects and mark as reserved

**What it does:**
- Connects to NetBox via API
- Fetches all /24 prefixes (skips /16)
- Creates IP object for each address .100-.150
- Sets status to "Reserved"
- Description: "DHCP Pool - Reserved for dynamic assignment"

**Results:**
- Created 255 IP objects across 5 VLANs
- 51 IPs per /24 subnet (.100 to .150 inclusive)
- All marked as "Reserved" status

## VLANs Configured

| VLAN | Subnet | DHCP Range | IPs Reserved |
|------|--------|------------|--------------|
| (No VLAN) | 192.168.2.0/24 | .100-.150 | 51 |
| Work Secure | 192.168.20.0/24 | .100-.150 | 51 |
| Family | 192.168.30.0/24 | .100-.150 | 51 |
| Guest | 192.168.40.0/24 | .100-.150 | 51 |
| IoT | 192.168.50.0/24 | .100-.150 | 51 |
| **Total** | | | **255** |

## Technical Details

### NetBox API Integration
- **URL:** https://netbox.pdmarf.co.uk
- **Authentication:** API Token (stored in /opt/docker/netbox/netbox_initial_populate.py)
- **Endpoints Used:**
  - `/api/ipam/prefixes/` - List all network prefixes
  - `/api/ipam/ip-ranges/` - Create IP range objects
  - `/api/ipam/ip-addresses/` - Create individual IP objects

### Script Features
- Environment variable or command-line argument for API token
- Error handling for duplicate entries
- Progress indicators for long-running operations
- Automatic network validation (IPs must be within subnet)
- Skips non-/24 networks (like /16) for IP reservation

### Initial Issue: Tags Not Found
First run failed because script tried to create tag "dhcp-pool" which didn't exist:
```
{'tags': ["Related object not found using the provided attributes: {'name': 'dhcp-pool'}"]}
```

**Fix:** Removed tags from IP Range creation, used only description field.

## Verification

**Before:**
- NetBox showed IPs .100-.150 as "Available"
- User saw 133 available IPs in VLAN 20 subnet

**After:**
- IPs .100-.150 marked as "Reserved"
- Available count reduced significantly
- Only IPs outside DHCP pool show as available for static assignment

**View Results:**
- IP Ranges: https://netbox.pdmarf.co.uk/ipam/ip-ranges/
- VLAN 20 IPs: https://netbox.pdmarf.co.uk/ipam/prefixes/2/ip-addresses/

## Files Created

**Scripts moved to system-apps repository:**
```
http://100.120.125.113:3000/pdm/system-apps
├── sys-apps-netbox-dhcp-setup.py
├── sys-apps-netbox-reserve-dhcp-ips.py
└── README.md
```

**Note:** Scripts were initially created in homelab-agents but moved to system-apps repository as they are VPS-specific configuration tools, not shared agents.

**Both scripts:**
- Follow naming convention: `{hostname}-{description}.py`
- Are executable (`chmod +x`)
- Accept API token as argument or environment variable
- Include comprehensive error handling and progress output

## DHCP Pool Standard

**Established standard for all VLANs:**
- DHCP pool range: `.100-.150` (51 IPs)
- Static assignment ranges: `.1-.99` and `.151-.254`
- Gateway typically: `.1`

This provides:
- 99 static IPs before DHCP pool
- 51 DHCP dynamic IPs
- 104 static IPs after DHCP pool
- Total usable in /24: 254 IPs

## Usage for Future VLANs

When adding a new VLAN, run both scripts to configure DHCP pool:

```bash
# Clone system-apps repository (if not already cloned)
git clone git@100.120.125.113:pdm/system-apps.git ~/system-apps
cd ~/system-apps

# 1. Create IP Range
python3 sys-apps-netbox-dhcp-setup.py 'YOUR_API_TOKEN'

# 2. Reserve Individual IPs
python3 sys-apps-netbox-reserve-dhcp-ips.py 'YOUR_API_TOKEN'
```

Or set environment variable once:
```bash
export NETBOX_TOKEN='YOUR_API_TOKEN'
python3 sys-apps-netbox-dhcp-setup.py
python3 sys-apps-netbox-reserve-dhcp-ips.py
```

## Key Decisions

### Why Two Scripts?
1. **IP Ranges** - Logical grouping, visual representation in NetBox
2. **Individual IPs** - Actual reservation, prevents "available" status

Both are needed because IP Ranges alone don't change IP availability status.

### Why Mark as "Reserved" Not "DHCP"?
NetBox standard status values:
- Active = In use
- Reserved = Allocated but not assigned
- **Reserved is correct** for DHCP pool (allocated to DHCP server, not assigned to specific device)

### Script Location
**Moved to `system-apps` repository** because:
- VPS-specific configuration tools (not shared agents)
- Belongs with other sys-apps infrastructure code
- `homelab-agents` = shared Claude Code agents only
- `system-apps` = VPS-specific automation and config
- Makes more sense in project-specific repo vs shared agent repo

## Next Session Recommendations

1. **Document NetBox token management** - Where tokens are stored, rotation policy
2. **Create tag for DHCP pools** - Add "dhcp-pool" tag in NetBox UI for easier filtering
3. **Consider automation** - Run scripts automatically when new VLAN is created
4. **Verify other subnets** - Check if any other networks need DHCP pool configuration

## Session Learning

**NetBox IPAM Best Practices:**
- IP Ranges = logical grouping
- Individual IP objects = actual reservation
- Both needed for proper IPAM
- Status "Reserved" = correct for DHCP pools
- API automation prevents manual clicking for 255 IPs

---

**Session successfully completed. NetBox now properly shows DHCP pool IPs as reserved.**