87 lines
3.7 KiB
Markdown
87 lines
3.7 KiB
Markdown
# `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.
|
|
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/>
|