Menu
▾
▴
[Devmon-devel] SF.net SVN: devmon:[194] trunk/docs/TEMPLATES
|
From: <buc...@us...> - 2011-01-21 14:58:30
|
Revision: 194
http://devmon.svn.sourceforge.net/devmon/?rev=194&view=rev
Author: buchanmilne
Date: 2011-01-21 14:58:23 +0000 (Fri, 21 Jan 2011)
Log Message:
-----------
Some documentation improvements from Richard Finegold #2592621
Modified Paths:
--------------
trunk/docs/TEMPLATES
Modified: trunk/docs/TEMPLATES
===================================================================
--- trunk/docs/TEMPLATES 2011-01-21 14:38:42 UTC (rev 193)
+++ trunk/docs/TEMPLATES 2011-01-21 14:58:23 UTC (rev 194)
@@ -51,15 +51,15 @@
nodes) are extraneous and should be removed. This way, when you
sync your templates on disk to your database, there's no
confusion as to which set of templates on disk match the ones
- that a multinode devmon installation is using (which are the
+ that a multinode Devmon installation is using (which are the
ones in the database).
For all our examples below, we will assume that we are working in
the template directory "/usr/local/devmon/templates". This will
- probably vary in your installation, depending on where you have
+ probably differ in your installation, depending on where you have
installed Devmon.
- The first tier of sub-directories in the templates dir are
+ The first tier of subdirectories in the templates dir are
vendor-model specific. So, each subdirectory represents a
particular model from a particular vendor (so, a Cisco 2950 would
have one directory, while a Cisco 3750 would have another). Any
@@ -67,7 +67,7 @@
are examined. The actual name of these directories is irrelevant,
as the actual vendor and model names are specified in the 'specs'
file (described below). However, it doesn't hurt to make the
- subdirectories somewhat descriptive, I usually use a
+ subdirectories somewhat descriptive; I usually use a
"vendor-model" style.
@@ -97,7 +97,7 @@
structure.
The 'vendor' and 'model' variables are specific to this
- particular device type, that is, there should not be another specs
+ particular device type -- there should not be another specs
file elsewhere in the templates tree that has the same values for
both variables. If there is, Devmon will complain about trying to
redefine a template and reject the second template.
@@ -149,6 +149,7 @@
is treated as a comment by Devmon, and ignored.
Now we'll go over each of these files in detail...
+
----------------------------------
-- The 'oids' file
@@ -176,8 +177,8 @@
Its important that you use the numeric version of an oid for
the second value in this file. Devmon will not map the string
version of an OID to its numeric version before it does a query,
- which means that your SNMP query is will fail if you use
- an alphanumeric oid instead of a numeric one (i.e. 'sysDescr'
+ which means that your SNMP query will fail if you use an
+ alphanumeric oid instead of a numeric one (i.e. 'sysDescr'
is alphanumeric, '.1.3.6.1.2.1.1.1.0' is numeric). I chose
to do this because it is a pain to keep all the various MIBs
installed on all of the nodes in a multi-node cluster, and it
@@ -186,17 +187,18 @@
separate alias from 'sysDescr'.
Also important to note is that OIDs are shared between tests
- on the same template. So if you specify OID aliases with i
+ on the same template. So if you specify OID aliases with
identical names (they are case sensitive, remember) in multiple
tests in a template, there is only going to be a single value
stored in memory, which both OID aliases point to. The upshot
- of this is, that if you use the same OID alias in multiple
- tests (and this is recommended, as it will make your template
- run faster), then they *MUST* have the numeric OID value. If
+ of this is, if you use the same OID alias in multiple tests
+ (and this is recommended, as it will make your template run
+ faster), then they *MUST* have the numeric OID value. If
they dont, you are going to get inconsistent results, as
- the value stored in memory might arbirtrarily be from one SNMP
+ the value stored in memory might arbitrarily be from one SNMP
variable or another.
+
----------------------------------
-- The 'transforms' file
----------------------------------
@@ -257,12 +259,12 @@
the transform input, the resulting transformed alias will
be a repeater.
- With regards to duplicated OID aliases across multiple tests
+ With regard to duplicated OID aliases across multiple tests
in a single template, transformed OID aliases have the same
rules as non-transformed aliases: if you use the same
transformed OID alias in multiple tests (which is recommended
- as this cuts down on the time devmon spends running test logic)
- then their transform rules *must be identical*, as must
+ as this cuts down on the time Devmon spends running test logic)
+ then their transform rules *must be identical*, as must
all OID aliases that your transformed alias depends on. So, for
example, if you have this defined in your if_load test on your
cisco-2950 template:
@@ -276,7 +278,7 @@
you are going to be in trouble, because the 'time' OID alias
might not even exist in the if_load test. So try to keep your
duplicated OID aliases as simple as possible, so you dont have
- you tests stepping on each others toes (although if you do have
+ your tests stepping on each others toes (although if you do have
two transformed OIDs doing the same transform on the same data,
you should by all means duplicate them, as this will make your
tests run much faster).
@@ -292,6 +294,7 @@
the 'best' and red being the 'worst') in the transformed data
alias. The oids can either be comma or space delimited.
+
'CHAIN' transform:
Occasionally a device will store a numeric SNMP oid (AKA the
@@ -312,7 +315,7 @@
.1.1.3.2342 = 'System fans are non-operational'
Chances are that you won't know what leaf values will be returned
- for .1.1.3, but you know that .1.1.2 returns consistant values.
+ for .1.1.3, but you know that .1.1.2 returns consistent values.
You can use the CHAIN transform to 'chain' these two oids together
to make the data more accessible. The format for the CHAIN
transform is:
@@ -326,7 +329,7 @@
'CONVERT' transform:
- Convert a string in either hexidecimal or octal to its
+ Convert a string in either hexadecimal or octal to its
decimal equivalent. Takes two arguments, a target OID alias
and a conversion type, which must be either 'hex' or 'oct'.
@@ -349,7 +352,7 @@
The limit is used as the maximum value of the data alias, and
comes in to play when the value from supplied data alias from
- last polling cycle is more than the value from your current
+ the last polling cycle is more than the value from your current
polling cycle.
This typically occurs when you have counter-wrap issues in
@@ -357,7 +360,7 @@
heavy traffic can wrap its ifOctet counters in less than
two minutes).
- If you don't specify a limit and Devmon detects a counter
+ If you don't specify a limit and Devmon detects a counter-
wrap, it will use either the 32bit or 64bit upper limit,
accordingly.
@@ -373,7 +376,7 @@
Keep in mind that the DELTA transform takes at least two
poll cycles to return meaningful data, so in the mean time
you will get a 'wait' result stored in the target OID alias
- (as well as an aliases that are transformed based off the
+ (as well as in aliases that are transformed based off the
target alias).
@@ -397,6 +400,7 @@
'INDEX' transform:
+
This transform allows you to access the index part of a
numerical OID in a repeater OID.
@@ -419,6 +423,7 @@
do on the index value should be possible with existing
transforms.
+
'MATH' transform:
The MATH transform performs a mathematical expression defined
@@ -481,7 +486,7 @@
templates included with Devmon, to include the ifAlias
information for an interface, but only if it has a value
defined. A very powerful, but easily misused transform.
- Should be interest in using it but not know much about
+ If you are interested in using it but don't know much about
substitution, you might want to google 'regular expression
substitution' and try reading up on it.
@@ -519,10 +524,10 @@
'SWITCH' transform:
The switch transform transposes one data value for another.
- This is most commonly used to transform numeric values
+ This is most commonly used to transform a numeric value
returned by an snmp query into its textual equivalent. The
- first argument in the transform input should be the oid to be
- transformed. Following this should be a list of comma-
+ first argument in the transform input should be the oid to be
+ transformed. Following this should be a list of comma-
delimited pairs of values, with each pair of values being
separated by an equals sign. For example:
@@ -533,7 +538,7 @@
the value of upsBattRepNum was 1, it would store a 'Battery OK'
value in the 'upsBattRep' data alias.
- You can use simple mathmatical tests on the values of the
+ You can use simple mathematical tests on the values of the
source OID alias, as well as assigning values for different
OIDs to the target alias. For instance:
@@ -543,7 +548,6 @@
floating point numerical value [i.e. 1, 5.33, 0.001, etc], and 's'
is a alphanumeric string):
-
n : Source alias is equal to this amount
>n : Source alias is greater than this amount
>=n : Source alias is greater than or equal to this amount
@@ -553,7 +557,6 @@
's' : Source alias matches this string exactly (case sensitive)
"s" : Source alias matches this regular expression (non-anchored)
-
Note that switch statements are applied in a left to right order;
so if you have a value that matches the target value on multiple
switch statements, the leftmost statement will be the one applied.
@@ -562,7 +565,6 @@
to the target OID alias, depending on the value of the source OID
alias, like this:
-
dhcpStatus : SWITCH : {dhcpPoolSize} 0 = No DHCP, >0 = {dhcpAvail}
This would assign the value 'No DHCP' to the 'dhcpStatus' alias
@@ -574,6 +576,7 @@
by the 'dhcpStatus' variable; if you want to inherit threshold
information, use the TSWITCH transform instead.
+
'TSWITCH' transform:
The TSWITCH transform is functionally equivalent to the SWITCH
@@ -639,13 +642,14 @@
the 'worst' and green being the 'best') in the transformed data
alias. The oids can either be comma or space delimited.
+
----------------------------------
-- The 'thresholds' file
----------------------------------
The thresholds file defines the limits against which the
various data aliases that you have created in your 'oids'
- and 'transforms' files are measured against. And example
+ and 'transforms' files are measured against. An example
thresholds file is as follows:
-<start file>-----------------------------
@@ -668,11 +672,11 @@
by colons. The first field in an entry is the data alias that the
threshold is to be applied against. The second field is the color
that will be assigned to the data alias should it match this
- threshold. The third field are the threshold values, which are
+ threshold. The third field has the threshold values, which are
the values that the data alias in the first field will be compared
- against. You can have multiple values, delimited by commas, in
- the third field. The fourth field is the threshold message, which
- will be assigned to the data alias in the first field if it
+ against. You can have multiple values, delimited by vertical bars,
+ in the third field. The fourth field is the threshold message,
+ which will be assigned to the data alias in the first field if it
matches this threshold.
The threshold message can contain other data aliases. If the data
@@ -685,7 +689,7 @@
match a red or yellow threshold. If you want to have a message
associated with a green threshold, you can specify it with
a green color and a threshold value of '_AUTOMATCH_' (with the
- single quotes). This will cause devmon to automatically match the
+ single quotes). This will cause Devmon to automatically match the
threshold when it gets to it, and will assign the green message
to the data alias.
@@ -708,13 +712,13 @@
If no math operator is defined in the threshold, Devmon assumes
that it is a 'greater than' type threshold. That is, if the
value obtained via SNMP is greater than this threshold value, the
- the threshold is considered to be met and devmon will deal with
+ the threshold is considered to be met and Devmon will deal with
it accordingly.
If a threshold value contains even one non-numeric character
(other than the math operators illustrated above), it is
considered a non-numeric threshold. Non-numeric thresholds are
- treated as regular expressions, and devmon tries to match
+ treated as regular expressions, and Devmon tries to match
them against the value of the data contained in the oid that
the threshold is applied against.
@@ -756,7 +760,7 @@
types of exceptions types that you can use, they are:
ignore:
- The 'ignore' exception type causes Devmon not display
+ The 'ignore' exception type causes Devmon to not display
rows in a repeater table which have a primary oid that
matches the exception regexp.
@@ -778,7 +782,7 @@
The exceptions are applied in the order above, and one primary
alias can match multiple exceptions. So if you have a primary
alias that matches both an 'ignore' and an 'alarm' exception,
- no alarm will be generated (in fact, the row wont even be
+ no alarm will be generated (in fact, the row won't even be
displayed in the repeater table).
The example file listed above, from a cisco 2950 if_stat test,
@@ -797,7 +801,7 @@
The messages file is what brings all the data collected from the
other files in the template together in a single cohesive entry.
- It is basically an web page (indeed, you can add html to it, if you
+ It is basically a web page (indeed, you can add html to it, if you
like) with some special macros embedded in it.
An example of a simple messages file is as follows:
@@ -842,10 +846,10 @@
color:
- This flag will print out the bb/hobbit color string
+ This flag will print out the bb/hobbit/xymon color string
assigned to this data alias by the thresholds (this string
looks like '&red' or '&green', etc). This color string
- will be interpreted by hobbit as a colored icon, which
+ will be interpreted by xymon as a colored icon, which
makes alarm conditions much easier to recognize. Like the
'errors' flag, it will also modify the global color.
@@ -856,11 +860,11 @@
assigned to the alias from a non-green threshold match (the
message is the value assigned in the fourth field of an entry
in the thresholds file, remember?). If the value assigned
- to an data alias is green, then this value that replaces this
+ to a data alias is green, then the value that replaces this
flag will be blank.
- Error messages will always be printed as the TOP of the message
- file, regardless of where they are defined with in it. This
+ Error messages will always be printed at the TOP of the message
+ file, regardless of where they are defined within it. This
is done to make sure that the user sees any errors that might
have occurred, which they might miss if the messages file is
too long.
@@ -883,7 +887,7 @@
thresh:
- The syntax for the threshold flag is {oid.thresh:<color>}.
+ The syntax for the thresh flag is {oid.thresh:<color>}.
It displays the value in the threshold file (or custom threshold)
that corresponds with the supplied color. So,
{CPUTotal5Min.thresh:yellow} would display the template value
@@ -910,7 +914,7 @@
Devmon basically just builds an HTML table out of the repeater
data. It can have an optional header, which should be specified
- on the line immediately after the 'TABLE:' tag. If not table
+ on the line immediately after the 'TABLE:' tag. If no table
header is desired, the line after the table tag should be the
row data identifier.
@@ -960,18 +964,22 @@
pad=n
Set the HTML table cellpadding size that Devmon will use
- An example of the some TABLE options in use:
+ rrd
+ See the GRAPHING document in this directory for explanation
+ An example of some TABLE options in use:
+
TABLE: alarmsonbottom,border=0,pad=10
The STATUS: key allows you to extend the first line of the status
- message that Devmon sends to BB/Hobbit. For example, if you need
- to get data to a Hobbit rrd collector module that evaluates data
+ message that Devmon sends to BB/Hobbit/Xymon. For example, if you need
+ to get data to a Xymon rrd collector module that evaluates data
in the first line of the message (such as the Hobbit la collector
which expects "up: <time>, %d users, %d procs load=%d.%d" you can
use this key as follows to get a load average graph:
STATUS: up: load={laLoadFloat2}
+
----------------------------------
-- Done!
@@ -991,20 +999,20 @@
using a dummy bb-hosts file (even if your production Devmon
cluster runs in multi-node mode, running the test Devmon in
single node mode prevents you from having to create an
- additional database for your devmon "test" installation).
+ additional database for your Devmon "test" installation).
With the -vv and -p flags (i.e. devmon -vv -p), you will
get verbose output from Devmon, and if you have a host
in the bb-hosts file that matches the sysdesc in the specs
file of the the model-vendor for the new template you created,
you will also get textual output of your new template!
- (the -p flag causes devmon to not run in the background and
+ (The -p flag causes Devmon to not run in the background and
to print messages to STDOUT as opposed to sending them to the
- display server, and the -vv flag causes Devmon to log verbosely).
+ display server, and the -vv flag causes Devmon to log verbosely.)
Once you are satisfied that your template is working correctly,
you can put it to work in your production installation. In
a single-node installation, this is as simple as copying the
- template directory to the appropriate sub-directory of your
+ template directory to the appropriate subdirectory of your
templates/ dir. On the next poll cycle, Devmon will pick up
the new template, and any new hosts discovered by your
readbbhosts cron job will be added to the Devmon database
@@ -1017,7 +1025,7 @@
and deleting all the template directories on the node machines).
Once you have it in place, run devmon with the --synctemplates
flag. This will read in the templates, update the database
- as necessary, and then notify all the devmon nodes that they
+ as necessary, and then notify all the Devmon nodes that they
need to reload their templates. A full template reload on
all your machines can take up to twice the interval of your
polling cycle, so be patient!
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
