= Installing !NetBox on Ubuntu 20.04 =
Import downloaded Ubuntu 20.04 for Netbox OVA file into Oracle virtual box from File > Import Appliance.

While importing make sure to select Generate new MAC addresses for all Network Adapters from MAC Address Policy.

The following software and services are needed to run the !NetBox.
* PostgreSQL database
* Redis
* !NetBox components
* Gunicorn
* HTTP server
!NetBox requires PostgreSQL 10 or later. Please note that MySQL and other relational databases are not supported.

=== PostgreSQL Database Installation ===
{{{
# sudo apt update
# sudo apt install -y postgresql
}}}

Once PostgreSQL has been installed, start the service and enable it to run at boot:
{{{
# sudo systemctl start postgresql
# sudo systemctl enable postgresql
}}}

=== Database Creation ===
At a minimum, we need to create a database for !NetBox and assign it a username and password for authentication. Start by invoking the PostgreSQL shell as the system Postgres user.
{{{
# sudo -u postgres psql
}}}

Within the shell, enter the following commands to create the database and user (role), substituting your own value for the password:
{{{
CREATE DATABASE netbox;
CREATE USER netbox WITH PASSWORD 'netbox123';
GRANT ALL PRIVILEGES ON DATABASE netbox TO netbox;
}}}
Do not use the password from the example. Choose a strong, random password to ensure secure database authentication for your !NetBox installation.

Once complete, enter ''' \q ''' to exit the PostgreSQL shell.

=== Redis Installation ===

Redis is an in-memory key-value store which !NetBox employs for caching and queuing. This section entails the installation and configuration of a local Redis instance.
Redis v4.0 or later required.
{{{
# sudo apt install -y redis-server
}}}

Before continuing, verify that your installed version of Redis is at least v4.0:
{{{
# redis-server -v
}}}
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.

{{{
# sudo systemctl start redis-server.service
}}}

Verify Service Status

Use the ''' redis-cli ''' utility to ensure the Redis service is functional:
{{{
# redis-cli ping
}}}
If successful, you should receive a ''' PONG ''' response from the server.

== !NetBox Installation ==
This section of the documentation discusses installing and configuring the !NetBox application itself.
=== Install System Packages ===
Begin by installing all system packages required by !NetBox and its dependencies.
Python 3.8 or later required

{{{
# sudo apt install -y python3 python3-pip python3-venv python3-dev build-essential libxml2-dev libxslt1-dev libffi-dev libpq-dev libssl-dev zlib1g-dev
}}}
Before continuing, check that your installed Python version is at least 3.8:
{{{
# python3 -V
}}}
=== 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 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 ===
Download the latest stable release from !GitHub as a tarball or ZIP archive and extract it to your desired path. In this example, we'll use ''' /opt/netbox ''' as the !NetBox root.
{{{
# sudo wget https://github.com/netbox-community/netbox/archive/vX.Y.Z.tar.gz
# sudo tar -xzf vX.Y.Z.tar.gz -C /opt
# sudo ln -s /opt/netbox-X.Y.Z/ /opt/netbox
}}}

=== Option B: Clone the Git Repository ===
Create the base directory for the !NetBox installation. For this guide, we'll use ''' /opt/netbox. '''
{{{
# sudo mkdir -p /opt/netbox/
# cd /opt/netbox/
}}}
if ''' git ''' is not already installed, install it:
{{{
# sudo apt 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.)
{{{
sudo git clone -b master --depth 1 https://github.com/netbox-community/netbox.git .
}}}
The git clone command should generate output similar to the following:
{{{
Cloning into '.'...
remote: Enumerating objects: 996, done.
remote: Counting objects: 100% (996/996), done.
remote: Compressing objects: 100% (935/935), done.
remote: Total 996 (delta 148), reused 386 (delta 34), pack-reused 0
Receiving objects: 100% (996/996), 4.26 MiB | 9.81 MiB/s, done.
Resolving deltas: 100% (148/148), done.
}}}

=== Create the !NetBox System User ===
Create a system user account named ''' netbox '''. We'll configure the WSGI and HTTP services to run under this account. We'll also assign this user ownership of the media directory. This ensures that !NetBox will be able to save uploaded files.
{{{
# sudo adduser --system --group netbox
# sudo chown --recursive netbox /opt/netbox/netbox/media/
}}}

=== Configuration ===
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.
{{{
# cd /opt/netbox/netbox/netbox/
# sudo cp configuration_example.py configuration.py
}}}
Open ''' configuration.py ''' with your preferred editor to begin configuring !NetBox. !NetBox offers many configuration parameters, but only the following four are required for new installations:
* ALLOWED_HOSTS
* DATABASE
* REDIS
* SECRET_KEY 

=== ALLOWED_HOSTS ===
This is a list of the valid hostnames and IP addresses by which this server can be reached. You must specify at least one name or IP address. (Note that this does not restrict the locations from which !NetBox may be accessed: It is merely for HTTP host header validation.)

{{{
# vim configuration.py

ALLOWED_HOSTS = ['netbox.example.com', '192.0.2.123']
}}}
If you are not yet sure what the domain name and/or IP address of the !NetBox installation will be, you can set this to a wildcard (asterisk) to allow all host values:
{{{
ALLOWED_HOSTS = ['*']
}}}

=== DATABASE ===
This parameter holds the database configuration details. You must define the username and password used when you configured PostgreSQL. If the service is running on a remote host, update the '''HOST and PORT ''' parameters accordingly. 
{{{
DATABASE = {
    'NAME': 'netbox',               # Database name
    'USER': 'netbox',               # PostgreSQL username
    'PASSWORD': 'netbox123',        # PostgreSQL password
    'HOST': 'localhost',            # Database server
    'PORT': '',                     # Database port (leave blank for default)
    'CONN_MAX_AGE': 300,            # Max database connection age (seconds)
}
}}}

=== REDIS ===
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. 

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.
{{{
REDIS = {
    'tasks': {
        'HOST': 'localhost',      # Redis server
        'PORT': 6379,             # Redis port
        'PASSWORD': '',           # Redis password (optional)
        'DATABASE': 0,            # Database ID
        'SSL': False,             # Use SSL (optional)
    },
    'caching': {
        'HOST': 'localhost',
        'PORT': 6379,
        'PASSWORD': '',
        'DATABASE': 1,            # Unique ID for second database
        'SSL': False,
    }
}
}}}
save the file and exit. Create the '''SECRET_KEY''' as follows.
=== SECRET_KEY ===
This parameter must be assigned a randomly-generated key employed as a salt for hashing and related cryptographic functions. (Note, however, that it is never directly used in the encryption of secret data.) This key must be unique to this installation and is recommended to be at least 50 characters long. It should not be shared outside the local system.

A simple Python script named ''' generate_secret_key.py ''' is provided in the parent directory to assist in generating a suitable key:
{{{
# python3 ../generate_secret_key.py
}}}
open the configuration file again and insert the '''SECRET_KEY'''.
{{{
# vim configuration.py
}}}
When you have finished modifying the configuration, remember to save the file.

=== Run the Upgrade Script ===
Once !NetBox has been configured, we're ready to proceed with the actual installation. We'll run the packaged upgrade script (upgrade.sh) to perform the following actions:

* Create a Python virtual environment
* Installs all required Python packages
* Run database schema migrations
* Builds the documentation locally (for offline use)
* Aggregate static resource files on disk

{{{
# sudo /opt/netbox/upgrade.sh
}}}
Note that Python 3.8 or later is required for !NetBox v3.2 and later releases. 

=== Create a Super User ===
!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:
{{{
# source /opt/netbox/venv/bin/activate
}}}
Once the virtual environment has been activated, you should notice the string ''' (venv) ''' prepended to your console prompt.

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.
{{{
# cd /opt/netbox/netbox
# python3 manage.py createsuperuser
}}}

Set ''' Username as Admin and Password as admin '''. Email Not required.
=== Test the Application ===
At this point, we should be able to run !NetBox's development server for testing. We can check by starting a development instance:
{{{
# python3 manage.py runserver 0.0.0.0:8000 --insecure
}}}
If successful, you should see output similar to the following:
{{{
Watching for file changes with StatReloader
Performing system checks...

System check identified no issues (0 silenced).
August 30, 2021 - 18:02:23
Django version 3.2.6, using settings 'netbox.settings'
Starting development server at http://127.0.0.1:8000/
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. Try logging in using the username and password specified when creating a superuser.

Type ''' Ctrl+c ''' to stop the development server.

=== Gunicorn ===
Like most Django applications, !NetBox runs as a WSGI application behind an HTTP server. This documentation shows how to install and configure gunicorn (which is automatically installed with !NetBox) for this role, however other WSGI servers are available and should work similarly well. uWSGI is a popular alternative.

''' 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 local changes to it do not get overwritten by a future upgrade.)

{{{
# sudo cp /opt/netbox/contrib/gunicorn.py /opt/netbox/gunicorn.py
}}}

''' 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 ''' daemon:
{{{
# sudo cp -v /opt/netbox/contrib/*.service /etc/systemd/system/
# sudo systemctl daemon-reload
}}}
Then, start the ''' netbox ''' and ''' netbox-rq ''' services and enable them to initiate at boot time:
{{{
# sudo systemctl start 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:
{{{
systemctl status netbox.service
}}}

You should see output similar to the following:
{{{
● netbox.service - NetBox WSGI Service
     Loaded: loaded (/etc/systemd/system/netbox.service; enabled; vendor preset: enabled)
     Active: active (running) since Mon 2021-08-30 04:02:36 UTC; 14h ago
       Docs: https://docs.netbox.dev/
   Main PID: 1140492 (gunicorn)
      Tasks: 19 (limit: 4683)
     Memory: 666.2M
     CGroup: /system.slice/netbox.service
             ├─1140492 /opt/netbox/venv/bin/python3 /opt/netbox/venv/bin/gunicorn --pid /va>
             ├─1140513 /opt/netbox/venv/bin/python3 /opt/netbox/venv/bin/gunicorn --pid /va>
             ├─1140514 /opt/netbox/venv/bin/python3 /opt/netbox/venv/bin/gunicorn --pid /va>
...
}}}

Once you've verified that the WSGI workers are up and running, move on to HTTP server setup.

=== HTTP Server Setup ===
''' Obtain an SSL Certificate '''

To enable HTTPS access to !NetBox, you'll need a valid SSL certificate. You can purchase one from a trusted commercial provider, obtain one for free from Let's Encrypt, or generate your own (although self-signed certificates are generally untrusted). Both the public certificate and private key files need to be installed on your !NetBox server in a location that is readable by the netbox user.

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.
{{{
# sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
-keyout /etc/ssl/private/netbox.key \
-out /etc/ssl/certs/netbox.crt
}}}
The above command will prompt you for additional details of the certificate; all of these are optional. So you can press Enter and keep continue.

''' HTTP Server Installation '''

''' Installing nginx '''

Begin by installing 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.)
{{{
# 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.
{{{
# sudo rm /etc/nginx/sites-enabled/default
# sudo ln -s /etc/nginx/sites-available/netbox /etc/nginx/sites-enabled/netbox
}}}
Finally, restart the ''' nginx ''' service to use the new configuration.
{{{
# sudo systemctl restart nginx
}}}
At this point, you should be able to connect to the HTTPS service at the server name or IP address you provided.

== !NetBox Lab ==
you can download working instance of !NetBox using following link:

https://docs.learn.ac.lk/index.php/s/DeENMSo1gAayciM

Lab Instructions:
 
https://ws.learn.ac.lk/attachment/wiki/Nmm2022/Agenda/Netbox/NetBox%20Lab.pdf


=== References for !NetBox configurations: ===
https://docs.netbox.dev/en/stable/

https://www.youtube.com/c/KeepingITSimple/search?query=netbox


'''After completing the lab''', you should email a screenshot of a configuration file(s) to ​deepthi@learn.ac.lk. Please mention your 'your workshop registration details, session and the session topic' in the email.