Project
Visit the nrappkit SourceForge page for project information.
The initial release of nrappkit 1.0b1 is available for
download now.
Email any questions or issues to ekr@networkresonance.com.
32/64-bit WARNING
This code was developed on 32-bit platforms. It has not yet
been ported to 64-bit platforms and will most likely fail.
If you get it working on 64-bits, please provide patches.
Overview
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
You'll first need to build openssl and libedit and point your
nrappkit Makefile to the correct paths. You can obtain these
packages at:
Builds are done semi-manually with port directories for each
platform. There are pre-existing ports to FreeBSD, Linux, 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 (nobody).
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. This is shared by all users on the system. |
nrregctl |
a registry control program |
nrsh |
the command shell |
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.