This shows you the differences between two versions of the page.
Next revision | Previous revision | ||
devel:hacking [2009/02/09 10:15] morten pasted in NAV's HACKING file. |
devel:hacking [2014/11/05 10:57] (current) morten |
||
---|---|---|---|
Line 1: | Line 1: | ||
- | ======================= | + | ====== Hacker's guide to NAV ====== |
- | 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. | + | |
+ | This document has moved to https://nav.uninett.no/doc/dev/hacking/hacking.html |