Command line utilities provided in NAV

In addition to various daemon and cron job programs, NAV provides some useful command line utilities to control NAV or work with NAV data.

nav

nav is the most central program to control NAV’s background processes and cron jobs, regardless of whether you are running under SysV init system, systemd or other process control systems.

If NAV doesn’t appear to be doing anything, the first order of business is checking the state of its background processes with the command nav status

Usage

usage: nav [-h] [--nonroot] [--verbose]
           {info,list,restart,start,status,stop,version,config} ...

This command is your interface to start, stop and query NAV services.

positional arguments:
  {info,list,restart,start,status,stop,version,config}
    info                lists each service and their associated description
    list                lists all the available service names
    restart             restarts services
    start               starts services
    status              reports the status of services
    stop                stops services
    version             reports the currently installed NAV version
    config              query or manipulate NAV configuration

optional arguments:
  -h, --help            show this help message and exit
  --nonroot             don't complain about not having root privileges
  --verbose, -V         let output from subcommands pass through

The selected command will be applied to all known services, unless you specify
a list of services after the command.

navcheckservice

This utility can be used to test servicemon checker plugins against arbitrary hosts (i.e. not necessarily registered in NAV).

Usage

usage: navcheckservice [-h] IP SYSNAME HANDLER

Utility to run one NAV servicemon checker plugin against an arbitrary host.
Useful for testing or debugging individual servicemon plugins.

positional arguments:
  IP          IP address of host to check
  SYSNAME     Name to associate with this device. Does not need to a be real
              name in any sense.
  HANDLER     Handler name of the checker plugin to use. Available handler
              plugins are ftp, https, imaps, ssh, mysql, oracle, radius, pop3,
              rpc, smtp, smb, dc, imap, dns, postgresql, dummy, dhcp, http,
              port, ldap.

optional arguments:
  -h, --help  show this help message and exit

Available handler plugins

These handler plugins are currently available from servicemon:

dc
dhcp
dns
dummy
ftp
http
https
imap
imaps
ldap
mysql
oracle
pop3
port
postgresql
radius
rpc
smb
smtp
ssh

navdf

This command is useful to generate lists of devices registered in NAV. Used without arguments, it will print out the sysname of every NAV-registered device.

It is mostly a programmers interface to filtering the device list: It takes an argument that must be valid Python code and a valid Django QuerySet filtering function, and therefore requires a bit of knowledge about how the NAV database is modeled in the Django ORM.

Please refer to the Django QuerySet documentation for more information about how to build filters.

Usage

/home/docs/checkouts/readthedocs.org/user_builds/nav/envs/latest/lib/python3.9/site-packages/nav/django/settings.py:73: UserWarning: Could not get connection parameters from db.conf: [Errno 2] No such file or directory: 'db.conf'
  warnings.warn(f"Could not get connection parameters from db.conf: {e}")
usage: navdf [filter]

Lists and filters IP devices monitored by NAV

positional arguments:
  filter      The filter expression must be a method call applicable to the
              Django-based Netbox model's manager class. Example:
              "filter(category__id='GSW')"

optional arguments:
  -h, --help  show this help message and exit

Recipes

List only GSW and GW category devices:

navdf "filter(category__id__in=(('GW', 'GSW')))"

List only Juniper devices:

navdf "filter(type__vendor__id='juniper')"

List only Cisco switches:

navdf "filter(type__vendor__id='cisco', category_id__in=(('SW', 'EDGE')))"

List only switches in the room 101:

navdf "filter(room__id='101', category_id__in=(('SW', 'EDGE')))"

navdump

This command can dump SeedDB data into CSV text files, which can later be re-imported in another NAV instance’s SeedDB bulk import feature.

Typical usage patterns are described in the data migration howto.

Usage

/home/docs/checkouts/readthedocs.org/user_builds/nav/envs/latest/lib/python3.9/site-packages/nav/django/settings.py:73: UserWarning: Could not get connection parameters from db.conf: [Errno 2] No such file or directory: 'db.conf'
  warnings.warn(f"Could not get connection parameters from db.conf: {e}")
usage: navdump [-h] [-s SEP] [-t TABLE] [-o FILE] [-a]

Dumps NAV database seed data to importable files

optional arguments:
  -h, --help            show this help message and exit
  -s SEP, --separator SEP
                        use SEP to separate fields in output, [default :]
  -t TABLE, --table TABLE
                        dump data from TABLE
  -o FILE, --output FILE
                        dump data to FILE instead of stdout
  -a, --all             dump all tables to files named TABLE.txt

naventity

This SNMP-specific utility can query the contents of a NAV-registered device’s ENTITY-MIB::entPhysicalTable and output the entity hierarchy to the terminal. This is a useful way of discovering what a device is actually reporting about its physical contents to NAV, or if it even supports this standard mechanism.

The ENTITY-MIB is defined by the IETF RFC 6933, and is the primary way NAV learns about the pysical innards of a network device.

Usage

/home/docs/checkouts/readthedocs.org/user_builds/nav/envs/latest/lib/python3.9/site-packages/nav/django/settings.py:73: UserWarning: Could not get connection parameters from db.conf: [Errno 2] No such file or directory: 'db.conf'
  warnings.warn(f"Could not get connection parameters from db.conf: {e}")
Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/nav/envs/latest/bin/naventity", line 5, in <module>
    from nav.bin.naventity import main
  File "/home/docs/checkouts/readthedocs.org/user_builds/nav/envs/latest/lib/python3.9/site-packages/nav/bin/naventity.py", line 35, in <module>
    from nav.ipdevpoll.snmp.common import SnmpError, SNMPParameters
  File "/home/docs/checkouts/readthedocs.org/user_builds/nav/envs/latest/lib/python3.9/site-packages/nav/ipdevpoll/snmp/__init__.py", line 20, in <module>
    import pynetsnmp.twistedsnmp
  File "/home/docs/checkouts/readthedocs.org/user_builds/nav/envs/latest/lib/python3.9/site-packages/pynetsnmp/twistedsnmp.py", line 12, in <module>
    from . import netsnmp
  File "/home/docs/checkouts/readthedocs.org/user_builds/nav/envs/latest/lib/python3.9/site-packages/pynetsnmp/netsnmp.py", line 55, in <module>
    lib.netsnmp_get_version.restype = c_char_p
  File "/home/docs/.asdf/installs/python/3.9.19/lib/python3.9/ctypes/__init__.py", line 387, in __getattr__
    func = self.__getitem__(name)
  File "/home/docs/.asdf/installs/python/3.9.19/lib/python3.9/ctypes/__init__.py", line 392, in __getitem__
    func = self._FuncPtr((name_or_ordinal, self))
AttributeError: /home/docs/checkouts/readthedocs.org/user_builds/nav/envs/latest/bin/python: undefined symbol: netsnmp_get_version

navoidverify

This command is useful for simple SNMP MIB conformance testing of NAV-registered devices in bulk.

It takes an SNMP OID as its only argument, and a list of NAV-registered device name in its standard input: It then runs SNMP GET-NEXT commands for the given OID against all the listed devices (using the SNMP credentials stored in NAV), testing to see whether the device response is from within a subtree of the requested OID. Any device that responds with a value from the subtree will have its name printed back to the standard output.

Usage

/home/docs/checkouts/readthedocs.org/user_builds/nav/envs/latest/lib/python3.9/site-packages/nav/django/settings.py:73: UserWarning: Could not get connection parameters from db.conf: [Errno 2] No such file or directory: 'db.conf'
  warnings.warn(f"Could not get connection parameters from db.conf: {e}")
Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/nav/envs/latest/bin/navoidverify", line 5, in <module>
    from nav.bin.navoidverify import main
  File "/home/docs/checkouts/readthedocs.org/user_builds/nav/envs/latest/lib/python3.9/site-packages/nav/bin/navoidverify.py", line 39, in <module>
    from nav.ipdevpoll.snmp.common import SNMPParameters, SnmpError
  File "/home/docs/checkouts/readthedocs.org/user_builds/nav/envs/latest/lib/python3.9/site-packages/nav/ipdevpoll/snmp/__init__.py", line 20, in <module>
    import pynetsnmp.twistedsnmp
  File "/home/docs/checkouts/readthedocs.org/user_builds/nav/envs/latest/lib/python3.9/site-packages/pynetsnmp/twistedsnmp.py", line 12, in <module>
    from . import netsnmp
  File "/home/docs/checkouts/readthedocs.org/user_builds/nav/envs/latest/lib/python3.9/site-packages/pynetsnmp/netsnmp.py", line 55, in <module>
    lib.netsnmp_get_version.restype = c_char_p
  File "/home/docs/.asdf/installs/python/3.9.19/lib/python3.9/ctypes/__init__.py", line 387, in __getattr__
    func = self.__getitem__(name)
  File "/home/docs/.asdf/installs/python/3.9.19/lib/python3.9/ctypes/__init__.py", line 392, in __getitem__
    func = self._FuncPtr((name_or_ordinal, self))
AttributeError: /home/docs/checkouts/readthedocs.org/user_builds/nav/envs/latest/bin/python: undefined symbol: netsnmp_get_version

Recipes

Let’s say you are interested in figuring which of your devices support the CISCO-VLAN-MEMBERSHIP-MIB::vmMembershipSummaryTable object. First, you need the full OID of this object, and then you can test it against all your devices thus (by also utiliziing the navdf command mentioned above):

$ snmptranslate -On CISCO-VLAN-MEMBERSHIP-MIB::vmMembershipSummaryTable
.1.3.6.1.4.1.9.9.68.1.2.1
$ navdf | navoidverify .1.3.6.1.4.1.9.9.68.1.2.1
example-cisco-sw1.example.org
example-cisco-sw2.example.org
...

navpgdump

This command can aid in dumping all or parts of the NAV PostgreSQL database into a text format (raw SQL commands) suitable for restoring on a different PostgreSQL server or NAV instance.

If a full dump/restore cycle is needed, you may be better off using the command line tools provided by your PostgreSQL distribution itself, but if you want to apply NAV-specific filtering to the data, this command is useful.

In particular, this command is used by NAV developers to do partial dumps of production data and load these into a development installation for testing/debugging and development of new features.

Typical usage patterns are described in the data migration howto.

Usage

Usage: navpgdump [options]

Dumps the NAV PostgreSQL database as plain-text SQL to stdout, with optional
data filtering.

Options:
  --version             show program's version number and exit
  -h, --help            show this help message and exit
  -e TABLE, --exclude=TABLE
                        Exclude TABLE data from dump
  -c, --only-open-cam   Only dump open CAM records
  -a, --only-open-arp   Only dump open ARP records
  -f FILTER, --filter=FILTER
                        Filter a table's contents. FILTER must match
                        <tablename>=<SQL where clause>

The output of the program can be inserted into an empty PostgreSQL database
using the psql program.

navsnmp

This little utility is useful when you want to use NET-SNMP command line utilities to talk to your NAV-registered network devices.

Supply a NAV-registered device’s name as its argument, and it will output the device’s SNMP credentials (as stored in NAV, if any) as valid NET-SNMP command line options. In this way, you don’t need to remember which SNMP version, community or IP address a device has - you only need to remember the first part of its name.

Usage

/home/docs/checkouts/readthedocs.org/user_builds/nav/envs/latest/lib/python3.9/site-packages/nav/django/settings.py:73: UserWarning: Could not get connection parameters from db.conf: [Errno 2] No such file or directory: 'db.conf'
  warnings.warn(f"Could not get connection parameters from db.conf: {e}")
usage: navsnmp [-h] [sysname]

Outputs NAV's SNMP configuration for input devices as NET-SNMP compatible
command line arguments.

positional arguments:
  sysname     sysname of device whose configuration should be output. If
              omitted, a list of names is taken from stdin instead.

optional arguments:
  -h, --help  show this help message and exit

Example usage: snmpwalk $(navsnmp example-sw.example.org) SNMPv2-MIB::system

Recipes

To walk the ENTITY-MIB::entPhysicalTable table of example-sw.example.org:

snmpwalk $(navsnmp example-sw) ENTITY-MIB::entPhysicalTable

navsyncdb

This is the central command line utility to create the NAV database schema in PostgreSQL and keep the schema in sync when upgrading to newer NAV versions.

Run with the correct privileges, it can both create the database user and the database before initializing the schema, or even drop an exsting NAV database completely if you want to start from scratch.

Its usage is described in most of the available installation guides. When installing NAV from Debian packages, you rarely need to interact with this command, though.

Usage

Usage: navsyncdb [options]

Synchronizes your NAV database schema with the latest changes.

Options:
  -h, --help            show this help message and exit
  -c, --create          Create NAV database
  -r FILE, --restore=FILE
                        Restore a database from the SQL dump in FILE. To use
                        input from stdin, specify - as the filename.
  --drop-database       Drops the NAV database if it already exists. THIS IS A
                        DESTRUCTIVE OPERATION!
  -o, --out-of-order    Apply missing schema changes even when they are older
                        than the newest applied change

To create the database, this program assumes it can access the PostgreSQL
client binaries as the postgres superuser.  Either run this program under the
postgres shell account, or set the environment variables required to connect
as the superuser to your PostgreSQL server (PGHOST, PGPASSWORD, and if
necessary, PGPORT)

navsynctypes

If you manage multiple NAV instances, this useful utility can assist you in making sure your device type registry is kept in sync between instances. It may be tedious to use SeedDB to manually assign proper names and descriptions for all the device types auto-created by ipdevpoll during the course of its run, but if you manage multiple NAV instances, you don’t want to have to repeat these manual steps.

When run on NAV instance A, his command line utility outputs to its standard output a set of SQL commands that can be run on NAV instance B’s PostgreSQL server to ensure that NAV instance B has at least all the same device types as instance A, with the same descriptions etc.

Usage

/home/docs/checkouts/readthedocs.org/user_builds/nav/envs/latest/lib/python3.9/site-packages/nav/django/settings.py:73: UserWarning: Could not get connection parameters from db.conf: [Errno 2] No such file or directory: 'db.conf'
  warnings.warn(f"Could not get connection parameters from db.conf: {e}")
usage: navsynctypes [-h]

NAV type registry synchronizer

optional arguments:
  -h, --help  show this help message and exit

This program dumps this NAV installation's IP device type registry to STDOUT
as a PostgreSQL compatible script. The resulting script can be used to
synchronize the type registry of another NAV installation. The script will add
missing types and update existing type names and descriptions.

navuser

This commands interacts with the NAV web interface’s user registry, enabling you to use the command line to add new user accounts, set account passwords, lock/unlock accounts or give admin privileges to select accounts.

Usage

/home/docs/checkouts/readthedocs.org/user_builds/nav/envs/latest/lib/python3.9/site-packages/nav/django/settings.py:73: UserWarning: Could not get connection parameters from db.conf: [Errno 2] No such file or directory: 'db.conf'
  warnings.warn(f"Could not get connection parameters from db.conf: {e}")
usage: navuser [-h] {list,passwd,verify,add,remove,admin,lock,unlock} ...

Lists and manipulates NAV web user accounts

positional arguments:
  {list,passwd,verify,add,remove,admin,lock,unlock}
                        sub-command help
    list                Lists user accounts
    passwd              Sets the password of a user account
    verify              Verifies the password of a user account
    add                 Adds a new user account
    remove              Removes a user
    admin               Sets whether an existing user belongs to the admin
                        group
    lock                Locks a user
    unlock              Unlocks a user

optional arguments:
  -h, --help            show this help message and exit