1. Using ipfw2dshield

ipfw2dshield searches for ipfw log messages and mails a report ready for submission to dshield.org. See http://www.dshield.org/howto.php for more information on the dshield output format and how to submit reports.

The ipfw2dshield software is free and can be redistributed and/or modified under the terms of the GNU General Public License. A copy of the GPL should have been received along with this program (see COPYING).

The script is written for FreeBSD and Darwin (MacOS X). Installation and execution require root permission. To install run

	make install 
This will install the following files:
Note: For the FreeBSD ports version the sample configuration file is instead
Copy or rename the sample configuration file to ~/.ipfw2dshield.rc and edit this latter file to fit your local demands. Please read section 2 below for an explanation of the configuration entries.

Note: The FreeBSD ports version does also accept /usr/local/etc/ipfw2dshield.rc as its configuration file. However, the preference is for ~/.ipfw2dshield.rc in case that both these files exist.

The script creates a stampfile in /var/tmp where it stores date and time information which will be accessed on a subsequent run to prevent multiple submission of log records. Hence this file should remain untouched for correct operation.

The executables and the sample configuration file can be removed by

	make uninstall
The config file ~/.ipfw2dhield.rc and the stampfile in /var/tmp are not deleted by this command.

Usually ipfw2dshield is invoked without arguments. However, it recognizes a number of options which might be convenient for special purposes, e.g., for testing the configuration. Run 'ipfw2dshield  -h' to get some usage instructions.

2. The configuration variables

Your DShield user ID if you have any, set to 0 otherwise.
mailto, mailcc, mailbcc
The 'To:', 'Cc:', and 'Bcc:' headers for mailing the report.
Sets the 'From:' and 'Return-Path:' mail headers for the report. This is particularly useful if ipfw2dshield is run by cron and your reports are directly submitted to dshield.org.
drop_source, drop_source_TCP, drop_source_UDP, drop_source_ICMP
Lists of host or subnet IP addresses that are to be ignored for the report if they occur as the source of logged IP packets. Entries in the drop_source list are assumed to match any protocol, the others are protocol specific according to the list suffix.

An optional 'ports' modifier can be supplied for each list entry. The general form thus is

where 'ip_address' stands for and where 'ports' is a comma-separated list of port numbers or ranges. For example, an entry,137-139,49152-
would cause the script to ignore all logs of packets from 192.168.50.* sent on port 53, 137-139, or 49152-65535. If given in combination with the unspecific subnet a 'ports' modifier applies to any IP address. ICMP packets do not use ports. However, if a 'ports' modifier is issued, logs of ICMP packets will be processed in the same manner as those of TCP/UDP packets where the source and destination port numbers are identified with ICMP types and codes, respectively.
drop_target, drop_target_TCP, drop_target_UDP, drop_target_ICMP
Exclusion lists corresponding to the previously described drop_source* lists, but specifying ignorable destinations of logged IP packets.
The time zone specification used for the output. Note that this variable does not imply assumptions for the timestamps of the input data read from the logs -- these are automatically understood in local time. Setting this value to "YES" will convert the timestamps to UTC, otherwise local time is preserved.
The expression that is searched for in the log lines.
The directory containing the logfiles, usually /var/log.
The basename of the logfiles to be inspected. For example, the value security is expanded to ${logdir}/security* and the files matching that pattern will be processed in their chronological order. Logs older than the current stampfile will be skipped. Logs whose modification time is more than 6 months in the past will be skipped.
The name of the stampfile in /var/tmp, usually ipfw2dshield.

3. Caveats

The timestamp of a log entry does not describe a unique point of time in that the information on the year and the timezone is not provided. For the dshield report format these data have to be substituted. The timezone is chosen according to /etc/localtime so that no problems are to be expected for machines that never change their timezone. For the year the current year is inserted unless the result corresponds to a future date or time, in which case the previous year is assumed.

4. Contact

For bug reports, suggestions, comments, and stuff like that send mail to Frank W. Josellis <frank at dynamical-systems.org>