NAME
Net::Firewall::BlockerHelper::backends::hosts_deny - TCP wrappers hosts.deny backend.
VERSION
Version 0.2.0
SYNOPSIS
use Net::Firewall::BlockerHelper;
my $fw_helper = Net::Firewall::BlockerHelper->new(
backend => 'hosts_deny',
name => 'sshd',
options => { daemon => 'sshd' },
);
$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 via TCP wrappers by maintaining a block of entries in /etc/hosts.deny. Only libwrap aware daemons (those linked against libwrap or launched via tcpd) honor this; it is not a packet filter.
The backend owns a single marked region of the file delimited by
# BEGIN Net::Firewall::BlockerHelper <prefix>_<name>
...
# END Net::Firewall::BlockerHelper <prefix>_<name>Everything outside that region is preserved untouched, so hand maintained rules and other instances (with a different prefix/name) coexist. Each ban is rendered as a <daemon> : <ip> line, with IPv6 addresses bracketed, <daemon> : [<ip>], as that is the only IPv6 form libwrap matches. No reload is needed as libwrap reads the file on each connection.
Updates are done under an exclusive flock(2) on <file>.lock, which is created if needed and left in place, so concurrent processes updating the same file serialize rather than losing each others changes. The new contents are written to a temp file in the same directory and renamed into place, so the update is atomic and a partial file can never be seen. The mode of the file being replaced is carried over.
METHODS
new
Initiates the object. Not really meant to be used directly, but instead called via Net::Firewall::BlockerHelper.
- options :: A hash of options. See below.
- name :: Required. Used, with prefix, to tag this instance's region.
- prefix :: Defaults to 'kur'. Combined with name for the region tag.The options hash accepts the following.
- file :: Path to the hosts.deny file.
- Default :: /etc/hosts.deny
- daemon :: The daemon_list portion of each rule. 'ALL' blocks the IP for
every libwrap daemon; a specific name (eg 'sshd') scopes it.
- Default :: ALLAll errors are considered fatal, meaning if new fails it will die.
init
Initiates the backend. Removes any stale region for this instance from the file. The markers are only written when there is something banned, so with no bans nothing is added.
ban
Bans an IP. The value of ban is validated as being a IPv4 or IPv6 address and lowercased, then added to the ban list. This instance's marked region in the hosts.deny file is rewritten with a <daemon> : <ip> line for each banned IP; content outside the region is preserved. Banning an already banned IP is a noop.
$fw_helper->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 ban list. This instance's marked region in the hosts.deny file is rewritten without it; if nothing remains banned the region, markers included, is removed entirely. Unbanning an IP that is not banned is a noop.
$fw_helper->unban( ban => $ip );list
List banned IPs. Returns an array of the currently banned IPs from the in-memory ban list; the hosts.deny file is not parsed.
my @banned = $fw_helper->list;re_init
Re-renders this instance's region from the retained ban list.
teardown
Removes this instance's region from the file, leaving everything else intact.
stop
Alias for "teardown".
check
Verifies our marked region is present in the file with a <daemon> : <ip> line for every banned IP. Returns 1 if healthy and 0 if not. With nothing banned there is nothing to verify and it reports healthy.
flush
Removes all bans at once by clearing the ban list and rewriting the file.
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.
7, invalidName
The name is undef.
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.
24, checkFailed
The backend check raised an error.
25, flushFailed
Failed to flush the bans.
31, fileWriteFailed
Failed to write the file. File write failures are normally raised using the error code of the operation that triggered the write, such as banFailed; this is the fallback if no operation code was passed internally.
32, banCidrFailed
Failed to ban the CIDR range.
33, unbanCidrFailed
Failed to unban the CIDR range.
34, 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.
35, cidrNotSupported
The backend does not support CIDR bans.
36, listCidrFailed
Failed to get a list of CIDR bans.
AUTHOR
Zane C. Bowers-Hadley, <vvelox at vvelox.ent>
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