/ 
Net-Firewall-BlockerHelper-0.1.0
/ Net::Firewall::BlockerHelper::backends::shell

NAME

Net::Firewall::BlockerHelper::backends::shell - A shell backend for Net::Firewall::BlockerHelper.

VERSION

Version 0.1.0

SYNOPSIS

This backend just runs the commands configured via the options hash, so what init, ban, and the like actually do is entirely up to the commands supplied. Wiring them up to something that really blocks traffic is the user's job. The example below just creates and removes files under /tmp to show the flow and blocks nothing.

use Net::Firewall::BlockerHelper;

my $fw_helper;
eval {
    $fw_helper = Net::Firewall::BlockerHelper->new(
            backend=>'shell',
            name=>'derp',
            options=>{
                      init=>'mkdir /tmp/fw_helper_example/',
                      teardown=>'rm -rf /tmp/fw_helper_example/',
                      unban=>'rm -rf /tmp/fw_helper_example/%%%BAN%%%',
                      ban=>'touch /tmp/fw_helper_example/%%%BAN%%%',
                      },
        );
};
if ($@) {
    print 'Error: '
        . $Error::Helper::error
        . "\nError String: "
        . $Error::Helper::errorString
        . "\nError Flag: "
        . $Error::Helper::errorFlag . "\n";
}

$fw_helper->init_backend;

$fw_helper->ban(ban => '5.6.7.8');
$fw_helper->ban(ban => '1.2.3.4');

$fw_helper->unban(ban => '5.6.7.8');

$fw_helper->teardown;

METHODS

new

Initiates the the object. Unlike other backends, this only takes uses the options hash.

- options :: A hash of options to pass to the backend.
    Default :: {}

- name :: Not used but is required by Net::Firewall::BlockerHelper.
    Default :: undef

The values used for options is as below. All must be defined and can't be ''. '2>&1' is appended to the end of the commands.

- init :: The command to run to init the blocking.
     Default :: undef

- teardown :: The command to run to teardown the blocking.
     Default :: undef

- ban :: The command to run to ban a IP. %%%BAN%%% is replaced with the IP.
     Default :: undef

- unban :: The command to run to un ban a IP. %%%BAN%%% is replaced with the IP.
     Default :: undef

- check :: Optional command to run to verify the blocking is still in place.
     A zero exit is treated as healthy. If not defined, check always
     reports healthy.
     Default :: undef

- flush :: Optional command to run to remove all bans at once. If not
     defined, flush falls back to unbanning each currently banned IP.
     Default :: undef

All errors are considered fatal, meaning if new fails it will die.

my $fw_helper;
eval {
    $fw_helper = Net::Firewall::BlockerHelper->new(
            backend=>'shell',
            name=>'derp',
            options=>{
                      init=>'mkdir /tmp/fw_helper_example/',
                      teardown=>'rm -rf /tmp/fw_helper_example/',
                      unban=>'rm -rf /tmp/fw_helper_example/%%%BAN%%%',
                      ban=>'touch /tmp/fw_helper_example/%%%BAN%%%',
                      },
        );
};
if ($@) {
    print 'Error: '
        . $Error::Helper::error
        . "\nError String: "
        . $Error::Helper::errorString
        . "\nError Flag: "
        . $Error::Helper::errorFlag . "\n";
}

init

Initiates the backend by running the configured init command with '2>&1' appended. A non-zero exit is an error.

Note that what this actually sets up is entirely down to the configured command. See "SYNOPSIS".

No arguments are taken.

If called a second time, it will error.

$backend->init;

ban

Bans an IP. The value of ban is validated as being a IPv4 or IPv6 address and lowercased, then the configured ban command is run with %%%BAN%%% replaced by the IP. A non-zero exit is an error.

$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 the configured unban command is run with %%%BAN%%% replaced by the IP. A non-zero exit is an error.

$fw_helper->unban(ban => $ip);

ban_cidr

Bans a CIDR range. The value of ban is validated as being a IPv4 or IPv6 CIDR range and lowercased, then the configured ban command is run with %%%BAN%%% replaced by the CIDR.

$fw_helper->ban_cidr(ban => '1.2.3.0/24');

unban_cidr

Unbans a CIDR range. The value of ban is validated as being a IPv4 or IPv6 CIDR range and lowercased, then the configured unban command is run with %%%BAN%%% replaced by the CIDR.

$fw_helper->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 = $fw_helper->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 = $fw_helper->list;

re_init

Tells the backend to re-init it's self.

This will call teardown and init again, re-running the configured teardown and init commands. teardown is best effort. After that the configured ban command is re-run for every previously banned IP and CIDR range.

$fw_helper->re_init;

teardown

Tears down the setup for the backend by running the configured teardown command. A non-zero exit is an error.

$fw_helper->teardown;

stop

Alias for "teardown", provided for parity with the fail2ban actionstop concept.

$fw_helper->stop;

check

Runs the optional check command from the options hash. A zero exit code is treated as healthy. If no check command was configured, this always reports healthy. This is the equivalent of fail2ban's actioncheck.

if ( !$fw_helper->check ) {
    $fw_helper->re_init;
}

flush

Removes all currently banned IPs at once. If a flush command was configured in the options hash it is run; otherwise it falls back to unbanning each currently banned IP. This is the equivalent of fail2ban's actionflush.

$fw_helper->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, initInvalid

The option init is undef or blank.

3, optionsUndef

The options hash passed to new is undef.

4, teardownInvalid

The option teardown is undef or blank.

5, banInvalid

The option ban is undef or blank.

6, unbanInvalid

The option unban is undef or blank.

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.

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. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Net::Firewall::BlockerHelper

You can also look for information at:

ACKNOWLEDGEMENTS

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