/ 
Net-Firewall-BlockerHelper-0.1.0
/ Net::Firewall::BlockerHelper::backends::xdp

NAME

Net::Firewall::BlockerHelper::backends::xdp - XDP/eBPF backend for Net::Firewall::BlockerHelper.

VERSION

Version 0.1.0

SYNOPSIS

use Net::Firewall::BlockerHelper::backends::xdp;

my $backend;
eval {
    $backend = Net::Firewall::BlockerHelper::backends::xdp->new(
            name    => 'derp',
            options => {
                      interfaces => ['eth0'],
                      },
        );
};
if ($@) {
    print 'Error: '
        . $Error::Helper::error
        . "\nError String: "
        . $Error::Helper::errorString
        . "\nError Flag: "
        . $Error::Helper::errorFlag . "\n";
}

$backend->init;

$backend->ban(ban=>'1.2.3.4');
$backend->ban(ban=>'4.3.2.1');

use Data::Dumper;
print Dumper($backend->list);

$backend->unban(ban=>'4.3.2.1');

$backend->teardown;

DESCRIPTION

This backend drops packets using XDP/eBPF via the xdp-filter tool from xdp-tools.

xdp-filter attaches an XDP program to one or more interfaces and maintains an IP blocklist in a BPF map. This backend loads the program with a default allow policy so only the IPs explicitly added to the blocklist are dropped.

Requires xdp-filter to be installed and in the PATH of the process, which must have sufficient privileges to run it.

METHODS

new

Initiates the the object.

- options :: A hash of options to pass to the backend. See below for
        further info.
    - Default :: {}

- ports :: Not used by this backend but is accepted for parity with
        Net::Firewall::BlockerHelper.
    - Default :: []

- protocols :: Not used by this backend but is accepted for parity with
        Net::Firewall::BlockerHelper.
    - Default :: []

- prefix :: Not used by this backend but is accepted for parity with
        Net::Firewall::BlockerHelper.
    - Default :: kur

- name :: Not used but is required by Net::Firewall::BlockerHelper.
    - Default :: undef

The options hash accepts the following.

- interfaces :: An array ref of interface names to load the XDP program
        onto, e.g. ['eth0']. This is required and must be a non-empty
        array ref.
    - Default :: undef

- xdp_filter_cmd :: The path to the xdp-filter binary.
    - Default :: xdp-filter

- mode :: The match mode passed to the 'ip' command via '-m', either
        'src' or 'dst'.
    - Default :: src

- xdp_mode :: The XDP attach mode used when loading the program, passed to
        the 'load' command via '-m'. One of 'native', 'skb', 'hw', or
        'unspecified'.
    - Default :: native

All errors are considered fatal, meaning if new fails it will die.

my $backend;
eval {
    $backend = Net::Firewall::BlockerHelper::backends::xdp->new(
            name    => 'derp',
            options => {
                      interfaces => ['eth0'],
                      },
        );
};
if ($@) {
    print 'Error: '
        . $Error::Helper::error
        . "\nError String: "
        . $Error::Helper::errorString
        . "\nError Flag: "
        . $Error::Helper::errorFlag . "\n";
}

init

Initiates the backend. For each configured interface this loads the xdp-filter program with the ipv4 and ipv6 features and a default allow policy, so only IPs added to the blocklist are dropped.

No arguments are taken.

If called a second time, it will error.

$backend->init;

ban

Bans an IP. The value of ban is validated as being a IPv4 or IPv6 address and lowercased, then added to the XDP blocklist by running xdp-filter ip <ip> -m <mode>. Banning an already banned IP is a noop.

$backend->ban(ban => $ip);

unban

Unbans an IP. The value of ban is validated as being a IPv4 or IPv6 address and lowercased, then removed from the XDP blocklist by running xdp-filter ip <ip> -m <mode> -r. Unbanning an IP that is not banned is a noop.

$backend->unban(ban => $ip);

ban_cidr

CIDR bans are not supported by this backend; this always sets the cidrNotSupported error.

$backend->ban_cidr(ban => '1.2.3.0/24');

unban_cidr

CIDR bans are not supported by this backend; this always sets the cidrNotSupported error.

$backend->unban_cidr(ban => '1.2.3.0/24');

list_cidr

CIDR bans are not supported by this backend, so this always returns an empty list.

my @banned_cidrs = $backend->list_cidr;

list

List banned IPs. Returns an array of the currently banned IPs.

my @banned = $backend->list;

re_init

Tells the backend to re-init it's self.

This will call teardown and init again. After that it will re-add all previously added bans.

$backend->re_init;

teardown

Tears down the setup for the backend.

This will unload the XDP program from each configured interface.

$backend->teardown;

stop

Alias for "teardown", provided for parity with the fail2ban actionstop concept.

$backend->stop;

check

Runs xdp-filter status to verify the setup is still in place. To be considered healthy the command must exit zero and every configured interface must be listed as loaded in its output; as the status is global, the exit code alone would miss a single interface having been unloaded. This is the equivalent of fail2ban's actioncheck.

if ( !$backend->check ) {
    $backend->re_init;
}

flush

Removes all currently banned IPs at once by removing each one from the XDP blocklist. This is the equivalent of fail2ban's actionflush.

$backend->flush;

ERROR CODES / FLAGS

Error handling is provided by Error::Helper. All errors are considered fatal.

1, notInited

The backend has not been inited yet.

8, optionsNotHash

The item passed to new for options is not a hash.

9, noBanItem

No IP specified to ban or unban.

10, banItemNotIP

The item to ban is not an IP. Either wrong ref type or regexp test using Regexp::IPv4 and Regexp::IPv6 failed.

12, backendInitError

Failed to init the backend.

13, banFailed

Failed to ban the item.

14, unbanFailed

Failed to unban the item.

15, listFailed

Failed to get a list of bans.

16, reInitFailed

Failed to re_init the backend.

17, teardownFailed

Failed to teardown the backend.

18, alreadyInited

init called, but the backend has already been inited.

20, modeInvalid

The option mode is not 'src' or 'dst'.

24, checkFailed

The backend check raised an error.

25, flushFailed

Failed to flush the bans.

30, interfacesInvalid

The interfaces option is either undef, not an array ref, or an empty array ref. It is required and must be a non-empty array ref.

31, banCidrFailed

Failed to ban the CIDR range.

32, unbanCidrFailed

Failed to unban the CIDR range.

33, cidrItemNotCidr

The item to ban is not a CIDR range. Either wrong ref type or it is not an IPv4 or IPv6 address followed by a prefix length valid for its family.

34, cidrNotSupported

The backend does not support CIDR bans.

35, listCidrFailed

Failed to get a list of CIDR bans.

AUTHOR

Zane C. Bowers-Hadley, <vvelox at vvelox.ent>

BUGS

Please report any bugs or feature requests to bug-net-firewall-blockerhelper at rt.cpan.org, or through the web interface at https://rt.cpan.org/NoAuth/ReportBug.html?Queue=Net-Firewall-BlockerHelper. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Net::Firewall::BlockerHelper

You can also look for information at:

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT

This software is Copyright (c) 2023 by Zane C. Bowers-Hadley.

This is free software, licensed under:

The GNU Lesser General Public License, Version 2.1, February 1999