leo-claude-mktplace/plugins/cmdb-assistant/commands/cmdb-register.md

description

description
Register the current machine into NetBox with all running applications

CMDB Machine Registration

Register the current machine into NetBox, including hardware info, network interfaces, and running applications (Docker containers, services).

Usage

/cmdb-register [--site <site-name>] [--tenant <tenant-name>] [--role <role-name>]

Options:

• --site <name>: Site to assign (will prompt if not provided)
• --tenant <name>: Tenant for resource isolation (optional)
• --role <name>: Device role (default: auto-detect based on services)

Instructions

You are registering the current machine into NetBox. This is a multi-phase process that discovers local system information and creates corresponding NetBox objects.

IMPORTANT: Load the netbox-patterns skill for best practice reference.

Phase 1: System Discovery (via Bash)

Gather system information using these commands:

1.1 Basic Device Info

# Hostname
hostname

# OS/Platform info
cat /etc/os-release 2>/dev/null || uname -a

# Hardware model (varies by system)
# Raspberry Pi:
cat /proc/device-tree/model 2>/dev/null || echo "Unknown"

# x86 systems:
cat /sys/class/dmi/id/product_name 2>/dev/null || echo "Unknown"

# Serial number
# Raspberry Pi:
cat /proc/device-tree/serial-number 2>/dev/null || cat /proc/cpuinfo | grep Serial | cut -d: -f2 | tr -d ' ' 2>/dev/null

# x86 systems:
cat /sys/class/dmi/id/product_serial 2>/dev/null || echo "Unknown"

# CPU info
nproc

# Memory (MB)
free -m | awk '/Mem:/ {print $2}'

# Disk (GB, root filesystem)
df -BG / | awk 'NR==2 {print $2}' | tr -d 'G'

1.2 Network Interfaces

# Get interfaces with IPs (JSON format)
ip -j addr show 2>/dev/null || ip addr show

# Get default gateway interface
ip route | grep default | awk '{print $5}' | head -1

# Get MAC addresses
ip -j link show 2>/dev/null || ip link show

1.3 Running Applications

# Docker containers (if docker available)
docker ps --format '{"name":"{{.Names}}","image":"{{.Image}}","status":"{{.Status}}","ports":"{{.Ports}}"}' 2>/dev/null || echo "Docker not available"

# Docker Compose projects (check common locations)
find ~/apps /home/*/apps -name "docker-compose.yml" -o -name "docker-compose.yaml" 2>/dev/null | head -20

# Systemd services (running)
systemctl list-units --type=service --state=running --no-pager --plain 2>/dev/null | grep -v "^UNIT" | head -30

Phase 2: Pre-Registration Checks (via MCP)

Before creating objects, verify prerequisites:

2.1 Check if Device Already Exists

dcim_list_devices name=<hostname>

If device exists:

• Inform user and suggest /cmdb-sync instead
• Ask if they want to proceed with re-registration (will update existing)

2.2 Verify/Create Site

If --site provided:

dcim_list_sites name=<site-name>

If site doesn't exist, ask user if they want to create it.

If no site provided, list available sites and ask user to choose:

dcim_list_sites

2.3 Verify/Create Platform

Based on OS detected, check if platform exists:

dcim_list_platforms name=<platform-name>

Platform naming:

• Raspberry Pi OS (Bookworm) for Raspberry Pi
• Ubuntu 24.04 LTS for Ubuntu
• Debian 12 for Debian
• Use format: {OS Name} {Version}

If platform doesn't exist, create it:

dcim_create_platform name=<platform-name> slug=<slug>

2.4 Verify/Create Device Role

Based on detected services:

• If Docker containers found → Docker Host
• If only basic services → Server
• If specific role specified → Use that

dcim_list_device_roles name=<role-name>

Phase 3: Device Registration (via MCP)

3.1 Get/Create Manufacturer and Device Type

For Raspberry Pi:

dcim_list_manufacturers name="Raspberry Pi Foundation"
dcim_list_device_types manufacturer_id=X model="Raspberry Pi 4 Model B"

Create if not exists.

For generic x86:

dcim_list_manufacturers name=<detected-manufacturer>

3.2 Create Device

dcim_create_device
  name=<hostname>
  device_type=<device_type_id>
  role=<role_id>
  site=<site_id>
  platform=<platform_id>
  tenant=<tenant_id>  # if provided
  serial=<serial>
  description="Registered via cmdb-assistant"

3.3 Create Interfaces

For each network interface discovered:

dcim_create_interface
  device=<device_id>
  name=<interface_name>  # eth0, wlan0, tailscale0, etc.
  type=<type>            # 1000base-t, virtual, other
  mac_address=<mac>
  enabled=true

Interface type mapping:

• eth*, enp* → 1000base-t
• wlan* → ieee802.11ax (or appropriate wifi type)
• tailscale*, docker*, br-* → virtual
• lo → skip (loopback)

3.4 Create IP Addresses

For each IP on each interface:

ipam_create_ip_address
  address=<ip/prefix>    # e.g., "192.168.1.100/24"
  assigned_object_type="dcim.interface"
  assigned_object_id=<interface_id>
  status="active"
  description="Discovered via cmdb-register"

3.5 Set Primary IP

Identify primary IP (interface with default route):

dcim_update_device
  id=<device_id>
  primary_ip4=<primary_ip_id>

Phase 4: Container Registration (via MCP)

If Docker containers were discovered:

4.1 Create/Get Cluster Type

virt_list_cluster_types name="Docker Compose"

Create if not exists:

virt_create_cluster_type name="Docker Compose" slug="docker-compose"

4.2 Create Cluster

For each Docker Compose project directory found:

virt_create_cluster
  name=<project-name>  # e.g., "apps-hotport"
  type=<cluster_type_id>
  site=<site_id>
  description="Docker Compose stack on <hostname>"

4.3 Create VMs for Containers

For each running container:

virt_create_vm
  name=<container_name>
  cluster=<cluster_id>
  site=<site_id>
  role=<role_id>        # Map container function to role
  status="active"
  vcpus=<cpu_shares>    # Default 1.0 if unknown
  memory=<memory_mb>    # Default 256 if unknown
  disk=<disk_gb>        # Default 5 if unknown
  description=<container purpose>
  comments=<image, ports, volumes info>

Container role mapping:

• *caddy*, *nginx*, *traefik* → "Reverse Proxy"
• *db*, *postgres*, *mysql*, *redis* → "Database"
• *webui*, *frontend* → "Web Application"
• Others → Infer from image name or use generic "Container"

Phase 5: Documentation

5.1 Add Journal Entry

extras_create_journal_entry
  assigned_object_type="dcim.device"
  assigned_object_id=<device_id>
  comments="Device registered via /cmdb-register command\n\nDiscovered:\n- X network interfaces\n- Y IP addresses\n- Z Docker containers"

Phase 6: Summary Report

Present registration summary:

## Machine Registration Complete

### Device Created
- **Name:** <hostname>
- **Site:** <site>
- **Platform:** <platform>
- **Role:** <role>
- **ID:** <device_id>
- **URL:** https://netbox.example.com/dcim/devices/<id>/

### Network Interfaces
| Interface | Type | MAC | IP Address |
|-----------|------|-----|------------|
| eth0 | 1000base-t | aa:bb:cc:dd:ee:ff | 192.168.1.100/24 |
| tailscale0 | virtual | - | 100.x.x.x/32 |

### Primary IP: 192.168.1.100

### Docker Containers Registered (if applicable)
**Cluster:** <cluster_name> (ID: <cluster_id>)

| Container | Role | vCPUs | Memory | Status |
|-----------|------|-------|--------|--------|
| media_jellyfin | Media Server | 2.0 | 2048MB | Active |
| media_sonarr | Media Management | 1.0 | 512MB | Active |

### Next Steps
- Run `/cmdb-sync` periodically to keep data current
- Run `/cmdb-audit` to check data quality
- Add tags for classification (env:*, team:*, etc.)

Error Handling

• Device already exists: Suggest /cmdb-sync or ask to proceed
• Site not found: List available sites, offer to create new
• Docker not available: Skip container registration, note in summary
• Permission denied: Note which operations failed, suggest fixes

User Request

$ARGUMENTS