salt.modules.netbox

NetBox

Module to query NetBox

codeauthor

Zach Moody <zmoody@do.co>

maturity

new

depends

pynetbox

The following config should be in the minion config file. In order to work with secrets you should provide a token and path to your private key file:

netbox:
  url: <NETBOX_URL>
  token: <NETBOX_USERNAME_API_TOKEN (OPTIONAL)>
  keyfile: </PATH/TO/NETBOX/KEY (OPTIONAL)>

New in version 2018.3.0.

salt.modules.netbox.create_circuit(name, provider_id, circuit_type, description=None)

New in version 2019.2.0.

Create a new Netbox circuit

name

Name of the circuit

provider_id

The netbox id of the circuit provider

circuit_type

The name of the circuit type

asn

The ASN of the circuit provider

description

The description of the circuit

CLI Example:

salt myminion netbox.create_circuit NEW_CIRCUIT_01 Telia Transit 1299 "New Telia circuit"
salt.modules.netbox.create_circuit_provider(name, asn=None)

New in version 2019.2.0.

Create a new Netbox circuit provider

name

The name of the circuit provider

asn

The ASN of the circuit provider

CLI Example:

salt myminion netbox.create_circuit_provider Telia 1299
salt.modules.netbox.create_circuit_termination(circuit, interface, device, speed, xconnect_id=None, term_side='A')

New in version 2019.2.0.

Terminate a circuit on an interface

circuit

The name of the circuit

interface

The name of the interface to terminate on

device

The name of the device the interface belongs to

speed

The speed of the circuit, in Kbps

xconnect_id

The cross-connect identifier

term_side

The side of the circuit termination

CLI Example:

salt myminion netbox.create_circuit_termination NEW_CIRCUIT_01 xe-0/0/1 myminion 10000 xconnect_id=XCON01
salt.modules.netbox.create_circuit_type(name)

New in version 2019.2.0.

Create a new Netbox circuit type.

name

The name of the circuit type

CLI Example:

salt myminion netbox.create_circuit_type Transit
salt.modules.netbox.create_device(name, role, model, manufacturer, site)

New in version 2019.2.0.

Create a new device with a name, role, model, manufacturer and site. All these components need to be already in Netbox.

name

The name of the device, e.g., edge_router

role

String of device role, e.g., router

model

String of device model, e.g., MX480

manufacturer

String of device manufacturer, e.g., Juniper

site

String of device site, e.g., BRU

CLI Example:

salt myminion netbox.create_device edge_router router MX480 Juniper BRU
salt.modules.netbox.create_device_role(role, color)

New in version 2019.2.0.

Create a device role

role

String of device role, e.g., router

CLI Example:

salt myminion netbox.create_device_role router
salt.modules.netbox.create_device_type(model, manufacturer)

New in version 2019.2.0.

Create a device type. If the manufacturer doesn't exist, create a new manufacturer.

model

String of device model, e.g., MX480

manufacturer

String of device manufacturer, e.g., Juniper

CLI Example:

salt myminion netbox.create_device_type MX480 Juniper
salt.modules.netbox.create_interface(device_name, interface_name, mac_address=None, description=None, enabled=None, lag=None, lag_parent=None, form_factor=None)

New in version 2019.2.0.

Attach an interface to a device. If not all arguments are provided, they will default to Netbox defaults.

device_name

The name of the device, e.g., edge_router

interface_name

The name of the interface, e.g., TenGigE0/0/0/0

mac_address

String of mac address, e.g., 50:87:89:73:92:C8

description

String of interface description, e.g., NTT

enabled

String of boolean interface status, e.g., True

lag:

Boolean of interface lag status, e.g., True

lag_parent

String of interface lag parent name, e.g., ae13

form_factor

Integer of form factor id, obtained through _choices API endpoint, e.g., 200

CLI Example:

salt myminion netbox.create_interface edge_router ae13 description="Core uplink"
salt.modules.netbox.create_interface_connection(interface_a, interface_b)

New in version 2019.2.0.

Create an interface connection between 2 interfaces

interface_a

Interface id for Side A

interface_b

Interface id for Side B

CLI Example:

salt myminion netbox.create_interface_connection 123 456
salt.modules.netbox.create_inventory_item(device_name, item_name, manufacturer_name=None, serial='', part_id='', description='')

New in version 2019.2.0.

Add an inventory item to an existing device.

device_name

The name of the device, e.g., edge_router.

item_name

String of inventory item name, e.g., Transceiver.

manufacturer_name

String of inventory item manufacturer, e.g., Fiberstore.

serial

String of inventory item serial, e.g., FS1238931.

part_id

String of inventory item part id, e.g., 740-01234.

description

String of inventory item description, e.g., SFP+-10G-LR.

CLI Example:

salt myminion netbox.create_inventory_item edge_router Transceiver part_id=740-01234
salt.modules.netbox.create_ipaddress(ip_address, family, device=None, interface=None)

New in version 2019.2.0.

Add an IP address, and optionally attach it to an interface.

ip_address

The IP address and CIDR, e.g., 192.168.1.1/24

family

Integer of IP family, e.g., 4

device

The name of the device to attach IP to, e.g., edge_router

interface

The name of the interface to attach IP to, e.g., ae13

CLI Example:

salt myminion netbox.create_ipaddress 192.168.1.1/24 4 device=edge_router interface=ae13
salt.modules.netbox.create_manufacturer(name)

New in version 2019.2.0.

Create a device manufacturer.

name

The name of the manufacturer, e.g., Juniper

CLI Example:

salt myminion netbox.create_manufacturer Juniper
salt.modules.netbox.create_platform(platform)

New in version 2019.2.0.

Create a new device platform

platform

String of device platform, e.g., junos

CLI Example:

salt myminion netbox.create_platform junos
salt.modules.netbox.create_site(site)

New in version 2019.2.0.

Create a new device site

site

String of device site, e.g., BRU

CLI Example:

salt myminion netbox.create_site BRU
salt.modules.netbox.delete_interface(device_name, interface_name)

New in version 2019.2.0.

Delete an interface from a device.

device_name

The name of the device, e.g., edge_router.

interface_name

The name of the interface, e.g., ae13

CLI Example:

salt myminion netbox.delete_interface edge_router ae13
salt.modules.netbox.delete_inventory_item(item_id)

New in version 2019.2.0.

Remove an item from a devices inventory. Identified by the netbox id

item_id

Integer of item to be deleted

CLI Example:

salt myminion netbox.delete_inventory_item 1354
salt.modules.netbox.delete_ipaddress(ipaddr_id)

New in version 2019.2.0.

Delete an IP address. IP addresses in Netbox are a combination of address and the interface it is assigned to.

id

The Netbox id for the IP address.

CLI Example:

salt myminion netbox.delete_ipaddress 9002
salt.modules.netbox.filter_(app, endpoint, **kwargs)

Get a list of items from NetBox.

app

String of netbox app, e.g., dcim, circuits, ipam

endpoint

String of app endpoint, e.g., sites, regions, devices

kwargs

Optional arguments that can be used to filter. All filter keywords are available in Netbox, which can be found by surfing to the corresponding API endpoint, and clicking Filters. e.g., role=router

Returns a list of dictionaries

salt myminion netbox.filter dcim devices status=1 role=router
salt.modules.netbox.get_(app, endpoint, id=None, **kwargs)

Get a single item from NetBox.

app

String of netbox app, e.g., dcim, circuits, ipam

endpoint

String of app endpoint, e.g., sites, regions, devices

Returns a single dictionary

To get an item based on ID.

salt myminion netbox.get dcim devices id=123

Or using named arguments that correspond with accepted filters on the NetBox endpoint.

salt myminion netbox.get dcim devices name=my-router
salt.modules.netbox.get_circuit_provider(name, asn=None)

New in version 2019.2.0.

Get a circuit provider with a given name and optional ASN.

name

The name of the circuit provider

asn

The ASN of the circuit provider

CLI Example:

salt myminion netbox.get_circuit_provider Telia 1299
salt.modules.netbox.get_interfaces(device_name=None, **kwargs)

New in version 2019.2.0.

Returns interfaces for a specific device using arbitrary netbox filters

device_name

The name of the device, e.g., edge_router

kwargs

Optional arguments to be used for filtering

CLI Example:

salt myminion netbox.get_interfaces edge_router name="et-0/0/5"
salt.modules.netbox.get_ipaddresses(device_name=None, **kwargs)

New in version 2019.2.0.

Filters for an IP address using specified filters

device_name

The name of the device to check for the IP address

kwargs

Optional arguments that can be used to filter, e.g., family=4

CLI Example:

salt myminion netbox.get_ipaddresses device_name family=4
salt.modules.netbox.make_interface_child(device_name, interface_name, parent_name)

New in version 2019.2.0.

Set an interface as part of a LAG.

device_name

The name of the device, e.g., edge_router.

interface_name

The name of the interface to be attached to LAG, e.g., xe-1/0/2.

parent_name

The name of the LAG interface, e.g., ae13.

CLI Example:

salt myminion netbox.make_interface_child xe-1/0/2 ae13
salt.modules.netbox.make_interface_lag(device_name, interface_name)

New in version 2019.2.0.

Update an interface to be a LAG.

device_name

The name of the device, e.g., edge_router.

interface_name

The name of the interface, e.g., ae13.

CLI Example:

salt myminion netbox.make_interface_lag edge_router ae13
salt.modules.netbox.openconfig_interfaces(device_name=None)

New in version 2019.2.0.

Return a dictionary structured as standardised in the openconfig-interfaces YANG model, containing physical and configuration data available in Netbox, e.g., IP addresses, MTU, enabled / disabled, etc.

device_name: None

The name of the device to query the interface data for. If not provided, will use the Minion ID.

CLI Example:

salt '*' netbox.openconfig_interfaces
salt '*' netbox.openconfig_interfaces device_name=cr1.thn.lon
salt.modules.netbox.openconfig_lacp(device_name=None)

New in version 2019.2.0.

Return a dictionary structured as standardised in the openconfig-lacp YANG model, with configuration data for Link Aggregation Control Protocol (LACP) for aggregate interfaces.

Note

The interval and lacp_mode keys have the values set as SLOW and ACTIVE respectively, as this data is not currently available in Netbox, therefore defaulting to the values defined in the standard. See interval and lacp-mode for further details.

device_name: None

The name of the device to query the LACP information for. If not provided, will use the Minion ID.

CLI Example:

salt '*' netbox.openconfig_lacp
salt '*' netbox.openconfig_lacp device_name=cr1.thn.lon
salt.modules.netbox.slugify(value)

' Slugify given value. Credit to Djangoproject https://docs.djangoproject.com/en/2.0/_modules/django/utils/text/#slugify

salt.modules.netbox.update_device(name, **kwargs)

New in version 2019.2.0.

Add attributes to an existing device, identified by name.

name

The name of the device, e.g., edge_router

kwargs

Arguments to change in device, e.g., serial=JN2932930

CLI Example:

salt myminion netbox.update_device edge_router serial=JN2932920
salt.modules.netbox.update_interface(device_name, interface_name, **kwargs)

New in version 2019.2.0.

Update an existing interface with new attributes.

device_name

The name of the device, e.g., edge_router

interface_name

The name of the interface, e.g., ae13

kwargs

Arguments to change in interface, e.g., mac_address=50:87:69:53:32:D0

CLI Example:

salt myminion netbox.update_interface edge_router ae13 mac_address=50:87:69:53:32:D0