User Tools

Site Tools


devel:hacking

This is an old revision of the document!


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 true open source project.

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

The community exists mainly through mailing lists, a wiki and a Subversion repository, although UNINETT also arranges seminars and gatherings for its target audience: Norwegian universities and university colleges. To participate:

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 from https://svn.itea.ntnu.no/repos/nav/navme/trunk/. New development always takes place on trunk. Bugfixes, enhancements, and new features are backported from there to the various release branches.
  • Take a look at the 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 older 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 process.
contrib/ Stuff that works with NAV, but that NAV doesn't depend on, and that is maintained by individuals who may or may not participate in NAV development.
packages/ Stuff to help packaging systems, like rpm and dpkg.
src/ Source code to Java subsystems of NAV (still here for historic reasons).
subsystem/ Source code to the rest of NAV - a lot of 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. Please check what's already there before you roll your own.
subsystem/webfront/ Python libraries for the web interface and front-page handler modules for mod_python.

Development languages

For historic reasons, NAV today is made up of several programming languages - these are Python, Java and Perl. Although this is unfortunate in many ways, no-one has been willing to invest in the time needed to rewrite stuff to reduce the number of languages.

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. The web interface is built using mod_python. Also, the integration with Cricket uses Cricket's web front-end, which is Perl CGI.
  • If your subsystem is a new back-end tool/daemon, please use Python. The Python API created for NAV is more complete than for any of the other languages, and you will receive a lot for free. You may use Perl if you absolutely abhor Python, but then you will be frowned upon.

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

Coding style

NAV has not previously bothered with having 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:

If you see violations of these guidelines, don't hesitate to report them and/or 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.

The NAV database actually consists of four PostgreSQL databases (although there are plans to merge them into a single database using PostgreSQL's support for schemas). The databases 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.
navprofiles Contains NAV user accounts and groups, user preferences and alert profiles.
logger Contains syslog entries collected by the 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 manage database
connection = nav.db.getConnection('default', 'manage')

The above code will open a connection to the manage database, or, if the connection had already been opened during the lifetime of the current process, returns the already existing connection from a connection cache.

The 'default' parameter is there for legacy reasons; the db.conf file allows one to configure separate database users for each subsystem (known as a script in db.conf) of NAV, but it is recommended to use only one user for all NAV database connections - hence the default “subsystem”.

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.1234175251.txt.gz · Last modified: 2009/02/09 10:27 by morten