/ 
Logwatch-RecordTree-2.056
River stage zero No dependents
/ Logwatch::RecordTree::IPv4

NAME

Logwatch::RecordTree::IPv4 - a subclass of Logwatch::RecordTree for IPv4 addresses

VERSION

version 2.056

SYNOPSIS

use Logwatch::RecordTree;
use Logwatch::RecordTree::IPv4 (
   neat_names => -1,   # left-justified neat names
   columnize  => 1,    # put into columns, if it fits
   identify   => 1,    # try to identify each IP's owner
   snowshoe   => 1,    # condense nets within /24 netblocks to CIDRs
);

my $tree = Logwatch::RecordTree->new( name => 'Service', ... );

$tree->log(..., ['Name', 'Logwatch::RecordTree::IPv4', { options }], '10.1.1.1', ...);

print $tree;

DESCRIPTION

Logwatch::RecordTree::IPv4 is a sub-class of Logwatch::RecordTree intended for collecting events that should be keyed by IPv4 addresses.

NOTE: this module should contain the IP address items, meaning that the children added to this module will have names (or sort_keys) that are IP addresses.

While this module is most useful when the names are actual IP addresses, it is tolerant of names that are not IP addresses. When sorting, non-IP addresses are separated out and sorted alphabetically. The IP addresses are sorted using Sort::Key::IPv4::ipv4sort and the two lists are concatenated.

Methods

Logwatch::RecordTree::IPv4->new ( [ %options ] )

Same as the Logwatch::RecordTree new method, but adds two flag options (identify and snowshoe), and sets the neat_names flag.

Options

identify

Child names to this item are normally IPv4 addresses. This flag enables use of the Net::IP::Identifier module to attempt to attach network block identification to those IP addresses. If identifiable, the first eight characters of the identity are prepended to the IP address. Sorting is still based on the original IP address.

snowshoe

Hackers / SPAMmers often rent blocks of IP addresses spreading out their 'footprint' (like a snowshoe) so their source address isn't exactly duplicated. Turning on this flag condenses long lists of IPs within a mask range into a single line. The value of this flag is the width of the mask, so 24 is 256 IPs (i.e 192.168.33.0 - 192.168.33.255), 16 is 65,536 IPs, etc. When false, snowshoe detection is disabled. Setting to one (1) is interpreted as 24 since a mask width of one is not very useful, and /24 is commonly seen.

See sprint below for more details.

In the following methods, either $tree or $item is used as the object reference. $item indicates that the particular item at that point of the RecordTree is affected. $tree indicates that the method is inherently recursive and may descend down through the RecordTree.

$item->sort_children

This method overrides the Logwatch::RecordTree method to provide tolerant IPv4 sorting.

$item->identifier

Creates (if necessary) a Net::IP::Identifier object and returns it. This is a class variable. The same Net::IP::Identifier is used for all instances.

$item->create_child

This method in Logwatch::RecordTree is overridden here to alter the default sprint_name method in children as they are added.

The new sprint_name method checks for this item's identify flag, and if true, it tries to identify the IPs in the childrens' names. For each identified IP, the name is modified with the identity (up to 8 leading characters of it).

$tree->sprint

This Logwatch::RecordTree method is overridden here to support the snowshoe option. When snowshoe is enabled, the children hash is replaced before Logwatch::RecordTree->sprint is called. In the replacement, groups of IPs that fall within the range specified by the snowshoe mask width are condensed into a single line. The counts of each individual IP are summed into the replacement line count.

SEE ALSO

Logwatch::RecordTree

AUTHOR

Reid Augustin <reid@hellosix.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2015 by Reid Augustin.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.