Skip to main content

nbtools

Collection of nblint and nbsync tools to operate on NetBox — the networking source of truth.

nblint has these linting commands:

Check

Description

unassigned-ips

Find IP addresses that sit on no interface.

empty-prefixes

Find prefixes that hold nothing: no address and no smaller prefix inside them.

duplicate-prefixes

Find prefixes that exist in more than one VRF.

duplicate-ips

Find IP addresses that exist in more than one VRF.

unparented-ips

Find IP addresses that no prefix of a sensible size covers.

duplicate-macs

Find MAC addresses that exist more than once.

device-bmcs

Find machines whose management controller cannot be reached.

subinterface-parents

Find numeric subinterfaces whose parent is not the interface their name names.

subinterface-labels

Find numeric subinterfaces whose label does not spell out their VRF.

interface-types

Find interfaces whose name says what type they are, but whose type does not.

unpaired-interface-tags

Find interfaces carrying a link tag that the far end of their cable does not.

interface-vlans

Find tagged interfaces whose 802.1Q mode and VLANs do not agree.

unattached-cables

Find physical cables that do not have both ends attached.

unattached-interfaces

Find interfaces that no cable is plugged into; the other half of unattached-cables.

discovered-items

List the devices and virtual machines that auto-discovery filed under “Discovery”.

tenant-names

Find tenants and tenant-groups whose name is not slug-style.

If you run nblint without a command, it will run all of them.

nbsync has these update commands:

Command

Description

clone-interface

Clone interface with subinterfaces from source to target.

migrate-gateway

Migrate a VM by moving the connected gateway IPs.

migrate-interface

Migrate properties of an interface from source to target.

set-interface-ip

Set IP on an interface.

set-interface-ip-by-mac

Set IP on the interface holding a MAC address.

set-interface-type

Set the type of interfaces, e.g. to bridge.

unset-interface-mac

Remove MAC addresses from an interface.

zap-interface

Zap (clean/wipe) properties from an interface.

swap-cables

Swap two connected cables.

Running an nbsync WITHOUT –batch is safe: it does nothing until you accept the change.

Exit codes: 0 clean, 1 nblint finding, 2 startup/usage error, 3 NetBox/state error.

Examples

For example, you can find empty prefixes in NetBox using nblint:

$ nblint empty-prefixes
--------------
empty-prefixes
--------------
- 10.7.7.0/24 #133 status=active vrf=DOSTNO_DAN
- 10.103.0.0/24 #1 status=active vrf=MGMT

Or cables that are only partially attached:

$ nblint unattached-cables
-----------------
unattached-cables
-----------------
- cable #227 status=connected a=<none> b=switch2:swp54s2

And you use one of the nbsync commands to perform actions that require lots of manual clicking in the NetBox web interface.

For instance, if you’ve noticed you got two cables mixed up:

$ nbsync -C dostno swap-cables pve3:enmlx0 pve3:enmlx1
-----------
swap-cables
-----------
- pve3:enmlx0 cable #187 set b_terminations=[]
- pve3:enmlx1 cable #182 set b_terminations=[{'object_type': 'dcim.interface', 'object_id': 177}]
- pve3:enmlx0 cable #187 set b_terminations=[{'object_type': 'dcim.interface', 'object_id': 178}]
Type 'yes' to continue: yes

Install

$ pipx install git+https://github.com/ossobv/nbtools.git@main

$ cat >~/.config/nbtools.ini <<EOF
[mynetbox]
api_url = https://netbox.example.com/api
api_token = 17801aeb9ce93006bea477e41e70ad5d53219919
EOF

$ source <(nblint completion bash)

$ source <(nbsync completion bash)

$ nblint --help
...

nblint vs nbsync?

The nbtools suite contains two commands: nblint and nbsync. nblint should be able to work with readonly tokens and is focused on finding things. nbsync needs write tokens, and is used for deliberate changes.

The two meet through the --porcelain argument and xargs (or stdin). nblint arguments can be passed to nbsync via the command line.

Arguments or stdin

Assume there is an application that dumps MAC and IP combinations, that can be tailed/followed:

$ feed-mac-and-ips
11:22:33:44:55:66 10.20.30.4/24
77:88:99:aa:bb:cc 10.20.30.17/24
...

You could use this, as individual calls:

$ feed-mac-and-ips | while read mac ip; do
    nbsync --batch set-interface-ip-by-mac $mac $ip
  done

Or, you could pass them through stdin:

$ feed-mac-and-ips |
    nbsync --batch --keep-going set-interface-ip-by-mac - -

That way, we only need to start nbsync once. The drawback of --keep-going is that you don’t get a clean exit code when there are issues with the input or NetBox, but sometimes that isn’t a problem.

Development

See the Makefile for basic dev setup.

DHCP example

Automatic updates from ISC dhcpd to NetBox:

[Unit]
Description=Write dhcp ACKs to netbox
Requires=isc-dhcp-server.service
After=isc-dhcp-server.service
ConditionPathExists=/etc/default/isc-dhcp-server-to-netbox
StartLimitIntervalSec=900
StartLimitBurst=90

[Service]
EnvironmentFile=/etc/default/isc-dhcp-server-to-netbox
ExecStartPre=/bin/test -n "${DHCP_RANGE}"
ExecStartPre=/bin/test -n "${DHCP_VRF}"
ExecStart=/bin/sh -c 'journalctl -f -u isc-dhcp-server.service -n 0 -o cat --grep ^DHCPACK | ipgrep --line-buffered "${DHCP_RANGE}" | sed --unbuffered -Ee "s@^DHCPACK on ([^ ]*) to ([^ ]*) .*@\\2 \\1/24@" | nbsync --batch set-interface-ip-by-mac - - --vrf="${DHCP_VRF}" --status=dhcp --single --force'
SyslogIdentifier=isc-dhcp-server-to-netbox
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

Metadata

Release files for netbox-tools 1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for netbox-tools 1.1
File Size Uploaded Provenance Actions
netbox_tools-1.1.tar.gz 168.3 kB Without provenance Details for netbox_tools-1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for netbox-tools 1.1
File Interpreter ABI Platform Actions
netbox_tools-1.1-py3-none-any.whl Python 3 none any Details for netbox_tools-1.1-py3-none-any.whl

Total release size: 268.6 kB

Release files / netbox_tools-1.1.tar.gz

Download URL netbox_tools-1.1.tar.gz
Size 168.3 kB
Tags Source
SHA-256 checksum
How to use checksums
ca4bcd07dea0d56714856a993ff1d545da5b0064e6a49dc106205feff393316c
BLAKE2b-256 checksum
How to use checksums
800762f69394e6893151a5d625a6f6f58c12eea481fdc4f6bea8280e1a54b268
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.10.12

Release files / netbox_tools-1.1-py3-none-any.whl

Download URL netbox_tools-1.1-py3-none-any.whl
Size 100.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
bb3275a5ad08edffe7746463caeb8ad62a39bbbd4b69aac3612d35600ad06f5c
BLAKE2b-256 checksum
How to use checksums
506d158624e77898862744dcf913be2748c24e48450551839dac30d363895002
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.10.12

Security for netbox-tools 1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page