NAME
Net::Firewall::BlockerHelper::backends::ufw - ufw backend for Net::Firewall::BlockerHelper.
VERSION
Version 0.2.0
SYNOPSIS
use Net::Firewall::BlockerHelper;
my $fw_helper = Net::Firewall::BlockerHelper->new(
backend => 'ufw',
ports => ['22'],
protocols => ['tcp'],
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 IPs using ufw(8), the uncomplicated firewall front end common on Ubuntu.
Unlike the table/set based backends there is no container to create; each ban prepends one or more per-IP rules (one per protocol) and each unban deletes them again. teardown removes the rules for all currently banned IPs without forgetting them, so re_init can re-add them.
ufw must already be enabled (ufw enable); init and check verify this via ufw status. Requires ufw 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 :: {}
- ports :: A array of ports to block. Checked to make sure they are ints within the
range 1 to 65535 or a valid service name via getservbyname. All ports will be
blocked if non are specified. Duplicates are removed.
- Default :: []
- protocols :: A array of protocols to block. This is checked against
/etc/protocols via the function getprotobyname and against the
protocols understood by ufw (tcp, udp, ah, esp, gre, igmp, and
ipv6). Duplicates will be discarded. If no protocols are given,
everything from the IP is blocked, unless ports are given, in
which case it defaults to tcp and udp. Ports are only attached to
tcp and udp; other protocols are blocked without a port.
- Default :: [], or ['tcp','udp'] when ports are given
- 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 :: undefThe options hash accepts the following.
- type :: The drop method to use. 'deny' silently drops. 'reject' sends
a reject back. See ufw(8).
- Default :: deny
- kill :: Kill existing connections/state for the banned IP. '' does
nothing, 'ss' uses ss -K, and 'conntrack' uses conntrack -D. Both
handle IPv4 and IPv6 and both are scoped to the configured
protocols, so blocking only udp will not kill tcp and vice versa;
with no protocols configured everything applicable is killed. For
ss that means -t/-u/-tu as appropriate (TCP connections and
connected UDP sockets are what ss can kill) and for conntrack -p
per blocked protocol.
- Default :: ''All errors are considered fatal, meaning if new fails it will die.
init
Initiates the backend. As there is no container to create, this just verifies that ufw is enabled via ufw status.
$backend->init;ban
Bans an IP. The value of ban is validated as being a IPv4 or IPv6 address and lowercased, then one ufw prepend <type> ... rule per protocol is added for it, based on the configured protocols and ports. If the kill option is set, existing connections/state for the IP are killed via ss -K or conntrack -D. 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 rules are removed via ufw delete <type> ..., one per protocol. Unbanning an IP that is not banned is a noop.
$backend->unban(ban => $ip);ban_cidr
Bans a CIDR range by prepending one or more per-range rules via ufw prepend <type> ..., one per protocol, in the same manner as a single IP. 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 per-range rules via ufw delete <type> .... 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 rules for all currently banned IPs. 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 ufw is still enabled. 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 deleting their rules 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.
2, invalidPortSpecified
Port is either not an int within the range 1 to 65535 or a name that can be resolved by getservbyname.
3, portsNotArray
The data passed to new for ports is not an array.
4, protocolsNotArray
The data passed to new for protocols is not an array.
5, invalidProtocolSpecified
The specified protocol could not be resolved via getprotobyname or is not one understood by ufw.
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, killInvalid
The option kill is not '', 'ss', or 'conntrack'.
20, typeInvalid
The option type is not 'deny' or 'reject'.
23, initFailed
init failed. ufw does not appear to be enabled.
24, checkFailed
The backend check raised an error.
25, flushFailed
Failed to flush the bans.
26, banCidrFailed
Failed to ban the CIDR range.
27, unbanCidrFailed
Failed to unban the CIDR range.
28, 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.
29, cidrNotSupported
The backend does not support CIDR bans.
30, 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