Merge branch 'bdlamprecht-adding_napalm'
This commit is contained in:
Christian Mäder
commit
ac41f7ed78
@ -19,6 +19,8 @@ RUN apk add --no-cache \
|
||||
RUN pip install \
|
||||
# gunicorn is used for launching netbox
|
||||
gunicorn \
|
||||
# napalm is used for gathering information from network devices
|
||||
napalm \
|
||||
# ruamel is used in startup_scripts
|
||||
ruamel.yaml
|
||||
|
||||
|
||||
140
README.md
140
README.md
@ -2,7 +2,7 @@
|
||||
|
||||
[][travis]
|
||||
|
||||
This repository houses the components needed to build Netbox as a Docker container.
|
||||
This repository houses the components needed to build NetBox as a Docker container.
|
||||
Images built using this code are released to [Docker Hub][netbox-dockerhub] every night.
|
||||
|
||||
[travis]: https://travis-ci.org/ninech/netbox-docker
|
||||
@ -10,7 +10,7 @@ Images built using this code are released to [Docker Hub][netbox-dockerhub] ever
|
||||
|
||||
## Quickstart
|
||||
|
||||
To get Netbox up and running:
|
||||
To get NetBox up and running:
|
||||
|
||||
```
|
||||
$ git clone -b master https://github.com/ninech/netbox-docker.git
|
||||
@ -33,8 +33,7 @@ $ open "http://$(docker-compose port nginx 8080)/"
|
||||
$ xdg-open "http://$(docker-compose port nginx 8080)/" &>/dev/null &
|
||||
```
|
||||
|
||||
Alternatively, use something like [Reception][docker-reception] to
|
||||
connect to _docker-compose_ projects.
|
||||
Alternatively, use something like [Reception][docker-reception] to connect to _docker-compose_ projects.
|
||||
|
||||
Default credentials:
|
||||
|
||||
@ -60,17 +59,77 @@ Read [Environment Variables in Compose][compose-env] to understand about the var
|
||||
(The easiest solution being simply adjusting that file.)
|
||||
|
||||
To find all possible variables, have a look at the [configuration.docker.py][docker-config] and [docker-entrypoint.sh][entrypoint] files.
|
||||
Generally, the environment variables are called the same as their respective Netbox configuration variables.
|
||||
Generally, the environment variables are called the same as their respective NetBox configuration variables.
|
||||
Variables which are arrays are usually composed by putting all the values into the same environment variables with the values separated by a whitespace ("` `").
|
||||
For example defining `ALLOWED_HOSTS=localhost ::1 127.0.0.1` would allows access to Netbox through `http://localhost:8080`, `http://[::1]:8080` and `http://127.0.0.1:8080`.
|
||||
For example defining `ALLOWED_HOSTS=localhost ::1 127.0.0.1` would allows access to NetBox through `http://localhost:8080`, `http://[::1]:8080` and `http://127.0.0.1:8080`.
|
||||
|
||||
[compose-env]: https://docs.docker.com/compose/environment-variables/
|
||||
|
||||
### Production
|
||||
|
||||
The default settings are optimized for (local) development environments.
|
||||
You should therefore adjust the configuration for production setups, at least the following variables:
|
||||
|
||||
* `ALLOWED_HOSTS`: Add all URLs that lead to your NetBox instance.
|
||||
* `DB_*`: Use a persistent database.
|
||||
* `EMAIL_*`: Use your own mailserver.
|
||||
* `MAX_PAGE_SIZE`: Use the recommended default of 1000.
|
||||
* `SUPERUSER_*`: Only define those variables during the initial setup, and drop them once the DB is set up.
|
||||
|
||||
### Running on Docker Swarm / Kubernetes / OpenShift
|
||||
|
||||
You may run this image in a cluster such as Docker Swarm, Kubernetes or OpenShift, but this is advanced level.
|
||||
|
||||
In this case, we encourage you to statically configure NetBox by starting from [NetBox's example config file][default-config], and mounting it into your container in the directory `/etc/netbox/` using the mechanism provided by your container platform (i.e. [Docker Swarm configs][swarm-config], [Kubernetes ConfigMap][k8s-config], [OpenShift ConfigMaps][openshift-config]).
|
||||
|
||||
But if you rather continue to configure your application through environment variables, you may continue to use [the built-in configuration file][docker-config].
|
||||
We discourage storing secrets in environment variables, as environment variable are passed on to all sub-processes and may leak easily into other systems, e.g. error collecting tools that often collect all environment variables whenever an error occurs.
|
||||
|
||||
Therefore we *strongly advise* to make use of the secrets mechanism provided by your container platform (i.e. [Docker Swarm secrets][swarm-secrets], [Kubernetes secrets][k8s-secrets], [OpenShift secrets][openshift-secrets]).
|
||||
[The configuration file][docker-config] and [the entrypoint script][entrypoint] try to load the following secrets from the respective files.
|
||||
If a secret is defined by an environment variable and in the respective file at the same time, then the value from the environment variable is used.
|
||||
|
||||
* `SUPERUSER_PASSWORD`: `/run/secrets/superuser_password`
|
||||
* `SUPERUSER_API_TOKEN`: `/run/secrets/superuser_api_token`
|
||||
* `DB_PASSWORD`: `/run/secrets/db_password`
|
||||
* `SECRET_KEY`: `/run/secrets/secret_key`
|
||||
* `EMAIL_PASSWORD`: `/run/secrets/email_password`
|
||||
* `NAPALM_PASSWORD`: `/run/secrets/napalm_password`
|
||||
|
||||
Please also consider [the advice about running NetBox in production](#production) above!
|
||||
|
||||
[docker-config]: https://github.com/ninech/netbox-docker/blob/master/docker/configuration.docker.py
|
||||
[default-config]: https://github.com/digitalocean/netbox/blob/develop/netbox/netbox/configuration.example.py
|
||||
[entrypoint]: https://github.com/ninech/netbox-docker/blob/master/docker/docker-entrypoint.sh
|
||||
[swarm-config]: https://docs.docker.com/engine/swarm/configs/
|
||||
[swarm-secrets]: https://docs.docker.com/engine/swarm/secrets/
|
||||
[openshift-config]: https://docs.openshift.org/latest/dev_guide/configmaps.html
|
||||
[openshift-secrets]: https://docs.openshift.org/latest/dev_guide/secrets.html
|
||||
[k8s-secrets]: https://kubernetes.io/docs/concepts/configuration/secret/
|
||||
[k8s-config]: https://kubernetes.io/docs/tasks/configure-pod-container/configure-pod-configmap/
|
||||
|
||||
### NAPALM Configuration
|
||||
|
||||
Since v2.1.0 NAPALM has been tightly integrated into NetBox.
|
||||
NAPALM allows NetBox to fetch live data from devices and return it to a requester via its REST API.
|
||||
To learn more about what NAPALM is and how it works, please see the documentation from the [libary itself][napalm-doc] or the documentation from [NetBox][netbox-napalm-doc] on how it is integrated.
|
||||
|
||||
To enable this functionality, simply complete the following lines in `netbox.env` (or appropriate secrets mechanism) :
|
||||
|
||||
* `NAPALM_USERNAME`: A common username that can be utilized for connecting to network devices in your environment.
|
||||
* `NAPALM_PASSWORD`: The password to use in combintation with the username to connect to network devices.
|
||||
* `NAPALM_TIMEOUT`: A value to use for when an attempt to connect to a device will timeout if no response has been recieved.
|
||||
|
||||
However, if you don't need this functionality, leave these blank.
|
||||
|
||||
[napalm-doc]: http://napalm.readthedocs.io/en/latest/index.html
|
||||
[netbox-napalm-doc]: https://netbox.readthedocs.io/en/latest/configuration/optional-settings/#napalm_username
|
||||
|
||||
### Custom Initialization Code (e.g. Automatically Setting Up Custom Fields)
|
||||
|
||||
When using `docker-compose`, all the python scripts present in `/opt/netbox/startup_scripts` will automatically be executed after the application boots in the context of `./manage.py`.
|
||||
|
||||
That mechanism can be used for many things, e.g. to create Netbox custom fields:
|
||||
That mechanism can be used for many things, e.g. to create NetBox custom fields:
|
||||
|
||||
```python
|
||||
# docker/startup_scripts/load_custom_fields.py
|
||||
@ -96,7 +155,7 @@ if created:
|
||||
|
||||
#### Initializers
|
||||
|
||||
Initializers are built-in startup scripts for defining Netbox custom fields, groups and users.
|
||||
Initializers are built-in startup scripts for defining NetBox custom fields, groups and users.
|
||||
All you need to do is to mount you own `initializers` folder ([see `docker-compose.yml`][netbox-docker-compose]).
|
||||
Look at the [`initializers` folder][netbox-docker-initializers] to learn how the files must look like.
|
||||
|
||||
@ -125,7 +184,7 @@ text_field:
|
||||
|
||||
#### Custom Docker Image
|
||||
|
||||
You can also build your own Netbox Docker image containing your own startup scripts, custom fields, users and groups
|
||||
You can also build your own NetBox Docker image containing your own startup scripts, custom fields, users and groups
|
||||
like this:
|
||||
|
||||
```
|
||||
@ -136,56 +195,9 @@ COPY startup_scripts/ /opt/netbox/startup_scripts/
|
||||
COPY initializers/ /opt/netbox/initializers/
|
||||
```
|
||||
|
||||
#### LDAP enabled variant
|
||||
|
||||
In the images tagged with "-ldap" you can authenticate netbox against an LDAP / AD server. The included ldap_config.py is configured to use an AD domain controller. The custom values can be injected with environment variables like those in the main configuration file.
|
||||
|
||||
### Production
|
||||
|
||||
The default settings are optimized for (local) development environments.
|
||||
You should therefore adjust the configuration for production setups, at least the following variables:
|
||||
|
||||
* `ALLOWED_HOSTS`: Add all URLs that lead to your Netbox instance.
|
||||
* `DB_*`: Use a persistent database.
|
||||
* `EMAIL_*`: Use your own mailserver.
|
||||
* `MAX_PAGE_SIZE`: Use the recommended default of 1000.
|
||||
* `SUPERUSER_*`: Only define those variables during the initial setup, and drop them once the DB is set up.
|
||||
|
||||
### Running on Docker Swarm / Kubernetes / OpenShift
|
||||
|
||||
You may run this image in a cluster such as Docker Swarm, Kubernetes or OpenShift, but this is advanced level.
|
||||
|
||||
In this case, we encourage you to statically configure Netbox by starting from [Netbox's example config file][default-config], and mounting it into your container in the directory `/etc/netbox/` using the mechanism provided by your container platform (i.e. [Docker Swarm configs][swarm-config], [Kubernetes ConfigMap][k8s-config], [OpenShift ConfigMaps][openshift-config]).
|
||||
|
||||
But if you rather continue to configure your application through environment variables, you may continue to use [the built-in configuration file][docker-config].
|
||||
We discourage storing secrets in environment variables, as environment variable are passed on to all sub-processes and may leak easily into other systems, e.g. error collecting tools that often collect all environment variables whenever an error occurs.
|
||||
|
||||
Therefore we *strongly advise* to make use of the secrets mechanism provided by your container platform (i.e. [Docker Swarm secrets][swarm-secrets], [Kubernetes secrets][k8s-secrets], [OpenShift secrets][openshift-secrets]).
|
||||
[The configuration file][docker-config] and [the entrypoint script][entrypoint] try to load the following secrets from the respective files.
|
||||
If a secret is defined by an environment variable and in the respective file at the same time, then the value from the environment variable is used.
|
||||
|
||||
* `SUPERUSER_PASSWORD`: `/run/secrets/superuser_password`
|
||||
* `SUPERUSER_API_TOKEN`: `/run/secrets/superuser_api_token`
|
||||
* `DB_PASSWORD`: `/run/secrets/db_password`
|
||||
* `SECRET_KEY`: `/run/secrets/secret_key`
|
||||
* `EMAIL_PASSWORD`: `/run/secrets/email_password`
|
||||
* `NAPALM_PASSWORD`: `/run/secrets/napalm_password`
|
||||
|
||||
Please also consider [the advice about running Netbox in production](#production) above!
|
||||
|
||||
[docker-config]: https://github.com/ninech/netbox-docker/blob/master/docker/configuration.docker.py
|
||||
[default-config]: https://github.com/digitalocean/netbox/blob/develop/netbox/netbox/configuration.example.py
|
||||
[entrypoint]: https://github.com/ninech/netbox-docker/blob/master/docker/docker-entrypoint.sh
|
||||
[swarm-config]: https://docs.docker.com/engine/swarm/configs/
|
||||
[swarm-secrets]: https://docs.docker.com/engine/swarm/secrets/
|
||||
[openshift-config]: https://docs.openshift.org/latest/dev_guide/configmaps.html
|
||||
[openshift-secrets]: https://docs.openshift.org/latest/dev_guide/secrets.html
|
||||
[k8s-secrets]: https://kubernetes.io/docs/concepts/configuration/secret/
|
||||
[k8s-config]: https://kubernetes.io/docs/tasks/configure-pod-container/configure-pod-configmap/
|
||||
|
||||
## Version
|
||||
|
||||
The `docker-compose.yml` file is prepared to run a specific version of Netbox.
|
||||
The `docker-compose.yml` file is prepared to run a specific version of NetBox.
|
||||
To use this feature, set the environment-variable `VERSION` before launching `docker-compose`, as shown below.
|
||||
`VERSION` may be set to the name of
|
||||
[any tag of the `ninech/netbox` Docker image on Docker Hub][netbox-dockerhub].
|
||||
@ -196,7 +208,7 @@ $ docker-compose pull netbox
|
||||
$ docker-compose up -d
|
||||
```
|
||||
|
||||
You can also build a specific version of the Netbox image. This time, `VERSION` indicates any valid
|
||||
You can also build a specific version of the NetBox image. This time, `VERSION` indicates any valid
|
||||
[Git Reference][git-ref] declared on [the 'digitalocean/netbox' Github repository][netbox-github].
|
||||
Most commonly you will specify a tag or branch name.
|
||||
|
||||
@ -212,6 +224,12 @@ This can increase the build speed if you're just adjusting the config, for examp
|
||||
[git-ref]: https://git-scm.com/book/en/v2/Git-Internals-Git-References
|
||||
[netbox-github]: https://github.com/digitalocean/netbox/releases
|
||||
|
||||
### LDAP enabled variant
|
||||
|
||||
The images tagged with "-ldap" contain anything necessary to authenticate against an LDAP or Active Directory server.
|
||||
The default configuration `ldap_config.py` is prepared for use with an Active Directory server.
|
||||
Custom values can be injected using environment variables, similar to the main configuration mechanisms.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
This section is a collection of some common issues and how to resolve them.
|
||||
@ -226,14 +244,14 @@ If your issue is not here, look through [the existing issues][issues] and eventu
|
||||
Running `docker-compose logs -f netbox` will just show the logs for netbox.
|
||||
* You can stop everything using `docker-compose stop`.
|
||||
* You can clean up everything using `docker-compose down -v --remove-orphans`. **This will also remove any related data.**
|
||||
* You can enter the shell of the running Netbox container using `docker-compose exec netbox /bin/bash`. Now you have access to `./manage.py`, e.g. to reset a password.
|
||||
* You can enter the shell of the running NetBox container using `docker-compose exec netbox /bin/bash`. Now you have access to `./manage.py`, e.g. to reset a password.
|
||||
* To access the database run `docker-compose exec postgres sh -c 'psql -U $POSTGRES_USER $POSTGRES_DB'`
|
||||
* To create a database backup run `docker-compose exec postgres sh -c 'pg_dump -cU $POSTGRES_USER $POSTGRES_DB' | gzip > db_dump.sql.gz`
|
||||
* To restore that database backup run `gunzip -c db_dump.sql.gz | docker exec -i $(docker-compose ps -q postgres) sh -c 'psql -U $POSTGRES_USER $POSTGRES_DB'`.
|
||||
|
||||
### Getting a "Bad Request (400)"
|
||||
|
||||
> When connecting to the Netbox instance, I get a "Bad Request (400)" error.
|
||||
> When connecting to the NetBox instance, I get a "Bad Request (400)" error.
|
||||
|
||||
This usually happens when the `ALLOWED_HOSTS` variable is not set correctly.
|
||||
|
||||
@ -275,7 +293,7 @@ You can use the following ENV variables to customize the build:
|
||||
|
||||
## Tests
|
||||
|
||||
To run the test coming with Netbox, use the `docker-compose.test.yml` file as such:
|
||||
To run the test coming with NetBox, use the `docker-compose.test.yml` file as such:
|
||||
|
||||
```
|
||||
$ docker-compose -f docker-compose.test.yml run --rm app
|
||||
|
||||
@ -9,7 +9,9 @@ EMAIL_USERNAME=netbox
|
||||
EMAIL_PASSWORD=
|
||||
EMAIL_TIMEOUT=5
|
||||
EMAIL_FROM=netbox@bar.com
|
||||
NAPALM_TIMEOUT=5
|
||||
NAPALM_USERNAME=
|
||||
NAPALM_PASSWORD=
|
||||
NAPALM_TIMEOUT=10
|
||||
MAX_PAGE_SIZE=0
|
||||
SECRET_KEY=r8OwDznj!!dci#P9ghmRfdu1Ysxm0AiPeDCQhKE+N_rClfWNj
|
||||
SUPERUSER_NAME=admin
|
||||
|
||||
Loading…
Reference in New Issue
Block a user