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