This shows you the differences between two versions of the page.
Both sides previous revision Previous revision Next revision | Previous revision | ||
devel:hacking [2009/02/09 11:50] morten update community section |
devel:hacking [2014/11/05 10:57] (current) morten |
||
---|---|---|---|
Line 1: | Line 1: | ||
- | :!: **Be warned, this information is becoming very out of date, it is currently being updated** :!: | ||
====== Hacker's guide to NAV ====== | ====== Hacker's guide to NAV ====== | ||
- | If you are contributing code to Network Administration Visualized, | + | This document has moved to https://nav.uninett.no/doc/dev/hacking/hacking.html |
- | 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, | + | |
- | [[https://launchpad.net/nav/|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 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 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.: | + | |
- | + | ||
- | <code python> | + | |
- | import nav.db | + | |
- | # Get a connection to the manage database | + | |
- | connection = nav.db.getConnection('default', 'manage') | + | |
- | </code> | + | |
- | + | ||
- | 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. | + |