Nazara is an experimental Rust program that automates the collection of system information for NetBox, using NetBox's API. It enables the automatic creation of new machines in NetBox or population of information fields for existing ones.
Nazara is in the early stages of its development. Please note that the information listed below is subject to change.
Note
Nazara is currently in a beta state. Bugs are bound to happen. If you encounter any, please report them.
Furthermore, Nazara currently does not support custom fields for any NetBox object. Though, this is the next item on our agenda.
We strive to make sure to stay compatible with the most recent NetBox version. Here you can see which version of Nazara is compatible with which version of NetBox. When major ports to newer NetBox versions happen - which usually include breaking changes - the old version of Nazara will be moved to its own branch and tagged accordingly.
| Nazara Version | NetBox Version | Branch | maintained? |
|---|---|---|---|
v0.1.0_beta.2 |
v4.3.x |
main |
✅ |
v0.1.0_beta.1 |
v4.3.x |
version/beta-1 |
❌ |
v0.1.0_alpha.2 |
v3.6.x |
version/alpha-2 |
❌ |
Maintenance work on these older versions is not planned.
To use Nazara, you will need to have the Rust programming language and cargo installed. If you do not have them
installed already, you can follow the instructions provided in the official Rust documentation.
Please note that this program only works on Linux systems.
Once you have everything installed, you can clone this repository and build the program by running the following commands:
git clone https://github.com/The-Nazara-Project/Nazara.git
cd Nazara
cargo build --releaseThis will create an executable file in the target/release directory.
Important
Running Nazara stock will cause it to use our NetBox API reference client library thanix_client.
This client was generated from the API spec of a stock NetBox instance (1.x from NetBox v3.6.9 and 2.x from NetBox 4.1.0).
If you encounter API request issues with your NetBox instance, you may need to generate your own using Thanix.
Nazara is published on crates.io. If your operating system permits cargo to install packages globally, simply run cargo install nazara to install it.
To use Nazara, you will need to configure the URL of your NetBox API and provide an API token to the program by configuring all of these parameters inside the configuration file.
After that, simply run
sudo nazarain your terminal. Nazara will automatically collect all required system information and decide whether to create a new device, or update an existing entry.
Nazara supports two ways of providing configuration parameters: CLI arguments and a configuration file.
Nazara accepts these parameters from you:
-d, --dry-run: Print all collected information without committing it to NetBox.-u, --uri <URI>: URI to your NetBox instance.-t, --token <TOKEN>: Your API authentication token.-p, --plugin <PLUGIN>: The path to a plugin script you want to use to fill in custom fields.-h, --help: Print help.-V, --version: Print version.
Here is an example for passing these parameters on using the CLI:
sudo nazara --uri <API_URL> --token <API_TOKEN> --name test_deviceWhen launching Nazara for the first time, a configuration file will be written at $HOME/.config/nazara/config.toml. If you pass CLI parameters, these will be automatically
transfered into the config file as well.
Nazara's configuration must be located in the root user's home directory at $HOME/.config/nazara/config.toml.
When launching Nazara for the first time, it will write a stock config file to that path. Certain parameters are required to be configured there manually. You recognize them by their line not being commented out.
Aside from the NetBox system parameters, configurationvia theconfig.tomlalso allows you to add certain custom fields to your system information that cannot be automatically selected. A great example would be theSystem Locationentry. To specify that, simply add the parameter under the[system]` block in your configuration file.
Note
Currently, configuration by config file is the proper way to use Nazara given the amount of data required to register a machine. We are investigating possibilities to make this less of a hassle. In the meantime, we suggest you copy-paste the config between machines of the same type and function.
For an example config, check out src/configuration/config_template.toml
Please note that the following section is still a work in progress and all information is subject to change.
Users are able to fill custom_fields parameters in their NetBox objects using custom bash scripts.
These scripts should be placed inside the $HOME/.config/nazara/scripts/ directory.
These scripts can collect the desired information and output a valid JSON representation to stdout.
Nazara then reads this output, validates it, and attempts to parse it to a HashMap of values.
If everything works out, this will populate all of your custom fields no matter what fields you specified, as long as your script is correct.
Warning
Users must make sure that the output of their scripts matches the name of their desired custom fields they specified in NetBox.
Currently, we only support text fields as all the other field types would require smart parsing on our end. We are currently investigating on how to achieve this.
If you would like to contribute to Nazara, feel free to check the contributing guide for information on our workflow and check the issues section for any open issue.
Nazara is released under the terms of the GPL-v3.0.
By submitting a contribution to The Nazara Project, you agree that your contribution shall be licensed under the same license(s) as the project at the time of contribution.
You also grant the project maintainers the right to relicense the project, including your contribution, under any future version of those license(s), or under any other license that is free and open source software (FOSS) and compatible with the current license(s).