User Guide logalert

Gabriel A. A. , Mon Oct 31 09:41:52 2005

I - About logalert

What is this ?

logalert is a logfile monitoring tool which executes a specific action whenever it matches a string (pattern) occurrence.

It reads an entire file (or starts at the end, just like tail -f), keeps track of any changes, waiting for a specific pattern (a syslog process error, a user login, ...) and fires an action you define when that happens.

Why should I use it?

Do I have to pay for it?

Absolutely NO!

It's free, GPL, open source, public domain, <put-your-favorite-buzzword-here>.

You can copy, use, modify, sell, release as yours. Software politics/copyright is not one of the author's major concerns.

II - Installation

Get the source !

Ok, first grab the latest tarball (.tar.gz file) at logalert's official site

Please always download logalert at official sourceforge website.

For historial purposes, you may find older releases here.

After you downloaded, make sure you compare the MD5 signature to garantee the authenticity:

Install it!

Binary /usr/local/bin/logalert
Manpage /usr/local/man/man.8/logalert.8

NOTE that the default instalation require root privileges. If this is no problem, jump to the next section.

  Oh no! No root for me, now what ?

No problem.

III - Using logalert

logalert monitors a file log ( not only, but we get to that later ) for a expected string or pattern to appear. Once that pattern is detected, it takes some action you define.

The basics

The parameter -m or --match specifies the string ( regular expression ) we're expecting, while the -e or --exec specifies our action, which is normally a path to a shell script, perl, python, binary, etc.

Finally, at the end we have the file name we'll monitor.

Also, we start reading at the end of the file, just like a tail -f command. If you would like to start reading from the beggining of the file you may use the parameter -b or --from-begin .

So, the following line:

  logalert -m 'File does not exist:' -e '/usr/local/bin/' /var/log/apache/errors.log

Would send me an email ( based on ) whenever we find a occurrence of the 'File does not exist:' . If I had used -b , it would scan the entire file instead of starting from the end.

Please note that is very important to surround your parameters with quotations marks (') or double quotations marks ("), specially when crafting some complex regular expression.

logalert always gives you some hints with the -h parameter.

Grabbing strings

Since version 0.3 is possible to grab some string in the regular expression pattern and use it in the command action as a parameter.

Imagine you monitor a log file, waiting for that specific string to appear to fire some action. Additionally, there could be something on that line - an IP Address, a specific error message, a username, etc - you'd like to grab and use it as a parameter in your action - example: send this information via email.

To grab some particular sub-string you should use parenthesis '()' around the pattern. To use it, you refer as $1. If you'd like grab another string, then $2, and so one.


Say you are monitoring users in a given system and would like to watch their behaviour, receiving a email when anything strange happens

  logalert -m ': user ([^\s\t]+) does not have access.' -e '/usr/local/bin/ -u $1' /var/log/access_users.log

Note that inside the parenthesis is the regular expression which will get the name of the user. Also, note that in the execution command it will be referred as '$1'.

Taking a breath - multiple matches, just one action

Sometimes we will have multiple occurrences in a very short period of time but we would like to take action just once. Imagine if you monitor a VPN log file that reports multiple lines containing the pattern Error indicating that the VPN tunnel had some problems. For that, we would like to restart the VPN only once, not everytime we match one line.

In these ocasions you can use the -s or --match-sleep parameter indicating how many seconds we should disable action after the first match.

Another example, using --match-sleep and more complex regular expression:

  logalert --match='[Ee][Rr]{2}[Or][Rr]: IPsec-SA' \
               --exec='/etc/init.d/ipsecclt restart' --match-sleep=8 /var/log/racoon.log

This would monitor the output of racoon IPSEC daemon, waiting for an error pattern, which in this case means that my VPN tunnel had some problems and terminated. Since I know racoon will vomit multiple lines of Error , I want it to disable the action for 8 seconds after the first match, this way I run my shell script to restart it the VPN only once.

Concerning security


Ok, there is no need to run this as root.

You can always change files and directories permissions so normal users can access them normally. On the other hand, just don't chmod 777 and let anyone look everywhere ! This is only a matter of organization.

If you take a look, your UNIX flavor always comes with some default users and each one has its own use.

logalert depends upon reading a file, and that can be arranged simply by creating a specific user or group and changing the files attributes to allow reading.


In UNIX is pretty common for syslogd daemon to administer system logs and that's usually kept on /var/log/ directory.

It's also very common to have a logrotate utility which organizes log files as they grown. They make a copy, compress, enumarate.

In my linux box I have logrotate perl script that does exactly this. It reads its configuration under /etc/logrotate.conf/ and/or /etc/logrotate.d/ where there's an entry for syslog . For this example, I'll deal with /var/log/messages/ famous log file, usually the place syslog dumps a lot of information.

NOTICE this may be different in your system. Solaris, for instance, keeps in /var/adm/messages/ . Please take a look in your /etc/syslog.conf/ file. Learn to use it. man syslog.conf

In my system I have the following logrotate entry:

  /var/log/messages {
      rotate 99
      size +4096k
      create 640 root sys
          /etc/init.d/syslog reload

Note the create 640 root root line which defines the permissions, which user and group the recent created /var/log/messages/ will have after logrotate rotates it.

It defines group sys can read the contents of the file. So, I can create a normal user from group sys to run logalert:

  useradd -c 'logalert user' -s /bin/false -g sys -d /tmp logalert

Now we have user logalert in sys group with no shell, exaclty what we need:

  logalert --user=logalert --match='account removed from group' \
           --exec='/usr/local/bin/' /var/log/messages

Parent mode - multiple instances of logalert

Everything we talked so far was about using logalert directly from a command line. While this is fine for a quick monitoring session, so users may want to have multiple instances of logalert for different files, different patterns and even different actions .

For that, you can create a configuration file specifying block files and their respc. options. It looks like this :

  filename /var/log/messages
          match           = /[Ee][Rr]{2}or: VPN lost connection/
          exec            = /etc/init.d/vpn restart
          match_sleep     = 10
          retry           = 3
          user            = logalert

This block will create a logalert instance that will monitor /var/log/messages/ as user logalert and will execute the vpn script for the first match, disabling it for 10 seconds. In case of any problems, it will retry reading the file 3 times.

Note that :