.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Hobbit 3pm" .TH Hobbit 3pm "2020-11-27" "perl v5.32.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Hobbit.pm \-\- Perl module to easily write Hobbit/Xymon tests .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 2 \& use Hobbit; \& my $bb = new Hobbit(\*(Aqtestname\*(Aq); \& \& if (somethings_is_not_so_good) { \& $bb\->color_line(\*(Aqyellow\*(Aq, \*(AqSomething is not so good\*(Aq); \& } \& \& if (somethings_is_really_bad) { \& $bb\->color_line(\*(Aqred\*(Aq, \*(AqSomething is really bad\*(Aq); \& } \& \& $bb\->send(); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" Hobbit.pm is part of the Debian package hobbit-plugins and was written to gather common tasks needed when writing tests for the Xymon monitoring system (formerly known as Hobbit). .SH "EXPORTABLE HELPER FUNCTIONS" .IX Header "EXPORTABLE HELPER FUNCTIONS" .ie n .SS "@regexps = file_to_list_of_regexps($file)" .el .SS "\f(CW@regexps\fP = file_to_list_of_regexps($file)" .IX Subsection "@regexps = file_to_list_of_regexps($file)" .ie n .SS "@globs = file_to_list_of_globs($file)" .el .SS "\f(CW@globs\fP = file_to_list_of_globs($file)" .IX Subsection "@globs = file_to_list_of_globs($file)" .SH "INTERNAL FUNCTIONS" .IX Header "INTERNAL FUNCTIONS" .ie n .SS "$max_color = max_color($color1, $color)" .el .SS "\f(CW$max_color\fP = max_color($color1, \f(CW$color\fP)" .IX Subsection "$max_color = max_color($color1, $color)" Out of two colors, returns the color with the highest severity. .SH "METHODS" .IX Header "METHODS" .SS "Constructor: new Hobbit('testname');" .IX Subsection "Constructor: new Hobbit('testname');" .SS "Constructor: new Hobbit({ test => 'testname', ttl => 60, ...});" .IX Subsection "Constructor: new Hobbit({ test => 'testname', ttl => 60, ...});" Creates a new Hobbit object. .PP \fICommon use cases\fR .IX Subsection "Common use cases" .PP .Vb 9 \& my $bb = new Hobbit(\*(Aqsometest\*(Aq); \& my $bb = new Hobbit({ test => \*(Aqtestname\*(Aq, \& color => \*(Aqgreen\*(Aq, \& hostname => \*(Aqhost.example.com\*(Aq, \& text => \*(AqTest successful\*(Aq, \& title => \*(AqSome Test\*(Aq, \& ttl => 60, \& type => \*(Aqstatus\*(Aq, \& dont_moan => 1 }); .Ve .PP \fIAvailable parameters\fR .IX Subsection "Available parameters" .IP "color" 3 .IX Item "color" The initial color of the test. (Default: \*(L"clear\*(R") .IP "dont_moan" 3 .IX Item "dont_moan" Disable \fBmoan()\fR and \fBcroak()\fR (see below). Needed if e.g. another used Perl module throws a lot of warnings but works fine otherwise, etc. .IP "hostname" 3 .IX Item "hostname" The hostname for which the test should report. (Default: \&\f(CW$ENV\fR{\s-1CLIENTHOSTNAME\s0} || \f(CW$ENV\fR{\s-1MACHINEDOTS\s0} || \f(CW$ENV\fR{\s-1MACHINE\s0} || \&'unknown') .IP "test" 3 .IX Item "test" The name of the test, i.e. the name of the column on the hobbit status web pages. (Mandatory) .IP "text" 3 .IX Item "text" Text which is prepended to generated report. (Default: the empty string) .IP "title" 3 .IX Item "title" The summary of the test. (Default: \*(L"$test \s-1OK\*(R"\s0 respectively \*(L"$test \s-1NOT\s0 ok\*(R") .IP "ttl" 3 .IX Item "ttl" How long the test result is valid before the test state is changed to purple by the xymon daemon if no newer test results have been received. .Sp The default value is set on the xymon server and is 300 seconds by default. .Sp Values without unit are interpreted as minutes. Valid units are h for hours, d for days, and w for weeks. No space between value and unit allowed. .IP "type" 3 .IX Item "type" Allows one to send messages of other types than \*(L"status\*(R", e.g. data, notify, disable, enable, etc. .Sp May not yet work with all of these types properly. Please report bugs via the Debian Bug Tracking system. .SS "Constructor: Hobbit::trends;" .IX Subsection "Constructor: Hobbit::trends;" .SS "Constructor: Hobbit::trends ('hostname');" .IX Subsection "Constructor: Hobbit::trends ('hostname');" Creates a new Hobbit trends object. This is a shorthand for new Hobbit({ type = \&'data', test = 'trends', hostname = \f(CW$hostname\fR, dont_moan => 1 }); .PP \fICommon use case\fR .IX Subsection "Common use case" .PP .Vb 4 \& my $trends = Hobbit::trends; \& $trends\->print ("[$bb\->{test},extralabel.rrd]\en"); \& $trends\->print ("DS:lambda:GAUGE:600:U:U $value\en"); \& $trends\->send; .Ve .SS "add_color('somecolor')" .IX Subsection "add_color('somecolor')" Minutes that a sub test caused the given color state. Adjusts the overall resulting color accordingly. .SS "print('some text')" .IX Subsection "print('some text')" Adds the given text to the end of the current report without changing the current color. .SS "sprintf('format', args ...)" .IX Subsection "sprintf('format', args ...)" Like the \fBprint()\fR method, but using \fBsprintf()\fR with format string and arguments. .SS "color_print('somecolor', 'some text')" .IX Subsection "color_print('somecolor', 'some text')" Adds the given text to the end of the current report and minutes that a sub test caused the given color state. Adjusts the overall resulting color accordingly. .SS "color_line('somecolor', 'some text')" .IX Subsection "color_line('somecolor', 'some text')" Adds the given text to the end of the current report and minutes that a sub test caused the given color state. Prepends that text with an accordingly colored Xymon icon and adjusts the overall resulting color accordingly. .SS "graph('graphname')" .IX Subsection "graph('graphname')" Adds \s-1HTML\s0 for showing a graph. Xymon itself can only show a single graph per test (others can be added to the \*(L"trends\*(R" column). This method works around that limitation by manually linking to the graph \s-1CGI.\s0 .SS "\fBsend()\fP" .IX Subsection "send()" Sends the report to the xymon server. .SH "FUNCTIONS" .IX Header "FUNCTIONS" .SS "grep(\fItag\fP)" .IX Subsection "grep(tag)" Run a xymongrep (bbhostgrep) query and return an array reference of hashes with keys \fBip\fR (string), \fBhostname\fR (string), and \fBtags\fR (array reference). .PP .Vb 4 \& my $list = Hobbit::grep(\*(Aqfoobar\*(Aq); \& foreach my $host (@$list) { \& print "$host\->{ip} $host\->{hostname}\en"; \& } .Ve .SH "INTERNAL METHODS" .IX Header "INTERNAL METHODS" .SS "\fBmoan()\fP" .IX Subsection "moan()" If the check issues a Perl warning, this warning is added to the report with color state \*(L"yellow\*(R". .PP Set dont_moan to 1 to disable this feature. .SS "\fBcroak()\fP" .IX Subsection "croak()" If the check issues a Perl error, this error is added to the report with color state \*(L"red\*(R". .PP Set dont_moan to 1 to disable this feature. .SH "AUTHORS AND COPYRIGHT" .IX Header "AUTHORS AND COPYRIGHT" .Vb 2 \& Copyright (C) 2008\-2011 Christoph Berg \& Copyright (C) 2011 Axel Beckert .Ve .SH "SEE ALSO" .IX Header "SEE ALSO" \fBbb\fR\|(5), \fBxymon\fR\|(1)