README (4675B)
1 $Id: README,v 1.3 2007/11/21 00:09:10 adamcain Exp $ 2 3 nrappkit 1.0b2 4 Copyright (C) 2006 Network Resonance, Inc. 5 6 7 nrappkit is a toolkit for building standalone applications and 8 appliances. 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 18 The contents of nrappkit were extracted from Network Resonance's 19 product on the theory that they were generally useful for 20 application developers. 21 22 THIS PACKAGE DOES NOT GRANT A LICENSE OR RIGHT TO ANY OTHER NETWORK 23 RESONANCE TECHNOLOGY OR SOFTWARE. 24 25 26 27 BUILDING 28 29 Builds are done semi-manually with port directories for each 30 platform. There are pre-existing ports to FreeBSD, Linux (Ubuntu 31 and Fedora Core), and Darwin (MacOSX). To build the system: 32 33 cd src/make/<platform> 34 gmake 35 36 Some of the platforms come in several variants. Most notably, 37 if a platform exists in "regular" and "-appliance" variant, 38 this means that the regular variant just builds binaries intended 39 to be run out of the make directory (for development) and the 40 appliance variant is intended to be installed in a real system. 41 42 By default we want to install things owned as user "pcecap". 43 Either make this user or edit the Makefile to be a user you 44 like (e.g., nobody). 45 46 If you want to include the 'nrsh' command-line configuration 47 tool in your build, you will need to make sure the line 48 BUILD_NRSH=yes 49 appears (uncommented-out) in your platform Makefile. You will 50 also need to to build OpenSSL and libedit and point your nrappkit 51 Makefile 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 59 INSTALLING 60 If you're doing an appliance as opposed to a development build, 61 you'll want to install it. This is easy: 62 63 su 64 gmake install 65 66 Most binaries and libraries ends up in /usr/local/pcecap while 67 data files are in /var/pcecap. However, you can tweak 68 this in the Makefile. By default it's all owned by pcecap. 69 70 To ensure that dynamic libraries are loaded correctly at runtime, 71 you'd want to make sure the right directory is included in your 72 LD_LIBRARY_PATH or via ldconfig. 73 74 75 QUICK TOUR 76 The 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 84 Using the nrcapctl script is the easiest way to interact with 85 the applications. It is run as "nrcapctl <command>" with the 86 following 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 108 Note: the "start" and "stop" nrcapctl commands do nothing as they 109 use components not included in nrappkit. However the associated 110 script logic in nrcapctl demonstrates how additional applications 111 might be launched using nrcapctl and particular registry settings. 112 113 114 EXTENDING 115 When things come up, they're pretty dumb. You'll probably want to 116 write your own applications, otherwise it's not clear why you're doing 117 this. The general idea is that you write your application using the 118 facilities that nrappkit provides and then write plugins to the 119 nrappkit components as necessary. So, for example, say you want 120 to 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 129 Examples of some of this stuff can be found in examples/demo_plugin. 130 Otherwise, read the source. More documentation will be on the way, 131 hopefully. 132 133