NAME
Net::Firewall::BlockerHelper::backends::npf - NetBSD npf backend for Net::Firewall::BlockerHelper.
VERSION
Version 0.2.0
SYNOPSIS
use Net::Firewall::BlockerHelper;
my $fw_helper = Net::Firewall::BlockerHelper->new(
backend => 'npf',
name => 'ssh',
options => { table => 'fail2ban' },
);
$fw_helper->init_backend;
$fw_helper->ban(ban => '1.2.3.4');
$fw_helper->unban(ban => '1.2.3.4');
$fw_helper->teardown;DESCRIPTION
Blocks IPs using npfctl(8) on NetBSD by adding them to a npf table.
Unlike the pf backend, npf tables and the rules referencing them can not be created on the fly; the table and a block rule using it must already be declared in npf.conf, for example...
table <fail2ban> type ipset
block in final from <fail2ban>Note that ipset tables only hold single addresses; if CIDR bans are going to be used, the table needs to be declared type lpm instead.
init and check verify the table exists. Ports and protocols are not supported by this backend as they belong to the rule in npf.conf; specifying either is an error. teardown flushes the table (the table itself can not be removed) while keeping the internal list of bans, so re_init can re-add them.
Requires npfctl to be in the PATH of the process, which must have sufficient privileges to run it.
METHODS
new
Initiates the the object.
- options :: Backend specific options that will be passed to the backend unchecked
outside of making sure it is a hash ref if defined. See below for furhter info.
- Default :: {}
- prefix :: Prefix to use. Must match the regex /^[a-zA-Z0-9]+$/
- default :: kur
- name :: Name of this specific instance. This must be specified.
- default :: undefPorts and protocols are not supported by this backend and specifying either is an error.
The options hash accepts the following.
- table :: The npf table name to use. Must be declared in npf.conf and
must match /^[a-zA-Z0-9_\-]+$/.
- Default :: <prefix>_<name>All errors are considered fatal, meaning if new fails it will die.
init
Initiates the backend. Verifies the table is declared and usable via npfctl table list, as it can not be created on the fly.
$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 configured npf table via npfctl table ... add. 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 configured npf table via npfctl table ... rem. Unbanning an IP that is not banned is a noop.
$backend->unban(ban => $ip);list
List banned IPs. Returns an array of the currently banned single IPs from the internal ban list. CIDR ranges are not included; for those see "list_cidr".
my @banned = $backend->list;ban_cidr
Bans a CIDR range by adding it to the npf table. Tables of type lpm accept a network prefix in the same manner as a single address; ipset tables do not, so for this to work the table must be declared type lpm in npf.conf.
$backend->ban_cidr(ban => '1.2.3.0/24');unban_cidr
Unbans a CIDR range by removing it from the npf table.
$backend->unban_cidr(ban => '1.2.3.0/24');list_cidr
List banned CIDR ranges. Returns an array of the currently banned CIDR ranges from the internal ban list.
my @banned_cidrs = $backend->list_cidr;re_init
Tells the backend to re-init it's self.
This will call teardown, which flushes the table, then init, which re-verifies the table is declared, and then re-add all retained bans, both single IPs and CIDR ranges, via npfctl table ... add.
$backend->re_init;teardown
Tears down the setup for the backend by flushing the table. The table itself lives in npf.conf and can not be removed. The internal list of bans is kept, so a following re_init will re-add them.
$backend->teardown;stop
Alias for "teardown", provided for parity with the fail2ban actionstop concept.
$backend->stop;check
Verifies that the npf table is still present and usable. Returns a true value if it is and a false value otherwise. This is the equivalent of fail2ban's actioncheck.
if ( !$backend->check ) {
$backend->re_init;
}flush
Removes all currently banned IPs at once by flushing the table and forgetting them. 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.
6, invalidPrefixSpecified
The specified prefix did not match /^[a-zA-Z0-9]+$/.
7, invalidName
The name is either undef or does not match /^[a-zA-Z0-9\-]+$/.
8, optionsNotHash
The item passed to new for options is not a hash.
9, noBanItem
No IP or CIDR range 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.
19, tableInvalid
The option table does not match /^[a-zA-Z0-9_\-]+$/.
23, initFailed
The table does not appear to be declared in npf.conf.
24, checkFailed
The backend check raised an error.
25, flushFailed
Failed to flush the bans.
26, portsNotSupported
The npf backend does not support ports. Ports belong to the rule referencing the table in npf.conf.
27, protocolsNotSupported
The npf backend does not support protocols. Protocols belong to the rule referencing the table in npf.conf.
28, banCidrFailed
Failed to ban the CIDR range.
29, unbanCidrFailed
Failed to unban the CIDR range.
30, 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.
31, cidrNotSupported
The backend does not support CIDR bans.
32, 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.
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