$Id: README,v 1.3 2007/11/21 00:09:10 adamcain Exp $ 

nrappkit 1.0b2
Copyright (C) 2006 Network Resonance, Inc.


nrappkit is a toolkit for building standalone applications and
appliances. It provides:

- registry-based configuration (with change callbacks)
- extensible command and configuration shell
- extensible statistics system
- configurable logging system
- event and timer handling
- generic plugin system
- launcher daemon

The contents of nrappkit were extracted from Network Resonance's
product on the theory that they were generally useful for 
application developers. 

THIS PACKAGE DOES NOT GRANT A LICENSE OR RIGHT TO ANY OTHER NETWORK
RESONANCE TECHNOLOGY OR SOFTWARE.



BUILDING

Builds are done semi-manually with port directories for each
platform. There are pre-existing ports to FreeBSD, Linux (Ubuntu
and Fedora Core), and Darwin (MacOSX). To build the system:

	cd src/make/<platform>
	gmake

Some of the platforms come in several variants. Most notably,
if a platform exists in "regular" and "-appliance" variant,
this means that the regular variant just builds binaries intended
to be run out of the make directory (for development) and the
appliance variant is intended to be installed in a real system.

By default we want to install things owned as user "pcecap".
Either make this user or edit the Makefile to be a user you
like (e.g., nobody).

If you want to include the 'nrsh' command-line configuration
tool in your build, you will need to make sure the line
  BUILD_NRSH=yes
appears (uncommented-out) in your platform Makefile.  You will 
also need to to build OpenSSL and libedit and point your nrappkit
Makefile to the correct paths. You can obtain these packages at:
    openssl-0.9.7l
    http://www.openssl.org/source/openssl-0.9.7l.tar.gz

    libedit-20060829-2.9
    http://freshmeat.net/redir/editline/53029/url_tgz/libedit-20060829-2.9.tar.gz


INSTALLING
If you're doing an appliance as opposed to a development build,
you'll want to install it. This is easy:

	su
 	gmake install

Most binaries and libraries ends up in /usr/local/pcecap while
data files are in /var/pcecap. However, you can tweak
this in the Makefile. By default it's all owned by pcecap.

To ensure that dynamic libraries are loaded correctly at runtime,
you'd want to make sure the right directory is included in your
LD_LIBRARY_PATH or via ldconfig.


QUICK TOUR
The build makes the following binaries that you may find useful:

- captured    -- the launcher (the name is historical)
- registryd   -- the registry daemon
- nrregctl    -- a registry control program
- nrsh        -- the command shell (when included in build)
- nrstatsctl  -- the stats control program

Using the nrcapctl script is the easiest way to interact with
the applications. It is run as "nrcapctl <command>" with the
following commands recognized:

  startup            -- fires up captured, which in turn runs and
                        initializes the registry

  shutdown           -- kills captured and its child processes

  status             -- prints the running status of captured in
                        human-readable form

  stat               -- prints the running status of captured in
                        a form easily parsed by scripts

  enable             -- alters the mode.txt file so that captured
                        starts 

  disable            -- alters the mode.txt file so that captured
                        does not start

  clear-statistics   -- equivalent to "nrstatsctl -z" (requires
                        that captured be running)

Note: the "start" and "stop" nrcapctl commands do nothing as they
use components not included in nrappkit. However the associated
script logic in nrcapctl demonstrates how additional applications
might be launched using nrcapctl and particular registry settings.


EXTENDING
When things come up, they're pretty dumb. You'll probably want to
write your own applications, otherwise it's not clear why you're doing
this. The general idea is that you write your application using the
facilities that nrappkit provides and then write plugins to the
nrappkit components as necessary. So, for example, say you want
to write a network daemon. You would:

 - configure the launcher to launch your daemon (using the registry,
   naturally).
 - make calls to the registry to get configuration data
 - make calls to the logging system to log data
 - implement a stats module to record statistics
 - write a plugin to nrsh to let people configure your parameters

Examples of some of this stuff can be found in examples/demo_plugin.
Otherwise, read the source. More documentation will be on the way,
hopefully.