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

Visual Output

When executing this command, display the plugin header:

┌──────────────────────────────────────────────────────────────────┐
│  🖥️ CMDB-ASSISTANT · Machine Registration                        │
└──────────────────────────────────────────────────────────────────┘

Then proceed with the 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