NeoAnd/netbox
1
0
Fork 0
mirror of https://github.com/netbox-community/netbox.git synced 2025-07-16 12:12:53 -06:00
Code Issues Actions 11 Packages Projects Releases Wiki Activity

Updated installation docs

Browse Source
This commit is contained in:
Jeremy Stretch 2020-11-17 12:01:10 -05:00
parent fc126d79cd
commit 59df724844
9 changed files with 135 additions and 132 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
docs/installation/1-postgresql.md
View File

@ -5,8 +5,6 @@ This section entails the installation and configuration of a local PostgreSQL da
!!! warning !!! warning
NetBox requires PostgreSQL 9.6 or higher. Please note that MySQL and other relational databases are **not** currently supported. NetBox requires PostgreSQL 9.6 or higher. Please note that MySQL and other relational databases are **not** currently supported.
The installation instructions provided here have been tested to work on Ubuntu 18.04 and CentOS 7.5. The particular commands needed to install dependencies on other distributions may vary significantly. Unfortunately, this is outside the control of the NetBox maintainers. Please consult your distribution's documentation for assistance with any errors.
## Installation ## Installation
#### Ubuntu #### Ubuntu
@ -14,8 +12,8 @@ The installation instructions provided here have been tested to work on Ubuntu 1
If a recent enough version of PostgreSQL is not available through your distribution's package manager, you'll need to install it from an official [PostgreSQL repository](https://wiki.postgresql.org/wiki/Apt). If a recent enough version of PostgreSQL is not available through your distribution's package manager, you'll need to install it from an official [PostgreSQL repository](https://wiki.postgresql.org/wiki/Apt).
```no-highlight ```no-highlight
# apt-get update sudo apt update
# apt-get install -y postgresql libpq-dev sudo apt install -y postgresql libpq-dev
``` ```
#### CentOS #### CentOS
@ -23,9 +21,9 @@ If a recent enough version of PostgreSQL is not available through your distribut
CentOS 7 does not ship with a recent enough version of PostgreSQL, so it will need to be installed from an external repository. The instructions below show the installation of PostgreSQL 9.6, however you may opt to install a more recent version. CentOS 7 does not ship with a recent enough version of PostgreSQL, so it will need to be installed from an external repository. The instructions below show the installation of PostgreSQL 9.6, however you may opt to install a more recent version.
```no-highlight ```no-highlight
# yum install -y https://download.postgresql.org/pub/repos/yum/reporpms/EL-7-x86_64/pgdg-redhat-repo-latest.noarch.rpm sudo yum install -y https://download.postgresql.org/pub/repos/yum/reporpms/EL-7-x86_64/pgdg-redhat-repo-latest.noarch.rpm
# yum install -y postgresql96 postgresql96-server postgresql96-devel sudo yum install -y postgresql96 postgresql96-server postgresql96-devel
# /usr/pgsql-9.6/bin/postgresql96-setup initdb sudo /usr/pgsql-9.6/bin/postgresql96-setup initdb
``` ```
CentOS users should modify the PostgreSQL configuration to accept password-based authentication by replacing `ident` with `md5` for all host entries within `/var/lib/pgsql/9.6/data/pg_hba.conf`. For example: CentOS users should modify the PostgreSQL configuration to accept password-based authentication by replacing `ident` with `md5` for all host entries within `/var/lib/pgsql/9.6/data/pg_hba.conf`. For example:
@ -38,8 +36,8 @@ host all all ::1/128 md5
Then, start the service and enable it to run at boot: Then, start the service and enable it to run at boot:
```no-highlight ```no-highlight
# systemctl start postgresql-9.6 sudo systemctl start postgresql-9.6
# systemctl enable postgresql-9.6 sudo systemctl enable postgresql-9.6
``` ```
## Database Creation ## Database Creation
@ -50,8 +48,8 @@ At a minimum, we need to create a database for NetBox and assign it a username a
**Do not use the password from the example.** Choose a strong, random password to ensure secure database authentication for your NetBox installation. **Do not use the password from the example.** Choose a strong, random password to ensure secure database authentication for your NetBox installation.
```no-highlight ```no-highlight
# sudo -u postgres psql $ sudo -u postgres psql
psql (10.12 (Ubuntu 10.12-0ubuntu0.18.04.1)) psql (12.5 (Ubuntu 12.5-0ubuntu0.20.04.1))
Type "help" for help. Type "help" for help.
postgres=# CREATE DATABASE netbox; postgres=# CREATE DATABASE netbox;
@ -68,13 +66,16 @@ postgres=# \q
You can verify that authentication works issuing the following command and providing the configured password. (Replace `localhost` with your database server if using a remote database.) You can verify that authentication works issuing the following command and providing the configured password. (Replace `localhost` with your database server if using a remote database.)
```no-highlight ```no-highlight
# psql --username netbox --password --host localhost netbox $ psql --username netbox --password --host localhost netbox
Password for user netbox: Password for user netbox:
psql (10.12 (Ubuntu 10.12-0ubuntu0.18.04.1)) psql (12.5 (Ubuntu 12.5-0ubuntu0.20.04.1))
SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, bits: 256, compression: off) SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, bits: 256, compression: off)
Type "help" for help. Type "help" for help.
netbox=> \conninfo
You are connected to database "netbox" as user "netbox" on host "localhost" (address "127.0.0.1") at port "5432".
SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, bits: 256, compression: off)
netbox=> \q netbox=> \q
``` ```
If successful, you will enter a `netbox` prompt. Type `\q` to exit. If successful, you will enter a `netbox` prompt. Type `\conninfo` to confirm your connection, or type `\q` to exit.

10
docs/installation/2-redis.md
View File

@ -10,16 +10,16 @@
### Ubuntu ### Ubuntu
```no-highlight ```no-highlight
# apt-get install -y redis-server sudo apt install -y redis-server
``` ```
### CentOS ### CentOS
```no-highlight ```no-highlight
# yum install -y epel-release sudo yum install -y epel-release
# yum install -y redis sudo yum install -y redis
# systemctl start redis sudo systemctl start redis
# systemctl enable redis sudo systemctl enable redis
``` ```
You may wish to modify the Redis configuration at `/etc/redis.conf` or `/etc/redis/redis.conf`, however in most cases the default configuration is sufficient. You may wish to modify the Redis configuration at `/etc/redis.conf` or `/etc/redis/redis.conf`, however in most cases the default configuration is sufficient.

67
docs/installation/3-netbox.md
View File

@ -12,25 +12,25 @@ Begin by installing all system packages required by NetBox and its dependencies.
### Ubuntu ### Ubuntu
```no-highlight ```no-highlight
# apt-get install -y python3.6 python3-pip python3-venv python3-dev build-essential libxml2-dev libxslt1-dev libffi-dev libpq-dev libssl-dev zlib1g-dev sudo apt install -y python3.6 python3-pip python3-venv python3-dev build-essential libxml2-dev libxslt1-dev libffi-dev libpq-dev libssl-dev zlib1g-dev
``` ```
### CentOS ### CentOS
```no-highlight ```no-highlight
# yum install -y gcc python36 python36-devel python36-setuptools libxml2-devel libxslt-devel libffi-devel openssl-devel redhat-rpm-config sudo yum install -y gcc python36 python36-devel python36-setuptools libxml2-devel libxslt-devel libffi-devel openssl-devel redhat-rpm-config
# easy_install-3.6 pip sudo easy_install-3.6 pip
``` ```
Before continuing with either platform, update pip (Python's package management tool) to its latest release: Before continuing with either platform, update pip (Python's package management tool) to its latest release:
```no-highlight ```no-highlight
# pip3 install --upgrade pip sudo pip3 install --upgrade pip
``` ```
## Download NetBox ## Download NetBox
This documentation provides two options for installing NetBox: from a downloadable archive, or from the git repository. Installing from a package (option A below) requires manually fetching and decompressing the archive for every future update, whereas installation via git (option B) allows for seamless upgrades by re-pulling the `master` branch. This documentation provides two options for installing NetBox: from a downloadable archive, or from the git repository. Installing from a package (option A below) requires manually fetching and extracting the archive for every future update, whereas installation via git (option B) allows for seamless upgrades by re-pulling the `master` branch.
### Option A: Download a Release Archive ### Option A: Download a Release Archive
@ -53,7 +53,7 @@ drwxr-xr-x 2 root root 4096 Jul 20 13:44 netbox-2.9.0
Create the base directory for the NetBox installation. For this guide, we'll use `/opt/netbox`. Create the base directory for the NetBox installation. For this guide, we'll use `/opt/netbox`.
```no-highlight ```no-highlight
# mkdir -p /opt/netbox/ && cd /opt/netbox/ sudo mkdir -p /opt/netbox/ && cd /opt/netbox/
``` ```
If `git` is not already installed, install it: If `git` is not already installed, install it:
@ -61,19 +61,19 @@ If `git` is not already installed, install it:
#### Ubuntu #### Ubuntu
```no-highlight ```no-highlight
# apt-get install -y git sudo apt install -y git
``` ```
#### CentOS #### CentOS
```no-highlight ```no-highlight
# yum install -y git sudo yum install -y git
``` ```
Next, clone the **master** branch of the NetBox GitHub repository into the current directory. (This branch always holds the current stable release.) Next, clone the **master** branch of the NetBox GitHub repository into the current directory. (This branch always holds the current stable release.)
```no-highlight ```no-highlight
# git clone -b master https://github.com/netbox-community/netbox.git . sudo git clone -b master https://github.com/netbox-community/netbox.git .
Cloning into '.'... Cloning into '.'...
remote: Counting objects: 1994, done. remote: Counting objects: 1994, done.
remote: Compressing objects: 100% (150/150), done. remote: Compressing objects: 100% (150/150), done.
@ -93,16 +93,16 @@ Create a system user account named `netbox`. We'll configure the WSGI and HTTP s
#### Ubuntu #### Ubuntu
``` ```
# adduser --system --group netbox sudo adduser --system --group netbox
# chown --recursive netbox /opt/netbox/netbox/media/ sudo chown --recursive netbox /opt/netbox/netbox/media/
``` ```
#### CentOS #### CentOS
``` ```
# groupadd --system netbox sudo groupadd --system netbox
# adduser --system -g netbox netbox sudo adduser --system -g netbox netbox
# chown --recursive netbox /opt/netbox/netbox/media/ sudo chown --recursive netbox /opt/netbox/netbox/media/
``` ```
## Configuration ## Configuration
@ -110,8 +110,8 @@ Create a system user account named `netbox`. We'll configure the WSGI and HTTP s
Move into the NetBox configuration directory and make a copy of `configuration.example.py` named `configuration.py`. This file will hold all of your local configuration parameters. Move into the NetBox configuration directory and make a copy of `configuration.example.py` named `configuration.py`. This file will hold all of your local configuration parameters.
```no-highlight ```no-highlight
# cd /opt/netbox/netbox/netbox/ cd /opt/netbox/netbox/netbox/
# cp configuration.example.py configuration.py sudo cp configuration.example.py configuration.py
``` ```
Open `configuration.py` with your preferred editor to begin configuring NetBox. NetBox offers [many configuration parameters](/configuration/), but only the following four are required for new installations: Open `configuration.py` with your preferred editor to begin configuring NetBox. NetBox offers [many configuration parameters](/configuration/), but only the following four are required for new installations:
@ -154,7 +154,7 @@ DATABASE = {
Redis is a in-memory key-value store used by NetBox for caching and background task queuing. Redis typically requires minimal configuration; the values below should suffice for most installations. See the [configuration documentation](/configuration/required-settings/#redis) for more detail on individual parameters. Redis is a in-memory key-value store used by NetBox for caching and background task queuing. Redis typically requires minimal configuration; the values below should suffice for most installations. See the [configuration documentation](/configuration/required-settings/#redis) for more detail on individual parameters.
Note that NetBox requires the specification of two separate Redis databases: `tasks` and `caching`. These may both be provided by the same Redis service, however each should have a unique database ID. Note that NetBox requires the specification of two separate Redis databases: `tasks` and `caching`. These may both be provided by the same Redis service, however each should have a unique numeric database ID.
```python ```python
REDIS = { REDIS = {
@ -182,7 +182,7 @@ This parameter must be assigned a randomly-generated key employed as a salt for
A simple Python script named `generate_secret_key.py` is provided in the parent directory to assist in generating a suitable key: A simple Python script named `generate_secret_key.py` is provided in the parent directory to assist in generating a suitable key:
```no-highlight ```no-highlight
# python3 ../generate_secret_key.py python3 ../generate_secret_key.py
``` ```
!!! warning !!! warning
@ -199,7 +199,7 @@ All Python packages required by NetBox are listed in `requirements.txt` and will
The [NAPALM automation](https://napalm-automation.net/) library allows NetBox to fetch live data from devices and return it to a requester via its REST API. The `NAPALM_USERNAME` and `NAPALM_PASSWORD` configuration parameters define the credentials to be used when connecting to a device. The [NAPALM automation](https://napalm-automation.net/) library allows NetBox to fetch live data from devices and return it to a requester via its REST API. The `NAPALM_USERNAME` and `NAPALM_PASSWORD` configuration parameters define the credentials to be used when connecting to a device.
```no-highlight ```no-highlight
# echo napalm >> /opt/netbox/local_requirements.txt sudo echo napalm >> /opt/netbox/local_requirements.txt
``` ```
### Remote File Storage ### Remote File Storage
@ -207,7 +207,7 @@ The [NAPALM automation](https://napalm-automation.net/) library allows NetBox to
By default, NetBox will use the local filesystem to store uploaded files. To use a remote filesystem, install the [`django-storages`](https://django-storages.readthedocs.io/en/stable/) library and configure your [desired storage backend](/configuration/optional-settings/#storage_backend) in `configuration.py`. By default, NetBox will use the local filesystem to store uploaded files. To use a remote filesystem, install the [`django-storages`](https://django-storages.readthedocs.io/en/stable/) library and configure your [desired storage backend](/configuration/optional-settings/#storage_backend) in `configuration.py`.
```no-highlight ```no-highlight
# echo django-storages >> /opt/netbox/local_requirements.txt sudo echo django-storages >> /opt/netbox/local_requirements.txt
``` ```
## Run the Upgrade Script ## Run the Upgrade Script
@ -220,7 +220,7 @@ Once NetBox has been configured, we're ready to proceed with the actual installa
* Aggregate static resource files on disk * Aggregate static resource files on disk
```no-highlight ```no-highlight
# /opt/netbox/upgrade.sh sudo /opt/netbox/upgrade.sh
``` ```
!!! note !!! note
@ -231,7 +231,7 @@ Once NetBox has been configured, we're ready to proceed with the actual installa
NetBox does not come with any predefined user accounts. You'll need to create a super user (administrative account) to be able to log into NetBox. First, enter the Python virtual environment created by the upgrade script: NetBox does not come with any predefined user accounts. You'll need to create a super user (administrative account) to be able to log into NetBox. First, enter the Python virtual environment created by the upgrade script:
```no-highlight ```no-highlight
# source /opt/netbox/venv/bin/activate source /opt/netbox/venv/bin/activate
``` ```
Once the virtual environment has been activated, you should notice the string `(venv)` prepended to your console prompt. Once the virtual environment has been activated, you should notice the string `(venv)` prepended to your console prompt.
@ -239,8 +239,8 @@ Once the virtual environment has been activated, you should notice the string `(
Next, we'll create a superuser account using the `createsuperuser` Django management command (via `manage.py`). Specifying an email address for the user is not required, but be sure to use a very strong password. Next, we'll create a superuser account using the `createsuperuser` Django management command (via `manage.py`). Specifying an email address for the user is not required, but be sure to use a very strong password.
```no-highlight ```no-highlight
(venv) # cd /opt/netbox/netbox (venv) $ cd /opt/netbox/netbox
(venv) # python3 manage.py createsuperuser (venv) $ python3 manage.py createsuperuser
Username: admin Username: admin
Email address: admin@example.com Email address: admin@example.com
Password: Password:
@ -250,28 +250,33 @@ Superuser created successfully.
## Test the Application ## Test the Application
At this point, we should be able to run NetBox. We can check by starting a development instance: At this point, we should be able to run NetBox's development server for testing. We can check by starting a development instance:
```no-highlight ```no-highlight
(venv) # python3 manage.py runserver 0.0.0.0:8000 --insecure (venv) $ python3 manage.py runserver 0.0.0.0:8000 --insecure
Performing system checks... Performing system checks...
System check identified no issues (0 silenced). System check identified no issues (0 silenced).
November 28, 2018 - 09:33:45 November 17, 2020 - 16:08:13
Django version 2.0.9, using settings 'netbox.settings' Django version 3.1.3, using settings 'netbox.settings'
Starting development server at http://0.0.0.0:8000/ Starting development server at http://0.0.0.0:8000/
Quit the server with CONTROL-C. Quit the server with CONTROL-C.
``` ```
Next, connect to the name or IP of the server (as defined in `ALLOWED_HOSTS`) on port 8000; for example, <http://127.0.0.1:8000/>. You should be greeted with the NetBox home page. Note that this built-in web service is for development and testing purposes only. **It is not suited for production use.** Next, connect to the name or IP of the server (as defined in `ALLOWED_HOSTS`) on port 8000; for example, <http://127.0.0.1:8000/>. You should be greeted with the NetBox home page.
!!! warning
The development server is for development and testing purposes only. It is neither performant nor secure enough for production use. **Do not use it in production.**
!!! warning !!! warning
If the test service does not run, or you cannot reach the NetBox home page, something has gone wrong. Do not proceed with the rest of this guide until the installation has been corrected. If the test service does not run, or you cannot reach the NetBox home page, something has gone wrong. Do not proceed with the rest of this guide until the installation has been corrected.
Note that the initial UI will be locked down for non-authenticated users. Note that the initial user interface will be locked down for non-authenticated users.
![NetBox UI as seen by a non-authenticated user](../media/installation/netbox_ui_guest.png) ![NetBox UI as seen by a non-authenticated user](../media/installation/netbox_ui_guest.png)
Try logging in as the super user we just created. Once authenticated, you'll be able to access all areas of the UI: Try logging in using the superuser account we just created. Once authenticated, you'll be able to access all areas of the UI:
![NetBox UI as seen by an administrator](../media/installation/netbox_ui_admin.png) ![NetBox UI as seen by an administrator](../media/installation/netbox_ui_admin.png)
Type `Ctrl+c` to stop the development server.

39
docs/installation/4-gunicorn.md
View File

@ -1,32 +1,31 @@
# Gunicorn # Gunicorn
Like most Django applications, NetBox runs as a [WSGI application](https://en.wikipedia.org/wiki/Web_Server_Gateway_Interface) behind an HTTP server. This documentation shows how to install and configure [gunicorn](http://gunicorn.org/) for this role, however other WSGIs are available and should work similarly well. Like most Django applications, NetBox runs as a [WSGI application](https://en.wikipedia.org/wiki/Web_Server_Gateway_Interface) behind an HTTP server. This documentation shows how to install and configure [gunicorn](http://gunicorn.org/) (which is automatically installed with NetBox) for this role, however other WSGI servers are available and should work similarly well. [uWSGI](https://uwsgi-docs.readthedocs.io/en/latest/) is a popular alternative.
## Configuration ## Configuration
NetBox ships with a default configuration file for gunicorn. To use it, copy `/opt/netbox/contrib/gunicorn.py` to `/opt/netbox/gunicorn.py`. (We make a copy of this file rather than pointing to it directly to ensure that any changes to it do not get overwritten by a future upgrade.) NetBox ships with a default configuration file for gunicorn. To use it, copy `/opt/netbox/contrib/gunicorn.py` to `/opt/netbox/gunicorn.py`. (We make a copy of this file rather than pointing to it directly to ensure that any local changes to it do not get overwritten by a future upgrade.)
```no-highlight ```no-highlight
# cd /opt/netbox sudo cp /opt/netbox/contrib/gunicorn.py /opt/netbox/gunicorn.py
# cp contrib/gunicorn.py /opt/netbox/gunicorn.py
``` ```
While this default configuration should suffice for most initial installations, you may wish to edit this file to change the bound IP address and/or port number, or to make performance-related adjustments. See [the Gunicorn documentation](https://docs.gunicorn.org/en/stable/configure.html) for the available configuration parameters. While the provided configuration should suffice for most initial installations, you may wish to edit this file to change the bound IP address and/or port number, or to make performance-related adjustments. See [the Gunicorn documentation](https://docs.gunicorn.org/en/stable/configure.html) for the available configuration parameters.
## systemd Setup ## systemd Setup
We'll use systemd to control both gunicorn and NetBox's background worker process. First, copy `contrib/netbox.service` and `contrib/netbox-rq.service` to the `/etc/systemd/system/` directory and reload the systemd dameon: We'll use systemd to control both gunicorn and NetBox's background worker process. First, copy `contrib/netbox.service` and `contrib/netbox-rq.service` to the `/etc/systemd/system/` directory and reload the systemd dameon:
```no-highlight ```no-highlight
# cp contrib/*.service /etc/systemd/system/ sudo cp -v /opt/netbox/contrib/*.service /etc/systemd/system/
# systemctl daemon-reload sudo systemctl daemon-reload
``` ```
Then, start the `netbox` and `netbox-rq` services and enable them to initiate at boot time: Then, start the `netbox` and `netbox-rq` services and enable them to initiate at boot time:
```no-highlight ```no-highlight
# systemctl start netbox netbox-rq sudo systemctl start netbox netbox-rq
# systemctl enable netbox netbox-rq sudo systemctl enable netbox netbox-rq
``` ```
You can use the command `systemctl status netbox` to verify that the WSGI service is running: You can use the command `systemctl status netbox` to verify that the WSGI service is running:
@ -34,16 +33,20 @@ You can use the command `systemctl status netbox` to verify that the WSGI servic
```no-highlight ```no-highlight
# systemctl status netbox.service # systemctl status netbox.service
● netbox.service - NetBox WSGI Service ● netbox.service - NetBox WSGI Service
Loaded: loaded (/etc/systemd/system/netbox.service; enabled; vendor preset: enabled) Loaded: loaded (/etc/systemd/system/netbox.service; enabled; vendor preset: enabled)
Active: active (running) since Thu 2019-12-12 19:23:40 UTC; 25s ago Active: active (running) since Tue 2020-11-17 16:18:23 UTC; 3min 35s ago
Docs: https://netbox.readthedocs.io/en/stable/ Docs: https://netbox.readthedocs.io/en/stable/
Main PID: 11993 (gunicorn) Main PID: 22836 (gunicorn)
Tasks: 6 (limit: 2362) Tasks: 6 (limit: 2345)
CGroup: /system.slice/netbox.service Memory: 339.3M
├─11993 /usr/bin/python3 /usr/local/bin/gunicorn --pid /var/tmp/netbox.pid --pythonpath /opt/netbox/... CGroup: /system.slice/netbox.service
├─12015 /usr/bin/python3 /usr/local/bin/gunicorn --pid /var/tmp/netbox.pid --pythonpath /opt/netbox/... ├─22836 /opt/netbox/venv/bin/python3 /opt/netbox/venv/bin/gunicorn --pid>
├─12016 /usr/bin/python3 /usr/local/bin/gunicorn --pid /var/tmp/netbox.pid --pythonpath /opt/netbox/... ├─22854 /opt/netbox/venv/bin/python3 /opt/netbox/venv/bin/gunicorn --pid>
├─22855 /opt/netbox/venv/bin/python3 /opt/netbox/venv/bin/gunicorn --pid>
... ...
``` ```
!!! note
If the NetBox service fails to start, issue the command `journalctl -eu netbox` to check for log messages that may indicate the problem.
Once you've verified that the WSGI workers are up and running, move on to HTTP server setup. Once you've verified that the WSGI workers are up and running, move on to HTTP server setup.

31
docs/installation/5-http-server.md
View File

@ -1,9 +1,9 @@
# HTTP Server Setup # HTTP Server Setup
This documentation provides example configurations for both [nginx](https://www.nginx.com/resources/wiki/) and [Apache](http://httpd.apache.org/docs/2.4), though any HTTP server which supports WSGI should be compatible. This documentation provides example configurations for both [nginx](https://www.nginx.com/resources/wiki/) and [Apache](http://httpd.apache.org/docs/current/), though any HTTP server which supports WSGI should be compatible.
!!! info !!! info
For the sake of brevity, only Ubuntu 18.04 instructions are provided here, these tasks not unique to NetBox and should carry over to other distributions with mininal changes. Please consult your distribution's documentation for assistance if needed. For the sake of brevity, only Ubuntu 20.04 instructions are provided here, these tasks not unique to NetBox and should carry over to other distributions with mininal changes. Please consult your distribution's documentation for assistance if needed.
## Obtain an SSL Certificate ## Obtain an SSL Certificate
@ -12,7 +12,7 @@ To enable HTTPS access to NetBox, you'll need a valid SSL certificate. You can p
The command below can be used to generate a self-signed certificate for testing purposes, however it is strongly recommended to use a certificate from a trusted authority in production. Two files will be created: the public certificate (`netbox.crt`) and the private key (`netbox.key`). The certificate is published to the world, whereas the private key must be kept secret at all times. The command below can be used to generate a self-signed certificate for testing purposes, however it is strongly recommended to use a certificate from a trusted authority in production. Two files will be created: the public certificate (`netbox.crt`) and the private key (`netbox.key`). The certificate is published to the world, whereas the private key must be kept secret at all times.
```no-highlight ```no-highlight
# openssl req -x509 -nodes -days 365 -newkey rsa:2048 \ sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
-keyout /etc/ssl/private/netbox.key \ -keyout /etc/ssl/private/netbox.key \
-out /etc/ssl/certs/netbox.crt -out /etc/ssl/certs/netbox.crt
``` ```
@ -26,27 +26,26 @@ The above command will prompt you for additional details of the certificate; all
Begin by installing nginx: Begin by installing nginx:
```no-highlight ```no-highlight
# apt-get install -y nginx sudo apt install -y nginx
``` ```
Once nginx is installed, copy the nginx configuration file provided by NetBox to `/etc/nginx/sites-available/netbox`. Be sure to replace `netbox.example.com` with the domain name or IP address of your installation. (This should match the value configured for `ALLOWED_HOSTS` in `configuration.py`.) Once nginx is installed, copy the nginx configuration file provided by NetBox to `/etc/nginx/sites-available/netbox`. Be sure to replace `netbox.example.com` with the domain name or IP address of your installation. (This should match the value configured for `ALLOWED_HOSTS` in `configuration.py`.)
```no-highlight ```no-highlight
# cp /opt/netbox/contrib/nginx.conf /etc/nginx/sites-available/netbox sudo cp /opt/netbox/contrib/nginx.conf /etc/nginx/sites-available/netbox
``` ```
Then, delete `/etc/nginx/sites-enabled/default` and create a symlink in the `sites-enabled` directory to the configuration file you just created. Then, delete `/etc/nginx/sites-enabled/default` and create a symlink in the `sites-enabled` directory to the configuration file you just created.
```no-highlight ```no-highlight
# cd /etc/nginx/sites-enabled/ sudo rm /etc/nginx/sites-enabled/default
# rm default sudo ln -s /etc/nginx/sites-available/netbox /etc/nginx/sites-enabled/netbox
# ln -s /etc/nginx/sites-available/netbox
``` ```
Finally, restart the `nginx` service to use the new configuration. Finally, restart the `nginx` service to use the new configuration.
```no-highlight ```no-highlight
# service nginx restart sudo systemctl restart nginx
``` ```
### Option B: Apache ### Option B: Apache
@ -54,26 +53,26 @@ Finally, restart the `nginx` service to use the new configuration.
Begin by installing Apache: Begin by installing Apache:
```no-highlight ```no-highlight
# apt-get install -y apache2 sudo apt install -y apache2
``` ```
Next, copy the default configuration file to `/etc/apache2/sites-available/`. Be sure to modify the `ServerName` parameter appropriately. Next, copy the default configuration file to `/etc/apache2/sites-available/`. Be sure to modify the `ServerName` parameter appropriately.
```no-highlight ```no-highlight
# cp /opt/netbox/contrib/apache.conf /etc/apache2/sites-available/netbox.conf sudo cp /opt/netbox/contrib/apache.conf /etc/apache2/sites-available/netbox.conf
``` ```
Finally, ensure that the required Apache modules are enabled, enable the `netbox` site, and reload Apache: Finally, ensure that the required Apache modules are enabled, enable the `netbox` site, and reload Apache:
```no-highlight ```no-highlight
# a2enmod ssl proxy proxy_http headers sudo a2enmod ssl proxy proxy_http headers
# a2ensite netbox sudo a2ensite netbox
# service apache2 restart sudo systemctl restart apache2
``` ```
## Confirm Connectivity ## Confirm Connectivity
At this point, you should be able to connect to the HTTP service at the server name or IP address you provided. At this point, you should be able to connect to the HTTPS service at the server name or IP address you provided.
!!! info !!! info
Please keep in mind that the configurations provided here are bare minimums required to get NetBox up and running. You may want to make adjustments to better suit your production environment. Please keep in mind that the configurations provided here are bare minimums required to get NetBox up and running. You may want to make adjustments to better suit your production environment.
@ -91,5 +90,5 @@ If you are unable to connect to the HTTP server, check that:
If you are able to connect but receive a 502 (bad gateway) error, check the following: If you are able to connect but receive a 502 (bad gateway) error, check the following:
* The WSGI worker processes (gunicorn) are running (`systemctl status netbox` should show a status of "active (running)") * The WSGI worker processes (gunicorn) are running (`systemctl status netbox` should show a status of "active (running)")
* nginx/Apache is configured to connect to the port on which gunicorn is listening (default is 8001). * Nginx/Apache is configured to connect to the port on which gunicorn is listening (default is 8001).
* SELinux is not preventing the reverse proxy connection. You may need to allow HTTP network connections with the command `setsebool -P httpd_can_network_connect 1` * SELinux is not preventing the reverse proxy connection. You may need to allow HTTP network connections with the command `setsebool -P httpd_can_network_connect 1`

13
docs/installation/6-ldap.md
View File

@ -9,13 +9,13 @@ This guide explains how to implement LDAP authentication using an external serve
On Ubuntu: On Ubuntu:
```no-highlight ```no-highlight
# apt-get install -y libldap2-dev libsasl2-dev libssl-dev sudo apt install -y libldap2-dev libsasl2-dev libssl-dev
``` ```
On CentOS: On CentOS:
```no-highlight ```no-highlight
# yum install -y openldap-devel sudo yum install -y openldap-devel
``` ```
### Install django-auth-ldap ### Install django-auth-ldap
@ -23,15 +23,14 @@ On CentOS:
Activate the Python virtual environment and install the `django-auth-ldap` package using pip: Activate the Python virtual environment and install the `django-auth-ldap` package using pip:
```no-highlight ```no-highlight
# cd /opt/netbox/ source /opt/netbox/venv/bin/activate
# source venv/bin/activate pip3 install django-auth-ldap
(venv) # pip3 install django-auth-ldap
``` ```
Once installed, add the package to `local_requirements.txt` to ensure it is re-installed during future rebuilds of the virtual environment: Once installed, add the package to `local_requirements.txt` to ensure it is re-installed during future rebuilds of the virtual environment:
```no-highlight ```no-highlight
(venv) # echo django-auth-ldap >> local_requirements.txt sudo echo django-auth-ldap >> /opt/netbox/local_requirements.txt
``` ```
## Configuration ## Configuration
@ -42,7 +41,7 @@ First, enable the LDAP authentication backend in `configuration.py`. (Be sure to
REMOTE_AUTH_BACKEND = 'netbox.authentication.LDAPBackend' REMOTE_AUTH_BACKEND = 'netbox.authentication.LDAPBackend'
``` ```
Next, create a file in the same directory as `configuration.py` (typically `netbox/netbox/`) named `ldap_config.py`. Define all of the parameters required below in `ldap_config.py`. Complete documentation of all `django-auth-ldap` configuration options is included in the project's [official documentation](http://django-auth-ldap.readthedocs.io/). Next, create a file in the same directory as `configuration.py` (typically `/opt/netbox/netbox/netbox/`) named `ldap_config.py`. Define all of the parameters required below in `ldap_config.py`. Complete documentation of all `django-auth-ldap` configuration options is included in the project's [official documentation](http://django-auth-ldap.readthedocs.io/).
### General Server Configuration ### General Server Configuration

10
docs/installation/index.md
View File

@ -1,5 +1,7 @@
# Installation # Installation
The installation instructions provided here have been tested to work on Ubuntu 20.04 and CentOS 7.5. The particular commands needed to install dependencies on other distributions may vary significantly. Unfortunately, this is outside the control of the NetBox maintainers. Please consult your distribution's documentation for assistance with any errors.
The following sections detail how to set up a new instance of NetBox: The following sections detail how to set up a new instance of NetBox:
1. [PostgreSQL database](1-postgresql.md) 1. [PostgreSQL database](1-postgresql.md)
@ -9,6 +11,14 @@ The following sections detail how to set up a new instance of NetBox:
5. [HTTP server](5-http-server.md) 5. [HTTP server](5-http-server.md)
6. [LDAP authentication](6-ldap.md) (optional) 6. [LDAP authentication](6-ldap.md) (optional)
## Requirements
| Dependency | Minimum Version |
|------------|-----------------|
| Python | 3.6 |
| PostgreSQL | 9.6 |
| Redis | 4.0 |
Below is a simplified overview of the NetBox application stack for reference: Below is a simplified overview of the NetBox application stack for reference:
![NetBox UI as seen by a non-authenticated user](../media/installation/netbox_application_stack.png) ![NetBox UI as seen by a non-authenticated user](../media/installation/netbox_application_stack.png)

65
docs/installation/upgrading.md
View File

@ -2,7 +2,7 @@
## Review the Release Notes ## Review the Release Notes
Prior to upgrading your NetBox instance, be sure to carefully review all [release notes](../../release-notes/) that have been published since your current version was released. Although the upgrade process typically does not involve additional work, certain releases may introduce breaking or backward-incompatible changes. These are called out in the release notes under the version in which the change went into effect. Prior to upgrading your NetBox instance, be sure to carefully review all [release notes](../../release-notes/) that have been published since your current version was released. Although the upgrade process typically does not involve additional work, certain releases may introduce breaking or backward-incompatible changes. These are called out in the release notes under the release in which the change went into effect.
## Update Dependencies to Required Versions ## Update Dependencies to Required Versions
@ -14,7 +14,7 @@ NetBox v2.9.0 and later requires the following:
| PostgreSQL | 9.6 | | PostgreSQL | 9.6 |
| Redis | 4.0 | | Redis | 4.0 |
## Install the Latest Code ## Install the Latest Release
As with the initial installation, you can upgrade NetBox by either downloading the latest release package or by cloning the `master` branch of the git repository. As with the initial installation, you can upgrade NetBox by either downloading the latest release package or by cloning the `master` branch of the git repository.
@ -25,47 +25,36 @@ Download the [latest stable release](https://github.com/netbox-community/netbox/
Download and extract the latest version: Download and extract the latest version:
```no-highlight ```no-highlight
# wget https://github.com/netbox-community/netbox/archive/vX.Y.Z.tar.gz wget https://github.com/netbox-community/netbox/archive/vX.Y.Z.tar.gz
# tar -xzf vX.Y.Z.tar.gz -C /opt sudo tar -xzf vX.Y.Z.tar.gz -C /opt
# cd /opt/ sudo ln -sfn /opt/netbox-X.Y.Z/ /opt/netbox
# ln -sfn /opt/netbox-X.Y.Z/ /opt/netbox
``` ```
Copy the 'configuration.py' you created when first installing to the new version: Copy `local_requirements.txt`, `configuration.py`, and `ldap_config.py` (if present) from the current installation to the new version:
```no-highlight ```no-highlight
# cp /opt/netbox-X.Y.Z/netbox/netbox/configuration.py /opt/netbox/netbox/netbox/configuration.py sudo cp /opt/netbox-X.Y.Z/local_requirements.txt /opt/netbox/
``` sudo cp /opt/netbox-X.Y.Z/netbox/netbox/configuration.py /opt/netbox/netbox/netbox/
sudo cp /opt/netbox-X.Y.Z/netbox/netbox/ldap_config.py /opt/netbox/netbox/netbox/
Copy your local requirements file if used:
```no-highlight
# cp /opt/netbox-X.Y.Z/local_requirements.txt /opt/netbox/local_requirements.txt
```
Also copy the LDAP configuration if using LDAP:
```no-highlight
# cp /opt/netbox-X.Y.Z/netbox/netbox/ldap_config.py /opt/netbox/netbox/netbox/ldap_config.py
``` ```
Be sure to replicate your uploaded media as well. (The exact action necessary will depend on where you choose to store your media, but in general moving or copying the media directory will suffice.) Be sure to replicate your uploaded media as well. (The exact action necessary will depend on where you choose to store your media, but in general moving or copying the media directory will suffice.)
```no-highlight ```no-highlight
# cp -pr /opt/netbox-X.Y.Z/netbox/media/ /opt/netbox/netbox/ sudo cp -pr /opt/netbox-X.Y.Z/netbox/media/ /opt/netbox/netbox/
``` ```
Also make sure to copy over any custom scripts and reports that you've made. Note that if these are stored outside the project root, you will not need to copy them. (Check the `SCRIPTS_ROOT` and `REPORTS_ROOT` parameters in the configuration file above if you're unsure.) Also make sure to copy or link any custom scripts and reports that you've made. Note that if these are stored outside the project root, you will not need to copy them. (Check the `SCRIPTS_ROOT` and `REPORTS_ROOT` parameters in the configuration file above if you're unsure.)
```no-highlight ```no-highlight
# cp -r /opt/netbox-X.Y.Z/netbox/scripts /opt/netbox/netbox/ sudo cp -r /opt/netbox-X.Y.Z/netbox/scripts /opt/netbox/netbox/
# cp -r /opt/netbox-X.Y.Z/netbox/reports /opt/netbox/netbox/ sudo cp -r /opt/netbox-X.Y.Z/netbox/reports /opt/netbox/netbox/
``` ```
If you followed the original installation guide to set up gunicorn, be sure to copy its configuration as well: If you followed the original installation guide to set up gunicorn, be sure to copy its configuration as well:
```no-highlight ```no-highlight
# cp /opt/netbox-X.Y.Z/gunicorn.py /opt/netbox/gunicorn.py sudo cp /opt/netbox-X.Y.Z/gunicorn.py /opt/netbox/
``` ```
### Option B: Clone the Git Repository ### Option B: Clone the Git Repository
@ -73,10 +62,9 @@ If you followed the original installation guide to set up gunicorn, be sure to c
This guide assumes that NetBox is installed at `/opt/netbox`. Pull down the most recent iteration of the master branch: This guide assumes that NetBox is installed at `/opt/netbox`. Pull down the most recent iteration of the master branch:
```no-highlight ```no-highlight
# cd /opt/netbox cd /opt/netbox
# git checkout master sudo git checkout master
# git pull origin master sudo git pull origin master
# git status
``` ```
## Run the Upgrade Script ## Run the Upgrade Script
@ -84,10 +72,10 @@ This guide assumes that NetBox is installed at `/opt/netbox`. Pull down the most
Once the new code is in place, verify that any optional Python packages required by your deployment (e.g. `napalm` or `django-auth-ldap`) are listed in `local_requirements.txt`. Then, run the upgrade script: Once the new code is in place, verify that any optional Python packages required by your deployment (e.g. `napalm` or `django-auth-ldap`) are listed in `local_requirements.txt`. Then, run the upgrade script:
```no-highlight ```no-highlight
# ./upgrade.sh sudo ./upgrade.sh
``` ```
This script: This script performs the following actions:
* Destroys and rebuilds the Python virtual environment * Destroys and rebuilds the Python virtual environment
* Installs all required Python packages (listed in `requirements.txt`) * Installs all required Python packages (listed in `requirements.txt`)
@ -99,23 +87,20 @@ This script:
* Clears all cached data to prevent conflicts with the new release * Clears all cached data to prevent conflicts with the new release
!!! note !!! note
It's possible that the upgrade script will display a notice warning of unreflected database migrations: If the upgrade script prompts a warning about unreflected database migrations, this indicates that some change has
been made to your local codebase and should be investigated. Never attempt to create new migrations unless you are
Your models have changes that are not yet reflected in a migration, and so won't be applied. intentionally modifying the database schema.
Run 'manage.py makemigrations' to make new migrations, and then re-run 'manage.py migrate' to apply them.
This may occur due to semantic differences in environment, and can be safely ignored. Never attempt to create new migrations unless you are intentionally modifying the database schema.
## Restart the NetBox Services ## Restart the NetBox Services
!!! warning !!! warning
If you are upgrading from an installation that does not use a Python virtual environment, you'll need to update the systemd service files to reference the new Python and gunicorn executables before restarting the services. These are located in `/opt/netbox/venv/bin/`. See the example service files in `/opt/netbox/contrib/` for reference. If you are upgrading from an installation that does not use a Python virtual environment (any release prior to v2.7.9), you'll need to update the systemd service files to reference the new Python and gunicorn executables before restarting the services. These are located in `/opt/netbox/venv/bin/`. See the example service files in `/opt/netbox/contrib/` for reference.
Finally, restart the gunicorn and RQ services: Finally, restart the gunicorn and RQ services:
```no-highlight ```no-highlight
# sudo systemctl restart netbox netbox-rq sudo systemctl restart netbox netbox-rq
``` ```
!!! note !!! note
It's possible you are still using supervisord instead of systemd. If so, please see the instructions for [migrating to systemd](migrating-to-systemd.md). If upgrading from an installation that uses supervisord, please see the instructions for [migrating to systemd](migrating-to-systemd.md). The use of supervisord is no longer supported.

3
upgrade.sh
View File

@ -84,7 +84,8 @@ if [ -v WARN_MISSING_VENV ]; then
echo "--------------------------------------------------------------------" echo "--------------------------------------------------------------------"
echo "WARNING: No existing virtual environment was detected. A new one has" echo "WARNING: No existing virtual environment was detected. A new one has"
echo "been created. Update your systemd service files to reflect the new" echo "been created. Update your systemd service files to reflect the new"
echo "Python and gunicorn executables." echo "Python and gunicorn executables. (If this is a new installation,"
echo "this warning can be ignored.)"
echo "" echo ""
echo "netbox.service ExecStart:" echo "netbox.service ExecStart:"
echo " ${VIRTUALENV}/bin/gunicorn" echo " ${VIRTUALENV}/bin/gunicorn"