michael@0: $Id: README,v 1.3 2007/11/21 00:09:10 adamcain Exp $ michael@0: michael@0: nrappkit 1.0b2 michael@0: Copyright (C) 2006 Network Resonance, Inc. michael@0: michael@0: michael@0: nrappkit is a toolkit for building standalone applications and michael@0: appliances. It provides: michael@0: michael@0: - registry-based configuration (with change callbacks) michael@0: - extensible command and configuration shell michael@0: - extensible statistics system michael@0: - configurable logging system michael@0: - event and timer handling michael@0: - generic plugin system michael@0: - launcher daemon michael@0: michael@0: The contents of nrappkit were extracted from Network Resonance's michael@0: product on the theory that they were generally useful for michael@0: application developers. michael@0: michael@0: THIS PACKAGE DOES NOT GRANT A LICENSE OR RIGHT TO ANY OTHER NETWORK michael@0: RESONANCE TECHNOLOGY OR SOFTWARE. michael@0: michael@0: michael@0: michael@0: BUILDING michael@0: michael@0: Builds are done semi-manually with port directories for each michael@0: platform. There are pre-existing ports to FreeBSD, Linux (Ubuntu michael@0: and Fedora Core), and Darwin (MacOSX). To build the system: michael@0: michael@0: cd src/make/ michael@0: gmake michael@0: michael@0: Some of the platforms come in several variants. Most notably, michael@0: if a platform exists in "regular" and "-appliance" variant, michael@0: this means that the regular variant just builds binaries intended michael@0: to be run out of the make directory (for development) and the michael@0: appliance variant is intended to be installed in a real system. michael@0: michael@0: By default we want to install things owned as user "pcecap". michael@0: Either make this user or edit the Makefile to be a user you michael@0: like (e.g., nobody). michael@0: michael@0: If you want to include the 'nrsh' command-line configuration michael@0: tool in your build, you will need to make sure the line michael@0: BUILD_NRSH=yes michael@0: appears (uncommented-out) in your platform Makefile. You will michael@0: also need to to build OpenSSL and libedit and point your nrappkit michael@0: Makefile to the correct paths. You can obtain these packages at: michael@0: openssl-0.9.7l michael@0: http://www.openssl.org/source/openssl-0.9.7l.tar.gz michael@0: michael@0: libedit-20060829-2.9 michael@0: http://freshmeat.net/redir/editline/53029/url_tgz/libedit-20060829-2.9.tar.gz michael@0: michael@0: michael@0: INSTALLING michael@0: If you're doing an appliance as opposed to a development build, michael@0: you'll want to install it. This is easy: michael@0: michael@0: su michael@0: gmake install michael@0: michael@0: Most binaries and libraries ends up in /usr/local/pcecap while michael@0: data files are in /var/pcecap. However, you can tweak michael@0: this in the Makefile. By default it's all owned by pcecap. michael@0: michael@0: To ensure that dynamic libraries are loaded correctly at runtime, michael@0: you'd want to make sure the right directory is included in your michael@0: LD_LIBRARY_PATH or via ldconfig. michael@0: michael@0: michael@0: QUICK TOUR michael@0: The build makes the following binaries that you may find useful: michael@0: michael@0: - captured -- the launcher (the name is historical) michael@0: - registryd -- the registry daemon michael@0: - nrregctl -- a registry control program michael@0: - nrsh -- the command shell (when included in build) michael@0: - nrstatsctl -- the stats control program michael@0: michael@0: Using the nrcapctl script is the easiest way to interact with michael@0: the applications. It is run as "nrcapctl " with the michael@0: following commands recognized: michael@0: michael@0: startup -- fires up captured, which in turn runs and michael@0: initializes the registry michael@0: michael@0: shutdown -- kills captured and its child processes michael@0: michael@0: status -- prints the running status of captured in michael@0: human-readable form michael@0: michael@0: stat -- prints the running status of captured in michael@0: a form easily parsed by scripts michael@0: michael@0: enable -- alters the mode.txt file so that captured michael@0: starts michael@0: michael@0: disable -- alters the mode.txt file so that captured michael@0: does not start michael@0: michael@0: clear-statistics -- equivalent to "nrstatsctl -z" (requires michael@0: that captured be running) michael@0: michael@0: Note: the "start" and "stop" nrcapctl commands do nothing as they michael@0: use components not included in nrappkit. However the associated michael@0: script logic in nrcapctl demonstrates how additional applications michael@0: might be launched using nrcapctl and particular registry settings. michael@0: michael@0: michael@0: EXTENDING michael@0: When things come up, they're pretty dumb. You'll probably want to michael@0: write your own applications, otherwise it's not clear why you're doing michael@0: this. The general idea is that you write your application using the michael@0: facilities that nrappkit provides and then write plugins to the michael@0: nrappkit components as necessary. So, for example, say you want michael@0: to write a network daemon. You would: michael@0: michael@0: - configure the launcher to launch your daemon (using the registry, michael@0: naturally). michael@0: - make calls to the registry to get configuration data michael@0: - make calls to the logging system to log data michael@0: - implement a stats module to record statistics michael@0: - write a plugin to nrsh to let people configure your parameters michael@0: michael@0: Examples of some of this stuff can be found in examples/demo_plugin. michael@0: Otherwise, read the source. More documentation will be on the way, michael@0: hopefully. michael@0: michael@0: