Looper - Alert Routing System.
Mohit Muthanna [mohit AT muthanna DOT com]

Writing Modules

Modules can be written in any language using the oldest (and simplest) form of communication: STDIN and STDOUT. All a module has to do is read token / value pairs or spit them out. As you may already know, there are two kinds of modules; input modules and output modules. Input modules are used to get data from an external source and feed into Looper. Output modules are used to send data from looper to the outside world. In a configuration, one can have only one input module but many output modules

Input Modules

On startup, an input module reads configuration data from standard input. The data is in the form of token value pairs. A pair is separated by an equal "=" sign and followed by a new-line. After all the data is read, the module should then start it's reading and send all data to standard output in the form of token / value pairs. Each set of token-value pairs is followed by the string "go" and a new-line. The "go" command tells looper to send this batch of data to the rules processor.

For example, go to the modules/input directory in your looper dir and run the syslog_in program. Then type the following (replace text as needed):

^D (That's control-D, grasshopper)

The syslog_in module, now knows which file to parse because of the filename token. An input module receives the configuration information on startup based on the values in the ".conf" file.

As soon as you end input, you'll see a list of token value pairs as so:

date=Jul 7 16:13:19
desc=PAM_pwdb[11266]: (login) session closed for user mohit
date=Jul 7 16:13:19
desc=PAM_pwdb[11266]: (login) session closed for user mohit

These tokens are parsed by Looper and populated into the %inputTokens hash for the rules files to process. And that's it. This is all your module should be doing to be an official looper compliant module. Examine the syslog_in bundled module for some code examples.

Note: Make sure you disable output buffering on STDOUT in your input modules, or you may see a delay in your event feeds. Trust me, it's a real headache to debug.

Output Modules

Output modules work slightly differently from input modules. They still work with token value pairs for input but are responsible for generating the required output in whatever format necessary. For example, the snmptrap_out module takes token / value pairs on input and sends out SNMP traps based on output.

Output modules (generally) first take configuration token / value pairs on input followed by the "configure" command. It then takes token / value data pairs followed by a "go" command. If the connection needs to be closed, send the "quit" command.

Let us examine the logfile_out output module. This is a sample module that accepts input and logs them to a file. Execute the "modules/output/logfile_out" program and type the following.

field2=Cat stuck in engine chassis
text=Testing testing...

Now examine the file specified by the filename configuration token (/tmp/test.log). You should see the event time followed by the token value pairs. The logfile_out module does not care about it's data tokens, but other module may. For example, the snmptrap_out modules need the tokens "generic-trap" and "specific-trap" to function correctly.

Output modules receive configuration input from Looper on startup based on the configuration in the ".conf" file and receive data every event cycle after the rules files is processed based on the %outputTokens hash.

All in all, you can see here how building output modules are just as simple. Just accept input from the terminal and do whatever you want with it. For code examples, examine the logfile_out and snmptrap_out modules.


As you have just learnt, writing modules is a very simple task. You can use any language (or even shell scripts) to build them and it really should be more than a quick hack. Your head must be churning now with all sorts of ideas for input / output modules. Go ahead and get started.

Go to the Looper Event / Alert System home page: looper.sf.net.