Welcome to Nazara's documentation hub!

Nazara is a Rust tool used to automate the registration and update process of machines and VMs in the IPAM tool NetBox.

Compatibility

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 (and if we still support it). When major ports to new versions of NetBox happen - which usually includes breaking changes - the old version of Nazara will be moved to its own branch and tagged accordingly.

Maintenance work on these older versions is not planned currently.

Distribution Channels

This is an overview of channels through which you can get Nazara.

For information about who maintains a package you are looking for, try looking into the PACKAGERS.md file in our project's root directory.

Design Documentation

Here you can find all documentation relating to Nazara's structure, architecture and style.

• Architecture Guide
• Code Style

Nazara Architecture Guide

Introduction

This document explains the structure and architecture chosen for Nazara and gives an overview over its components.

Nazara is a tool for automating the registration and update process of physical machines and virtual machines in NetBox, a open-source IPAM tool.

Ease of use is important in this regard, users should be able to pick Nazara up quickly, and be able to comfortably integrate it into their daily workflow. With automation if they wish.

Nazara, very roughly, has 3 main functions: Collection, Translation and Publishing. (Excluding the configuration module here)

The Collection module is soley responsible for collecting information about the host system the user wants to register. This includes things like the device's network interfaces, IP addresses and other hardware information. All collected from the DMI tables.

The Translator module handles data process and translates all information that the collector has collected into appropriate API payload objects. These objects are defined by the NetBox API and brought to Nazara via the thanix_client crate. This crate is generated automatically by us and serves as the API client library used for making API requests to NetBox.

The Publisher module is the most "superior" module hierarchially. It handles the whole registration process and decided when which translation needs to be made and which API call to be sent.

Goals

Now, what problem does Nazara solve?

Some system administrators have a overwhelming number of machines. Or maybe they get sent upgrades to prototype hardware multiple times a year. When dealing with this large amount of machine turnover, Nazara provides an easy to use tool to eliminate the tedious task of manually registering or updating device or VM information.

What are the essential features and goals for Nazara?

• Ease of use
• Registration of machines and VMs and their associated components
• Automatization of custom field collection

Non-Goals

Nazara is simply a tool to register/update machines and VMs in NetBox. Beyond that it is currently not planned to have any other kind of managing role alongside NetBox or other IPAM tools.

Design

Nazara - codewise - is supposed to be highly modular and respect strict separation of concerns. This means that one logical unit does only one thing and contain all the logic necessary to achieve their goal.

This starts with modules: The Collector, Configuration, Translator and Publisher modules all only have one responsibility.
We believe that - wherever sensible and possible - each module, each file and each function should have one responsibility. For a new additional feature we would rather introduce another module that handles that responsibility than break this principle.

In addition to this all interfaces between modules should be as small as possible. Preferably one or two functions. This makes it easier to mentally follow the execution flow and avoids any kind of cross referencing or massive rewrites once a single module needs to be rewritten.

This philosophy should also extend to Nazara's Git-History. You can find more on that in the Contributor Guide.

High-Level-Design

As mentioned before, Nazara is designed with strict separation of concerns in mind. The following is a very high-level overview of Nazara's four logical parts:

• The Collectors
• The Configuration Package
• The Publisher
• The Main module

It also shows the two modules of our thanix_client crate, which we created specifically for sending API requests to NetBox. More on that later.

The following diagram gives an overview over the program flow once started by a user. Note that the exact function calls within translator.rs and the difference between POST/PATCH requests has been omitted for simplicity.

In reality, the publisher checks if the device has already been registered. The easiest way to do this would be to pass the ID the device or VM has in NetBox, however we are capable of searching given several parameters like serial number or UUID. Though these methods are less reliable.

In any way, the publisher then decides whether a POST or PATCH request shall be made.

Nazara Code Style Guide

General Guide

In regards to formatting, we follow the current Rust code style set by the Cargo formatter (cargo fmt).

The easiest way to enforce this, is using pre-commit to automatically format and check any code before it is committed.

Panics

We heavily discourage the use of the panic!() macro when aborting the process. Instead, we prefer to handle an error and abort gracefully with a helpful error message and error code.

We only want to panic, when the issue we encounter is both catastrophic and unfixable by the user.

Instead of panicking, we write custom error types to wrap errors of certain functions and include a well formatted error message alongside the error. For an exampel on how that looks, please check and of the error.rs files found in any of Nazara's packages.

#![allow(unused)]
fn main() {
//! This module provides error types for the config parser.

use std::io::Error as IoError;
use std::{error::Error, fmt};
use toml::{de::Error as TomlDeError, ser::Error as TomlSeError};

/// All errors the config parser can encounter.
#[derive(Debug)]
pub enum ConfigError {
    /// Used for handling errors during file operations.
    FileOpError(IoError),
    /// Indicates that no config file has been found, or it has been moved or deleted during program startup.
    NoConfigFileError(String),
    /// Indicates that a required config option is missing from the config file.
    MissingConfigOptionError(String),
    /// Indicates an error during deserialization of the TOML config file.
    DeserializationError(TomlDeError),
    /// Indicates an error during Serialization of config parameters to a TOML value.
    SerializationError(TomlSeError),
    /// Expects a `String` message. Used for edge cases and general purpose error cases.
    Other(String),
}

impl fmt::Display for ConfigError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            ConfigError::FileOpError(err) => {
                write!(f, "\x1b[31m[error]\x1b[0m File operation failed: {err}")
            }
            ConfigError::NoConfigFileError(err) => {
                write!(f, "\x1b[31m[error]\x1b[0m No config file found: {err}")
            }
            ConfigError::MissingConfigOptionError(err) => {
                write!(
                    f,
                    "\x1b[31m[error]\x1b[0m Missing required config parameter: {err}"
                )
            }
            ConfigError::DeserializationError(err) => {
                write!(f, "\x1b[31m[error]\x1b[0m Invalid config file: {err}")
            }
            ConfigError::SerializationError(err) => {
                write!(f, "\x1b[31m[error]\x1b[0m Serialization error: {err}")
            }
            ConfigError::Other(err) => {
                write!(f, "\x1b[31m[error]\x1b[0m Config Parser error: {err}")
            }
        }
    }
}

impl Error for ConfigError {
    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
        match self {
            ConfigError::FileOpError(err) => Some(err),
            ConfigError::NoConfigFileError(_) => None,
            ConfigError::MissingConfigOptionError(_) => None,
            ConfigError::DeserializationError(err) => Some(err),
            ConfigError::SerializationError(err) => Some(err),
            ConfigError::Other(_) => None,
        }
    }
}
}

Focus on Readability

When writing code, we value readability above complexity.

Rust offers a lot of possibilities when it comes to reducing code down into a one-line statement. And that's nice, and sometimes even necessary.

However, we want to take a readability first approach with our codebase. Both to aid maintainability and increase accessibility for newcomers.

Of course, sometimes using Rust's more "advanced" features will drastically improve performance. So a balance has to be struck between readability and performance. It is very hard to define a solid policy for this, so this is a decision every developer and contributor has to do for themselves and - when necessary - engage in discussion with maintainers, devs and other contributors about their approach and possible alternatives.

Documenting Code

For a smilar reason, we encourage devs to properly document their contributions. This includes but is not limited to:

• Using inline comments to explain possibly hard to understand syntax
• Using Rust's powerful docstring feature to properly document functions, structs and modules
• Adding to this documentation when applicable
• Filling out Issue and PR templates appropriately to aid maintainers review their changes

The following examples will show you an ideal docstring style.

#![allow(unused)]
fn main() {
/// This function does X.
///
/// This function does X by doing Y using Z. (Detailed explanation optional)
///
/// # Parameters
/// * `arg: str` - A string argument to process
///
/// # Returns
/// * `Ok(str)` - Returns A, if ...
/// * `Err` - Returns an `ErrType`
pub fn foo(arg: str) -> Result<str, Err> {
 // ...
}
}

#![allow(unused)]
fn main() {
/// This function does X.
///
/// # Paramters
/// - `path: &str` - The path to a file
///
/// # Returns
/// - `String` - The contents of the file.
///
/// # Aborts
/// This function will exit the process if the file cannot be found.
pub fn read_file(path: &str) -> String {
    match fs::read_to_string(path) {
        Ok(contents) => contents,
        Err(err) => {
            eprintln!("[Error] File '{}' does not exist: {}", path, err);
            process::exit(1);
        }
    }
}
}

#![allow(unused)]
fn main() {
/// Information about a Person.
pub struct Person {
    /// The name of the Person.
    pub name: String,
    /// The age of the Person.
    pub age: i64,
}
}

#![allow(unused)]
fn main() {
//! This module handles X.
}

We are aware that to some of you, this feels like cluttering the code files. However, we believe that properly documenting our code is the key to providing a more inclusive and more maintainable development experience for all.

Terminal Output/User Interface

When it is necessary to inform the user about a process, we want to make it short, but as expressive as possible. For this, the following styles apply:

• Process X has been started... - Basic white text indicates the current process.
• \x1b[32m[success]\x1b[0m Something has succeeded - Green colored [success] prefix before the message.
• \x1b[31m[error]\x1b[0m Something has failed! - Red colored [error] prefix before error message. This should automatically be added by our custom error types when they are given a error message.
• \ẋ1b[36m[info]\x1b[0m Information level message. - Light blue colored [info] prefix.
• \x1b[33m[warning]\x1b[0m Something went wrong, but we can continue... - Yellow colored [warning] prefix.

Contributing to Nazara

Thank you for considering contributing to Nazara!

The following documents should provide you with all the information you need to start contributing to Nazara.

If you are completely new, make sure you have the following things installed:

• rustc: The Rust compiler
• rustup: The Rust toolchain manager
• cargo: The Rust package manager

If you are unsure about how to set up a Rust development environment, please refer to the Rust documentation for a guide.

Becoming a Packager

If you would like to package Nazara for your distribution, please open an Issue and refer to our Becoming a Packager guide for more info.

Setting up a Test Environment

In case you don't have a dedicated test instance of NetBox, you can easily set up a local instance via docker-compose.

1. Simply clone the netbox-docker repository
2. Modify the docker-compose.yml file to the required NetBox version

services:
    netbox: &netbox
        image: docker.io/netboxcommunity/netbox:v4.3.3
        ...

and execute these commands in accordance to netbox-docker's setup guide:

git clone -b release https://github.com/netbox-community/netbox-docker.git
cd netbox-docker
tee docker-compose.override.yml <<EOF
services:
  netbox:
    ports:
      - 8000:8080
EOF

3. Then build the environment by running docker compose up
4. When the container is built, you need to create a superuser test account

docker compose exec netbox /opt/netbox/netbox/manage.py createsuperuser

Simply select a username and password of your wishes.

5. When that is done, you need to create an API Token username > API Tokens > Add a Token and paste it, along with the container's URL into the Nazara config file at ~/.nazara/config.toml

6. After that, you need to create a few dummy fields that are sadly required to create a device via API

   • Device Type
   • Device Role
   • Manufacturer
   • Site (And depending on what you want to work on, replicate the custom fields you need 1:1 from your production instance.)

   If you want to specifiy and play around with some optional fields, you must create the objects you reference (like e.g Tenants) first.

7. After that's done, take the IDs of these objects and place it into the corresponding fields in the ~/.nazara/config.toml

Now it should work, if you have trouble setting it up, please reach out in the discussion section.

Contributing Workflow

Setup

1. Fork the project repository by clicking on the "Fork" button on the project's GitHub page. This will create a copy of the repository under your GitHub account.
2. Clone your forked repository to your local machine using the git clone command. This will create a local copy of the repository that you can work on.
3. Install the project dependencies by installing libopenssl-dev and libdbus-sys are installed on your system. Both are required by Nazara to compile.

4. Install and set up pre-commit for code quality checks. This tool will automatically execute the hooks we implemented which will check your code for formatting or styling issue before each commit.

Changing Documentation

In case you want - or need - to do changes to this documentation, you need to install both mdbook and mdbook-admonish via cargo.

Simply run these commands:

cargo install mdbook mdbook-admonish

To build the documentation run these commands from the repo's root:

mdbook build docs && mdbook serve docs

This will create a local deployment of the documentation at localhost:3000 with automatic rebuilds upon change.

Making changes

Once you have set up the project your can start working on your contribution.

1. Create a new branch for your changes

Note that working branches should have one of these prefixes.

• feature/: For adding new features to Nazara
• docs/: For changing documentation
• ci/: For CI/CD maintenance
• fix/: For bugfixes
• dep/: For deprecations
• tests/: For branches that add/change tests

2. Make meaningful committs

It is important to pay attention to the scope of your contribution. To this end please only make changes in one Pull Request which are related to your specific contribution.

This makes it easier for us to review your PR and to keep the commit history clean. (If you encounter something else you want to change, which is not directly linked to your contribution, please open a PR on a separate branch for this change.)

3. Include tests in your code

Automated tests are essential to ensure the correctness and reliability of the codebase. Therefore it is required that Pull Requests, which change the existing behaviour of the codebase (e.g by adding features), must be covered with tests by the contributor whenever possible in the same PR as the contribution itself. Code without tests might be rejected or take longer to process.

4. Push your branch to your fork.

5. Open a PR against the main repository.

Fill out the PR form and provide a detailed description of what your PR does and the reason or motivation behind the change.

6. Wait for CI to pass.

Our CI workflows run on pushes and PRs and will check for code quality, format and vulnerabilities. They might also execute all tests they find. It is imperative that all checks are green before a contribution is green. Please check and fix any errors the workflows find.

7. Wait for review.

That's it, now you can, if not already automatically done so, request a review by one of the repository maintainers. We will come back to you as quickly as we can.

Pay Attention To

1. To ensure that all code is properly formatted, please run cargo format on you code before submitting it. pre-commit will tell you when your code is not properly formatted.
2. Documentation is key. We require, that all code contributions are properly documented not only with commit messages and meaningful PR descriptions, but also that the code itself is properly documented with docstrings. This ensures that new contributors and maintainers alike can navigate their way through the codebase. This has the added benefit that your PR can be accepted much quicker too.

Introducing a Dependency

While we would prefer contributors not to introduce new dependencies, we acknowledge that this is not always possible.

Therefore, please refer to our Dependency Policy to see which dependencies we accept, and also please be ready to explain why introducing this dependency was necessary.

A word on vulnerabilities

If you discover a security vulnerability in our code, please inform us privately immediately according to our Security Policy.

If you wish to fix a vulnerability, please also inform us and stand by for our green light. We would still like to investigate the vulnerability for ourselves to get an overview over the severity and scope of the problem. Please refrain from publishing a fix until we came back to you or have published a security advisory.

License Disclaimer

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).

Dependencies

To keep Nazara secure, lightweight, and maintainable, we follow a strict policy on introducing external dependencies.

We only accept external dependencies that meet all of these criteria:

• Are actively maintained
• Are essential to solving the given issue
• Have permissive or at least compatible licenses (MIT, BSD, LGPL, etc.)
• Are reviewed by maintainers before inclusion

Preferance Guidelines

We prefer:

• Standard Library functionality wherever possible
• Zero-dependency alternatives over large general-purpose crates
• Lean and well-maintained crates over obscure or overly complex ones

The goal is not to avoid dependencies at all ocsts - only to avoid unnecessary, unstable, insecure or high-maintenance ones.

Security Policy

Reporting a Vulnerability

If you discover a security vulnerability in this project, please report it by emailing the project owner. Please provide detailed information about the vulnerability, including steps to reproduce, possible ways of exploitation and any relevant details about your environment.

We appreciate responsible disclosure.

Handling of Vulnerabilities

Once a vulnerability is reported, we will review and prioritize it based on its severity. We aim to have a statement ready as soon as possible and provide updates about its status.

Dependency Security

We use automated workflows to assess the security of our used dependencies. We recommend to use cargo audit to check dependencies which you may be planning to introduce to the project beforehand to avoid your PR to be rejected.

Disclaimer

This security policy is subject to change. It is the responsibility of all project contributors and users to stay updated on any modifications. By participating in this project, you agree to abide by this security policy.

Nazara is designed to run only within your local network. The user is responsible for their network setup themselves.

We are not liable for any damages that are caused by insufficient network security. Security Policy

Becoming a Packager

Projects like Nazara live from people who volunteer to maintain packages for their distributions.

System settings or security policies may prohibit package managers like cargo, pip or npm from installing executables on a system. Or maybe company policies require that all software must only come from OS repos, where they can be monitored and audited.

That's why we need you to help to bring Nazara to new platforms.

If you have a distribution that we do not provide a package for, please follow these steps.

1. Open a new discussion stating what you want to package for.

2. Clone the repo and add yourself to the PACKAGERS.md in the project root

3. Open a PR with your changes, and link your request in the PR.

4. A maintainer will eventually approve or deny your request.

Maintainer Information

This section is information for maintainers of the Nazara Project. It documents workflows and guides that are okay to be public.

• Release Workflow
• API Update Workflow

Release Workflow

When it's time to make a new release of Nazara, this procedure should be followed.

1. Update all Version numbers

Make sure to update all version numbers in the following places:

• Cargo.toml
• Nazara.spec
• README.md (Add to Compatibility List)
• docs/src/intro.md (Add to Compatibility List)

1.1 Version Numbers

We generally orient ourselves along the lines of semantic versioning. The following guidelines apply for versioning:

• Patch Versions: Smaller changes/updates/bugfixes without updates to the API client
• Minor Versions: Updates to the API client without major reworks/breaking changes
• Major Versions: Breaking Changes with the API client OR completion of a large feature that significantly impacts Nazara's behaviour or expands scope.

2. Tag New Version

Tag a new version on the latest commit on the main branch.

$ git tag -a v0.1.0_beta.1 -m "v0.1.0_beta.1: Feature X"
$ git push $REMOTE v0.1.0_beta.1

$REMOTE here is the name of the upstream Nazara remote. By default, when cloning upstream, it's origin.

3. Build and Publish to crates.io

Publish the newest version of Nazara to crates.io.

$ cargo publish

4. Updating Distribution Packages

-- Coming Soon --

API Update Workflow

From time to time, it can happen that Nazara becomes incompatible with the newest NetBox release.

Follow these steps in order to bring Nazara up to speed again.

To do this, you will need to install Thanix and clone the thanix_client repository.

1. Create Version Branch

The first thing we do, is lock the current version into a new branch. This ensures we have a fallback, and allows users to patch the version that may still be compatible to their running NetBox instance.

To do this, use this format:

$ git checkout -b version/alpha-2

Or for full release versions:

$ git checkout -b version/vX.Y.Z

2. Update thanix_client

thanix_client is the crate we use to handle API requests to and from NetBox. It is generated by Thanix using the current upstream NetBox API schema.

2.1 Get the latest API schema

Get the latest API schema YAML (Download may take a couple seconds)

2.2 Generate new thanix_client crate

Throw the downloaded YAML file into Thanix to generate a new crate. You will get a new directory wherever you executed it containing a completely new thanix_client repo.

Take the src directory from that output and copy it, in its entirety, into the thanix_client repository you cloned from GitHub. If prompted, agree to overtwrite all existing files.

Update the version numbers in thanix_client accordingly.

Test build the crate by running:

$ cargo build --release

This may take a while depending on your system. If all is good, publish it to crates.io:

$ cargo publish

3. Perform Port of Nazara

First thing you need to do is to update the thanix_client version number in Nazara's Cargo.toml file.

It is almost guaranteed that Nazara won't build after updating that API client. This means that you have to go and fix all the issues that arise. Most likely these will be linked to the payloads and their corresponding fields (like it was moving from 3.x to 4.x).

You will have to fix these in order to fully port Nazara to the newest NetBox version.

4. Follow Release Workflow

Ports of the API client like these are always a separate minor release.

After the codebase is updated, and has been tested and verified and the associated PRs merged, a new release will have to be created.

For this, follow the release workflow.

User Documentation

This documentation is supposed to help you get started with Nazara.

Configuration

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.
• -n, --name <NAME>: The name of the device.
• -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.

Configuring via CLI

Here is an example for passing these parameters on using the CLI:

sudo nazara --uri <API_URL> --token <API_TOKEN> --name test_device . . .

When launching Nazara for the first time, a configuration file will be written at $HOME/.config/nazara/config.toml. You can use CLI parameters to override your settings in the config file.

Configuring via TOML file (recommended)

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.

Aside from the NetBox system parameters, configuration via the config.toml also allows you to add certain custom fields to your system information that cannot be automatically collected. Please check the example file below for exact information about which options are possible.

# Template nazara-config.toml file for v0.1.0-beta.2

# Configuration parameters for the NetBox connection
[netbox]
netbox_api_token = ""
netbox_uri = ""

# Common settings that always have to be provided.
[common]
# The name of the device/VM.
name = ""
description = ""
# A comment left by Nazara if anything gets modified by it.
comments = "Automatically registered by Nazara."
# The current status of the device/VM.
status = "active"

# ---------------------------------------------------------------
# Use [device] for devices, or [vm] if this is a virtual machine.
# ---------------------------------------------------------------

# [device]
# device_type = 0
# role = 0
# site = 0

# [vm]
# cluster = 0

Please note that this section is still a work in progress and all information is subject to change.

The Plugin System