Basic Interface Commands

Starting out

To see a list of availabe modules use the show modules command. To see a list of running tasks, use the show tasks command.

show modules
Name, Type, Status, TID

show tasks
TID, PID, Name, Type, Path

As you can see above, there are no modules availabe or tasks running. Since we did not start LooperNG with a configuration file, there were no modules for it to load or run.

Adding modules

The add command lets you add modules to the module list. The syntax of the add command is:

add module name input|output path

As an example let us add the syslog_in input module:

add
Syntax: add module_name (input|output) path

add syslog1 input /opt/local/looper/modules/syslog_in
Adding syslog1 (/opt/local/looper/modules/syslog_in).

show modules
Name, Type, Status, TID

syslog1 Input   Stopped -1

The above command adds an input module named syslog1 located at /opt/local/looper/modules/syslog_in. As the output of show modules states, the module is in the list and is not running. The TID is the module's task identifier. -1 simply means that there is no task associated with that module.

Configuring Modules

The configure command is used to send a configuration token to the module. The syntax of the configure command is as so:

Add a configuration token:
configure module token value

Remove a configuration token:
configure module token

List configuration tokens:
configure module

So, to tell syslog1 to monitor the syslog file /var/log/messages, use the following command:

configure syslog1 logfile /var/log/messages
Configuring syslog1 (logfile).

To tell syslog1 to send it's debug messages to /opt/local/looper/log/syslog1.log, use the following command:

configure syslog1 debugmessages /opt/local/looper/log/syslog1.log
Configuring syslog1 (debugmessages).

To tell syslog1 to start reading the log file from the last 10 lines, use the following command:

configure syslog1 tailstyle 10
Configuring syslog1 (tailstyle).

To see the syslog1 configuration, type:

configure syslog1
Configuration for syslog1:
        tailstyle = 10
        debugmessages = /opt/local/looper/log/syslog1.log
        logfile = /var/log/messages

Adding an output module

Now, using the above commands, let's add an output module. The logfile_out output module is a useful one to start with. It is used to append events to a log file and is a useful debugging aid.

add log1 output /opt/local/looper/modules/logfile_out
Adding log1 (/opt/local/looper/modules/logfile_out).

configure log1 filename /tmp/log1.out
Configuring log1 (filename).

configure log1 debugmessages /tmp/log1.debug.out
Configuring log1 (debugmessages).

show modules
Name, Type, Status, TID

log1    Output  Stopped -1
syslog1 Input   Stopped -1

Now we have an input module and an output module.

Starting the modules

It is good practice to start the output modules before the input modules. This is because if there are no output modules currently running LooperNG will just drop alerts it gets from the input modules.

To start a module, use the start command:

start log1
Starting log1.

start syslog1
Starting syslog1.

show modules
Name, Type, Status, TID

log1    Output  Running 5
syslog1 Input   Running 6

show tasks
TID, PID, Name, Type, Path

6       2742    syslog1 Input   /opt/local/looper/modules/syslog_in
5       2741    log1    Output  /opt/local/looper/modules/logfile_out

If you're monitoring LooperNG's log output, you'll see a lot of juicy information. If you go and examine /tmp/log1.out, you'll see it grow as syslog events come in.

What is going on right now, is that since there is no rules file, LooperNG just forwards all alerts it gets from any input module to all output modules. This may not be what we want. We may want to filter / enrich the alerts and route them to the right locations, eg., all Auth Failed alerts go to snmp1 (which generates an SNMP trap for eg.). To do this we need to add a rules file (which we will discuss shortly).

Stopping tasks and deleting modules

To stop a running task use the stop command followed by the TID of the task. The stop all command stops all running tasks.

show tasks
TID, PID, Name, Type, Path

4       2823    log1    Output  /opt/local/looper/modules/logfile_out
5       2824    syslog1 Input   /opt/local/looper/modules/syslog_in

stop 5
Stopping syslog1(5).

show tasks
TID, PID, Name, Type, Path

4       2823    log1    Output  /opt/local/looper/modules/logfile_out

show modules
Name, Type, Status, TID

log1    Output  Running 4
syslog1 Input   Stopped -1

To delete the module, first make sure the task is stopped, then use the delete command.

show modules
Name, Type, Status, TID

log1    Output  Stopped -1
syslog1 Input   Stopped -1

delete log1
Deleting log1.

delete syslog1
Deleting syslog1.

show modules
Name, Type, Status, TID

Handling SIGHUP

LooperNG handles SIGHUP by stopping all running tasks and restarting them after 5 seconds. It also reloads the rulesfile. SIGHUP is a quick way to tell LooperNG that the rules file has been changed.

Shutting down LooperNG

The shutdown command stops all tasks and schedules LooperNG for shutdown after all tasks exit. To undo a shutdown (before exiting the admin client), send it a SIGUSR1 signal. This enables the admin server again. LooperNG basically exits if it has nothing to do, i.e., if there are no running tasks for it to manage and the admin server is disabled.

Proceed to Using a configuration file

---

Back to LooperNG Tutorial