diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index d58b66e8..d48d34b9 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -15,6 +15,8 @@ - [Release Workflow](./maintainers/release_workflow.md) - [API Update Workflow](./maintainers/api_update_workflow.md) - [User Documentation](./users/index.md) - - [Installation Instructions](./users/installation.md) + - [Install](./users/install.md) - [Configuration](./users/configuration.md) + - [Registering a Device or VM](./users/registration.md) + - [Updating a Device or VM](./users/update.md) - [The Plugin System](./users/plugins.md) diff --git a/docs/src/intro.md b/docs/src/intro.md index 9051bbfc..84fb7146 100644 --- a/docs/src/intro.md +++ b/docs/src/intro.md @@ -7,12 +7,8 @@ Nazara is a Rust tool used to automate the registration and update process of machines and VMs in the IPAM tool [NetBox](https://netboxlabs.com/docs/netbox/). -```admonish info -Nazara is currently in it's Beta stage. Bugs are bound to happen. -``` - -```admonish tip -Found a bug or a typo? [Open an issue on GitHub](https://github.com/The-Nazara-Project/Nazara/issues/new/choose) +```admonish bug title="Found a bug?" +Please [Open an issue on GitHub](https://github.com/The-Nazara-Project/Nazara/issues/new/choose). ``` ## Compatibility diff --git a/docs/src/maintainers/release_workflow.md b/docs/src/maintainers/release_workflow.md index 891efd00..dd65371c 100644 --- a/docs/src/maintainers/release_workflow.md +++ b/docs/src/maintainers/release_workflow.md @@ -58,6 +58,21 @@ In order to be able to publish new versions, you must be given permissions to do If the publishing fails, please reach out to the Project Owner. ~~~ -## 4. Updating Distribution Packages +## 4. Create a New Release + +The next step includes creating a new Release via the VC Web UI. + +To do so, follow these steps: + +- [ ] Select latest tag +- [ ] Select previous tag (if not already done automatically) +- [ ] Press "Generate Release Notes" and split into `Added`, `Fixed`, `Removed` sections + as it seems fitting +- [ ] Describe the core changes of this release in a short `What's new?` section at the top +- [ ] Manually build a `.deb` package using `cargo deb` and attach that and the release + binary to the Release for people who want to manually download it +- [ ] Hit "Create Release" + +## 5. Updating Distribution Packages -- Coming Soon -- diff --git a/docs/src/users/install.md b/docs/src/users/install.md new file mode 100644 index 00000000..8afbedf1 --- /dev/null +++ b/docs/src/users/install.md @@ -0,0 +1,43 @@ +# Installing Nazara + +You can install Nazara in a bunch of different ways. +Our recommended solutions is to either get it from [`crates.io`](https://crates.io/crates/nazara), or +build the latest release from source yourself. + + +~~~ admonish info title="Native Packages" +We are currently hard at work to build distribution packages in the future with the first one being +targeted at openSUSE Tumbleweed, Slowroll, Leap and SLES16. + +If you would like to build a package for your distribution, please [refer to our packager's guide](../contributors/becoming_packager.md). +~~~ + +## Installing via `crates.io` + +To install Nazara via Rust's package index, make sure you have `cargo` and a current Rust toolchain installed. + +Then in your Terminal, run + +```bash +cargo install --locked nazara +``` + +After installation you should be able to run Nazara just like you would any other program. If it doesn't work, it is likely +that cargo's bin directory is not in your path. Refer to cargo's documentation for help with that problem. + +## Building from Source + +For this, please make sure you have cargo, `libopenssl` and a current Rust toolchain installed. (The last of which should be +compatible with Rust edition `2024`). + +Simply clone the repository and run `cargo build` to build it yourself. + +```bash +git clone https://github.com/The-Nazara-Project/Nazara && cd Nazara +cargo build --release +``` + +This process may take a while, mainly thanks to our API client library +[thanix_client](https://github.com/The-Nazara-Project/thanix_client). + +Once completed you have a portable binary at `./target/release/nazara`. diff --git a/docs/src/users/installation.md b/docs/src/users/installation.md deleted file mode 100644 index d72c8671..00000000 --- a/docs/src/users/installation.md +++ /dev/null @@ -1,8 +0,0 @@ -# Installation Instructions - -You can install Nazara in a bunch of different way. -Our recommended solutions is to either get it from [`crates.io`](https://crates.io/crates/nazara), or -build the latest release from source yourself. - -We are currently hard at work to build distribution packages in the future with the first one being -targeted at openSUSE Tumbleweed and SLES15. diff --git a/docs/src/users/registration.md b/docs/src/users/registration.md new file mode 100644 index 00000000..12b110e5 --- /dev/null +++ b/docs/src/users/registration.md @@ -0,0 +1,91 @@ +# Registering a Device or VM + +Registering a device with Nazara is as straight forward as +[setting up the config file](./configuration.md) and running +a simple command. + +~~~admonish info +Please make sure you have `sudo` privileges on the machine or VM you want to register, otherwise +DMI information collection **will fail**. +~~~ + +## Example Registration Workflow (Physical Device) + +On a physical device, a example registration workflow may look like this: + +### 1. Set up Configuration + +The user wrote a configuration file at `/root/.config/nazara/config.toml` + +~~~admonish example title="Example: Device Config" collapsible=true +```toml +# Configuration parameters for the NetBox connection +[netbox] +netbox_api_token = "XXXXXXXX" +netbox_uri = "https://netbox.organisation.com" + +# Common settings that always have to be provided +[common] +# The name of the device/VM +name = "user@" +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" +primary_ip4 = "192.168.0.1" +primary_ip6 = "" + +# --------------------------------------------------------------- +# Use [device] for devices, or [vm] if this is a virtual machine. +# --------------------------------------------------------------- + +[device] +device_type = 1 +role = 1 +site = 1 +``` + +The configuration file for a VM looks quite similarly. For a list +of allowed config parameters, please refer to our [template](https://github.com/The-Nazara-Project/Nazara/blob/main/src/configuration/config_template.toml). + +You can verify the integrity of your config by running `nazara check-config`. +~~~ + +### 2. Run `nazara register` + +To register your device, simply run + +```bash +nazara register +``` + +### Common Issues + +#### TOML Deserialization Error + +This is most likely an issue with your config file. +Make sure it has correct TOML syntax and all the fields +specified in the template are present in your example. + +#### Unexpected Response + +We know this output is ugly but please bear with us we are on it. +Check the output for a status code: + +- **400 - Bad Request**: + This usually means that Nazara's payload was rejected by NetBox. Most commonly + this means that you want to assign this device to a role, device type or site + that does not exist (invalid ID). It can also mean that the device already exists + so check if a device with the configured name has already been registered. + +#### File OP error + +This usually indicates that Nazara cannot open the config file at `/root/.config/nazara/config.toml` +it's either missing, or you forgot to run Nazara as root. + +~~~admonish bug title="Any missing?" +You have issues with registering your device and don't know how to proceed? + +This could be a bug! Please [report it](http://github.com/The-Nazara-Project/Nazara/issues). +~~~ diff --git a/docs/src/users/update.md b/docs/src/users/update.md new file mode 100644 index 00000000..d8fd84f4 --- /dev/null +++ b/docs/src/users/update.md @@ -0,0 +1,71 @@ +# Updating a Device or VM + +If you have already registered you Device or VM +in NetBox, you can update the entry using the +`nazara update` command. + +For this, you need to check if your configuration is still valid and +up-to-date. Use the `write-config` command to change the info +you want to update. + +~~~admonish info +This process **also requires `sudo` privileges**, please +make sure you have them before attempting an update. + +This command will try to update **any information** +that has been changed in a PATCH request. +Information that has not changed will not be touched. +~~~ + +## Example Updating Workflow (Physical Device) + +### 1. Update Configuration File + +Make sure your config file at `/root/.config/nazara/config.toml` +is up to date. + +If you want to change any parameter you can do so by using the +`write-config` command. + +For example, we want to switch the device's site from `id=1` to `id=2`. + +```bash +sudo nazara write-config --site 2 +``` + +This will update the entry in the configuration file. + +### 2. Update the Entry + +Now, to update the entry, go and get the entry's ID from NetBox. +You can see it in the URL of your browser. In our case: +`http://localhost:8000/dcim/devices/57/` (device id: 57) + +Then simply run + +``` +sudo nazara update --id 57 +``` + +This will then update the entry for you. + +### Common Issues + +#### IP "X.X.X.X" has not been registered in NetBox + +This is a common issue with environments that use DHCP +with frequently changing IP addresses. In this case the new IP address +has not been registered with NetBox beforehand, so there is no IP entry to update. + +In this case, you must register that new IP manually in NetBox +as the update process is forbidden from doing so. + +Alternatively, you can delete and re-register the device.¹ + +We are actively working on a managed mode that forbids Nazara's +IP management alltogether in cases where you have a different source +of truth for them. + + +¹ Not recommended if you touch your device entries manually. +