NAME
Net::Firewall::BlockerHelper::backends::linux_ip_route - Blackhole route backend for Net::Firewall::BlockerHelper.
VERSION
Version 0.2.0
SYNOPSIS
use Net::Firewall::BlockerHelper;
my $fw_helper = Net::Firewall::BlockerHelper->new(
backend => 'linux_ip_route',
name => 'ssh',
);
$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 whole IPs via null routes using ip(8) from iproute2. Fast for very large numbers of blocked IPs and requires no firewall at all, making it a good fallback. The routes are destination based, so what is directly stopped is traffic headed back to the banned IP, which is enough to keep connections from completing. For the inbound packets themselves to be dropped as well, reverse path filtering, rp_filter, needs to be enabled, in which case they are tossed at the route lookup before entering any firewall chains.
Blocking is per IP and never per service; ports and protocols are not supported and specifying them is an error.
check verifies the route for each currently banned IP is still present, so externally flushed routes are noticed and self-heal can re-add them. teardown deletes the route for each banned IP, tolerating already-removed routes, and keeps the internal list of bans so re_init can re-add them.
NOTES
check looks for a ban's route using the type selector, for example ip route show type unreachable 192.0.2.4. A missing route is reported by iproute2 as a zero exit with no output, which is what check keys off of.
CIDR ranges must be passed with the host bits zeroed, such as 192.0.2.0/24. iproute2 rejects prefixes with host bits set, such as 192.0.2.4/24, with "Invalid prefix for given prefix length", which will show up as a banCidrFailed error.
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.
- blocktype :: The route type to use. 'blackhole' silently drops while
'unreachable' and 'prohibit' send the corresponding ICMP reject
back. See ip-route(8).
- Default :: unreachableAll errors are considered fatal, meaning if new fails it will die.
init
Initiates the backend. Null routes need no setup, so no commands are run.
$backend->init;ban
Bans an IP. The value of ban is validated as being a IPv4 or IPv6 address and lowercased, then a route of the configured blocktype is added for it via ip route add (ip -6 route add for IPv6). 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 its route is removed via ip route del (ip -6 route del for IPv6). Unbanning an IP that is not banned is a noop.
$backend->unban(ban => $ip);ban_cidr
Bans a CIDR range by adding a route of the configured blocktype for it via ip route add, the same way a single IP is handled. The value of ban is validated as being a IPv4 or IPv6 CIDR range and lowercased. Banning an already banned range is a noop.
$backend->ban_cidr(ban => '1.2.3.0/24');unban_cidr
Unbans a CIDR range by deleting its route via ip route del. The value of ban is validated as being a IPv4 or IPv6 CIDR range and lowercased. Unbanning a range that is not banned is a noop.
$backend->unban_cidr(ban => '1.2.3.0/24');list_cidr
List banned CIDR ranges. Returns an array of the currently banned CIDR ranges. Single IPs are not included; for those see "list".
my @banned_cidrs = $backend->list_cidr;list
List banned IPs. Returns an array of the currently banned single IPs. CIDR ranges are not included; for those see "list_cidr".
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-added all previously added bans.
$backend->re_init;teardown
Tears down the setup for the backend by deleting the route for each currently banned IP. Routes that were already removed externally are tolerated, so re_init works after an external wipe. 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 the route for each currently banned single IP is still present. Returns a true value if they all are and a false value if any are missing. Routes for banned CIDR ranges are not checked. This is the equivalent of fail2ban's actioncheck.
if ( !$backend->check ) {
$backend->re_init;
}flush
Removes all currently banned IPs at once by deleting their routes 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.
20, blocktypeInvalid
The option blocktype is not "unreachable", "blackhole", or "prohibit".
23, initFailed
One of the required commands for init failed.
24, checkFailed
The backend check raised an error.
25, flushFailed
Failed to flush the bans.
26, portsNotSupported
Ports were specified, but the backend does not support ports.
27, protocolsNotSupported
Protocols were specified, but the backend does not support protocols.
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