Installing NAV from source code

This is a generic guide to installing NAV from source code on a *NIX flavored operating system. The specifics of how to install NAV’s dependencies, such as PostgreSQL or Graphite will be entirely up to you and your choice of OS. Note that building NAV from source will also require Node.js and npm to be installed in order to manage frontend assets.

Dependencies

This section specifies what software packages are needed to build and run NAV. Be aware that many of these packages have dependencies of their own.

Build requirements

To build NAV, you need at least the following:

  • Python >= 3.9.0

  • Sphinx >= 1.0 (for building this documentation)

Additionally to build frontend assets (like CSS and JS), you will need:

  • Node.js >= 14.0

  • npm >= 6.0

Runtime requirements

To run NAV, these software packages are required:

  • Apache2 + mod_wsgi (or, really, any web server that supports the WSGI interface)

  • PostgreSQL >= 13 (With the hstore extension available)

  • Graphite

  • Python >= 3.9.0

  • nbtscan = 1.5.1

  • dhcping (only needed if using DHCP service monitor)

PostgreSQL and Graphite are services that do not necessarily need to run on the same server as NAV.

While the required Python modules can be installed from your OS package manager, most distributions do not provide all of them, or cannot provide them in the required versions. We recommend creating a Python virtual environment (virtualenv), which will ensure NAV’s Python requirements do not interfere with your system Python libraries. Use pip to install all Python requirements from the Python Package Index (PyPI), using the method described below. The packages can also be installed from PyPI in a separate step, using the pip tool and the provided requirements and constraints files:

pip install -r requirements.txt -c constraints.txt

However, some of the required modules are C extensions that will require the presence of some C libraries to be correctly built (unless PyPI provides binary wheels for your platform). These include the psycopg2 driver and the python-ldap and Pillow modules.

The current Python requirements are as follows:

Django>=4.2,<4.3
pytz

# for debian build-deps, see the apt-get commands in
# Dockerfile

asciitree==0.3.3  # optional, for naventity
psycopg2==2.9.9  # requires libpq to build
IPy==1.01
pyaml

twisted>=23.8.0,<24.0

networkx==2.6.3
# Cannot be removed as long as qrcode is included
Pillow>3.3.2
qrcode>7.4
pyrad==2.1
sphinx==7.4.7
sphinxcontrib-programoutput==0.17
sphinxcontrib-django
# Needed for autogenerated docs
Markdown==3.3.6

feedparser==6.0.8
dnspython<3.0.0,>=2.1.0

django-filter>=2
djangorestframework>=3.12

# REST framework
iso8601

pynetsnmp-2>=0.1.10

napalm==3.4.1

git+https://github.com/Uninett/drf-oidc-auth@v4.0#egg=drf-oidc-auth

# The following modules are really sub-requirements of Twisted, not of
# NAV directly.  They may be optional from Twisted's point of view,
# but they are required for parts of the Twisted library that NAV uses:
#
# PyOpenSSL is required for TLS verification during PaloAlto API GET operations
PyOpenSSL==23.3.0
# service-identity is required to make TLS communication libraries shut up about potential MITM attacks
service-identity==21.1.0

requests

pyjwt>=2.6.0

Installing NAV

First you need to build the static assets. To do this, you will need to have Node.js and npm installed. Once you have these installed, you can run the following command to build the CSS assets:

npm install
npm run build:sass

This will build the CSS assets and place them in the python/nav/web/static/css directory.

We recommend installing NAV into a Python virtual environment, to avoid interfering with your system-wide Python libraries. Pick a suitable path for the virtual environment (e.g. /opt/nav), create it and activate it in your shell before installing NAV:

python3 -m venv /opt/nav
source /opt/nav/bin/activate

To build and install NAV and all its Python dependencies in the activated virtual environment, run:

pip install -r requirements.txt -c constraints.txt .

If you want to make sure you can run all NAV programs without first explicitly activating the virtual environment in a shell, you can add the virtual environment’s bin directory to your system’s PATH variable, e.g.:

export PATH=$PATH:/opt/nav/bin

Initializing the configuration

NAV will look for its configuration files in various locations on your file system. These locations can be listed by running:

nav config path

To install a set of pristine NAV configuration files into one of these locations, e.g. in /etc/nav, run:

nav config install /etc/nav

To verify that NAV can find its main configuration file, run:

nav config where

Initializing the database

Before NAV can run, the database schema must be installed in your PostgreSQL server. NAV can create a database user and a database schema for you.

Choose a password for your NAV database user and set this in the userpw_nav in the db.conf config file. As the postgres superuser, run the following command:

navsyncdb -c

This will attempt to create a new database user, a new database and initialize it with NAV’s schema.

Configuring the web interface

NAV’s web interface is implemented using the Django framework, and can be served in any web server environment supported by Django (chiefly, any environment that supports WSGI). This guide is primarily concerned with Apache 2.

An example configuration file for Apache2 is provided the configuration directory, apache/apache.conf.example. This configuration uses mod_wsgi to serve the NAV web application, and can be modified to suit your installation paths. Once complete, it can be included in your virtualhost config, which needn’t contain much more than this:

ServerName nav.example.org
ServerAdmin webmaster@example.org

Include /path/to/your/nav/apache.conf

Important

You should always protect your NAV web site using SSL!

Installing static resources

You want your web server to be able to serve all of NAV’s static resources. You can install all of them by issuing the following command:

# django-admin collectstatic --settings=nav.django.settings
You have requested to collect static files at the destination
location as specified in your settings:

    /usr/share/nav/www/static

This will overwrite existing files!
Are you sure you want to do this?

Type 'yes' to continue, or 'no' to cancel:

In this example, type yes, hit Enter, and ensure your web server’s document root points to /usr/share/nav/www, because that is where the static directory is located. If that doesn’t suit you, you will at least need an Alias to point the /static URL to the static directory.

Users and privileges

Apart from the pping and snmptrapd daemons, no NAV processes should ever be run as root. You should create a non-privileged system user and group, and ensure the NAV_USER option in nav.conf is set accordingly. Also make sure this user has permissions to write to the directories configured in PID_DIR, LOG_DIR and UPLOAD_DIR.

Note

The pping and snmptrapd daemons must be started as root to be able to create privileged communication sockets. Both daemons will drop privileges and run as the configured non-privileged user as soon as the sockets have been acquired.

Building the documentation

If you wish, this HTML documentation can be built separately using this step:

sphinx-build

The resulting files will typically be placed in build/sphinx/html/.

If you want to serve this documentation on your NAV web server, you should copy the html directory to a suitable location and make sure that location is served as /doc on the web server. If using the example Apache configuration (apache.conf.example), there is a define named documentation_path, which can be set to point to this file system location.