Configuration
You can configure alerttail in two ways.
Configuration Concepts:
Alerttail is configured in a tree manner with the following elements:
- Parsers: For each line it will evaluate input text and if it matches it will trigger associated actions.
- Actions: Each action will execute custom logic or it will modify input text.
Cardinality is here defined:
Text 1 — n Parsers 1 — n Actions
Each action can filter - modify incoming text. This text will fall through the chain modified.
Gui configuration
Gui usage is quite easy. Please read the included manual for further instructions.
Manual configuration
* Know from examples.
1. Auth example
2. Proftpd example
3. IpTables example
* Know from theory.
1. Logging config.
2. Alerttail config.
For advanced regexp patterns we suggest you to try kodos a very nice regex debugger.
(ubuntu: sudo apt-get install kodos)
(remember that alerttail needs double escaped regex, see later).
Know from Examples:
Please use example provided with source dist.
All those example are provided with source distribution.
1) Auth.log monitoring.
We will begin with a sample example: Tail /var/log/auth.log to be notified on ’su’ commands.
Just create a file named /usr/local/etc/alertTail-auth.cfg:
You can find auth.cfg here
#####################################
# su auth.log monitoring
######################################
# This example ask alerttail to notify user with a popup indicating that a su (Switch user) command happened.
#
#Note puntuaction is mandatory where needed.
file:{
fileName=”/var/log/auth.log”; # File path to monitor.
sleepSeconds=2; # Second check interval.
textFallDown = true;};
log:{
consoleLevel=”INFO”; #DEBUG INFO WARN ERROR #Console debug level. Choose between those levels. Lower to higher verbosity.
fileLevel=”INFO”; #DEBUG INFO WARN ERROR #File debug level.
filePath=”./logs/alerttail.log”; #Path to a desired alerttail output log.
#Note: to disable fileLevel leave it blank. ie: fileLevel=”";
};
parser:{ #Defined parsers.
parsers=(
{ #First and only parser. #Remember to double escape regex \ with \\type=”regexParser”; #Regular expression parser, if it matches actions are executed.
pattern=”.* su .*”; #Parser will match for any text containing white space su and white space.
actions=( #Defined actions.
{
type=”regexGroupAction”; #Regex grouping text filtering action.
groupPattern=”.*((?:FAILED|Successful).*$)”; #Only this regex group will be displayed.
},
{
type=”notifyAction”; #Other action, this will show a popup.
notificationName=”alerttail”; #Logical name of this popup
title=”SwitchUser SU”; #Title showd on this popup
imagePath=”/usr/local/share/alerttail/gtk-dialog-warning.png”; #Path of the image
duration=0; #Popup show milliseconds duration, 0 is forever and 4000 is 4 seconds.
urgency=”CRITICAL”; #Choice between LOW NORMAL CRITICAL
}
);}
);
};
Note that puntuaction is mandatory where needed.
After have created and edited this file just type on the console
alertTail -c /usr/local/etc/alertTail-auth.cfg
from another shell instance type
su pippo
that will show a popup similar to this one:
Back to top page.
2) Proftpd log monitoring.
In this example we would like to know basic events that occours on our proftpd server.
For log in and session monitoring just create a file named /usr/local/etc/alertTail-proftpd.cfg:
You can find proftpd.cfg here
#####################################
# Proftpd log in and session monitoring
#####################################
file:{
fileName=”/var/log/proftpd/proftpd.log”; # File path to monitor.
sleepSeconds=2; # Second check interval.
textFallDown = false; #this way parsers will have the original matched text instead of the one ouput by the first parser
};
#Logging configuration
#
log:{
consoleLevel=”INFO”; #DEBUG INFO WARN ERROR #Console debug level. Choose between those levels. Lower to higher verbosity.
fileLevel=”INFO”; #DEBUG INFO WARN ERROR #File debug level.
filePath=”./logs/alerttail.log”; #Path to a desired alerttail output log.
#Note: to disable fileLevel leave it blank. ie: fileLevel=”";
};
#Remember to double escape regex \ with \\
parser:{ #Defined parsers.
parsers=(
{ #First of two parsers.
type=”regexParser”; #Regular expression parser.
pattern=”.*USER.*”; #Parser will match for any text containing USER word.
actions=(
{
type=”regexGroupAction”; #Regex grouping filtering action.
groupPattern=”.*(USER.*$)”; # This means only USER text to the end will be displayed.},
{type=”notifyAction”; #Other action, this will show a popup.
notificationName=”alerttail”; #Logic name of this popup
title=”Proftpd User event”; #Title showd on this popup
imagePath=”/usr/local/share/alerttail/gtk-dialog-warning.png”; #Path of the image
duration=0; #Popup show milliseconds duration, 0 is forever and 4000 is 4 seconds
urgency=”NORMAL”; # Choice between LOW NORMAL CRITICAL}
);
}, #note comma is used as a separator
{ #Second parser
type=”regexParser”;
pattern=”.*FTP session.*”; #Parser will match for any text containing “FTP session” words.
actions=(
{
type=”regexGroupAction”;
groupPattern=”.*(\\b\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}).*( FTP session.*)”;
# This means only IP and FTP session text to the end will be displayed.
#NOTE that all back slashes are escaped: \ will be \\},
{type=”notifyAction”;
notificationName=”alerttail”;
title=”Proftpd User event”; #Title showd on this popup
imagePath=”/usr/local/share/alerttail/gtk-dialog-warning.png”;
duration=4000; #Popup will be shown for 4 seconds
urgency=”LOW”; # Choice between LOW NORMAL CRITICAL}
);
}
);
};
Note that puntuaction is mandatory where needed.
Note that all back slashes are escaped: \ will be \\
After have created and edited this file just type on the console
alertTail -c /usr/local/etc/alertTail-proftpd.cfg
then try ftp your server. ie: ftp localhost
than it will be shown a popup similar to this one:
If you want to track also file download or uploads check this example:
######################
# Proftpd download monitoring
######################
file:{
fileName=”/var/log/proftpd/xferlog”;
sleepSeconds=2;
textFallDown = true;
};
#Logging configuration
#
log:{
consoleLevel=”INFO”; #DEBUG INFO WARN ERROR #Console debug level. Choose between those levels. Lower to higher verbosity.
fileLevel=”INFO”; #DEBUG INFO WARN ERROR #File debug level.
filePath=”./logs/alerttail.log”; #Path to a desired alerttail output log.
#Note: to disable fileLevel leave it blank. ie: fileLevel=”";
};
#Remember to double escape regex \ with \\
parser:{
parsers=(
{
type=”regexParser”;
pattern=”.*/.*”;
actions=({
type=”regexGroupAction”;
groupPattern=”.*(\\s/.*$)”;},
{type=”notifyAction”;
notificationName=”alerttail”;
title=”Proftpd User download”;
imagePath=”/usr/local/share/alerttail/gtk-dialog-warning.png”;
duration=10000;
urgency=”NORMAL”; #LOW NORMAL CRITICAL}
);
}
);
};
Back to top page.
3) Iptables monitoring.
In this example we will monitor iptables logging.
On any direct connnection to our box we will show a popup with a text link to maps.google.com localizing the ip source.
To try this example you will need a geoip localization database.
Download http://www.maxmind.com/app/geolitecity geolite city database (Download the latest GeoLite City Binary Format) to a known location and unpack it.
Iptables is configured like this
/sbin/iptables -A INPUT –in-interface eth0 –protocol TCP –match state –state NEW -j LOG –log-level info –log-prefix “myiptables SERVICE DENIED: ”
(This command is only for example purpose)
Then we will configure a file for greping “myiptables SERVICE DENIED” text pattern.
Create the following file /usr/local/etc/alertTail-iptables.cfg:
You can find iptables.cfg here
#####################################
# iptables monitoring
#####################################
file:{
fileName=”/var/log/messages”; #File locationto tail.
sleepSeconds=2; #File check interval inseconds.
textFallDown = false; #Parser’s input text will not be affected by chain parsers ouput
};
#Logging configuration
#
log:{
consoleLevel=”INFO”; #DEBUG INFO WARN ERROR #Console debug level. Choose between those levels. Lower to higher verbosity.
fileLevel=”INFO”; #DEBUG INFO WARN ERROR #File debug level.
filePath=”./logs/alerttail.log”; #Path to a desired alerttail output log.
#Note: to disable fileLevel leave it blank. ie: fileLevel=”";
};
#Remember to double escape regex \ with \\
parser:{
parsers=(# a list of parsers to be called on each line.
{#First parsertype=”regexParser”; #type of the parser: aregular expression parser
pattern=”.*SERVICE DENIED.*”;
#matcher pattern, here any log line that matches “SERVICE DENIED” textactions=( # a list of actions to be called if the former parsers matches.
{
type=”regexReplaceAction”; #this action will replace text into formatted text where $number is the captured group
groupPattern=”.*IN=(\\w{3,4}\\d{1})\\s{1}.*SRC=((?:\\d+\\.)+\\d+)\\s.*DST=((?:\\d+\\.)+\\d+)\\s.*SPT=(\\d+).*DPT=(\\d+)\\s.*”;
formattedText=”Incoming connection to local ip [$3] iface [$1] to port <b>[$5]</b> detected From <b>[$2]</b>:$4 “;
#this way we will have a nice text with relevant information. Note that basic html tags are for notifyAction.
},
#{
# type=”commandAction”; # this action execute custom commands. Here not used.
# commandName=”echo \”Matched text is $text\”"; #any shell command.
#},
{
type=”geoipAction”; #this actions takes an ip to filter in geo ip localization info.
cityDatFilePath=”/path/to/geocity/file/GeoLiteCity.dat”; #geoip database path
ipPattern=”.*From\\s<b>\\[((?:\\d+\\.)+\\d+)\\]</b>.*”; #regex pattern to find the ip to localize.
formattedText = “Ip lookup resolved to $town $country <a href=\”http://maps.google.com/?q=$latitude+$longitude\”>Show on maps</a>”;
formattedTextNotFound = “Ip unknown”},
{
type=”notifyAction”; #notification popup action
notificationName=”alerttail”; #notification name
title=”Warning incoming connection blocked”; #title of the popup
imagePath=”/usr/local/share/alerttail/gtk-dialog-warning.png”; #image to be shown
duration=4000; #duration in milliseconds of the popup
urgency=”NORMAL”; #popup urgency, between “LOW NORMAL CRITICAL”
}
);},
{ #Second Parser#This action is very similar to the former one except that it matches accepted incoming connections.
type=”regexParser”;
pattern=”.*SERVICE ACCEPTED.*”;
actions=(
{
type=”regexReplaceAction”; #this action will replace text into formatted text where $number is the captured group
groupPattern=”.*IN=(\\w{3,4}\\d{1})\\s{1}.*SRC=((?:\\d+\\.)+\\d+)\\s.*DST=((?:\\d+\\.)+\\d+)\\s.*SPT=(\\d+).*DPT=(\\d+)\\s.*”;
formattedText=”Incoming connection to local ip [$3] iface [$1] to port <b>[$5]</b> detected From <b>[$2]</b>:$4 “;
#this way we will have a nice text with relevant information. Note that basic html tags are for notifyAction.
},
{
type=”geoipAction”;
cityDatFilePath=”/path/to/geocity/file/GeoLiteCity.dat”;
ipPattern=”.*From\\s<b>\\[((?:\\d+\\.)+\\d+)\\]</b>.*”;
formattedText = “Ip lookup resolved to $town $country <a href=\”http://maps.google.com/?q=$latitude+$longitude\”>Show on maps</a>”;
formattedTextNotFound = “Ip unknown”;},
{
type=”notifyAction”;
notificationName=”alerttail”;
title=”!ALERT! Incoming Connection ACCEPTED”;
imagePath=”/usr/local/share/alerttail/applet-critical.png”;
duration=0;
urgency=”CRITICAL”;
}
);}
);#end parsers
};
start alerttail by typing
alertTail -c /usr/local/etc/alertTail-iptables.cfg
If you wish to try it without configuring iptables just type this to a console as super user
echo “myiptables SERVICE ACCEPTED Drop: IN=eth3 OUT= MAC=00:11:d8:a0:bd:8e:00:07:84:50:b3:fc:08:00 src=111.111.111.111 DST=222.222.222.222 LEN=40 TOS=0×00 PREC=0×00 TTL=48 ID=7398 DF PROTO=TCP SPT=59485 DPT=22 WINDOW=0 RES=0×00 RST URGP=0″ >> /var/log/messages
change 111.111.111.111 and 222.222.222.222 to some public ip.
It would popup something like this:
Back to top page.
Know from theory:
Alerttail has two main configuration points: It’s own logging and main tail config.
1. Logging config.
Basic:
Alerttail logs events into his log file. This could be useful to review all alert messages.
log:{
consoleLevel=”DEBUG”;
fileLevel=”INFO”;
filePath=”./logs/alerttail.log”;
};
consoleLevel is a level between DEBUG INFO WARN ERROR. Lowest to highest verbosity. It will log to shell console as ouput.
fileLevel is a level between DEBUG INFO WARN ERROR. Lowest to highest verbosity.
filePath this is needed to identify logging file location.
This examples disable logging (Only console with warn level).
log:{
consoleLevel=”";
fileLevel=”";
filePath=”";
};
File configuration
file :
{
fileName = “/var/log/messages”;
sleepSeconds = 2;
textFallDown = false;
};
where fileName is the location of the file to be watched.
SleepSeconds is the interval between two check
textFallDown if true any matched text will be given between parsers as the output of the preceeding parser.
If a parser and it’s action will modify incoming text and textFallDown is true text it will be passed modified to the subsequent parser.
2. Parsers and Actions config.
Alerttail works with Parsers and Actions.
Parsers parse each line tailed by alerttail and decide if it matches.
If a parser matches a line then it will call several action in chain passing the interested line.
Note ANY action filtering will interest all subsequencing nodes.
It means that if an action filters all but a word, only that word will fall through the chain and any actions or parsers will see only that word as an incoming input.
For parsers if you want original text always to be passed into subsequent parsers just configure textFallDown = false; into file section.
Alerttail Parsers available are:
- A regular expression parser. This parser will execute actions to the line if the regex pattern matches.
- type:regexParser
- arguments:
-pattern=”.*regexMatchingPattern.*”;
Actions execute some logic associated to a matched line.
Actions can modify the given line and pass it to the next registered action.
Alerttail Actions available are:
- A regular expression filtering action. This action will filter the input line according to regex grouping. This can be useful when you want to caputer only some part of the log message.
Only matching regex group will be shown.- type:regexGroupAction
- arguments:
-groupPattern=”.*(IN=\\w{3}\\d{1}\\s{1}).*”
Note: you will need to escape \ to double \\
- A regular expression replace action. This action enable text replacing and reordering with custom text.
You can capture groups and rewrite those back in different form.- type:regexReplaceAction
- arguments:
-groupPattern=”.*(Group1).*(Group2).*(Group3).*”;
-formattedText=”This is custom text. Group three is $3 and group one is $2″;
- A command action that will execute a shell command.
- type:commandAction
- arguments:
-commandName=”ls -al”
command Name accepts $text placeholder that it will be modified during execution. (ex: echo \”matched text is $text bye!\”
- A notify action that will popup to the desktop a notification.
- type:notifyAction
- arguments:
-notificationName=a logical name to this notification action
-title=a title that will be showned on the popup. (accepts html simple tags)
-imagePath=path to an image to be shown
-duration=duration of the popup in milliseconds i.e 4000 = 4 seconds (0 = forever)
-urgency= a value between LOW NORMAL CRITICAL
Note: notification text can contains simple html, invalid html will result in no text to be shown.
- A geoip action. This action will parse the log line and try to look up the location from a database file.
- type:geoipAction
- arguments:
-cityDatFilePath= a path to ip to city location db file
(download it from http://www.maxmind.com/app/geolitecity “Download the latest GeoLite City Binary Format”)
-ipPattern=Regex pattern to identify the ip address on the log line.
-formattedText=localization geoip ouput will be incapsulated into placeholder such as $town $country $latitude $longitude (ex: Ip lookup resolved to $town $country <a href=\”http://maps.google.com/?q=$latitude+$longitude\”>Show on maps </a>)
-formattedTextNotFound=text to be displayed in case of unknown ip.
In case you have more files we suggest you to create a script file to execute alerttail once.
Then if you want you can bind it to your window’s manager autostart.
/usr/local/bin/alerttailStartup.sh:
#!/bin/bash
alertTail -c /usr/local/etc/alertTail-iptables.cfg &
alertTail -c /usr/local/etc/alertTail-auth.cfg &
alertTail -c /usr/local/etc/alertTail-proftpd.cfg &
alertTail -c /usr/local/etc/alertTail-proftpd-downloads.cfg &
Back to top page.
