# `netbox` role

A role for setting up NetBox.  
It automatically pulls in all required dependencies like Redis and PostgreSQL, deploys the provided systemd services and gunicorn config and sets up a PostgreSQL database named `netbox` with an owner named `netbox` and the specified password.
However providing the [NetBox configuration](#netbox-configuration), [setting up a web server like nginx to proxy to gunicorn](#web-server-setup) and tasks like creating users, etc. you have to do yourself.

## Supported Distributions

Should work on Debian-based distributions.

## Required Arguments

- `netbox__version`: The NetBox version to deploy.
- `netbox__db_password`: The password to use for connection to the database.
  This is required since the upgrade script runs as root and therefore peer authentication doesn't work.
- `netbox__config`: The NetBox config to deploy.
  See [NetBox Configuration](#netbox-configuration) for more infos.

## Optional Arguments

- `netbox__custom_pipeline_oidc_group_and_role_mapping`: Whether or not to have custom pipeline code for OIDC group and role mapping present.
  See [Custom Pipeline Code for OIDC Group and Role Mapping](#custom-pipeline-code-for-oidc-group-and-role-mapping) for more infos.  
  Defaults to `false`.

## NetBox Configuration

The NetBox configuration should include a connection to Redis as well as a connection to PostgreSQL.  
Configuration for the Redis connection:

```python
REDIS = {
    "tasks": {
      "HOST": "localhost",
      "PORT": 6379,
      "USERNAME": "",
      "PASSWORD": "",
      "DATABASE": 0,
      "SSL": False,
    },
    "caching": {
      "HOST": "localhost",
      "PORT": 6379,
      "USERNAME": "",
      "PASSWORD": "",
      "DATABASE": 1,
      "SSL": False,
    },
}
```

Configuration for the PostgreSQL connection:

```python
DATABASE = {
  "HOST": "localhost",
  "NAME": "netbox",
  "USER": "netbox",
  "PASSWORD": "<same as netbox__db_password>",
}
```

Further configuration should take place. Some relevant resources can be found here:

- Installation guide configuration docs: <https://netboxlabs.com/docs/netbox/en/stable/installation/3-netbox/#configuration>
- Configuration docs: <https://netboxlabs.com/docs/netbox/en/stable/configuration/>
- Example configuration: <https://github.com/netbox-community/netbox/blob/main/netbox/netbox/configuration_example.py>

## Web Server Setup

As this role just sets up gunicorn, but doesn't set up a web server, you need to do that yourself.  
The relevant documentation on how to do that can be found here:

- Web server setup docs: <https://netboxlabs.com/docs/netbox/en/stable/installation/5-http-server/>
- Example base nginx config: <https://github.com/netbox-community/netbox/blob/main/contrib/nginx.conf>

## Custom Pipeline Code for OIDC Group and Role Mapping

Setting the option `netbox__custom_pipeline_oidc_group_and_role_mapping` to `true` makes this role ensure custom pipeline code for OIDC group and role mapping is present.
Note that this role uses code for NetBox >= 4.0.0.  
The code is available in `files/custom_pipeline_oidc_group_and_role_mapping.py`, licensed under the CC BY-SA 4.0 license and taken from [this authentik NetBox documentation](https://docs.goauthentik.io/integrations/services/netbox/).
The documentation also shows how to use the pipeline code by defining a custom `SOCIAL_AUTH_PIPELINE`, which you also need to do, as the configuration isn't provided by this role.
However instead of under `netbox.custom_pipeline.` the functions are available under `netbox.custom_pipeline_oidc_mapping.` with this role.
See also [the default settings.py](https://github.com/netbox-community/netbox/blob/main/netbox/netbox/settings.py) for the default `SOCIAL_AUTH_PIPELINE`.

## Links & Resources

- The NetBox Git Repo: <https://github.com/netbox-community/netbox>
- The NetBox installation docs: <https://netboxlabs.com/docs/netbox/en/stable/installation/>