User Tools

Site Tools


devel:hacking

This is an old revision of the document!


:!: Be warned, this information is becoming very out of date, it is currently being updated :!:

Hacker's guide to NAV

If you are contributing code to Network Administration Visualized, please read this first.

Participating in the community

Originally, NAV was a closed source project, initiated by the Norwegian University of Science and Technology (NTNU), and eventually sponsored by UNINETT on behalf of the Norwegian higher education community. In 2004, however, NTNU and UNINETT started distributing NAV under the GNU General Public License, making it a truly free software system.

While NTNU and UNINETT are still the main contributors to NAV, developing NAV to support the needs of the Norwegian higher education community, contributions from third parties is highly appreciated.

We communicate mainly through mailing lists, Launchpad, and the wiki and Mercurial repositories hosted at http://metanav.uninett.no/ . At times, UNINETT also arranges workshops and gatherings for its customers: Norwegian universities, university colleges and research institutions.

To contribute:

Go to http://metanav.uninett.no/ and

  • Join the mailing lists. The nav-dev mailing list in

particular is for discussing NAV development. So far, this is a

  low traffic list. We can only hope this will change ;-)
* Get a copy of the latest development sources by cloning the
  Mercurial repository at http://metanav.uninett.no/hg/default/.
  Most new development takes place on this branch.
* Take a look at the [[:navprojects|project reports from previous
  development projects at NTNU]] (NAVMe, NAVMore, tigaNAV and
  others) - design specifications and other useful bits of historic
  NAV information is mostly to be found in these.  Unfortunately,
  some of the oldest project documentation is in Norwegian only.  Do
  not hesitate to ask for help on the mailing lists.

If you wish to contribute code to the project, please tell us about it on the nav-dev mailing list. It is always a good idea to check if someone is already working on something similar, and to get some helpful tips on how to integrate your code with the rest of the project. If you already went ahead and wrote a patch, announce it on nav-dev and provide a link to the patch so it can be studied for possible inclusion into NAV.

Directory layout

A rough guide to the source tree:

conf/ Files related to the autoconf build system.
doc/ User and developer documentation, SQL scripts and example NAV configuration files.
tools/ Tool scripts for the build and release processes.
contrib/ User contributed NAV tools. NAV doesn't depend on these, and any maintenance of them is left up to the original developers. We do not offer support for these tools.
packages/ Stuff to help packaging NAV for various platforms, such as RedHat, CentOS, FreeBSD, Debian and soforth.
src/ Source code to Java subsystems of NAV (here for historic reasons).
subsystem/ Source code to the rest of NAV - most of it Python. NAV is loosely divided into subsystems, and each one of these has its own subdirectory in here.
subsystem/lib-python/ Python libraries & APIs. Please check what's already there before you roll your own.
subsystem/lib-perl/ Perl libraries & APIs. Only a single piece of Perl code remains in NAV; once this has been replaced, this directory will cease to exist.
subsystem/webfront/ Python libraries for the web interface and front-page handler modules for mod_python.

Development languages and frameworks

For historic reasons, different parts of NAV are written in different programming languages (Perl, Java, PHP and Python). This has been unfortunate in may ways, not at least for the sake of consistency and maintenance, but fortunately we have a long-term goal of reducing the number of languages and dependencies. The last few years we've spent a significant amount of time rewriting parts that were written in Perl and PHP to Python, which is the language we are currently gravitating towards.

Currently (as of February 2009), major parts of NAV are written in Python and Java, while only a single Perl program remains (makecricketconfig.pl).

When contributing patches to existing code, or plugins to existing subsystems, use the language that subsystem was written in.

When writing entirely new subsystems, the following rules apply:

  • If your subsystem is a new tool for the web interface, use Python

and Django. The legacy parts of the web system interface directly

  with ''mod_python'', using Cheetah for HTML templating.  Anything
  written in 2008 and later uses Django.  There is also
  [[devel:django_introduction|a guide for interfacing Django
  applications with the legacy web code]].
  • If your subsystem is a new back-end tool/daemon, please use

Python. The NAV Python API is more complete than for any of the

  other languages, and you will receive a lot for free.

If these rules are not followed, your patches will not be accepted into NAV (but if they are really good, we will consider including them in the contrib directory).

If *YOU* are willing to invest in porting some of the existing Java/Perl code to Python, then you will be celebrated as a NAV hero!

Coding style

Much of the legacy NAV code was written without using any coding style guidelines. This has resulted in some chaotic combination of styles, which we hope to reduce in the future. For new code, please follow these guidelines:

  • For Java code, please refer to SUN's “Code conventions for the

Java Programming Language”: http://java.sun.com/docs/codeconv/

  • For Python code, please refer to PEP-8, “Style Guide for Python

Code” http://www.python.org/doc/peps/pep-0008/

FIXME Add info about header guidelines for Python files.

If you see violations of these guidelines, don't hesitate to fix them. If you fix file-wide indentation problems etc., please submit this as a separate patch to make your other patches look clean and readable.

Database connections

NOTE: The following is Python-specific, more info should be added for the other languages used in NAV.

NAV uses PostgreSQL as its database backend. Namespaces (schemas) are employed to logically group tables and relations. NAV versions prior to 3.5 employed separate PostgreSQL databases instead of namespaces.

The namespaces currently in use are:

manage The core knowledge database of NAV, containing all sorts of information about the monitored IP Devices, events, alerts, network topology and machine tracking data.
profiles Contains NAV user accounts and groups, user preferences and alert profiles.
logger Anything related to NAV's syslog parser/browser system.
arnold The port detention system Arnold stores it's data here.

To obtain a connection to the NAV database, use the API accordingly, e.g.:

import nav.db
# Get a connection to the NAV database
connection = nav.db.getConnection('default')

The above code will open a connection to NAV's database, or, if a previous connection with these parameters is already open, returns the already existing connection from a connection cache.

The default parameter is there for legacy reasons; it specifies the name of a subsystem. The db.conf file allows configuration of separate database users for each subsystem (known as a script in db.conf) of NAV. The default db.conf file specifies a database user for a subsystem called default, and also specifies the same database user for all known subsystem names. At present, using a subsystem name that is not configured in db.conf will raise an exception in nav.db.getConnection().

Web interface

When programming for NAV's web interface, a few special considerations need to be made.

Mod_python

NAV uses mod_python to interface with the Apache web server. See http://www.modpython.org/.

Cheetah Templates

The NAV web interface makes extensive use of Cheetah templates for generating its HTML output, see http://www.cheetahtemplate.org/ .

Most of the existing Cheetah templates are to be found in subsystem/webfront/nav/web/templates, although some of NAV's subsystems store their templates along with their code in their respective subsystem subdirectories. The compiled templates should be placed in the nav.web.templates package.

If you are making a new web module for NAV, your module's Cheetah template should subclass MainTemplate.tmpl found in subsystem/webfront/nav/web/templates/. See other templates for code examples of how to inherit from this template.

Database connections in the web interface

As stated above, use the nav.db.getConnection function to open or retrieve an existing database connection. All NAV web modules share the same interpreter and namespace per Apache process, which also means that database connections will be shared between the modules running in each process. Therefore, the following conventions apply for connections obtained from nav.db.getConnection:

  • Do not, under any circumstances, retain references to a database

connection between client requests. Make sure to retrieve a new

  connection at the start of each request cycle - the API will cache
  connections between requests, and will automagically re-open
  broken connections.  As the connection is shared between several
  modules, retained references may be invalid in the next request
  cycle.
* Do not explicitly close database connections.  Although the API
  will try to reopen any closed or broken connections, you create
  extra overhead, and you don't play nice with the other web
  modules.
* Do not enable/disable autocommit or alter a connection's
  transaction isolation level, unless you make pretty darn sure to
  reset them to their original states at the end of a request cycle.
* NAV 3.0 makes connections autocommit by default, whereas NAV 3.1
  will not - make sure to commit your transactions when needed.  NAV
  will help unfortunate souls by attempting to commit transactions
  in a mod_python cleanuphandler, but you should nevertheless
  explicitly call connection.commit to avoid having your
  transactions accidentally rolled back.
devel/hacking.1234183921.txt.gz · Last modified: 2009/02/09 12:52 by morten