Details | Last modification | View Log | RSS feed
Rev | Author | Line No. | Line |
---|---|---|---|
86 | daniel-mar | 1 | # VNag - Nagios Framework for PHP |
2 | Developed by Daniel Marschall (www.viathinksoft.com) |
||
3 | Licensed under the terms of the Apache 2.0 license |
||
4 | |||
5 | ## Introduction |
||
6 | |||
7 | VNag is a small framework for Nagios Plugin Developers who use PHP CLI scripts. |
||
8 | The main purpose of VNag is to make the development of plugins as easy as possible, so that |
||
9 | the developer can concentrate on the actual work. VNag will try to automate as much |
||
10 | as possible. |
||
11 | |||
12 | Please note that your script should include the +x chmod flag: |
||
13 | chmod +x myscript.php |
||
14 | |||
15 | Please see the the demo/ folder for a few examples how to use this framework. |
||
16 | |||
17 | ## Arguments |
||
18 | |||
19 | Example: |
||
20 | $this->addExpectedArgument($argSilent = new VNagArgument('s', 'silent', VNagArgument::VALUE_FORBIDDEN, null, 'Description for the --silent output', $defaultValue)); |
||
21 | $this->addExpectedArgument($argHost = new VNagArgument('H', 'host', VNagArgument::VALUE_REQUIRED, 'hostname', 'Description for the --host output', $defaultValue)); |
||
22 | |||
23 | In the example above, the two argument objects $argSilent and $argHost were created. |
||
24 | With these objects of the type VNagArgument, you can query the argument's value, |
||
25 | how often the argument was passed and if it is set: |
||
26 | |||
27 | $argSilent->count(); // 1 if "-s" is passed, 2 if "-s -s" is passed etc. |
||
28 | $argSilent->available(); // true if "-s" is passed, false otherwise |
||
29 | $argHost->getValue(); // "example.com" if "-h example.com" is passed |
||
30 | |||
31 | It is recommended that you pass every argument to $this->addExpectedArgument() . |
||
32 | Using this way, VNag can generate a --help page for you, which lists all your arguments. |
||
33 | Future version of VNag may also require to have a complete list of all valid arguments, |
||
34 | since the Nagios Development Guidelines recommend to output the usage information if an illegal |
||
35 | argument is passed. Due to PHP's horrible bad implementation of GNU's getopt(), this check for |
||
36 | unknown arguments is currently not possible, and the developer of VNag does not want to use |
||
37 | dirty hacks/workarounds, which would not match to all argument notation variations/styles. |
||
38 | See: https://bugs.php.net/bug.php?id=68806 |
||
39 | https://bugs.php.net/bug.php?id=65673 |
||
40 | https://bugs.php.net/bug.php?id=26818 |
||
41 | |||
42 | ## Setting the status: |
||
43 | |||
44 | You can set the status with: |
||
45 | $this->setStatus(VNag::STATUS_OK); |
||
46 | If you don't set a status, the script will return Unknown instead. |
||
47 | setStatus($status) will keep the most severe status, e.g. |
||
48 | $this->setStatus(VNag::STATUS_CRITICAL); |
||
49 | $this->setStatus(VNag::STATUS_OK); |
||
50 | will result in a status "Critical". |
||
51 | If you want to completely overwrite the status, use $force=true: |
||
52 | $this->setStatus(VNag::STATUS_CRITICAL); |
||
53 | $this->setStatus(VNag::STATUS_OK, true); |
||
54 | The status will now be "OK". |
||
55 | |||
56 | Possible status codes are: |
||
57 | (For service plugins:) |
||
58 | VNag::STATUS_OK = 0; |
||
59 | VNag::STATUS_WARNING = 1; |
||
60 | VNag::STATUS_CRITICAL = 2; |
||
61 | VNag::STATUS_UNKNOWN = 3; |
||
62 | |||
63 | (For host plugins:) |
||
64 | VNag::STATUS_UP = 0; |
||
65 | VNag::STATUS_DOWN = 1; |
||
66 | |||
67 | ## Output: |
||
68 | |||
69 | After the callback function cbRun() of your job has finished, |
||
70 | the framework will automatically output the results in the Nagios console output format, |
||
71 | the visual HTML output and/or the invisible HTML output. |
||
72 | |||
73 | In case of CLI invokation, the Shell exit code will be remembered and |
||
74 | automatically returned by the shutdown handler once the script normally |
||
75 | terminates. (In case you run different jobs, which is not recommended, the |
||
76 | shutdown handler will output the baddest exit code). |
||
77 | |||
78 | The Shell output format will be: |
||
79 | <Service status text>: <Comma separates messages> | <whitespace separated primary performance data> |
||
80 | "Verbose information:" |
||
81 | <Multiline verbose output> | <Multiline secondary performance data> |
||
82 | |||
83 | <Service status text> will be automatically created by VNag. |
||
84 | |||
85 | Verbose information are printed below the first line. Most Nagios clients will only print the first line. |
||
86 | If you have important output, use $this->setHeadline() instead. |
||
87 | You can add verbose information with following method: |
||
88 | $this->addVerboseMessage('foobar', $verbosity); |
||
89 | |||
90 | Following verbosity levels are defined: |
||
91 | VNag::VERBOSITY_SUMMARY = 0; // always printed |
||
92 | VNag::VERBOSITY_ADDITIONAL_INFORMATION = 1; // requires at least -v |
||
93 | VNag::VERBOSITY_CONFIGURATION_DEBUG = 2; // requiers at least -vv |
||
94 | VNag::VERBOSITY_PLUGIN_DEBUG = 3; // requiers at least -vvv |
||
95 | |||
96 | All STDOUT outputs of your script (e.g. by echo) will be interpreted as "verbose" output |
||
97 | and is automatically collected, so |
||
98 | echo "foobar"; |
||
99 | has the same functionality as |
||
100 | $this->addVerboseMessage('foobar', VNag::VERBOSITY_SUMMARY); |
||
101 | |||
102 | You can set messages (which will be added into the first line, which is preferred for plugin outputs) |
||
103 | using |
||
104 | $this->setHeadline($msg, $append, $verbosity); |
||
105 | Using the flag $append, you can choose if you want to append or replace the message. |
||
106 | |||
107 | VNag will catch Exceptions of your script and will automatically end the plugin, |
||
108 | returning a valid Nagios output. |
||
109 | |||
110 | ## Automatic handling of basic arguments: |
||
111 | |||
112 | VNag will automatic handle of following CLI arguments: |
||
113 | -? |
||
114 | -V --version |
||
115 | -h --help |
||
116 | -v --verbose |
||
117 | -t --timeout (only works if you set declare(ticks=1) at the beginning of each of your scripts) |
||
118 | -w --warning |
||
119 | -c --critical |
||
120 | |||
121 | You can performe range checking by using: |
||
122 | $example_value = '10MB'; |
||
123 | $this->checkAgainstWarningRange($example_value); |
||
124 | this is more or less the same as: |
||
125 | $example_value = '10MB'; |
||
126 | $wr = $this->getWarningRange(); |
||
127 | if (isset($wr) && $wr->checkAlert($example_value)) { |
||
128 | $this->setStatus(VNag::STATUS_WARNING); |
||
129 | } |
||
130 | |||
131 | In case that your script allows ranges which can be relative and absolute, you can provide multiple arguments; |
||
132 | $wr->checkAlert() will be true, as soon as one of the arguments is in the warning range. |
||
133 | The check will be done in this way: |
||
134 | $example_values = array('10MB', '5%'); |
||
135 | $this->checkAgainstWarningRange($example_values); |
||
136 | this is more or less the same as: |
||
137 | $example_values = array('10MB', '5%'); |
||
138 | $wr = $this->getWarningRange(); |
||
139 | if (isset($wr) && $wr->checkAlert($example_values)) { |
||
140 | $this->setStatus(VNag::STATUS_WARNING); |
||
141 | } |
||
142 | |||
143 | Note that VNag will automatically detect the UOM (Unit of Measurement) and is also able to convert them, |
||
144 | e.g. if you use the range "-w 20MB:40MB", your script will be able to use $wr->checkAlert('3000KB') |
||
145 | |||
146 | Please note that only following UOMs are accepted (as defined in the Plugin Development Guidelines): |
||
147 | - no unit specified: assume a number (int or float) of things (eg, users, processes, load averages) |
||
148 | - s, ms, us: seconds |
||
149 | - %: percentage |
||
150 | - B, KB, MB, TB: bytes // NOTE: GB is not in the official development guidelines,probably due to an error, so I've added them anyway |
||
151 | - c: a continous counter (such as bytes transmitted on an interface) |
||
152 | |||
153 | ## Multiple warning/critical ranges: |
||
154 | |||
155 | The arguments -w and -c can have many different values, separated by comma. |
||
156 | We can see this feature e.g. with the official plugin /usr/lib/nagios/plugins/check_ping: |
||
157 | It has following syntax for the arguments -w and -c: <latency>,<packetloss>% |
||
158 | |||
159 | When you are using checkAgainstWarningRange, you can set the fourth argument to the range number |
||
160 | you would like to check (beginning with 0). |
||
161 | |||
162 | Example: |
||
163 | // -w 1MB:5MB,5%:10% |
||
164 | $this->checkAgainstWarningRange('4MB', true, true, 0); // check value 4MB against range "1MB:5MB" (no warning) |
||
165 | $this->checkAgainstWarningRange('15%', true, true, 1); // check value 15% gainst range "5%:10%" (gives warning) |
||
166 | |||
167 | ## Visual HTTP output: |
||
168 | |||
169 | Can be enabled/disabled with $this->http_visual_output |
||
170 | |||
171 | Valid values: |
||
172 | |||
173 | VNag::OUTPUT_SPECIAL = 1; // illegal usage / help page, version page |
||
174 | VNag::OUTPUT_NORMAL = 2; |
||
175 | VNag::OUTPUT_EXCEPTION = 4; |
||
176 | VNag::OUTPUT_ALWAYS = 7; |
||
177 | VNag::OUTPUT_NEVER = 0; |
||
178 | |||
179 | ## Encryption and Decryption: |
||
180 | |||
181 | In case you are emitting machine-readable code in your HTTP output |
||
182 | (can be enabled/disabled by $this->http_invisible_output), |
||
183 | you can encrypt the machine-readable part of your HTTP output by |
||
184 | setting $this->password_out . If you want to read the information, |
||
185 | you need to set $this->password_in at the web-reader plugin. |
||
186 | The visual output is not encrypted. So, if you want to hide the information, |
||
187 | then you must not enable visual HTML output. |
||
188 | If you don't want to encrypt the machine-readable output, |
||
189 | please set $this->password_out to null or empty string. |
||
190 | |||
191 | Attention! |
||
192 | - Encryption and decryption require the OpenSSL extension in PHP. |
||
193 | |||
194 | ## Digital signature: |
||
195 | |||
196 | You can sign the output by setting $this->privkey with a filename containing |
||
197 | a private key created by OpenSSL. If it is encrypted, please also set |
||
198 | $this->privkey_password . |
||
199 | To check the signature, set $this->pubkey at your web-reader plugin with |
||
200 | the filename of the public key file. |
||
201 | |||
202 | Attention! |
||
203 | - Signatures require the OpenSSL extension in PHP. |
||
204 | |||
205 | ## Performance data: |
||
206 | |||
207 | You can add performance data using |
||
208 | $this->addPerformanceData(new VNagPerformanceData($label, $value, $warn, $crit, $min, $max)); |
||
209 | or by the alternative constructor |
||
210 | $this->addPerformanceData(VNagPerformanceData::createByString("'XYZ'=100;120;130;0;500")); |
||
211 | $value may contain an UOM, e.g. "10MB". All other parameters may not contain an UOM. |
||
212 | |||
213 | ## Guidelines: |
||
214 | |||
215 | This framework currently supports meets following guidelines: |
||
216 | - https://nagios-plugins.org/doc/guidelines.html#PLUGOUTPUT (Plugin Output for Nagios) |
||
217 | - https://nagios-plugins.org/doc/guidelines.html#AEN33 (Print only one line of text) |
||
218 | - https://nagios-plugins.org/doc/guidelines.html#AEN41 (Verbose output) |
||
219 | - https://nagios-plugins.org/doc/guidelines.html#AEN78 (Plugin Return Codes) |
||
220 | - https://nagios-plugins.org/doc/guidelines.html#THRESHOLDFORMAT (Threshold and ranges) |
||
221 | - https://nagios-plugins.org/doc/guidelines.html#AEN200 (Performance data) |
||
222 | - https://nagios-plugins.org/doc/guidelines.html#PLUGOPTIONS (Plugin Options) |
||
223 | - https://nagios-plugins.org/doc/guidelines.html#AEN302 (Option Processing) |
||
224 | Note: The screen output of the help page will (mostly) be limited to 80 characters width; but the max recommended length of 23 lines cannot be guaranteed. |
||
225 | |||
226 | This framework does currently NOT support following guidelines: |
||
227 | - https://nagios-plugins.org/doc/guidelines.html#AEN74 (Screen Output) |
||
228 | - https://nagios-plugins.org/doc/guidelines.html#AEN239 (Translations) |
||
229 | - https://nagios-plugins.org/doc/guidelines.html#AEN293 (Use DEFAULT_SOCKET_TIMEOUT) |
||
230 | - https://nagios-plugins.org/doc/guidelines.html#AEN296 (Add alarms to network plugins) |
||
231 | - https://nagios-plugins.org/doc/guidelines.html#AEN245 (Don't execute system commands without specifying their full path) |
||
232 | - https://nagios-plugins.org/doc/guidelines.html#AEN249 (Use spopen() if external commands must be executed) |
||
233 | - https://nagios-plugins.org/doc/guidelines.html#AEN253 (Don't make temp files unless absolutely required) |
||
234 | - https://nagios-plugins.org/doc/guidelines.html#AEN259 (Validate all input) |
||
235 | - https://nagios-plugins.org/doc/guidelines.html#AEN317 (Plugins with more than one type of threshold, or with threshold ranges) |
||
236 | |||
237 | We will intentionally NOT follow the following guidelines: |
||
238 | - https://nagios-plugins.org/doc/guidelines.html#AEN256 (Don't be tricked into following symlinks) |
||
239 | Reason: We believe that this guideline is contraproductive. |
||
240 | Nagios plugins usually run as user 'nagios'. It is the task of the system administrator |
||
241 | to ensure that the user 'nagios' must not read/write to files which are not intended |
||
242 | for access by the Nagios service. Symlinks, on the other hand, are useful for several tasks. |
||
243 | See also https://stackoverflow.com/questions/27112949/nagios-plugins-why-not-following-symlinks |
||
244 | |||
245 | ## VNag over HTTP: |
||
246 | |||
247 | A script that uses the VNag framework can run as CLI script (normal Nagios plugin) or as web site (or both). |
||
248 | Having the script run as website, you can include a Nagios information combined with a human friendly HTML output which can |
||
249 | include colors, graphics (like charts) etc. |
||
250 | |||
251 | For example: |
||
252 | A script that measures traffic can have a website which shows graphs, |
||
253 | and has a hidden Nagios output included, which can be read by a Nagios plugin that |
||
254 | converts the hidden information on that website into an output that Nagios can evaluate. |
||
255 | |||
256 | Here is a comparison of the usage and behavior of VNag in regards to CLI and HTTP calls: |
||
257 | |||
258 | | CLI script | HTTP script |
||
259 | |-------------------------------------------|----------------------------------------------| |
||
260 | | * "echo" will be discarded. | * "echo" output will be discarded. | |
||
261 | |-------------------------------------------|----------------------------------------------| |
||
262 | | * Exceptions will be handled. | * Exceptions will be handled. | |
||
263 | |-------------------------------------------|----------------------------------------------| |
||
264 | | * outputHTML() will be ignored. | * outputHTML() will be handled. | |
||
265 | | (This allows you to have the same | | |
||
266 | | script running as CLI and HTML) | | |
||
267 | |-------------------------------------------|----------------------------------------------| |
||
268 | | * Arguments are passed via CLI. | * Arguments are passed via $_REQUEST | |
||
269 | | | (i.e. GET or POST) | |
||
270 | |-------------------------------------------|----------------------------------------------| |
||
271 | | * Arguments: "-vvv" | * Arguments: GET ?v[]=&v[]=&v[]= or POST | |
||
272 | |-------------------------------------------|----------------------------------------------| |
||
273 | | * When run() has finished, the program | * When run() has finished, the program | |
||
274 | | flow continues, although it is not | flow continues. | |
||
275 | | recommended that you do anything after | | |
||
276 | | it. (The exit code is remembered for | | |
||
277 | | the shutdown handler) | | |
||
278 | |-------------------------------------------|----------------------------------------------| |
||
279 | | * Exactly 1 job must be called, resulting | * You can call as many jobs as you want. | |
||
280 | | in a single output of that job. | A website can include more than one | |
||
281 | | | Nagios output which are enumerated with | |
||
282 | | | a serial number (0,1,2,3,...) or manual ID.| |
||
283 | |-------------------------------------------|----------------------------------------------| |