Auto-Inventory

Overview

The ARROW auto-inventory system automatically collects hardware information from devices during PXE boot. This enables streamlined device onboarding, accurate hardware tracking, and efficient device-to-request matching.

How Auto-Inventory Works

When a device boots via PXE (network boot), the inventory system:

1. MAC Check: Device queries if inventory collection is needed
2. Boot Decision: System directs device to inventory or imaging
3. Collection: Inventory image gathers hardware details
4. Submission: Hardware data sent to ARROW backend
5. Record Creation: Device record created or updated in database

sequenceDiagram
    participant Device
    participant PXE as PXE Server
    participant Backend
    participant Database

    Device->>PXE: Boot via Network
    PXE->>Backend: Check MAC Address
    Backend->>Database: Find Pending Requests
    Database-->>Backend: Needs Inventory
    Backend-->>PXE: Inventory Required

    PXE->>Device: Boot Inventory Image
    Device->>Device: Collect Hardware Info
    Device->>Backend: Submit Inventory Data
    Backend->>Database: Create/Update Device Record
    Backend->>Database: Match Device Spec
    Backend->>Database: Update Imaging Status
    Backend-->>Device: Inventory Complete

    Device->>Device: Reboot to Imaging

Authentication

All auto-inventory API endpoints require authentication via the X-Service-Api-Key header. This header must contain the value configured in the DEVICE_LOOKUP_API_KEY environment variable on the backend.

Required Header

X-Service-Api-Key: <your-device-lookup-api-key>

The following endpoints require this authentication:

• POST /api/inventory/check-mac
• POST /api/inventory/submit
• POST /api/inventory/update-status

If the header is missing or invalid, the API will return a 400 Bad Request or 401 Unauthorized error.

MAC Address Check

Before inventory collection, devices check if they need to report hardware information.

Check Process

The PXE environment queries the ARROW backend with the device’s MAC address:

POST /api/inventory/check-mac
Content-Type: application/json
X-Service-Api-Key: <your-device-lookup-api-key>

{
  "mac_address": "00:e0:4c:92:f7:a4"
}

Response Values

Field	Type	Description
needs_inventory	boolean	Whether device should collect inventory
device_id	string	Existing device ID if found
organization	string	Target organization for the device

When Inventory Is Required

The system requests inventory collection when:

• Device MAC is associated with a pending device request
• Device was manually added and flagged for inventory
• Device record exists but hardware details are incomplete

Inventory Data Collection

The inventory image collects comprehensive hardware information from the device.

Collected Data Fields

Field	Description	Example
mac_address	Array of interface:MAC pairs	["eth0:00:e0:4c:92:f7:a4", "wlo1:08:bf:b8:c0:c5:83"]
device_name	Generated device hostname	PVE-1234
serial_number	Hardware serial number	ABC123XYZ
device_spec	Device specification name	Intel NUC 11 Pro
has_modem	Cellular modem present	true
imei	Modem IMEI number	123456789012345
hardware_generated_sn	Serial from hardware	true
sn_source	Source of serial number	dmidecode, bios, chassis

MAC Address Format

MAC addresses are collected in interface:MAC format to identify the network interface:

• eth0:00:e0:4c:92:f7:a4 - Primary Ethernet
• wlo1:08:bf:b8:c0:c5:83 - WiFi interface
• wwan0:00:1e:10:1f:00:00 - Cellular modem

Serial Number Sources

The system attempts to retrieve serial numbers from multiple sources in priority order:

1. DMI/SMBIOS: Most reliable for OEM systems
2. BIOS: Fallback for older systems
3. Chassis: Alternative location for some hardware

The sn_source field indicates which method was successful.

Inventory Submission

After collection, hardware data is submitted to the ARROW backend.

Submission Process

POST /api/inventory/submit
Content-Type: application/json
X-Service-Api-Key: <your-device-lookup-api-key>

{
  "inventory_data": {
    "mac_address": ["eth0:00:e0:4c:92:f7:a4", "wlo1:08:bf:b8:c0:c5:83"],
    "device_name": "PVE-1234",
    "serial_number": "ABC123XYZ",
    "device_spec": "Intel NUC 11 Pro",
    "has_modem": true,
    "imei": "123456789012345",
    "hardware_generated_sn": true,
    "sn_source": "dmidecode"
  }
}

Record Creation/Update

Based on the submission, the system:

1. New Device: Creates device record with inventory status newly_inventoried
2. Existing Device: Updates record with status updated_via_inventory
3. Device Spec Matching: Attempts to match device specification by name
4. Organization Assignment: Associates device with pending request organization

Inventory Status Values

Status	Description
newly_inventoried	Device record created via auto-inventory
updated_via_inventory	Existing record updated with new inventory data
manually_added	Device added manually through portal

Quick MAC Inventory

For scenarios where devices need to be pre-registered before PXE boot, the portal provides a Quick MAC Inventory feature.

Adding Devices by MAC

1. Navigate to the inventory management section
2. Enter the device MAC address
3. Specify the target organization
4. Device is flagged for auto-inventory on next PXE boot

Duplicate Detection

The system prevents duplicate MAC addresses:

• MAC addresses are normalized (lowercase, colon-separated)
• Existing device records are checked before creation
• Warning displayed if MAC already exists in system

Manual Entry Workflow

Manually added devices follow a modified inventory flow:

1. Manual Entry: Device created with manually_added status
2. PXE Boot: Device boots and checks MAC address
3. Inventory Collection: System requests full inventory
4. Status Update: Changes to updated_via_inventory

Inventory Status Management

Administrators can update inventory status to track device processing.

Status Update Values

Status	Meaning
processed	Inventory reviewed and verified
assigned	Device assigned to a request
reviewed	Manual review completed

Bulk Status Updates

Multiple devices can have their status updated simultaneously for efficient inventory management.

POST /api/inventory/update-status
Content-Type: application/json
X-Service-Api-Key: <your-device-lookup-api-key>

{
  "device_ids": ["device_id_1", "device_id_2"],
  "new_status": "processed"
}

Device Spec Matching

During inventory submission, the system attempts to match the reported device specification with known configurations.

Matching Process

1. Device reports device_spec field (e.g., “Intel NUC 11 Pro”)
2. System searches for matching specification by name
3. If found, device is linked to the specification
4. If not found, device is created without spec association

Benefits of Spec Matching

• Accurate hardware capability tracking
• Automated VM template selection
• Consistent configuration across similar devices

Troubleshooting

Device Not Found During MAC Check

Symptom: PXE boot doesn’t trigger inventory collection

Solutions:

• Verify MAC address format (colon-separated, lowercase)
• Check that a pending device request exists
• Ensure the MAC address matches the request’s target device
• Verify network connectivity to ARROW backend

Inventory Submission Failures

Symptom: Inventory collection completes but record not created

Solutions:

• Verify service API key authentication is configured
• Check that all required fields are populated
• Review backend logs for validation errors
• Ensure device specification name matches an existing spec

Duplicate MAC Address Errors

Symptom: Cannot add device, MAC already exists

Solutions:

• Search for existing device with the MAC address
• If device exists, verify it’s the correct record
• Contact support if duplicate needs resolution
• Check for MAC address format inconsistencies

Serial Number Not Detected

Symptom: Device created without serial number

Solutions:

• Some hardware doesn’t expose serial via standard methods
• Check BIOS settings for serial number configuration
• Manual serial entry may be required for older hardware
• Contact device manufacturer for serial location

Related Documentation

• Device Management - Complete device lifecycle management
• Device Shipments - Shipping and tracking workflows
• Device Requests - Creating and managing device requests