NAME

Linux::Netfilter::Log - Read packets logged using the NFLOG mechanism

SYNOPSIS

  use Linux::Netfilter::Log qw(:constants);
  use Socket qw(PF_INET);
  
  my $log = Linux::Netfilter::Log->open();
  
  eval { $log->unbind_pf(PF_INET) };
  $log->bind_pf(PF_INET);
  
  my $group = $log->bind_group(0);
  
  $group->callback_register(sub
  {
          my ($packet) = @_;
          
          ...
  });
  
  while(1)
  {
          $log->recv_and_process_one() or warn "Buffer filled!";
  }

DESCRIPTION

This module provides a wrapper around libnetfilter_log, allowing a Perl program to process packets logged using the NFLOG iptables target.

CONSTANTS

The libnetfilter_log constants may be imported from this module individually or using the :constants import tag.

CLASS METHODS

open()

Constructor. Sets up an nflog handle and underlying netlink socket.

INSTANCE METHODS

bind_pf(protocol_family)

Binds the given nflog handle to process packets belonging to the given protocol family (ie. PF_INET, PF_INET6, etc).

unbind_pf(protocol_family)

Unbinds the given nflog handle from processing packets belonging to the given protocol family.

bind_group($group)

Creates a new Linux::Netfilter::Log::Group object bound to the chosen group number. Throws on failure.

fileno()

Returns the file descriptor of the underlying netlink socket, for polling with select or similar.

recv_and_process_one()

Reads one Netlink message from the socket and processes it, invoking callbacks registered with Group->callback_register().

A single message may contain multiple packets, if the callback throws an exception, any which have not yet been processesed will be lost.

Returns true on success, false if recv() failed with ENOBUFS (indicating the buffer filled up and some messages have been lost). Any other recv() errors will trigger an exception.

BUGS

The size of the buffer used to read netlink messages is currently fixed at 64k.

This is probably bigger than most people need, but if you intend to copy large packet payloads from the kernel AND queue multiple packets at a time, it may not be big enough (recv_and_process_one() will emit warnings upon possible truncation).

I will change this to be dynamically sized automatically in the future if I come up with an efficient way to do it (suggestions welcome).

SEE ALSO

Linux::Netfilter::Log::Group

AUTHOR

Daniel Collins <daniel.collins@smoothwall.net>

COPYRIGHT AND LICENSE

Copyright (C) 2016 Smoothwall Ltd.

This library is free software; you may redistribute it and/or modify it under the same terms as Perl itself.

cpanm Linux::Netfilter::Log

perl -MCPAN -e shell
install Linux::Netfilter::Log