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.
To build NAV, you need at least the following:
- make
- automake
- autoconf
- Python >= 2.7.0 < 3
- Sphinx >= 1.0 (for building this documentation)
- A sass compiler >= 3.2.12, < 3.4 to build the NAV web interface’s stylesheets. Installing the rubygem sass or using the package ruby-sass from Debian 8 (Jessie) or newer would satisfy this requirement.
To run NAV, these software packages are required:
- Apache2 + mod_wsgi (or, really, any web server that supports the WSGI interface)
- PostgreSQL >= 9.4 (With the
hstore
extension available)- Graphite
- Python >= 2.7.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.
Required Python modules can be installed from source using pip
install -r requirements.txt (some of these modules are extensions that will
require some C libraries to be correctly built. These include the psycopg2
driver and the python-ldap
module), or you may opt to use your OS’ package
manager to install these dependencies. The current requirements are as
follows:
Django==1.7.1
# for debian build-deps, see the apt-get commands in
# tools/vagrant-provision.sh
asciitree==0.3.3 # optional, for naventity
configparser==3.5.0 ; python_version < '3'
psycopg2==2.5.4 # requires libpq to build
IPy==0.83
twisted>=14.0.1,<18 ; python_version < '3'
twisted>=16.6.0,<18 ; python_version >= '3'
networkx>=1.7,<1.8
xmpppy==0.5.0rc1 # optional, for alerting via Jabber
Pillow==3.0.0
pyrad==2.1
python-ldap==2.4.10 ; python_version < '3' # optional for LDAP authentication, requires libldap (OpenLDAP) to build
sphinx>=1.0
django-crispy-forms==1.3.2
crispy-forms-foundation==0.2.3
django-hstore>=1.2.4,<1.3
feedparser>=5.1.2,<5.2
markdown==2.5.1
dnspython==1.15.0
# REST framework
djangorestframework==2.4.4
django-filter>=0.7,<0.8
iso8601
pynetsnmp-2==0.1.3
If you want to connect a mobile phone to your NAV server and enable SMS alerts
in alert profiles, you will need to install Gammu and the Python
gammu
module. The SMS daemon can use plugins to dispatch text
messages through other means, but using Gammu as an SMS dispatcher is the
default.
If you wish to use the Jabber plugin for alertengine, the python module xmpp
is required.
To build and install NAV:
./autogen.sh
./configure
make
make install
If you wish to configure NAV to run from a different location than the default
/usr/local/nav
you should specify a new directory using the
--prefix=
option of the configure script, e.g. ./configure
--prefix=/opt/nav
.
If you are building an RPM package (or similar) of NAV, you may wish to have
the files installed in a physically different location (a temporary build
directory) than what you configured the package for. In this case, you should
specify this build directory by adding
DESTDIR=/your/build/directory
to the make install
command.
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.
For more details on setting up PostgreSQL and initializing the schema, please
refer to the sql/README
file.
By default, NAV’s Python libraries are not installed in Python’s
site-packages
directory. To make them available system-wide, you need
to add the path to the libraries to Python’s search path.
One way of accomplishing this is altering Python’s sys.path
value at
startup time, by modifying or adding your Python installation’s
sitecustomize.py
module, which is loaded every time python runs. Add
these lines:
import sys
__navpath = "/usr/local/nav/lib/python"
if __navpath not in sys.path:
sys.path.append(__navpath)
You should now be able to run the python command line interpreter and run import nav without a hitch:
$ python
Python 2.7.3 (default, Sep 26 2013, 20:03:06)
[GCC 4.6.3] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> import nav
>>>
NAV’s web interface is implemented using the Django framework, and can be served in any web server environment supported by Django.
NAV does, however, come with Apache configuration to serve the web interface using mod_wsgi. For legacy reasons, NAV requires being served at the document root of the web server domain. The apache config file can be included in your virtualhost config, which needn’t contain much more than this:
ServerName nav.example.org
ServerAdmin webmaster@example.org
Include /usr/local/nav/etc/apache/apache.conf
NAV processes should run as the navcron user (the name of this user is configurable via the ./configure command at build-time), and preferably, a separate nav group should be added to the system:
sudo addgroup --system nav
sudo adduser --system --no-create-home --home /usr/local/nav \
--shell /bin/sh --ingroup nav navcron;
If you want to use NAV’s SMS functionality in conjunction with Gammu, you should make sure the navcron user is allowed to write to the serial device you’ve connected your GSM device to. Often, this device has a group ownership set to the dialout group, so the easieast route is to add the navcron user to the dialout group:
sudo addgroup navcron dialout
You should also make sure navcron has permission to write log files, pid files and various other state information:
cd /usr/local/nav/var
sudo chown -R navcron:nav .
NAV uses Graphite to store and retrieve/graph time-series data. NAV must be
configured with the IP address and port of your Graphite installation’s Carbon
backend, and the URL to the Graphite-web frontend used for graphing. These
settings can be configured in the graphite.conf
configuration file.
Note
NAV requires the Carbon backend’s UDP listener to be enabled, as it will only transmit metrics over UDP.
For a simple, local Graphite installation, you may not need to touch this configuration file at all, but at its simplest it looks like this:
[carbon]
host = 127.0.0.1
port = 2003
[graphiteweb]
base = http://localhost:8000/
Installing Graphite itself is out of scope for this guide, but you will need to configure some options before letting NAV send data to Graphite.
First and foremost, you will need to enable the UDP listener in the
configuration file carbon.conf
.
For performance reasons, Carbon will also limit the number of new Whisper
files that can be created per minute. This number is fairly low by default,
and when starting NAV for the first time, it may send a ton of new metrics
very fast. If the limit is set to 50, it will take a long time before all
the metrics are created. You might want to increase the
MAX_CREATES_PER_MINUTE
option, or temporarily set it to inf
.
You should add the suggested storage-schema configurations for the
various nav
prefixes listed in etc/graphite/storage-schemas.conf
:
# Recommended Whisper schema definitions for using Graphite with NAV.
#
# If you already have a Graphite installation you wish to use, use these
# examples to adapt your own config.
#
# Carbon's internal metrics. This entry should match what is specified in
# CARBON_METRIC_PREFIX and CARBON_METRIC_INTERVAL settings
[carbon]
pattern = ^carbon\.
retentions = 60:90d
# Statistics - store data for a long time is more important than short
# intervals.
[nav-statistics]
pattern = ^nav\.stats\.
retentions = 300s:10d, 1h:100d, 1d:6y
# NAV device/system metrics
[nav-system]
pattern = ^nav\..*(system|cpu|memory|services|ipdevpoll|sensors)\.
retentions = 60s:1d, 300s:7d, 30m:12d, 2h:50d, 1d:600d
# NAV multicast metrics
[nav-multicast]
pattern = ^nav\.multicast\.groups\.
retentions = 60s:1d, 300s:7d, 30m:12d, 2h:50d, 1d:600d
# NAV pping metrics. The default pping configuration pings in 20 second
# intervals; the most detailes retention archive should match up with this.
[nav-pping]
pattern = ^nav\..*\.ping\.
retentions = 20s:6h, 60s:1d, 300s:7d, 30m:12d, 2h:50d, 1d:600d
# NAV IP prefix utilization metrics. Default ARP/ND collection interval is
# 30 minutes.
[nav-prefix]
pattern = ^nav\.prefixes\.
retentions = 30m:30d, 2h:90d, 6h:600d
# NAV generic metric retention archive
[nav-generic]
pattern = ^nav\.
retentions = 300s:7d, 30m:12d, 2h:50d, 1d:600d
# A not-very-sane default for any metric not caught by the above.
[default_1min_for_1day]
pattern = .*
retentions = 60s:1d
The highest precision retention archives are the most important ones here, as their data point interval must correspond with the collection intervals of various NAV processes. Other than that, the retention periods and the precision of any other archive can be freely experimented with.
Remember, these schemas apply to new Whisper files as they are created. You should not start NAV until the schemas have been configured, otherwise the Whisper files will be created with the global Graphite defaults, and your data may be munged or inaccurate, and your graphs will be spotty.
You should add the suggested storage-aggregation configurations listed in
the file etc/graphite/storage-aggregation.conf
:
# Recommended Whisper aggregation methods for using Graphite with NAV.
#
# If you already have a Graphite installation you wish to use, use these
# examples to adapt your own config.
#
# ipdevpoll jobs don't necesarily run very often; an xFilesFactor of 0 ensures
# we roll up everything into the lower precision archives no matter how often
# runs are logged.
[ipdevpoll]
pattern = ^nav\..*\.ipdevpoll\..*runtime$
xFilesFactor = 0
aggregationMethod = average
# Any kind of event counter NAV uses will log the number of events since the
# last time the metric was logged, so the approprate aggregation is to sum the
# counts.
[event-counts]
pattern = ^nav\..*-count$
xFilesFactor = 0
aggregationMethod = sum
# NAV stores the raw octet/packet/error/etc counters of interfaces in Graphite.
# Since these counter values are absolute, and the rates are calculated using
# the difference of the port counter and the time difference between two
# counter numbers, the appropriate aggregation method would be to picke the
# last counter value when rolling up.
[port-counters]
pattern = ^nav\..*ports\..*
aggregationMethod = last
These will ensure that time-series data sent to Graphite by NAV will be aggregated properly when Graphite rolls them into lower-precision archives.