Content-type: text/html Manpage of FIRELOGD

FIRELOGD

Section: Maintenance Commands (8)
Updated: January 17, 2001
Index Return to Main Contents

NAME

firelogd - firewall log daemon

SYNOPSIS

firelogd [-dmskh] [-b buffersize] [-e email] [-l log] [-t template] [-]

DESCRIPTION

Firelogd will read ipchains or netfilter/iptables firewall log data in (nearly) real time. It will queue up a small batch of alerts and mail them to you.

It can also be used to parse an existing log file or take log data on standard input for formatting.

WARNING

THIS IS NOT A FIREWALL! It will not increase the security of your machines except that it makes it easy to review your log data and respond to it. It will not affect your existing log setup. This software is offered for free and without restrictions of any sort except that you agree not to hold the author responsible if it does something you don't like. If that does happen, the author would appreciate hearing about it.

FEATURES

Firelogd performs host name resolution and port/protocol lookups, it also provides icmp code/type data. It was designed to be run as a daemon process, but you can use it to output data to a terminal or to turn a logfile into something readable. Output templates can be written to format the data any way you like. Some examples are given below. NOTE: Because firelogd will attempt to resolve all IP addresses, some delay may be expected in the output. Some queries will have to time out.

HOW DOES IT WORK?

Firelogd reads a FIFO (first in, first out) file that is written by syslog. Syslog writes to the pipe and firelogd is there to parse the log entry into a readable format. It will save a (BUFFERSIZE) number of log alerts and mail them to you when the threshold is reached. NOTE: the mechanism used to send the email alerts depends on the mail(1) command being in the path of the user executing firelogd. If you wish to change the command that sends mail you will need to obtain the firelogd sources and make the appropriate changes.

BASIC SETUP REQUIRED

You need a firewall using ipchains or iptables. This program will not do anything for you if you do not have your firewall rules logging to syslog. You should see the documentation for your particular system to properly set up the firewall itself.

Create the FIFO that syslog will write to by using the command "mkfifo". See the mkfifo(1) man page for instructions.

Example:
mkfifo /var/log/kernelpipe

Add a directive to your syslog configuration file which will send log data to the pipe. See the syslog.conf(5) man page for instructions.

Example (in /etc/syslog.conf):
kern.* |/var/log/kernelpipe

Restart syslog to start sending data to the FIFO.

OPTIONS

firelogd accepts the following options:

-h, --help, [any unrecognized option]: Show summary of options and version information.
[no options]: Open the default log file (FIFO) and print formatted log entries to standard output.
-, (standard input): Take the data to be parsed from standard input.
Example:
cat <logfile> | firelogd -
-d, (daemon): Open the default log file (FIFO) and become a daemon process. The default mail buffer size (10 entries) and default email address (root@localhost) will be used.
-b<buffersize>, (buffersize, assumes daemon): Set the size of the mailbuffer - the number of alerts to queue before sending report. This value can range from 1 up to available memory. The default is 10. Example: firelogd -b5
-e<email address>, (set the email address for alerts): The default email address for alerts when running in daemon mode is "root" on the firewall box. You can use this option to set it to any valid email address.
Examples:
firelogd -eian
firelogd -e root@isdpt.my.com
-k, (kill): Kill a running firelogd daemon process. If there are any queued alerts they will be written to a temporary buffer file. This buffer will be read and removed the next time the program is run in daemon mode.
This option can also be useful if the program is otherwise terminated ungracefully. If this happens, a stale pid file will remain. The '-k' option removes the pid file.
-l<logfile>, (log file or fifo to open): Specify the log file to open or the FIFO to watch. The default file is /var/log/kernelpipe
This option can not be used if there is a firelogd daemon process already running. If daemon is already runing, use the '-' flag (above) to parse a particular file.
-m, (mixed log data, tables and chains data together): Normally firelogd will try to figure out if the log data being given to it is from ipchains or iptables. When a log entry matches one, no further attempts will be made to match the other. The '-m' option will cause firelogd to continue looking for both types of data. This might be useful if you are collecting logs over the network from different sources, or if you are experimenting with different setups on your firewall.
This option does impose a performance penalty, so don't use it if you don't need it.
-s, (disable extended services lookup): Do not use the extended services file for port lookups. If this option is used the normal system services lookup is done (getservbyname). The extended services file is located at "/etc/iana-port-numbers" and you can replace it with one of your own.
-t<template>, (output template file): Set the template file for the output preprocesser. This is read in on program startup and the output will be formated according to the directives in the active template. The default location for the template file is /etc/firelogd.conf

OUTPUT TEMPLATES

Using an output template you can have the log data formatted any way you want. This is done by creating a template file which is read in on program startup by specifying it with the "-t <template>" option. If you do not specify an output template the program will use it's own default format.

Output templates are simply a file with space delimited tokens, any single word or collection of characters is a token. The token '$' is simply a three character token with no special meaning. In the output for each log entry, the token '$' would stand for itself with no whitespace around it.

There are special tokens that will get replaced with log data or whitespace. One example of this is the two character token nl. It will cause a newline to be output in it's place for each log entry. The token sp will output a space character. An actual space in the template file is required to distinguish one token from another, but it will not print anything in the program's output.

Two other special tokens are: srcip and r_srcip
srcip will be replaced with the source IP address of the host that logged an alert on your firewall and r_srcip will output the resolved hostname (if available).

A simple output template then could consist of the following:

The sp host sp r_srcip sp - sp IP sp address sp srcip nl hit sp me sp on sp month sp day sp at sp time sp YIKES !! ! nl nl

The previous template in a file named template in the current directory would show the following for three firewall hits using the command:
tail -3 /var/log/kernel | firelogd -t template -

The host badman.crack.nl - IP address 214.0.3.6
hit me on Dec 1 at 12:20:37 YIKES!!!

The host 10.0.0.1 - IP address 10.0.0.1
hit me on Dec 1 at 12:53:01 YIKES!!!

The host ovia.com.ar - IP address 209.13.214.134
hit me on Dec 2 at 18:15:41 YIKES!!!

The special tokens are actually variable names in the data structure which hold the log data. If you want to use one of the special token names you can split it up into two tokens and they becomes just themselves.

All tokens and replacements are concatenated together on output. The special token time can be written as two tokens: ->ti<- and ->me<-. Together they will print time in the output with no replacement. The single token time would print something like 12:20:37 in the output.

You can put comments into your template file by using the special tokens:
startcomment endcomment

TEMPLATE FILE TOKENS

The complete list of special tokens follows:

sp: Output a space character.
nl: Output a newline character.
tab: Output a tab character.
ltype: The log data type. Either IPTABLES or IPCHAINS.
proto: The protocol of the packet. (ICMP, TCP, UDP...)
log: The actual log entry.
month: Jan - Dec
day: 1 - 31
time: 00:00:00 - 23:59:59
msg: The user defined log message under iptables. With ipchains log entries this will print a combination of the disposition (DENY, REJECT), the chain being traversed (input, output) and the rule number which caught the packet.
in: Incoming interface.
out: Outgoing interface.
mac: MAC address
srcip: The source IP address
r_srcip: The resolved source address if available. Otherwise, just the IP address.
dstip: The destination IP address
r_dstip: The resolved destination address if available. Otherwise, just the IP address.
iplen: The IP header length.
tos: The TOS field (in hex notation)
sflags: The TOS bits - (***** - DTREC) - Delay|Throughput|Reliability|ECT-ECN/Monetary|CE-ECN/Reserved
prec: The TOS precedence field (in hex notation)
pflags: The precedence bits - (*** - 123)
ttl: Time To Live
id: The IP ID
frag: fragment data
fflags: IP flags (*** - CDM) - RESERVED/CE(?)|Don't Fragment|More Fragments - ?? Does anyone know why linux sets bit 0 of the IP flags as the congestion bit? RFC2481 refers to the TOS bits 6&7 ???
ICMP SPECIFIC
type: The ICMP type
code: The ICMP code
info: Resolved ICMP information.
trigger: The triggering packet's data (netfilter only)
recursed: NETFILTER ONLY - The resolved information for the triggering packet. This token acts as a complete log entry with the message "TRIGGERING PACKET".
TCP SPECIFIC
window: The TCP window.
res: The TCP reserved bits (in hex notation)
flags: TCP flags, text. (SYN only for ipchains) URG|ACK PSH|RST|SYN|FIN
tflags: TCP flag bits - (******** - 12UAPRSF) - Reserved/ECN|Reserved/ECN|URG|ACK|PSH|RST|SYN|FIN
UDP SPECIFIC
ulen: UDP datagram length
TCP/UDP SERVICE PORTS
srcpt: Source port number
r_srcpt: Source port, resolved
dstpt: Destination port number
r_dstpt: Destination port, resolved

TEMPLATE NOTES

Fields that evaluate to a blank will not be printed. For example, the token info (resolved ICMP information) will not cause any output for a TCP log. The token srcpt (source port) will not print anything for an ICMP packet.

The token recursed will output a complete log entry corresponding to the information from the packet that triggered the ICMP error message. The context information (date, time) is set to the context of the ICMP packet. The log message TRIGGERING PACKET denotes these entries. This is not possible with ipchains.

Some of the fields are specific to netfilter/iptables. Ipchains log data will produce a blank field ("") for these tokens. Example: recursed, prec

FILES

/etc/iana-port-numbers - The extended services file
/etc/iana-icmp-numbers - The icmp lookup data
/etc/firelog.conf - The default output template file
/var/log/kernelpipe - The default log source
/usr/sbin/firelogd - The program file
/var/tmp/firelogd.buffer - The temporary buffer file
/var/run/firelogd.pid - The temporary pid file

DOWNLOAD and UPDATES

The latest version of this program can always be found at:
http://www.speakeasy.org/~roux/dmn

Please report any bugs or update requests to the author.

AUTHOR

Ian Jones <roux@speakeasy.org>.

This document was created by man2html, using the manual pages.
Time: 00:56:43 GMT, April 21, 2001