netbox-extractor

A Crystal CLI that extracts data from Netbox to generate:

• Ansible inventories
• Icinga2 configuration files
• Bind DNS zone files

Installation

Get binary from releases page.

If you use mise, install it from the jbox-web aqua registry:

# mise.toml
[settings]
aqua.registries = ["https://github.com/jbox-web/aqua-registry"]

[tools]
"aqua:jbox-web/netbox-extractor" = "2.3.0"

The registry has to be declared: the tool is not in the default aqua registry, and without that setting the name resolves to nothing.

Usage

netbox-extractor <subcommand> <action> [flags...]

Common flags:

Examples:

# Generate Ansible + Icinga config for every configured site
netbox-extractor ansible generate
netbox-extractor icinga generate

# Restrict to one site, with an explicit config path
netbox-extractor icinga generate --site dc1 --config /etc/netbox-extractor.yml

Checking the configuration

config check reports what a generation run would quietly ignore, and writes nothing:

# Validate the file itself: schema, duplicate site ids, colliding or unsafe
# role filenames. Instant, no network, no token needed.
netbox-extractor config check

# Also match everything the config says against what Netbox holds: checks_config
# entries, include_objects/exclude_objects and roles designating no object,
# objects carrying no platform, and platform slugs the OS detection cannot
# classify unambiguously.
netbox-extractor config check --with-netbox

An include_objects/exclude_objects entry that matches no host is reported with the near miss when there is one, because the two cases call for opposite fixes — these filters match exactly, so an entry differing only in case or by a domain is not dead config, it is a filter that silently does nothing:

WARNING  [dc1] exclude_objects entry 'W2022' matches no host of this site, but 'w2022' does
         — the exclusion is not being applied, as these filters match exactly (config/dc1.yml)
WARNING  [dc1] exclude_objects entry 'mattermost' matches no host of this site (config/dc1.yml)

The first has to be corrected, the second deleted.

--with-netbox loads each site's inventories, so it costs as many API calls as a generation run — which is why it is not the default.

Exit status:

Warnings are things to clean up rather than breakage, so they do not fail a pipeline unless --strict says they should:

netbox-extractor config check --with-netbox --strict

Seeing the effective configuration

The file on disk is a template: it interpolates ENV, and it may pull whole sites in from sites_config:. config dump prints what the program actually ended up with — template rendered, external site files merged, defaults applied:

netbox-extractor config dump

# One site only
netbox-extractor config dump --site dc1

The output is valid YAML, so it can be piped into anything that reads YAML.

Secrets are redacted: api_token and every password come out as <redacted>. There is no flag to reveal them — the value would land on a terminal, in a redirected file, and in the log of whichever CI job ran the command. Read the config file itself if you need them.

Configuration

netbox-extractor is driven by a YAML config file (netbox-extractor.yml by default) plus an env file (.env) for secrets. See netbox-extractor.yml.example for a complete, loadable example.

• Netbox connection — netbox.hostname, netbox.port and netbox.api_token. The token is typically injected from the env file, e.g. api_token: "{{ ENV['NETBOX_TOKEN_API'] }}".
• Sites — declared inline under sites: or loaded from external files listed in sites_config:. Each site lists the Netbox device/vm roles to export and, for Icinga, the checks to generate.
• Filtering — objects can be included/excluded per site via include_objects and exclude_objects.
• Tag-driven behavior — the check-by-snmp tag forces SNMP monitoring, check-only-ping restricts a host to a ping check; OS detection is based on the Netbox platform slug.
• BMCs (iDRAC, iLO) — a BMC can be a device of role network-bmc, or the out-of-band IP (oob_ip) of the server it manages. The latter is rendered as the very same host, with the role network-bmc: named after the IP's DNS name, addressed and tagged by the IP, monitored while the IP is active, with the server's vendor and the name of the interface holding the IP as model and platform (iDrac9 → platform idrac9). An oob_ip without a DNS name, or not on an interface, yields no host and a warning. A name still held by a device is left to the device, so BMC devices can be moved to their servers one by one without a host being rendered twice. A DNS name designated by the oob_ip of two servers goes to the first one in Netbox's order, with a warning for the other.

Development

Tooling is managed with mise.

mise run dev:deps          # Install dependencies (shards install)
mise run dev:build         # Compile bin/netbox-extractor
mise run dev:spec          # Run tests
mise run dev:spec-mt       # Run tests multi-threaded
mise run dev:ameba         # Static analysis (ameba)
mise run dev:format        # Format code
mise run dev:format-check  # Check formatting without writing
mise run dev:docs          # Build API docs
bin/netbox-extractor

CI runs dev:format-check, dev:ameba, dev:docs, dev:spec and dev:spec-mt, so all five should pass before pushing.

Contributing

1. Fork it (https://github.com/your-github-user/netbox-extractor/fork)
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

Contributors

• Nicolas Rodriguez - creator and maintainer