<html><head><title>Transform::Alert</title>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" >
</head>
<body class='pod'>
<!--
generated by Pod::Simple::HTML v3.03,
using Pod::Simple::PullParser v2.02,
under Perl v5.010001 at Fri Apr 19 17:46:18 2013 GMT.
If you want to change this HTML document, you probably shouldn't do that
by changing it directly. Instead, see about changing the calling options
to Pod::Simple::HTML, and/or subclassing Pod::Simple::HTML,
then reconverting this document from the Pod source.
When in doubt, email the author of Pod::Simple::HTML for advice.
See 'perldoc Pod::Simple::HTML' for more info.
-->
<!-- start doc -->
<a name='___top' class='dummyTopAnchor' ></a>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="NAME"
>NAME</a></h1>
<p>Transform::Alert - Transform alerts from one type to another type</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="SYNOPSIS"
>SYNOPSIS</a></h1>
<pre> # In your configuration
BaseDir /opt/transalert
<Input test_in>
Type POP3
Interval 60 # seconds (default)
<ConnOpts>
Username bob
Password mail4fun
# See Net::POP3->new
Host mail.foobar.org
Port 110 # default
Timeout 120 # default
</ConnOpts>
<Template>
TemplateFile test_in/foo_sys_email.re
OutputName test_out
</Template>
<Template>
TemplateFile test_in/server01_email.re
Munger test_in/Munger.pm MyMunger->munge
OutputName test_out
</Template>
</Input>
<Output test_out>
Type Syslog
TemplateFile outputs/test.tt
# See Net::Syslog->new
<ConnOpts>
Name TransformAlert
Facility local4
Priority info
SyslogHost syslog.foobar.org
SyslogPort 514 # default
</ConnOpts>
</Output>
# On a prompt
> transalert_ctl -c file.conf -l file.log -p file.pid</pre>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="DESCRIPTION"
>DESCRIPTION</a></h1>
<p>Ever have a need to transform one kind of alert/message into another? For example:</p>
<ul>
<li>Taking a bunch of alert emails and converting them into Syslogs</li>
<li>Converting Syslog alerts to SNMP traps</li>
<li>Converting SNMP traps to Syslogs</li>
<li>Traps to email</li>
<li>Anything to anything</li>
</ul>
<p>Then this platform delivers.</p>
<p>Transform::Alert is a highly extensible platform to transform alerts from anything to anything else. Everything is ran through a configuration file, a couple of templates, and <a href="http://search.cpan.org/perldoc?transalert_ctl" class="podlinkpod"
>Transform::Alert's daemon app</a>.</p>
<p>Or to show it with a UTF8 drawing, the platform works like this:</p>
<pre> Input ──┬── InTemplate ────────────── Output + OutTemplate
├── InTemplate + Munger ──┬── Output + OutTemplate
│ └── Output + OutTemplate
├── InTemplate + Munger ──┬── Output + OutTemplate
└── InTemplate ───────────┘
Input ──┬── InTemplate ────────────── Output + OutTemplate
└── InTemplate + Munger ───── Output + OutTemplate</pre>
<p>All <a href="http://search.cpan.org/perldoc?Transform%3A%3AAlert%3A%3AInput" class="podlinkpod"
>inputs</a> and <a href="http://search.cpan.org/perldoc?Transform%3A%3AAlert%3A%3AOutput" class="podlinkpod"
>outputs</a> are separate modules, so if there isn't a protocol available, they are easy to make. Input templates use a multi-line regular expression with named captures to categorize the variables. Output templates are <a href="http://search.cpan.org/perldoc?Template%3A%3AToolkit" class="podlinkpod"
>TT</a> templates with a <code>[% var %]</code> syntax. If you need to transform the data after it's been captured, you can use a "munger" module to play with the variables any way you see fit.</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="DETAILS"
>DETAILS</a></h1>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="Configuration_Format"
>Configuration Format</a></h2>
<p>The configuration uses an Apache-based format (via <a href="http://search.cpan.org/perldoc?Config%3A%3AGeneral" class="podlinkpod"
>Config::General</a>). There's a number of elements required within the config file:</p>
<h3><a class='u' href='#___top' title='click to go to top of document'
name="BaseDir"
>BaseDir</a></h3>
<pre> BaseDir [dir]</pre>
<p>The base directory is used as a starting point for the daemon and any of the relative paths in the config file. The <code>BaseDir</code> option itself can use a relative path, in which case will start at the config path.</p>
<h3><a class='u' href='#___top' title='click to go to top of document'
name="Input"
>Input</a></h3>
<pre> <Input [name]> # one or more
Type [type]
Interval [seconds] # optional; default is 60s
# <ConnOpts> section; module-specific
# <Template> sections
</Input></pre>
<p>The <code>Input</code> section specifies a single input source. All <code>Input</code> sections must be named. Multiple <code>Input</code> sections can be specified, but the name must be unique. (Currently, the input name isn't used, but this may change in the future.)</p>
<p>The <code>Type</code> specifies the type of input used. This maps to a <code>Transform::Alert::Input::*</code> class. More information about the different modules be found with the corresponding documentation.</p>
<p>The <code>Interval</code> specifies how frequently the input should be checked (in seconds). Server-based input shouldn't be checked too often, as it might be considered abusive. To prevent overruns, the input will only be re-checked after the interval is complete. (In other words, the "last finished" time is recorded, not the "last start".)</p>
<p>There is one <code>ConnOpts</code> section in each input. The options will be specific to each type, so look there for documentation.</p>
<p>The engine may someday be changed to have multi-processed inputs, but the need isn't immediate right now. (Patches welcome.)</p>
<h3><a class='u' href='#___top' title='click to go to top of document'
name="Template"
>Template</a></h3>
<pre> <Input ...>
<Template> # one or more
# Template/File can be optional
TemplateFile [file] # not used with Template
Template "[String]" # not used with TemplateFile
Munger [file] [class]->[method] # optional
OutputName test_out # one or more
</Template>
</Input></pre>
<p>All <code>Input</code> sections must have one or more <code>Template</code> sections. As messages are being processed, each message is tested on all of the templates. Input messages will be ran through <b>all</b> templates tied to that input, even if that message matched a previous template. To prevent a message from matching multiple templates, make sure they are reasonably unique.</p>
<p>All templates must either have a <code>TemplateFile</code> or <code>Template</code> option. In most cases, you should stick with file-based templates, as inline templates are whitespace sensitive, and should only be used for single line REs.</p>
<p>If you don't set a Template option, a template file is not used. Without a Munger to validate the hash, these templates will be accepted (and sent to the outputs), as long as it passes data.</p>
<p>The optional <code>Munger</code> option can be used to specify a module used in changing the variables between the input and output. (More details about <a href="#Mungers" class="podlinkpod"
>Mungers further down</a>.) The option itself can be expressed in a number of ways:</p>
<pre> Munger File.pm
Munger File.pm->method
Munger File.pm My::Munger
Munger My::Munger
Munger My::Munger->method
Munger File.pm My::Munger->method # preferred</pre>
<p>If a class isn't specified, the first package name found in the file is used. If the method is missing, the default is <code>munge</code>. If there isn't a file specified, it will try to load the class like <code>use/require</code>. (Technically, you could take advantage of the <code>.</code> path in <code>%INC</code>, but it's better to just provide the filename.)</p>
<p>If both <code>Template/File</code> & <code>Munger</code> options are passed, it will test both forms as an AND-based match, testing the text form via template first. This has the benefit of using the input templates as a "gatekeeper", and can be used to delegate different templates to different Mungers. Any named captures from the input template will be passed as a <code>t</code> hash in the variables to the Munger.</p>
<p>The <code>OutputName</code> options provide the name of the Output sources to use after a template match is found. (These sources are defined below.) More that one option means that the alert will be sent to multiple sources.</p>
<h3><a class='u' href='#___top' title='click to go to top of document'
name="Output"
>Output</a></h3>
<pre> <Output [name]> # one or more
Type [type]
TemplateFile [file] # not used with Template
Template "[String]" # not used with TemplateFile
# <ConnOpts> section; module-specific
</Output></pre>
<p>Like <code>Input</code>, <code>Output</code> sections need to be uniquely named. This name is used with the <code>OutputName</code> option above. Also like <code>Input</code>, the <code>Type</code> functions the same way (mapping to a <code>Transform::Alert::Output::*</code> class), and <code>ConnOpts</code> contains all of the module-specific options.</p>
<p>Similar to <code>Template</code> sections, the <code>Output</code> section must either have a <code>TemplateFile</code> or a <code>Template</code> option. However, you can only use a single template per <code>Output</code>. If you need more, use another section with most of the same options.</p>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="Directory_Structure"
>Directory Structure</a></h2>
<p>Depending on how large your setup is, you may want to create a directory structure like this:</p>
<pre> /opt/transalert # config, log, PID
/opt/transalert/input1 # various input template directories
/opt/transalert/input2
/opt/transalert/input3
/opt/transalert/outputs # single directory for output templates</pre>
<p>If your set up is small, you can get away with a single directory, or at least single input/output directories. Just be sure to use the log/PID options in <a href="http://search.cpan.org/perldoc?transalert_ctl" class="podlinkpod"
>transalert_ctl</a>, so that they are put in the right directory.</p>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="Input_Templates"
>Input Templates</a></h2>
<p>Input templates are basically big multi-line regular expressions. These are NOT <code>/x</code> whitespace-insensitive regular expressions, as those would make copy/pasting large bodies of text more difficult. (There's an assumption that most input templates will have more static text than freeform RE parts.) Besides, you can still use a <code>(?x...)</code> construct for whitespace-insensitivity and comments. Also, leading and trailing whitespace is removed, so stray whitespace should not be an issue there. RE templates are also put into a <code>^$re$</code>, with begin/end symbols, which can easily be overriden with <code>.*</code>.</p>
<p>Please note that a matched template doesn't stop the matching process, so make sure the templates are unique enough if you don't want to match multiple templates.</p>
<p>Here's an example using an email template:</p>
<pre> [\s\S]*\QTo: <alert@foobar.org>
From: <alert@foobar.org>
Subject: Email Alert - \E(?<subject>[^\n]+)
Date: (?<date>[^\n]+)
[\s\S]+
We found a problem on this device:
\QName :\E (?<name>\w+)
\QProblem :\E (?<problem>[^\n]+)
\QTicket #:\E (?<ticket>\w+)
.*</pre>
<p>Of course, this is taking some assumptions about the order and format of headers, but if this is coming from an automated platform that uses the same mail server, there really shouldn't be much change at all. If you need finer control of the verification process, you can make use of <a href="#Mungers" class="podlinkpod"
>Mungers</a>.</p>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="Output_Templates"
>Output Templates</a></h2>
<p>Output templates use <a href="http://search.cpan.org/perldoc?Template%3A%3AToolkit" class="podlinkpod"
>Template::Toolkit</a>. If you want a quick and dirty lesson on how they work, check out <a href="http://search.cpan.org/perldoc?Template%3A%3AManual%3A%3ASyntax" class="podlinkpod"
>Template::Manual::Syntax</a>. If <b>that</b> is too wordy for you, then just remember that variables are replaced with a <code>[% t.var %]</code> syntax.</p>
<p>The variables passed to the Output (or Munger, if specified) will look like this:</p>
<pre> {
t => {
# text form variables acquired from the input RE template
},
p => {
# preparsed hash variables, sent by the Input module
}
}</pre>
<p>For a structure of the <code>p</code> hash passed, look at the documentation for that input module (under <code>Preparsed Hash</code>). Note that Munger mangling could totally change the structure of the hash passed to the Outputs, depending on what it returns.</p>
<p>Here's an example output template that looks similar to the input one above:</p>
<pre> To: [% t.to %]
From: [% t.from %]
Subject: Email Alert - [% t.subject %]
Date: [% t.date %]
We found a problem on this device:
Name : [% t.name %]
Problem : [% t.problem %]
Ticket #: [% t.ticket %]</pre>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="Mungers"
>Mungers</a></h2>
<p>Mungers are an optional second piece to the input template structure. Regular expressions, as powerful as they are with finding and capturing information, only do just that. Sometimes you need to warp the information you've captured to fit the mold that the output can use. Or sometimes you need to validate the input in a better fashion than REs can provide. Mungers fit both of those roles.</p>
<p>Mungers are basically freeform Perl modules that transform and/or validate the input data passed to it. Here's an example munger, straight from the test platform:</p>
<pre> package TestMunger;
sub munge {
my ($class, $vars, $tmpl_grp) = @_;
$vars->{t}{thingy} = delete $vars->{t}{item};
return int rand(2) ? $vars : undef;
}
1;</pre>
<p>This munger does two (useless) things: change the name of the <code>item</code> variable to <code>thingy</code>, and randomly reject the input. But, this munger could just as easily do anything Perl can do to transform and validate the data.</p>
<p>All mungers are called by their class (ie: <code>TestMunger->munge</code>), so all of them should have a package name. They should also return either <code>undef</code> (as a rejection) or the variable list (as a hashref). If the input ends up with multiple alerts, a munger can also pass an arrayref (of hashrefs), and they will be sent to the outputs individually.</p>
<p>A munger could also become the <b>primary</b> piece for input transformation/validation by not specifying a Template option.</p>
<p>Mungers are also passed the <a href="http://search.cpan.org/perldoc?Transform%3A%3AAlert%3A%3ATemplateGrp" class="podlinkpod"
>TemplateGrp</a> object. This is mostly used as a way to hook into the log, like:</p>
<pre> $tmpl_grp->log->debug("Munger didn't like Message Body");</pre>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="Variable_Passing"
>Variable Passing</a></h2>
<p>If you're still confused on the variable passing, look at it this way:</p>
<pre> Input ──┬── $text ───── InTemplate ───── t => { %+ } ──┬── Munger ───── { ??? } ───── Out...
└── $hash ────────────────────── p => $hash ──┘
Input ──┬── $text ────────────────────── t => { } ──┬── Munger ───── { ??? } ───── Out...
└── $hash ────────────────────── p => $hash ──┘
Input ──┬── $text ───── InTemplate ───── t => { %+ } ──┬───────────────────────────── Out...
└── $hash ────────────────────── p => $hash ──┘
Input ──┬── $text ────────────────────── t => { } ──┬── Munger ───── [ { ??? }, ── Out...
└── $hash ────────────────────── p => $hash ──┘ { ??? }, ── Out...
{ ??? } ] ─ Out...
...OutTemplate ───── $str ───── Output</pre>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="CAVEATS"
>CAVEATS</a></h1>
<ul>
<li>This doesn't work on Windows. Blame <a href="http://search.cpan.org/perldoc?Proc%3A%3AProcessTable" class="podlinkpod"
>Proc::ProcessTable</a>. Or rather, <a href="https://rt.cpan.org/Ticket/Display.html?id=75931" class="podlinkurl"
>this bug</a>.</li>
</ul>
<ul>
<li>One would consider this a grand feat of over-engineering, which doesn't apply to every single protocol cleanly. For example,</li>
</ul>
<pre> email input templates alone probably shouldn't be used, as header order might change, and the SNMP I/O doesn't translate to text
very well. YMMV.</pre>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="TODO"
>TODO</a></h1>
<ul>
<li>Moar I/O:</li>
</ul>
<pre> Inputs Outputs
------ -------
HTTP::Atom
HTTP::RSS
File::CSV File::CSV
File::Text File::Text
IRC</pre>
<ul>
<li><a href="http://search.cpan.org/perldoc?Pegex" class="podlinkpod"
>Pegex</a> support for input templates, maybe when we stop playing with the syntax :)</li>
<li>Multi-threaded and/or -processed inputs/outputs</li>
</ul>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="AVAILABILITY"
>AVAILABILITY</a></h1>
<p>The project homepage is <a href="https://github.com/SineSwiper/Transform-Alert/wiki" class="podlinkurl"
>https://github.com/SineSwiper/Transform-Alert/wiki</a>.</p>
<p>The latest version of this module is available from the Comprehensive Perl Archive Network (CPAN). Visit <a href="http://www.perl.com/CPAN/" class="podlinkurl"
>http://www.perl.com/CPAN/</a> to find a CPAN site near you, or see <a href="https://metacpan.org/module/Transform::Alert/" class="podlinkurl"
>https://metacpan.org/module/Transform::Alert/</a>.</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="SUPPORT"
>SUPPORT</a></h1>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="Internet_Relay_Chat"
>Internet Relay Chat</a></h2>
<p>You can get live help by using IRC ( Internet Relay Chat ). If you don't know what IRC is, please read this excellent guide: <a href="http://en.wikipedia.org/wiki/Internet_Relay_Chat" class="podlinkurl"
>http://en.wikipedia.org/wiki/Internet_Relay_Chat</a>. Please be courteous and patient when talking to us, as we might be busy or sleeping! You can join those networks/channels and get help:</p>
<ul>
<li>irc.perl.org
<p>You can connect to the server at 'irc.perl.org' and join this channel: #web-simple then talk to this person for help: SineSwiper.</p>
</li>
</ul>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="Bugs_/_Feature_Requests"
>Bugs / Feature Requests</a></h2>
<p>Please report any bugs or feature requests via <a href="http://search.cpan.org/perldoc?GitHub" class="podlinkpod"
><a href="https://github.com/SineSwiper/Transform-Alert/issues" class="podlinkurl"
>https://github.com/SineSwiper/Transform-Alert/issues</a></a>.</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="AUTHOR"
>AUTHOR</a></h1>
<p>Brendan Byrd <BBYRD@CPAN.org></p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="COPYRIGHT_AND_LICENSE"
>COPYRIGHT AND LICENSE</a></h1>
<p>This software is Copyright (c) 2013 by Brendan Byrd.</p>
<p>This is free software, licensed under:</p>
<pre> The Artistic License 2.0 (GPL Compatible)</pre>
<!-- end doc -->
</body></html>