.Dd June 13, 1999
.Dt IPL 4
.Os
.Sh NAME
.Nm ipl
.Nd IP packet log device
.Sh DESCRIPTION
The
.Nm
pseudo device's purpose is to provide an easy way to gather
packet headers of packets you wish to log. If a packet header is to be
logged, either the entire header (including any
.Tn IP
options \(en
.Tn TCP/UDP
options are not included when it calculates header size) is logged or nothing.
Up to 128 bytes of the packet content are logged after the header.
.Pp
Prepending every packet header logged are two structures containing information
relevant to the packet following and why it was logged. The first structure
is
.Fa iplog
and the second is
.Fa ipflog .
Both are declared in
.Aq Pa netinet/ip_fil.h .
and their formats are as follows:
.Bd -literal -offset indent
struct	iplog	{
	u_long	ipl_magic;	/* IPL_MAGIC 0x49504c4d 'IPLM' */
	u_long	ipl_sec;
	u_long	ipl_usec;
	u_int	ipl_len;
	u_int	ipl_count;
	size_t	ipl_dsize;
	struct	iplog	*ipl_next;
}

struct	ipflog	{
	u_char	fl_ifname[IFNAMSIZ];
	u_char	fl_plen;	/* extra data after hlen       */
	u_char	fl_hlen;	/* length of IP headers saved  */
	u_short	fl_rule;	/* assume < 64k rules, total   */
	u_short	fl_group;
	u_32_t	fl_flags;
}
.Ed
.Pp
In the case of the header causing the buffer to finish on a non-32-bit
boundary, padding will be appended to ensure that the next log entry
is aligned to a 32-bit boundary.
.Pp
If the packet content is more than 128 bytes, only
the first 128 bytes of the
packet content are logged. Should the packet content finish on a non-32-bit
boundary, then the last few bytes are not logged to ensure the log entry
is aligned to a 32-bit boundary.
.Pp
.Nm
is a read-only (sequential) character pseudo-device.
.Pp
The ioctls which are loaded with this device can be found under
.Xr ipf 4 .
The only ioctl which is used for logging and doesn't affect the filter is:
.Pp
.Dl Fn ioctl fd SIOCIPFFB "int *"
.Pp
This ioctl flushes the log buffer and returns the number of bytes flushed.
.Pp
There is currently no support for non-blocking IO with this device, meaning
all read operations should be considered blocking in nature (if there is no
data to read, it will sleep until some is made available).
.Sh FILES
.Bl -tag -width /dev/ipl -compact
.It Pa /dev/ipl
IP packet logging pseudo-device
.El
.Sh SEE ALSO
.Xr ipf 4 ,
.Xr ipmon 8
.Sh BUGS
Packet headers are dropped when the internal buffer (static size) fills.