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:

* 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/

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 dta.

* '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.1234174507.txt.gz · Last modified: 2009/02/09 10:15 by morten