README
1$Id: README,v 1.3 2007/11/21 00:09:10 adamcain Exp $
2
3nrappkit 1.0b2
4Copyright (C) 2006 Network Resonance, Inc.
5
6
7nrappkit is a toolkit for building standalone applications and
8appliances. It provides:
9
10- registry-based configuration (with change callbacks)
11- extensible command and configuration shell
12- extensible statistics system
13- configurable logging system
14- event and timer handling
15- generic plugin system
16- launcher daemon
17
18The contents of nrappkit were extracted from Network Resonance's
19product on the theory that they were generally useful for
20application developers.
21
22THIS PACKAGE DOES NOT GRANT A LICENSE OR RIGHT TO ANY OTHER NETWORK
23RESONANCE TECHNOLOGY OR SOFTWARE.
24
25
26
27BUILDING
28
29Builds are done semi-manually with port directories for each
30platform. There are pre-existing ports to FreeBSD, Linux (Ubuntu
31and Fedora Core), and Darwin (MacOSX). To build the system:
32
33 cd src/make/<platform>
34 gmake
35
36Some of the platforms come in several variants. Most notably,
37if a platform exists in "regular" and "-appliance" variant,
38this means that the regular variant just builds binaries intended
39to be run out of the make directory (for development) and the
40appliance variant is intended to be installed in a real system.
41
42By default we want to install things owned as user "pcecap".
43Either make this user or edit the Makefile to be a user you
44like (e.g., nobody).
45
46If you want to include the 'nrsh' command-line configuration
47tool in your build, you will need to make sure the line
48 BUILD_NRSH=yes
49appears (uncommented-out) in your platform Makefile. You will
50also need to to build OpenSSL and libedit and point your nrappkit
51Makefile to the correct paths. You can obtain these packages at:
52 openssl-0.9.7l
53 http://www.openssl.org/source/openssl-0.9.7l.tar.gz
54
55 libedit-20060829-2.9
56 http://freshmeat.net/redir/editline/53029/url_tgz/libedit-20060829-2.9.tar.gz
57
58
59INSTALLING
60If you're doing an appliance as opposed to a development build,
61you'll want to install it. This is easy:
62
63 su
64 gmake install
65
66Most binaries and libraries ends up in /usr/local/pcecap while
67data files are in /var/pcecap. However, you can tweak
68this in the Makefile. By default it's all owned by pcecap.
69
70To ensure that dynamic libraries are loaded correctly at runtime,
71you'd want to make sure the right directory is included in your
72LD_LIBRARY_PATH or via ldconfig.
73
74
75QUICK TOUR
76The build makes the following binaries that you may find useful:
77
78- captured -- the launcher (the name is historical)
79- registryd -- the registry daemon
80- nrregctl -- a registry control program
81- nrsh -- the command shell (when included in build)
82- nrstatsctl -- the stats control program
83
84Using the nrcapctl script is the easiest way to interact with
85the applications. It is run as "nrcapctl <command>" with the
86following commands recognized:
87
88 startup -- fires up captured, which in turn runs and
89 initializes the registry
90
91 shutdown -- kills captured and its child processes
92
93 status -- prints the running status of captured in
94 human-readable form
95
96 stat -- prints the running status of captured in
97 a form easily parsed by scripts
98
99 enable -- alters the mode.txt file so that captured
100 starts
101
102 disable -- alters the mode.txt file so that captured
103 does not start
104
105 clear-statistics -- equivalent to "nrstatsctl -z" (requires
106 that captured be running)
107
108Note: the "start" and "stop" nrcapctl commands do nothing as they
109use components not included in nrappkit. However the associated
110script logic in nrcapctl demonstrates how additional applications
111might be launched using nrcapctl and particular registry settings.
112
113
114EXTENDING
115When things come up, they're pretty dumb. You'll probably want to
116write your own applications, otherwise it's not clear why you're doing
117this. The general idea is that you write your application using the
118facilities that nrappkit provides and then write plugins to the
119nrappkit components as necessary. So, for example, say you want
120to write a network daemon. You would:
121
122 - configure the launcher to launch your daemon (using the registry,
123 naturally).
124 - make calls to the registry to get configuration data
125 - make calls to the logging system to log data
126 - implement a stats module to record statistics
127 - write a plugin to nrsh to let people configure your parameters
128
129Examples of some of this stuff can be found in examples/demo_plugin.
130Otherwise, read the source. More documentation will be on the way,
131hopefully.
132
133
134
README_MOZILLA
1This import of nrappkit is a subset of the distribution at:
2
3 nrappkit.sourceforge.net
4
5
6The last revision included in this import was on Nov 25, 2008.
7This import includes a small nunber of portability fixes that
8have been submitted to the upstream repository and are included
9in upstream.diff.
10
11
12Out of the list in the README, we use:
13
14- registry-based configuration (with change callbacks)
15 [but without the registry daemon]
16- configurable logging system
17- event and timer handling
18 [though partly reimplemented]
19
20Also, we use a bunch of the generic utilities such as string handling,
21generic hash tables in C, yet another concrete type mapping, etc.
22
23