Skip to content

Python classes and scripts to interact with Netbox (create, update, delete Netbox objects)

License

Notifications You must be signed in to change notification settings

allenrobel/netbox-tools

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

netbox-tools: Tools for Netbox operations

netbox-tools

This repo contains python classes and scripts that implement CRUD operations on Netbox using the excellent pynetbox library.

Below, you'll find a quick-start setup guide and listing of all the scripts and what they do.

News

Recent news about changes that may affect you.

2022-11-09 BREAKING CHANGE: Previously, some interface config was defined under the devices dictionary in the yaml file. We have moved all interface configuration under the interfaces dictionary, and changed the interface value in the devices dictionary to be a pointer to the interface configuration of the device's management interface. This broke the device and ip_address libraries and related scripts, so we've updated these as well. We also changed mgmt_ip, which was under devices, to ip4, which is now under interfaces to align with Netbox terminology. We've also changed (hopefully all) relevant script args to match.

2022-11-01 DEPRECATION: We've changed the keys token and url in the secrets file to netbox_token and netbox_url to align with other netbox repos we maintain which use netbox_token and netbox_url. You'll see a deprecation warning when using the older key names, but things will still work until 2023-11-01. Please change your keys when you get a free moment.

2022-10-08 BREAKING CHANGE: The library location has changed. Due to conflicts with libraries in other namespaces, we've moved the libraries under ./lib/netbox_tools/ and changed the imports to from netbox_tools.<library> import foo. We've also updated the Getting Started section of this README below with suggested PYTHONPATH addition.

2022-09-29 BREAKING CHANGE: The devices data structure has changed. Specifically, the name key was changed to device and the mgmt_interface key was changed to interface. We've added code to lib/netbox_tools/device.py, lib/netbox_tools/interface.py, lib/netbox_tools/ip_address.py that modifies these keys to the new names, and prints a deprecation warning for each. To avoid these warnings, update your YAML file(s). We've modified script args for a few scripts to use the new key names: device_create_update.py, device_create_with_ip.py, interface_create_update.py.

Getting started

To clone this repo

git clone https://github.com/allenrobel/netbox-tools.git

Dependencies

pynetbox

Install with:

pip install pynetbox

Ansible (we use ansible vault to store secrets)

Install with:

pip install ansible

Quick setup guide

netbox-tools uses a python script (netbox_config.py) to load a config file (config.yml) that currently just points your ansible vault file so that the various scripts in this repo have a standard way of finding and reading this file.

  1. Edit ./lib/netbox_tools/config/netbox_config.py

In this file, edit the line that starts with config_file and change config_file to point to config.yml (it's also located in lib/netbox_tools/config, but you can move it somewhere else if you'd like):

# EDIT THIS LINE TO POINT TO YOUR CONFIG FILE
config_file = '/home/myaccount/netbox-tools/lib/netbox_tools/config/config.yml'
  1. Edit ./lib/netbox_tools/config/config.yml

Among other things, config.yml points to your Ansible vault with the line below (in this case, it points to an Ansible vault file named secrets). Edit this to point to your Ansible vault file. If you don't have a vault file, we're going to create one in the next step. There are a couple other options in this file related to SSL certificates which we don't cover here, but which are described in the comments in this file. If you encounter any urllib3 errors related to SSL certificates, have a look here and play with these options.

vault: '/home/myaccount/netbox-tools/lib/netbox_tools/config/secrets'
  1. Create an Ansible vault file.

It is recommended (but not mandatory) that you encrypt your netbox token and url. The Ansible vault file can contain both of these in plaintext or as encrypted strings.

If you don't care about security, then the file need only contain, e.g.:

netbox_token: mytoken
netbox_url: https://mynetbox.foo.com

Where:

  • netbox_token comes from your Netbox installation. In netbox, go to the upper-right corner where there's a dropdown menu that usually says Admin but may contain your netbox username if you're logged in as someone other than Admin. Click that, and select API Tokens. Select one of the tokens on this screen, and replace mytoken with it.

  • netbox_url is the base url of your netbox installation, including the port number, if you're using a port other than 80 or 443. E.g.:

netbox_url: https://mynetbox.foo.com:8000

If you care about security, then you'll want to encrypt these. As follows (replacing /home/myaccount/netbox-tools/lib/netbox_tools/config/secrets, with the location you specified in step 2 above)

ansible-vault encrypt_string 'mytoken' --name 'netbox_token' >> /home/myaccount/netbox-tools/lib/netbox_tools/config/secrets
ansible-vault encrypt_string 'myurl' --name 'netbox_url' >> /home/myaccount/netbox-tools/lib/netbox_tools/config/secrets

If you encrypt these items, then ansible-vault will prompt you for a vault password. You'll use this password later when you run each of the scripts in this repo.

Example:

% ansible-vault encrypt_string '0123456789abcdef0123456789abcdef11133333' --name 'netbox_token' >> /home/myaccount/netbox-tools/lib/netbox_tools/config/secrets
New Vault password: 
Confirm New Vault password: 
% ansible-vault encrypt_string 'https://mynetbox.foo.com:8080' --name 'netbox_url' >> /home/myaccount/netbox-tools/lib/netbox_tools/config/secrets
New Vault password: 
Confirm New Vault password: 
% cat /home/myaccount/netbox-tools/lib/netbox_tools/config/secrets
netbox_token: !vault |
          $ANSIBLE_VAULT;1.1;AES256
          62653864393663336334643664356430633961633534396262353136643039363761323831393965
          6536353038326234656639646332363266356532326663660a333865323331633237393230646538
          34313266363631346263663331323065386539343661363637626464346563336437363539393361
          3738363662333638310a633163396266613836376135356236663132343737333465386632343938
          36333332323465346434346235393766643630366366316530383238313238396239396239646266
          6634323838313232616263353332356232626439323437313831
netbox_url: !vault |
          $ANSIBLE_VAULT;1.1;AES256
          31353832386139656434633734366635646631613839376537643263623139636133356161336632
          6564333230633730363237306564396138383165313834650a623361316337373631613763643531
          35383464636465613361616264663239373262626361626638396661353966393764323739663362
          3239323366376161630a616134353734313466376138333365383131303831626531373764323231
          62656663613739356362386530376330313663343030373165366461626165373232
  1. Append the path to this repo's lib directory to your PYTHONPATH, for example:

export PYTHONPATH=$PYTHONPATH:/home/myaccount/repos/netbox-tools/lib

  1. Copy netbox-tools/example.yml and edit it to include the information about your network environment.

There are example entries for sites, racks, locations, manufacturers, device types, devices, device roles, tags, etc.

Follow the comments in this file and create your first device. Then use the script below to add it to netbox (it adds all the other items as well):

./entity_create_update_all.py --yaml /path/to/your/edited.yml

If you encrypted netbox_token and netbox_url, you'll be asked for the ansible vault password you created in step 3 above.

Example:

% ./entity_create_update_all.py --yaml ../info.yml
Vault password: 
---
Site.update: mysite
---
Location.update: row-a
Location.update: row-b
Location.update: row-c
etc...

CAVEATS

Item Caveat
cable_create_update_all 2022-11-10 pynetbox issue 491 causes update not to work for cable.
                            For now, as a workaround, Cable.update() deletes the cable, then recreates it.  This is not ideal since the
                            cable id changes, which deletes any journal entries and change logs for the cable.

Scripts

The first script you should look at is:

Script Description
entity_create_update_all.py Creates all sites, locations, manufacturers, device types, devices, device roles, and tags. Pretty much the main script to get started.

Below is a complete list.

Script Description
cable_create_update_all See CAVEATS: Create/update all cables defined in --yaml
cable_create_update_one Create/update cable in Netbox with key --key in file --yaml
cable_delete_all Delete all cables defined in --yaml
cable_delete_one Delete cable from Netbox with key --key in file --yaml
cluster_create_update_all Create/update clusters defined in ``--yaml`
cluster_create_update_one Create/update cluster with key --key in file --yaml
cluster_type_create_update_all Create/update cluster_types defined in ``--yaml`
console_port_create_update_all Create/update all console ports defined in --yaml
console_port_delete Delete console_port from netbox, given --device --port
console_ports_print Display information about all console ports
console_server_port_create_update_all Create/update all console server ports defined in --yaml
console_server_port_create_update Create/update a console server port using command line options
console_server_port_delete Delete console_server_port --port from netbox
console_server_ports_print Display information about all console server ports
credentials_example Demonstrates usage for the netbox credentials library in this repo
device_assign_primary_ip.py Assign an ip address to a device and make this address the primary ip for the device
device_choices_print Display choices associated with Netbox endpoint dcim.devices
device_count Print the number of devices matching a given query
device_create_update_all Create/update all devices defined in --yaml
device_create_update_one Create/update device with key --key in file --yaml
device_print_filtered Print devices matching --location, --model, and --tags
device_print_mgmt_ip Print mgmt ip of --device. Can be used in bash scripts to e.g. ssh to devices.
device_type_create_update Create/update a device type using command line options
device_type_create_update_all Create/update all device types defined in --yaml
device_type_delete_all Delete all device types contained in the YAML file --yaml
device_type_delete Delete device_type --model from netbox
device_type_print Display information about a device type
device_types_print Display summary information about all device types
entity_create_update_all.py Create/update all Netbox entities (console server ports, device types, etc) defined in --yaml
interface_create_update Create/update an interface using command line options
interface_create_update_all Create/update all interfaces defined in --yaml
interface_delete Delete interface --interface from netbox
interface_print Display interface information for --device ``--interface`
interfaces_print Display information about all interfaces
ip_choices_print Display choices associated with endpoint ipam.ip_addresses
ip_address_create_update_all Create/update all ip addresses defined in --yaml
ip_address_delete Delete an ip address using command line options --ip
ip_prefix_create_update_all Create/update all ip prefixes defined in --yaml
ip_prefix_create_update Create/update an ip prefix using command line options
ip_prefix_delete Delete ip prefix --prefix from netbox
ipam_addresses_print Display all ip addresses
ipam_prefixes_print Display all ip prefixes
location_create_update_all Create/update locations defined in --yaml.
location_delete_all Delete all locations defined in --yaml
location_delete Delete location --location from netbox
manufacturer_create_update_all Create/update all manufacturers defined in --yaml
manufacturer_create_update Create/update manufacturer --manufacturer
manufacturer_delete Delete manufacturer --manufacturer
rack_create_update_all Create/update all racks defined in --yaml
rack_create_update Create/update using command line options --comments, --location, --rack, --site, --tags, --u_height
rack_delete Delete rack --rack
rack_print Display information about --rack
racks_print Display information about all racks
role_create_update_all Create/update all device roles defined in --yaml
role_create_update Create/update device role using command line options --color, --description, --role, --tags
role_delete Delete role --role
role_print Display information about device role --role
roles_print Display information about all device roles
site_create_update_all Create/update all sites defined in --yaml
site_delete Delete site --site
site_print Display information about --site
sites_print Display information about all sites
tag_create_update_all Create/update all tags defined in --yaml
tag_delete Delete tag --tag
tags_print Display information about all tags
virtual_ip_address_create_update_all Create/update all virtual_ip_addresses (those belonging to virtual machines) defined in --yaml
virtual_ip_address_delete_all Delete all virtual_ip_addresses (those belonging to virtual machines) defined in --yaml
virtual_machine_create_update_all Create/update virtual_machines defined in --yaml
virtual_machine_create_update_one Create/update virtual_machine with key --key in file --yaml
vlan_create_update_all Create/update all vlans defined in --yaml
vlan_delete Delete vlan --vlan
vlan_group_create_update_all Create/update all vlan_groups defined in --yaml
vlan_group_create_update Create/update a vlan_group with command line options --description, --max_vid, --min_vid, --tags, --vlan_group
vlan_group_delete Delete vlan_group --vlan_group
vlan_group_print Display information about vlan_group --vlan_group

Code of Conduct

This repository follows the Contributor Covenant Code of Conduct. Please read and familiarize yourself with this document.

Licensing

GNU General Public License v3.0 or later.

See LICENSE for full text.

About

Python classes and scripts to interact with Netbox (create, update, delete Netbox objects)

Topics

Resources

License

Code of conduct

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published