"Fossies" - the Fresh Open Source Software Archive 
Member "node-runner-0.6.0/README" (29 Dec 2004, 7284 Bytes) of package /linux/www/old/node-runner-0.6.0.tar.gz:
As a special service "Fossies" has tried to format the requested text file into HTML format (style:
standard) with prefixed line numbers.
Alternatively you can here
view or
download the uninterpreted source code file.
1 Node Runner - Open Source Network Monitor
2
3 Overview
4 ========
5
6 Node Runner is a PHP network monitor designed to contact nodes in a
7 hierarchial fashion based on the configuration of the node. If a node does
8 not respond, dependencies (parents) of that node are systematically checked
9 until the problem is isolated.
10
11 Node Runner uses a shell script for its basic network polling, a PHP web
12 interface for node information, reports, etc., and and abstraction
13 layers for multi-platform database support.
14
15 Why bother? Well, most network monitor packages available on the market
16 today are commercially distributed and Windows-based. Of the open source
17 network monitors I've seen, few seem to have the capability to query
18 dependant nodes if a primary node is unreachable, and those that do include
19 this functionality are difficult to set up or maintain. Node Runner
20 strives to exceed both of these goals and more.
21
22
23 Installation
24 ============
25 For installation instructions, see the INSTALL file that came with this
26 application.
27
28
29 System Requirements
30 ===================
31 1. PHP 4.3+ (compiled w/ cgi, socket and SNMP support highly recommended)
32 2. MySQL 3.x
33 3. Available Web server with PHP support (does not need to be local machine)
34
35 NOTE 1: If you do not compile PHP with cgi, socket, and SNMP support, you will
36 likely see errors if you attempt to query nodes of these types. Node Runner
37 has NOT been designed to check for proper compilation of these features before
38 it attempts to poll a node. Therefore, based on the operating system, it may
39 generate errors or simply fail if you do not have these features compiled
40 properly. To check for proper compilation, you will need to create a script
41 that outputs the configuration of php using the phpinfo() function.
42
43 That script could be as simple as the following code:
44
45 <?php
46 phpinfo();
47 ?>
48
49 Save it as any filename you like, and upload it to your web documents root.
50 When you pull it up in the browser, you should see sections for socket, SNMP,
51 etc.
52
53 NOTE 2: Due to the nature of the query script (node.start), it is recommended
54 that you adjust the error reporting levels of PHP to prevent warnings. The
55 decision is completely up to you, but if you don't, you will likely see a number
56 of WARNING messages in your debugging output if nodes fail to respond to network
57 queries. To adjust the error reporting level, modify the error_reporting line
58 in your php.ini file to the following:
59
60 error_reporting = E_ALL & ~E_NOTICE & ~E_WARNING
61
62
63
64 MODULAR NETWORK QUERIES
65 =======================
66
67 As of version 0.6.0, network queries have been extracted from the node.start
68 script and moved to the 'include' directory. The scripts you will find in that
69 directory each serve their own purpose, such as polling SNMP or ICMP. There is
70 a template file for creating your own query scripts in the 'contribs' directory,
71 but you should have a good understanding of sockets before attempting to write
72 your own custom queries.
73
74
75 CONSIDERATIONS FOR CRON SCHEDULING
76 ==================================
77
78 My test setup is configured to run the 'node.start' script every
79 three minutes, but you can use your own judgement, bearing in mind
80 that more servers take more time to poll, so don't set your
81 cron jobs too close together.
82
83 (My production setup uses about 150 servers, and takes less than
84 3 minutes to execute even with multiple failing nodes.) Your
85 $max_attempts variable (nr.inc) is an important factor to consider
86 also. Put some thought into your configuration, and check your
87 total execution time using the $debug option if you think your cron
88 jobs are bleeding into one another.
89
90
91 USING THE DEBUG OPTION
92 ======================
93
94 Beginning in version 0.4.4, I've added a level of debugging that can
95 be used when troubleshooting the node.start script. Set the $debug
96 variable to 1 in the 'nr.inc' file, and change your cron to output
97 to a file .
98
99 You also have the option of running the node.start script manually, (which
100 will give you screen output), but because of the anal nature of my timing
101 functions within the script, I would not recommend it.
102
103 The output should give you a status of each server. If a server does not
104 respond, it will display the status of its dependency, and so on. Execution
105 time is also summarized at the end of each cycle.
106
107 In the early stages of development, while getting a feel for my own network,
108 I turned the debugging option on and added one more cron job to delete the
109 text file (created by the output) at the end of each day. This way, if I get
110 a strange alert, I'll be able to track it down.
111
112
113 ENDPOINTS vs. NON-ENDPOINTS
114 ===========================
115
116 "Endpoints" are defined as nodes that will be contacted on a regular
117 schedule (eg. each time the cron job executes the 'node.start' script).
118 In most cases, people will use actual servers in this list, but if you
119 need to continually monitor another node, you should classify it as an
120 endpoint. An example of this might be an an ethernet interface of a router.
121 Treat it as an endpoint, and it will be polled each time. "Non-endpoints"
122 are only polled when an endpoint doesn't respond, at which time Node Runner
123 starts polling backward up the chain of parent nodes (think traceroute) that
124 you defined as you added each node to the web interface. Be careful not
125 to create endpoint-to-endpoint dependencies (one endpoint depends on another),
126 as it wastes resources and slows down the scripts.
127
128
129 KEEP WORKSTATION TIME ACCURATE
130 ==============================
131
132 It is very important to have the correct time on your Node Runner
133 (localhost) machine. All logging features (measuring downtime) are
134 dependent upon a consistent time. The best way to keep time consistent
135 is to keep it up to date. Most people set up a cron job to handle that.
136
137
138 DATABASE ABSTRACTION LAYERS
139 ===========================
140
141 The original files have been revised to allow use of database abstraction
142 layers instead of hardcoded MySQL support. So far, I've only tested
143 the abstraction layer for MySQL, but it's fairly easy to build layers for
144 other databases as well. There are really only 4-5 functions that need
145 to run, so it's not a huge undertaking to make the layers. I'll post
146 the development layers and .sql import files on Sourceforge if anyone
147 would like to take a crack at testing/fixing them. If anyone is
148 interested in making one or more of them work, I'd be glad to give them
149 all the credit for doing so, but I won't distribute those files until
150 I know they've been tested.
151
152
153
154 License Information
155 ===================
156
157 Copyright (C) 2001-2005 Brad Fears.
158
159 This program is free software; you can redistribute it and/or
160 modify it under the terms of the GNU General Public License
161 as published by the Free Software Foundation; either version 2
162 of the License, or (at your option) any later version.
163
164 This program is distributed in the hope that it will be useful,
165 but WITHOUT ANY WARRANTY; without even the implied warranty of
166 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
167 GNU General Public License for more details.
168
169 You should have received a copy of the GNU General Public License
170 along with this program; if not, write to the Free Software
171 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
172
173 -- Brad Fears <brad@tricountywebdesign.com>
174