Homelab: [homelab-agents] - Session 2025-11-30
Added NetBox DHCP pool configuration automation scripts. Created tools to reserve DHCP pool IP ranges (.100-.150) via NetBox API, preventing them from showing as "available" for static assignment. Changes: - Created sys-apps-netbox-dhcp-setup.py: Creates IP Range objects for DHCP pools - Created sys-apps-netbox-reserve-dhcp-ips.py: Reserves individual IPs as "Reserved" status - Updated sys-apps-session-summary.md with comprehensive session documentation - Updated CLAUDE.md with session 2025-11-30 history entry - Configured 255 IPs across 5 VLANs (51 IPs per /24 subnet) - Established DHCP pool standard: .100-.150 for all networks Repository: http://100.120.125.113:3000/pdm/homelab-agents Next Session Focus: Document NetBox token management and create dhcp-pool tag 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Homelab Automation
@@ -1,168 +1,190 @@
|
||||
# Homelab Agents Session Summary - sys-apps
|
||||
**Date:** 2025-11-28
|
||||
**Date:** 2025-11-30
|
||||
**VPS:** sys-apps
|
||||
**Repository:** homelab-agents (shared agent repository)
|
||||
**Session Type:** Documentation cleanup and naming convention updates
|
||||
**Session Type:** NetBox DHCP pool configuration
|
||||
|
||||
## Session Overview
|
||||
|
||||
This session focused on simplifying the homelab-agents repository documentation, establishing clear file naming conventions, and ensuring the finish-up agent works correctly across all VPS instances.
|
||||
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.
|
||||
|
||||
## User Requests & Accomplishments
|
||||
## Problem Statement
|
||||
|
||||
### 1. Agent Renaming Verification
|
||||
**Request:** User wanted to rename "Sysadmin Session Closer Agent" to "Finish Up Agent" with VPS hostname in filenames.
|
||||
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.
|
||||
|
||||
**Finding:** All changes were already completed in previous session (commit 1602733).
|
||||
**Issue:** NetBox was showing 133 "available" IPs in VLAN 20, but most of those (.100-.150) were actually in the DHCP pool.
|
||||
|
||||
**Status:** ✓ Verified complete
|
||||
## Solution Implemented
|
||||
|
||||
### 2. Workflow Documentation
|
||||
**Request:** Create simple workflow guide for using agents.
|
||||
### Two-Step Approach:
|
||||
|
||||
**Accomplished:**
|
||||
- Created `WORKFLOW.md` with streamlined instructions
|
||||
- One-line VPS setup using curl bootstrap script
|
||||
- Simple 3-step project workflow (cd → work → finish up)
|
||||
- Key rules for where to run finish-up agent
|
||||
- Quick reference table
|
||||
1. **Create IP Ranges** - Logical grouping of DHCP pool
|
||||
2. **Reserve Individual IPs** - Mark each IP .100-.150 as "Reserved" status
|
||||
|
||||
### 3. Documentation Consolidation
|
||||
**Request:** Remove duplicate documentation files.
|
||||
## Scripts Created
|
||||
|
||||
**Accomplished:**
|
||||
- Deleted `QUICK-START.md` (redundant with README + WORKFLOW)
|
||||
- Renamed `HOW-TO-GUIDE.md` → `GIT-REFERENCE.md` (clearer purpose)
|
||||
- Simplified documentation structure:
|
||||
- `README.md` = Overview and installation
|
||||
- `WORKFLOW.md` = Simple workflow guide
|
||||
- `GIT-REFERENCE.md` = Detailed git commands reference
|
||||
- `VPS-SSH-KEY-SETUP.md` = SSH configuration
|
||||
### 1. sys-apps-netbox-dhcp-setup.py
|
||||
**Purpose:** Create IP Range objects for DHCP pools
|
||||
|
||||
### 4. Session Summary Filename Simplification
|
||||
**Request:** Remove redundant project name from session summary filenames.
|
||||
**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)"
|
||||
|
||||
**Accomplished:**
|
||||
- Changed format from `[PROJECT_NAME]-[HOSTNAME]-session-summary.md`
|
||||
- To simplified: `[HOSTNAME]-session-summary.md`
|
||||
- Rationale: File is saved inside project directory, so project name is redundant
|
||||
- Updated in:
|
||||
- `agents/finish-up.md` (Steps 1, 3, 7)
|
||||
- `CLAUDE.md` (naming convention)
|
||||
- `WORKFLOW.md` (agent behavior)
|
||||
**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
|
||||
|
||||
### 5. VPS Hostname Change
|
||||
**Request:** Rename files for VPS hostname change from "108-system-apps" to "sys-apps".
|
||||
### 2. sys-apps-netbox-reserve-dhcp-ips.py
|
||||
**Purpose:** Create individual IP objects and mark as reserved
|
||||
|
||||
**Accomplished:**
|
||||
- Renamed `homelab-agents-108-system-apps-session-summary.md` → `sys-apps-session-summary.md`
|
||||
- Removed old session summaries:
|
||||
- `gitea-installation-session-summary.md`
|
||||
- `gitea-domain-and-ssh-fixes-session-summary.md`
|
||||
**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"
|
||||
|
||||
### 6. Git Basics Reference
|
||||
**Request:** User asked for explanation of `git add -A` and `git commit -m` but said "i'll forget that".
|
||||
**Results:**
|
||||
- Created 255 IP objects across 5 VLANs
|
||||
- 51 IPs per /24 subnet (.100 to .150 inclusive)
|
||||
- All marked as "Reserved" status
|
||||
|
||||
**Accomplished:**
|
||||
- Created `sys-apps-git-quick-reference.md` with:
|
||||
- Daily workflow commands
|
||||
- Simple explanations of git add/commit/push
|
||||
- Common patterns and examples
|
||||
- When to use finish-up vs manual git
|
||||
## VLANs Configured
|
||||
|
||||
### 7. File Naming Convention
|
||||
**Request:** Ensure all new files have hostname prefix automatically.
|
||||
| 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** |
|
||||
|
||||
**Accomplished:**
|
||||
- Added file naming convention to `CLAUDE.md`:
|
||||
- **Rule:** ALL new files must use `{hostname}-{description}.md` format
|
||||
- **Exception:** Agent files in `agents/` directory (shared)
|
||||
- **Important:** Always run `hostname` command (never hardcode)
|
||||
- Generic rule works on any VPS without modification
|
||||
- Future sessions will follow this automatically
|
||||
## 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
|
||||
|
||||
```
|
||||
/home/pdm/.homelab-agents/sys-apps-netbox-dhcp-setup.py
|
||||
/home/pdm/.homelab-agents/sys-apps-netbox-reserve-dhcp-ips.py
|
||||
```
|
||||
|
||||
**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
|
||||
# 1. Create IP Range
|
||||
python3 /home/pdm/.homelab-agents/sys-apps-netbox-dhcp-setup.py 'YOUR_API_TOKEN'
|
||||
|
||||
# 2. Reserve Individual IPs
|
||||
python3 /home/pdm/.homelab-agents/sys-apps-netbox-reserve-dhcp-ips.py 'YOUR_API_TOKEN'
|
||||
```
|
||||
|
||||
Or set environment variable once:
|
||||
```bash
|
||||
export NETBOX_TOKEN='YOUR_API_TOKEN'
|
||||
python3 /home/pdm/.homelab-agents/sys-apps-netbox-dhcp-setup.py
|
||||
python3 /home/pdm/.homelab-agents/sys-apps-netbox-reserve-dhcp-ips.py
|
||||
```
|
||||
|
||||
## Key Decisions
|
||||
|
||||
### Documentation Structure
|
||||
- Consolidated from 5+ docs to 4 focused files
|
||||
- Each has clear, distinct purpose
|
||||
- No duplication between files
|
||||
### Why Two Scripts?
|
||||
1. **IP Ranges** - Logical grouping, visual representation in NetBox
|
||||
2. **Individual IPs** - Actual reservation, prevents "available" status
|
||||
|
||||
### Filename Format
|
||||
- Session summaries: `{hostname}-session-summary.md` (no timestamp, overwrites)
|
||||
- All documentation: `{hostname}-{description}.md`
|
||||
- Hostname detection: Always run `hostname` command dynamically
|
||||
Both are needed because IP Ranges alone don't change IP availability status.
|
||||
|
||||
### Git Workflow
|
||||
- finish-up agent = comprehensive documentation + session closure
|
||||
- Manual git = quick commits during work
|
||||
- Users can choose based on context
|
||||
### 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)
|
||||
|
||||
## Technical Changes
|
||||
|
||||
### Files Modified:
|
||||
- `agents/finish-up.md` - Updated filename format (3 locations)
|
||||
- `CLAUDE.md` - Added file naming convention, updated session history
|
||||
- `WORKFLOW.md` - Updated agent behavior description
|
||||
|
||||
### Files Created:
|
||||
- `WORKFLOW.md` - Simple workflow guide
|
||||
- `sys-apps-git-quick-reference.md` - Git basics reference
|
||||
|
||||
### Files Deleted:
|
||||
- `QUICK-START.md` - Redundant documentation
|
||||
- `gitea-installation-session-summary.md` - Old session summary
|
||||
- `gitea-domain-and-ssh-fixes-session-summary.md` - Old session summary
|
||||
|
||||
### Files Renamed:
|
||||
- `HOW-TO-GUIDE.md` → `GIT-REFERENCE.md` - Clearer naming
|
||||
- `homelab-agents-108-system-apps-session-summary.md` → `sys-apps-session-summary.md` - Hostname update
|
||||
|
||||
## Repository Status
|
||||
|
||||
- **Type:** Shared agent repository (homelab-agents)
|
||||
- **Location:** http://100.120.125.113:3000/pdm/homelab-agents.git
|
||||
- **Branch:** main
|
||||
- **Status:** All changes committed and pushed
|
||||
|
||||
## Session Commits
|
||||
|
||||
1. `43770a7` - Add simple workflow guide for homelab agents
|
||||
2. `201f6b8` - Consolidate documentation to remove duplication
|
||||
3. `9673641` - Simplify session summary filename format
|
||||
4. `9177b02` - Rename session summary to match VPS hostname change
|
||||
5. `c44a697` - Remove outdated session summaries
|
||||
6. `6b2e43a` - Add git quick reference for sys-apps VPS
|
||||
7. `18003e5` - Add file naming convention to CLAUDE.md
|
||||
8. `ea3ff43` - Make hostname rule generic for all VPS instances
|
||||
|
||||
## Insights & Learnings
|
||||
|
||||
### User Preferences
|
||||
- Prefers simple, streamlined documentation over comprehensive guides
|
||||
- Values automation (naming conventions, dynamic hostname)
|
||||
- Wants quick reference materials (git commands)
|
||||
- Appreciates clean, organized repository structure
|
||||
|
||||
### Repository Design
|
||||
- `~/.homelab-agents` = Infrastructure/tooling (like `.ssh`, `.config`)
|
||||
- Project repos = Actual work (`~/vps-system-apps`, etc.)
|
||||
- Session summaries belong in project repos, not shared repo
|
||||
- File naming with hostname enables multi-VPS tracking
|
||||
### Script Location
|
||||
Placed in `~/.homelab-agents/` because:
|
||||
- Infrastructure/automation tools
|
||||
- Can be reused across VPS instances
|
||||
- Follows established pattern (agents, scripts, tools live here)
|
||||
- Prefixed with `sys-apps-` per naming convention
|
||||
|
||||
## Next Session Recommendations
|
||||
|
||||
1. Test the finish-up agent on a real project (not homelab-agents itself)
|
||||
2. Deploy agents to additional VPS instances via bootstrap script
|
||||
3. Consider creating additional specialized agents for common tasks
|
||||
4. Document any VPS-specific configurations if needed
|
||||
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
|
||||
|
||||
## Questions for Future Consideration
|
||||
## Session Learning
|
||||
|
||||
- Should session summaries in homelab-agents go to `session-logs/` directory?
|
||||
- Are there other common tasks that warrant dedicated agents?
|
||||
- Should we create a template for new project initialization?
|
||||
**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 documented and all changes pushed to Gitea.**
|
||||
**Session successfully completed. NetBox now properly shows DHCP pool IPs as reserved.**
|
||||
|
||||
Reference in New Issue
Block a user