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.

powershell $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.

```powershell $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.).

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

Step 4: Create the device

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

``powershell $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

```powershell

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).

powershell 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