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:

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

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.