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