NAME
Net::Firewall::BlockerHelper::backends::firewalld - firewalld backend for Net::Firewall::BlockerHelper.
VERSION
Version 0.1.0
SYNOPSIS
use Net::Firewall::BlockerHelper;
my $fw_helper = Net::Firewall::BlockerHelper->new(
backend => 'firewalld',
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 on hosts managed by firewalld(1), where using the iptables backend directly would fight the daemon and be lost on reload.
Like the iptables backend, two ipsets are created via ipset(8), one for IPv4 (<prefix>_<name>_4) and one for IPv6 (<prefix>_<name>_6). The block rules are inserted through the firewalld direct interface (firewall-cmd --direct) into the configured chain (INPUT_direct by default). Banning an IP adds it to the relevant ipset.
Requires firewall-cmd and ipset to be installed and in the PATH of the process, which must have sufficient privileges to run them. firewalld must be running.
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. Duplicates will be
discarded. If no protocols are given, everything sourced from the
sets is blocked, unless ports are given, in which case it defaults
to tcp and udp. Ports are only attached to port-capable protocols
(tcp/udp/sctp); 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. Should either be 'drop' or 'reject'.
'reject' sends an ICMP port-unreachable back.
- Default :: drop
- chain :: The direct interface chain to add the rules to.
Must match /^[a-zA-Z0-9_\-]+$/. Only the *_direct chains,
such as the default, are called automatically by firewalld;
a custom chain must already exist and be jumped to from
somewhere in the ruleset or the rules will never be evaluated.
- Default :: INPUT_direct
- kill :: Use conntrack(8) to drop existing connection tracking entries
for the banned IP, for both IPv4 and IPv6. When protocols are
configured the kill is scoped to them via -p, so blocking only
udp will not drop tcp entries and vice versa; protocols conntrack
can not filter by are skipped. With no protocols configured
everything is being blocked, so entries of every protocol are
dropped.
- Default :: 0All errors are considered fatal, meaning if new fails it will die.
init
Initiates the backend. Any stale direct rules and ipsets from a previous run are removed first, with failures ignored. Then the two ipsets are created via ipset create and the block rules are added to the configured chain via firewall-cmd --direct --add-rule.
$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 relevant ipset via ipset add. If the kill option is set, conntrack(8) is used to drop existing connection tracking entries for the IP. 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 relevant ipset via ipset del. 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 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 via ipset add.
$backend->re_init;teardown
Tears down the setup for the backend.
This will remove the direct rules and the ipsets.
$backend->teardown;stop
Alias for "teardown", provided for parity with the fail2ban actionstop concept.
$backend->stop;check
Verifies that firewalld is running, the ipsets are still present, and each of the direct rules is still in place. Returns a true value if the setup is intact and a false value if any part is missing. 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 ipsets, leaving the rules in place. This is the equivalent of fail2ban's actionflush.
$backend->flush;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;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, invalidPortSpecified
Port is either not an int within the range 1 to 65535 or a name that can be resolved by getservbyname.
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 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, chainInvalid
The option chain does not match /^[a-zA-Z0-9_\-]+$/.
20, typeInvalid
The option type is either a ref or not "drop" or "reject".
21, nameTooLong
The combined prefix and name is longer than 29 characters, leaving no room for the _4/_6 suffix within the 31 character ipset name limit.
23, initFailed
Init failed. A command run during init exited non-zero.
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