IPL(4)

✨ NAME ✨

okay bestie, gather round 💖 this is ipl — the IP packet log device. she logs packet headers for you, no cap.

🌸 DESCRIPTION 🌸

so the whole purpose of the ipl pseudo device is to give you an easy lil way to collect packet headers of the packets you wanna log 🎀 and here's the vibe: if a packet header is gonna be logged, the entire header gets logged — IP options included, bestie — or it doesn't get logged at all. no half-measures. (tiny note tho: TCP/UDP options are not included when it calculates header size. iykyk.)

the packet contents get logged after the header too, obviously. and if the log reader is busy or otherwise can't read log records? up to IPLLOGSIZE bytes of data are stored — and 8192 is the default, periodt. 💅

prepended to every packet header logged is a structure holding info about the packet that follows and why it got logged. its format is literally this:

/*
 * Log structure.  Each packet header logged is prepended by one of these.
 * Following this in the log records read from the device will be an ipflog
 * structure which is then followed by any packet data.
 */
typedef struct iplog    {
        u_long  ipl_sec;
        u_long  ipl_usec;
        u_int   ipl_len;
        u_int   ipl_count;
        size_t  ipl_dsize;
        struct  iplog   *ipl_next;
} iplog_t;

typedef struct  ipflog  {
#if (defined(NetBSD) && (NetBSD <= 1991011) && (NetBSD >= 199603))
        u_char  fl_ifname[IFNAMSIZ];
#else
        u_int   fl_unit;
        u_char  fl_ifname[4];
#endif
        u_char  fl_plen;        /* extra data after hlen */
        u_char  fl_hlen;        /* length of IP headers saved */
        u_short fl_rule;        /* assume never more than 64k rules, total */
        u_32_t  fl_flags;
} ipflog_t;

when you're reading from the ipl device you have to call read(2) with a buffer big enough to hold at least 1 complete log record 🫶 because reading partial log records? not supported. not a thing. don't try it.

also if the packet contents are more than 128 bytes when log body is used, then only 128 bytes of the packet contents get logged. that's the limit, bestie. 😭

now — even tho it's only possible to read from the ipl device, opening it for writing is required when you're using an ioctl that changes any kernel data. the way that works is just how it works, okay? 💀

the ioctls loaded with this device live over in ipf(4) 👑 but the ones that are for logging and don't mess with the filter are:

ioctl(fd, SIOCIPFFB, int *)
ioctl(fd, FIONREAD, int *)

the SIOCIPFFB ioctl flushes the log buffer and returns the number of bytes flushed ✨ FIONREAD returns the number of bytes currently used for storing log data 🌈

⚠️ and listen — if IPFILTER_LOG is not defined when compiling, SIOCIPFFB is not available, and FIONREAD will return but not do anything. like, it shows up but does nothing. ghosting you fr fr. 🙈

one more thing: there's currently no support for non-blocking IO with this device 😳 which means all read operations should be considered blocking in nature — if there's no data to read, it will sleep until some is made available. she naps. she waits. main character energy. 😴💜

🌟 SEE ALSO 🌟

• ipf(4)

💀 BUGS 💀

packet headers are dropped when the internal buffer (static size) fills. yeah. she fills up and starts dropping them. iconic but tragic. 😭

🎀 FILES 🎀

• /dev/ipl0

and that's the whole page, bestie 💖 this was IPL(4) from the Kernel Interfaces Manual — source/version and all, mwah 🫶 now go log some packets responsibly ✨💅