Skip to content

Adding a Device

The add_device method provides a fully typed interface for adding devices to LibreNMS. It supports SNMP v1/v2c/v3 discovery, ICMP-only (ping) devices, and all optional configuration the LibreNMS API accepts.

Quick Start

from libreclient import LibreClient

client = LibreClient()

Default (Auto-detect SNMP)

When snmpver is not specified, LibreNMS uses its global configuration defaults and auto-detects the SNMP version during discovery.

# Let LibreNMS use its configured defaults
response = client.devices.add_device("10.0.0.1")

# With a display name
response = client.devices.add_device(
    "switch-core-01.example.com",
    display="{{ $sysName }}",
)

SNMP v1 / v2c

When using SNMP v1 or v2c, the community string is required.

response = client.devices.add_device(
    "10.0.0.1",
    snmpver="v2c",
    community="public",
)

response = client.devices.add_device(
    "10.0.0.1",
    snmpver="v1",
    community="public",
)

SNMP v3

When using SNMP v3, you must provide an SnmpV3Credentials instance via the snmp_v3 parameter.

from libreclient.models import SnmpV3Credentials

creds = SnmpV3Credentials(
    authlevel="authPriv",
    authname="snmpuser",
    authpass="authSecret123",
    authalgo="SHA",
    cryptopass="cryptoSecret456",
    cryptoalgo="AES",
)

response = client.devices.add_device(
    "10.0.0.1",
    snmpver="v3",
    snmp_v3=creds,
)

Auth Levels

Level Description Required Fields
noAuthNoPriv No authentication, no encryption —
authNoPriv Authentication only authname, authpass, authalgo
authPriv Authentication + encryption authname, authpass, authalgo, cryptopass, cryptoalgo

Supported Algorithms

  • Auth: MD5, SHA, SHA-224, SHA-256, SHA-384, SHA-512
  • Crypto: AES, AES-192, AES-256, AES-256-C, DES

ICMP Only (Disable SNMP)

For devices that don't support SNMP, set snmp_disable=True. You can optionally provide device metadata via the icmp_device parameter.

from libreclient.models import IcmpOnlyDevice

response = client.devices.add_device(
    "10.0.0.50",
    snmp_disable=True,
)

# With device metadata
icmp = IcmpOnlyDevice(
    os="linux",
    sys_name="web-server-01",
    hardware="x86_64",
)

response = client.devices.add_device(
    "10.0.0.50",
    snmp_disable=True,
    icmp_device=icmp,
)

Note

When snmp_disable=True and no icmp_device is provided, the device OS defaults to "ping".

Common Options

All examples above support these additional parameters:

response = client.devices.add_device(
    "10.0.0.1",
    snmpver="v2c",
    community="public",
    # Display name (supports templates)
    display="{{ $hostname }}",
    # SNMP connection settings
    port=161,
    transport="udp",  # udp, tcp, udp6, tcp6
    # Port identification method
    port_association_mode="ifIndex",  # ifIndex, ifName, ifDescr, ifAlias
    # Distributed polling
    poller_group=1,
    # Location (mutually exclusive — use one or the other)
    location="DC1 Row A Rack 5",
    # location_id=42,
    # Skip discovery checks
    force_add=True,
    # Fall back to ping if SNMP fails
    ping_fallback=True,
)
Parameter Type Default Description
display str hostname Display name. Templates: {{ $hostname }}, {{ $sysName }}, {{ $sysName_fallback }}, {{ $ip }}
port int config default SNMP port
transport str config default udp, tcp, udp6, tcp6
port_association_mode str ifIndex ifIndex, ifName, ifDescr, ifAlias
poller_group int 0 Poller group ID for distributed polling
force_add bool False Skip all checks, add directly (credentials required)
ping_fallback bool False Add as ping-only if SNMP fails
location str — Set location by text
location_id int — Set location by ID

Warning

You cannot specify both location and location_id — a ValueError will be raised. When either is set, override_sysLocation is automatically enabled.

API Reference

Add a new device.

Route: POST /api/v0/devices

Parameters:

Name Type Description Default
hostname str

Device hostname or IP address (required).

 required
display str | None

Display name for the device. Supports templates: {{ $hostname }}, {{ $sysName }}, {{ $sysName_fallback }}, {{ $ip }}. Defaults to hostname (or device_display_default setting).

 None
overwrite_ip str | None

Override hostname field and use this IP.

 None
snmpver SnmpVersion | None

SNMP version — 'v1', 'v2c', or 'v3'. Defaults to None to use the LibreNMS global config default.

 None
community str | None

SNMP community string. Required when snmpver is 'v1' or 'v2c'.

 None
snmp_v3 SnmpV3Credentials | None

SNMPv3 credentials. Required when snmpver is 'v3'. Use a :class:~libreclient.models.devices.SnmpV3Credentials instance to supply authlevel, authname, authpass, authalgo, cryptopass, and cryptoalgo.

 None
port int | None

SNMP port. Defaults to the port defined in LibreNMS config.

 None
transport SnmpTransport | None

SNMP transport protocol — 'udp', 'tcp', 'udp6', or 'tcp6'. Defaults to the transport defined in LibreNMS config.

 None
port_association_mode PortAssociationMode | None

Method to identify ports — 'ifIndex', 'ifName', 'ifDescr', or 'ifAlias'.

 None
poller_group int

Poller group ID for distributed polling. Defaults to 0.

 0
force_add bool

Skip all checks and add the device directly. SNMP credentials are required when using this option.

 False
ping_fallback bool

If SNMP checks fail, add the device as ping-only instead of failing.

 False
snmp_disable bool

If True, disable SNMP and use ICMP only.

 False
icmp_device IcmpOnlyDevice | None

Additional device info for ICMP-only mode. Use a :class:~libreclient.models.devices.IcmpOnlyDevice instance to supply os, sysName, and hardware. Only used when snmp_disable is True.

 None
location str | None

Set device location by text (mutually exclusive with location_id).

 None
location_id int | None

Set device location by ID (mutually exclusive with location).

 None

Raises:

Type Description
ValueError

If both location and location_id are provided, or if snmpver is v1/v2c without community, or v3 without snmp_v3.

handler: python options: show_root_heading: false show_source: false heading_level: 3

Bases: BaseModel

SNMPv3 authentication and encryption credentials.

Use this when adding a device with snmpver='v3'.

Example::

creds = SnmpV3Credentials(
    authlevel="authPriv",
    authname="myuser",
    authpass="secret",
    authalgo="SHA",
    cryptopass="encrypt_secret",
    cryptoalgo="AES",
)
client.devices.add_device("10.0.0.1", snmpver="v3", snmp_v3=creds)

authalgo = 'SHA' class-attribute instance-attribute

SNMP auth algorithm (MD5, SHA, SHA-224, SHA-256, SHA-384, SHA-512).

authlevel = 'noAuthNoPriv' class-attribute instance-attribute

SNMP auth level (noAuthNoPriv, authNoPriv, authPriv).

authname = None class-attribute instance-attribute

SNMP auth username. Required for authNoPriv and authPriv.

authpass = None class-attribute instance-attribute

SNMP auth password. Required for authNoPriv and authPriv.

cryptoalgo = 'AES' class-attribute instance-attribute

SNMP crypto algorithm (AES, AES-192, AES-256, AES-256-C, DES).

cryptopass = None class-attribute instance-attribute

SNMP crypto password. Required for authPriv.

handler: python options: show_root_heading: true show_source: false heading_level: 3

Bases: BaseModel

Additional fields for ICMP-only (snmp_disable) devices.

Use this when adding a device with snmp_disable=True.

Example::

icmp = IcmpOnlyDevice(os="linux", sys_name="myhost", hardware="x86_64")
client.devices.add_device("10.0.0.1", snmp_disable=True, icmp_device=icmp)

hardware = None class-attribute instance-attribute

Device hardware.

os = 'ping' class-attribute instance-attribute

OS short name for the device. Defaults to 'ping'.

sys_name = Field(default=None, alias='sysName') class-attribute instance-attribute

sysName for the device.

handler: python options: show_root_heading: true show_source: false heading_level: 3