
pflogx is a simple tool to export OpenBSD's packet filter logs to XML files. It reads a binary logfile generated by the pf logging daemon (pflogd) to generate a human-readable and exploitable XML file. Using an XSLT processor you can convert this XML file to any other format (HTML, CSV, SQL, ...).


REQUIREMENTS
============

Supported systems
-----------------

- FreeBSD 6.0,
- NetBSD 3.0,
- OpenBSD 3.X.


Softwares
---------

- g++ (gcc2 or gcc3),
- make.


Libraries / Headers
-------------------

- Expat [optional],
- libpcap,
- Packet filter's headers.


INSTALLATION
============

Expat
-----

The Expat XML Parser is required to compile pflogx if you want to use the events merging functionality (option "-m"). You can install Expat from packages or build it from sources. 
The "Compilation options" section explains how to specify Expat's headers and libraries directory for build process.


Packet filter's headers and NetBSD
----------------------------------

To compile pflogx under NetBSD 3.0, you need to retrieve an include file from NetBSD userland sources. This file is named if_pflog.h and is located into the /usr/src/sys/dist/pf/net directory. If you have already installed userland sources, you can skip this specific step and directly go to the compilation step.

We will use anonymous CVS access to NetBSD sources tree to retrieve the required file. For further information, please read the "Tracking NetBSD-current with anoncvs" section of the "Tracking NetBSD-current" documentation.

	# cd /usr
	# CVSROOT=:pserver:anoncvs@anoncvs.NetBSD.org:/cvsroot; export CVSROOT
	# cvs login (use password "anoncvs")
	# cvs export -R netbsd-3-0-RELEASE src/sys/dist/pf
	# cvs logout


Compilation & Installation
--------------------------

Compilation and installation of pflogx is quite simple. To compile it without Expat, just type the following command:  

	# make

If you have installed Expat on your system, type the following command instead:

	# make WITH_EXPAT=1

When compilation succeeds you just have to copy the pflogx binary to a suited directory, for example /usr/local:	

	# cp src/pflogx /usr/local/bin/pflogx


Compilation options
-------------------

Maybe you have noticed above that you can pass to make command the "WITH_EXPAT" variable to build pflogx with Expat. Actually there are other existing variables which are detailed in this section.

- DEBUG_MODE: Produce a debug version of pflogx binary. Set any value to the variable to activate it.

- EXPAT_INCLUDEDIR: Specify the directory containing Expat's headers. Default value is "/usr/local/include" for FreeBSD and OpenBSD, "/usr/pkg/include" for NetBSD.

- EXPAT_LIBDIR: Specify the directory containing Expat's library. Default value is "/usr/local/lib" for FreeBSD and OpenBSD, "/usr/pkg/lib" for NetBSD.

- WITH_EXPAT: Build pflogx with Expat. Set any value to the variable to activate it.


USAGE
=====

Executed without options, pflogx reads packet filter logfile from standard input and generates an XML file containing all entries of logfile to standard output.
Available options are detailed in the next section.

Output XML file contains the following fields:
	- Date,
	- Interface name,
	- Action,
	- Rule number,
	- Direction,
	- Protocol,
	- Source address [only for ICMP, TCP and UDP protocols],
	- Source port [only for TCP and UDP protocols],
	- Destination address [only for ICMP, TCP and UDP protocols],
	- Destination port [only for TCP and UDP protocols].

	
Options
-------

	-i <input_file>: Specify path to input packet filter logfile. To read it from standard input, use the special path "-". Default value: standard input. 
	
	-o <output_file>: Specify path to output XML file. To write it to standard output, use the special path "-". Default value: standard output.
	
	-m: Merge new events with already existing events in output XML file. When you specify this option, new events retrieved from packet filter logfile are merged with events already existing in output XML file. This option allows to store whole packet filter history into a single XML file. Please note that other options (filters, date format and events sorting order) are applied to all entries and not only to new entries [requires Expat].	
	
	-a <filter>: Define filter on action. A filter is a list of actions separated by commas. Only the actions matching the given filter will be included in output file. Valid filters for this option are "pass", "drop" and "all". Default value: no filter (ie "all").
	
	-d <filter>: Define filter on direction. A filter is a list of directions separated by commas. Only the directions matching the given filter will be included in output file. Valid filters for this option are "in", "out", "in-out" and "all". Default value: no filter (ie "all").
	
	-p <filter>: Define filter on protocol. A filter is a list of protocols separated by commas. Only the protocols matching the given filter will be included in output file. Valid filters for this option are "icmp", "ip", "raw", "tcp", "udp" and "all". Default value: no filter (ie "all").

	-n <filter>: Define filter on network interface. A filter is a list of network interfaces separated by commas. Only the network interfaces matching the given filter will be included in output file. Default value: no filter (ie "all").

	-t <h|s>: Specify output format for date. Available values are "h" for human representation and "s" for number of seconds since the epoch. Default value: "h".

	-r: Sort events in reverse chronological order instead of chronological order.
	
	-e: Show erroneous packets. Write to error channel the list of packets excluded from output for parsing errors.
	
	-h: Display program usage.

	-v: Display program version.


Samples
-------

- Generates an XML file containing all entries logged by pflogd to standard output:
	# pflogx -i /var/log/pflog

- Generates an XML file "drop.xml" containing all dropped packets:
	# pflogx -i /var/log/pflog -a drop -o drop.xml

- Generates an XML file "pass.xml" containing all authorized outgoing TCP and UDP packets:
	# pflogx -i /var/log/pflog -a pass -d out -p "udp,tcp" -o pass.xml

- Generates an XML file "pflog.xml" containing whole packet filter history [requires Expat]:
	# pflogx -i /var/log/pflog -o pflog.xml -m


XSLT TRANSFORMATION
===================

The xsl directory contains some samples XSLT files.

	- export_csv.xsl: Generates a CSV file. Fields separator is defined in the "separator" variable and can be changed. 

	- export_html.xsl: Generates an HTML 4.01 Strict file with no style. Refresh time is defined in the "refresh-time" variable and can be changed or disabled (with "0").

	- export_xhtml.xsl: Generates an XHTML 1.0 Strict file with no style. Refresh time is defined in the "refresh-time" variable and can be changed or disabled (with "0").

	- first_date.xsl: Retrieves the date of the first entry. It's the oldest entry of the file or, if you have specified the "-r" option, the newest one.

	- last_date.xsl: Retrieves the date of the last entry. It's the newest entry of the file or, if you have specified the "-r" option, the oldest one.


COMPATIBILITY
=============

Format of packet filter logfile is not fixed and can change between releases. For example, packet filter in OpenBSD 3.8 adds logging of UID and PID to logfile. So you can not use a version of pflogx compiled on OpenBSD 3.7 to export a logfile produced on OpenBSD 3.8 and vice versa.


TESTED SYSTEMS
==============

pflogx was successfully tested on the following systems and CPU architectures:

- FreeBSD 6.0 / i386,
- NetBSD 3.0 / i386,
- OpenBSD 3.6 / i386,
- OpenBSD 3.7 / i386,
- OpenBSD 3.8 / i386,
- OpenBSD-current (2006/05) / alpha,
- OpenBSD-current (2006/05) / sgi,
- OpenBSD-current (2006/05) / sparc,
- OpenBSD-current (2006/05) / sparc64.


CONTACT
=======

For any comments, questions or bugs reporting, please send me an email to <akldev@free.fr>. Please also report to me if you have successfully tested (or not :)) pflogx on a system which is not listed in the "TESTED SYSTEMS" section.

Latest releases can be found at <http://akldev.free.fr/pflogx>.


THANKS
======

- Jasper Lievisse Adriaanse <jasper@nedbsd.nl> who has tested pflogx on OpenBSD/alpha, OpenBSD/sgi, OpenBSD/sparc and OpenBSD/sparc64. He has also reported compilation problems with gcc2. 


LINKS
=====

- Daniel Hartmeier's pf page: <http://www.benzedrine.cx/pf.html>.
- pf manual page: <http://www.openbsd.org/faq/pf/>.
- Hatchet: <http://www.dixongroup.net/hatchet/>.
- pf2xml: <http://monkey.org/~jose/software/pf2xml/>.
- Solarflux pf page: <http://solarflux.org/pf/>.


COPYRIGHT
=========

Copyright (c) 2005, Arnaud KLEIN
All rights reserved.

Distributed under the terms of the BSD license. Consult the LICENSE file or http://opensource.org/licenses/bsd-license.php for further details.
