cdist-type__netbox(7)
=====================

NAME
----
cdist-type__netbox - Install and configure NetBox


DESCRIPTION
-----------
This (singleton) type installs and configures a NetBox instance, a web
application to help manage and document computer networks.

It installs it with the user ``netbox`` at ``/opt/netbox`` with `python-venv`.
Netbox will be run via `gnuicorn` as WSGI service. It setup systemd unit files
for the services `netbox` and `netbox-rq`.


REQUIRED PARAMETERS
-------------------
version
    NetBox version to be installed. You can find the correct and newest version
    on GitHub at the NetBox project page under
    "`Releases <https://github.com/netbox-community/netbox/releases>`_".

database
    PostgreSQL database name.

database-user
    PostgreSQL database user.

database-password
    PostgreSQL database password.

secret-key
    Random secret key of at least 50 alphanumeric characters. This key must be
    unique to this installation and must not be shared outside the local
    system.

host
    Hostname (domain or IP address) on which the application is served.

OPTIONAL PARAMETERS
-------------------
database-host
    PostgreSQL database hostname. Defaults to ``localhost``.

database-port
    PostgreSQL database port. Defaults to empty (uses the default port).

ldap-server
    LDAP server URI. Enables LDAP-backed authentication if specified.

ldap-bind-dn
    DN for the NetBox service account. Required for LDAP authentication.

ldap-bind-password
    Password for the NetBox service account. Required for LDAP authentication.

ldap-user-base
    Base used for searching user entries. Required for LDAP authentication.

ldap-group-base
    Base used for searching group entries.

ldap-require-group
    Group required to login.

ldap-superuser-group
    Make members of this groups superusers.

redis-host
    Redis database hostname. Defaults to ``localhost``.

redis-port
    Redis database port. Defaults to ``6379``.

redis-password
    Redis password. Defaults to empty password.

redis-dbid-offset
    Offset to set the redis database id's. The `tasks` database id is
    `offset + 0`     and `caching` is `offset + 1`. The offset defaults
    to ``0``.

smtp-host
    Host of the SMTP email server. Defaults to ``localhost``.

smtp-port
    Port of the SMTP email server. Defaults to ``25``.

smtp-user
    Username to access the SMTP email server. Defaults to empty.

smtp-password
    Password to access the SMTP email server. Defaults to empty.

smtp-from-email
    Email from which NetBox will be sent of. Defaults to empty.

basepath
    Base URL path if accessing netbox within a directory instead of directly the
    webroot ``/``. For example, if installed at https://example.com/netbox/, set
    the value ``netbox/``.

http-proxy
https-proxy
    Proxy which will be used with any HTTP request like webhooks.

BOOLEAN PARAMETERS
------------------
redis-ssl
    Enables a secure TLS/SSL connection to the redis database. By default, ssl
    is disabled.

smtp-use-tls
    Uses TLS to connect to the SMTP email server. `See documentation
    <https://docs.djangoproject.com/en/3.1/ref/settings/#email-use-tls`_
    for more information.

smtp-use-ssl
    Uses implicit TLS with the SMTP email server. `See documentation
    <https://docs.djangoproject.com/en/3.1/ref/settings/#email-use-ssl`_
    for more information.

login-required
    Sets if a login is required to access all sites. By default, anounymous users
    can see most data (excluding secrets) but not make any changes.

MESSAGES
--------
installed $VERSION
    Netbox was fresh installed or updated. The new version number is appended.

configuration
    Some configuration files got updated and therefore the service was
    restarted. This message will not be echoed if configuration got updated due
    a standard installation.


EXAMPLES
--------

.. code-block:: sh

  __netbox --version 2.8.7 --database netbox \
			--database-password "secretsecretsecret" \
			--secret-key "secretsecretsecret" \
			--host "${__target_host:?}" \
			--ldap-server "ldaps://ldap.domain.tld" \
			--ldap-bind-dn "uid=netbox,ou=services,dc=domain,dc=tld" \
			--ldap-bind-password "secretsecretsecret" \
			--ldap-user-base "ou=users,dc=domain,dc=tld" \
			--ldap-group-base "ou=groups,dc=domain,dc=tld" \
			--ldap-require-group "cn=netbox-login,ou=groups,dc=domain,dc=tld" \
			--ldap-superuser-group "cn=netbox-admin,ou=groups,dc=domain,dc=tld"


NOTES
-----
The configuration of NetBox contains more optional settings than that what can
be set with this type. If you think an important setting is missing or there
is a more good way to inject python code for dynamic configuration variables,
you are welcome to contribute!

- `Possible optional settings
  <https://netbox.readthedocs.io/en/stable/configuration/optional-settings/>`

SEE ALSO
--------
- `NetBox documentation <https://netbox.readthedocs.io/en/stable/>`_

AUTHORS
-------
Timothée Floure <t.floure@e-durable.ch>


COPYING
-------
Copyright \(C) 2020 Timothée Floure. You can redistribute it
and/or modify it under the terms of the GNU General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.