Skip to content

Your first device

This 5-minute walk-through creates a complete device in NetBox: a site, a manufacturer, a device type, a role, and finally the device itself. We will then query, update, and clean it up.

Prerequisites

  • Module installed (see Installation)
  • Connected to a NetBox instance (see Connecting)
  • Token has write permission for DCIM objects

Step 1: Create a site

Devices live in sites. The -Name parameter is required; -Slug is optional and auto-generated by NetBox if omitted.

$site = New-NBDCIMSite -Name 'Demo DC'
$site.id   # Note this ID; we'll reference it below

Step 2: Create a manufacturer and device type

A device type is the hardware model. It belongs to a manufacturer. -Manufacturer takes the manufacturer's integer ID, not its name.

$mfg = New-NBDCIMManufacturer -Name 'Acme' -Slug 'acme'

$type = New-NBDCIMDeviceType `
    -Manufacturer $mfg.id `
    -Model 'AX-1000' `
    -Slug 'ax-1000' `
    -U_Height 1

Step 3: Create a device role

Roles classify devices (firewall, switch, server, etc.).

$role = New-NBDCIMDeviceRole -Name 'Firewall' -Slug 'firewall'

Step 4: Create the device

Now the device itself. The parameter is -Role (not -Device_Role).

$device = New-NBDCIMDevice `
    -Name 'fw-demo-01' `
    -Site $site.id `
    -Device_Type $type.id `
    -Role $role.id

$device | Format-List name, status, site, device_type, role

Step 5: Query and update

# Find it back by name
Get-NBDCIMDevice -Name 'fw-demo-01'

# Update the description
Set-NBDCIMDevice -Id $device.id -Description 'Demo firewall - safe to delete'

Step 6: Clean up

Delete in reverse-dependency order (device before the objects it references).

Remove-NBDCIMDevice     -Id $device.id -Confirm:$false
Remove-NBDCIMDeviceRole -Id $role.id   -Confirm:$false
Remove-NBDCIMDeviceType -Id $type.id   -Confirm:$false
Remove-NBDCIMManufacturer -Id $mfg.id  -Confirm:$false
Remove-NBDCIMSite       -Id $site.id   -Confirm:$false

Where to next

  • Common workflows - Bulk patterns and real-world examples
  • DCIM examples - More device, rack, and cable scenarios
  • Browse the reference - Start with Get-NBDCIMDevice, then explore neighbors
  • Use Get-Help <CmdletName> -Full for inline help on any of the ~500 cmdlets