NAME

Net::Silk::Bag - SiLK bag file interface

SYNOPSIS

  use Net::Silk::Bag;
  use Net::Silk::IPSet;
  use Net::Silk::IPWildcard;

  my $bag1 = Net::Silk::Bag->new_ipaddr;
  $bag1->add('1.1.1.1', '2.2.2.2', '3.3.3.3');
  $bag1->incr('3.3.3.3');

  my $bag2 = Net::Silk::Bag->new_ipaddr;
  $bag2->add('3.3.3.3', '4.4.4.4', '5.5.5.5');

  # intersection
  my $bag3 = $bag1 & $bag2;

  # IO handle
  while (my $kv = <$bag3>) {
    print "$kv->[0] -> $kv->[1]\n";
  }

  # hash interface
  foreach my $key (keys %$bag3) {
    print "$key -> $bag3->{$key}\n";
  }

  # iterator
  my $iter = $bag3->iter;
  while (my $kv = $iter->()) {
    print "$kv->[0] -> $kv->[1]\n";
  }

  # interact with other object types
  my $set   = Net::Silk::IPSet->new('3.3.3.3');
  my $wc    = Net::Silk::IPWildcard->new('3.3.3.3');
  my %hash  = ('3.3.3.3' => 1);
  my @array = qw( 3.3.3.3 );
  my $bag4 = $bag1 & $set;
  my $bag5 = $bag1 & $wc;
  my $bag6 = $bag1 & \%hash;
  my $bag7 = $bag1 & \@array;

DESCRIPTION

Net::Silk::Bag is a representation of a multiset. Each key represents a potential element in the set, and the key's value represents the number of times that key is in the set. As such, it is also a reasonable representation of a mapping from keys to integers. Despite its set-like properties, a bag object is not nearly as efficient as a <Net::Silk::IPSet> when representing large contiguous ranges of key data.

METHODS

The following are methods are available for bags:

CONSTRUCTORS

new(...)

Returns a new bag object. Accepts the following keyword arguments:

key_type

Type of key to use. Valid types are listed below. Defaults to 'any-IPv6' if SILK_IPV6_ENABLED is true, otherwise 'any-IPv4'.

key_len

Length of key. If not specified, defaults to the default number of bytes for the given key type.

counter_type

Type of counter to use. Valid types are listed below. Defaults to 'custom'.

counter_len

Length of the counter type. Currently this defaults to 8, which is the only valid value so far.

mapping

Values with which to initialize the bag. This can be a reference to a hash, array, or Net::Silk::IPSet. In the latter two cases, the count values are set to 1.

Valid key and counter types are:

      sIPv4                 class
  dIPv4                 type
  sPort                 icmpTypeCode
  dPort                 sIPv6
  protocol              dIPv6
  packets               nhIPv6
  bytes                 records
  flags                 sum-packets
  sTime                 sum-bytes
  duration              sum-duration
  eTime                 any-port
  sensor                any-snmp
  input                 any-time
  output                custom
  nhIPv4                any-IPv4
  initialFlags          any-IPv6
  sessionFlags          application
  attributes
new_ipaddr()

Creates a bag using 'any-ipv6' if SILK_IPV6_ENABLED is true, otherwise using 'any-ipv4'.

new_ipv4addr()

Creates a bag using 'any-ipv4', regardless of SILK_IPV6_ENABLED.

new_integer()

Returns a bag using the 'custom' key type (integer bag).

copy()

Returns a copy of the bag object.

load($filename)

Returns a bag object loaded from the given filename.

save($filename)

Saves the bag object into th given filename.

META METHODS

field_types()

Return a list of valid key/counter type values.

get_info()

Return a hash of key type, counter type, and their respective lengths for this bag.

set_info(...)

Modify the key and counter characteristics of the bag. Accepts the following keyword arguments:

      key_type
  key_len
  counter_type
  counter_len
type_merge($type1, $type2)

Return the field type that would be given (by default) to a bag that is a result of co-mingling two bags of the given types. For example, 'sport' and 'dport' would merge to 'any-port'.

key_type_merge($other)

Given another bag, return the key merge type that results from co-mingling with that bag.

MANIPULATION METHODS

add($item1, $item2, ...)

Add values to the bag. Items can be keys, arrays of keys, hashes, a Net::Silk::IPSet, or other bags. For items having key/value pairs, the given value is added to the current value for that key. For keys and lists of keys, the value is incremented by 1.

remove($item1, $item2, ...)

Remove values from the bag. Items can be keys, arrays of keys, hashes, a Net::Silk::IPSet, or other bags. For items having key/value pairs, the given value is subtracted from the current value for that key. For keys and lists of keys, the value is deccremented by 1.

get($key)

Return the value for the given key.

set($key, $val)

Set the given key to the given value.

del($key)

Delete the given key.

update($item1, $item2, ...)

Update the bag with the key/values in the given items. Items can be other bags, hashes, arrays of keys, single keys, etc. In the latter two cases, the value for the keys is 1.

constrain_keys($min, $max)

Delete all keys which do not fall into the given range. Either min or max can be undef, but not both.

constrain_values($min, $max)

Delete all keys having values which do not fall into the given range. Either min or max can be undef, but not both.

incr($key, $val)

Increment the number of the given key in the bag by the given value, which defaults to 1.

decr($key, $val)

Decrement the number of the given key in the bag by the given value, which defaults to 1. If the given value is greater than the current value, the key is deleted.

div($item1, $item2, ...)

Divide the bag by the given items. Items can be other bags or hashes. Returns a new bag for which values in the original bag are divided by their corresponding values in the given bag (non-zero), rounded to the nearest integer.

mul()

Multiply the bag by the given items. Items can be other bags or hashes. Returns a new bag for which values in the original bag are multiplied by their corresponding values in the given bag.

scalar_div($val)

Return a new bag where all values are divided by the given value, rounded to the nearest integer.

scalar_mul()

Return a new bag where all values are multiplied by the given value.

clear()

Empty the bag.

QUERY METHODS

cardinality()

Return a count of how many keys are present in the bag.

contains($key)

Return whether or not the bag contains the given key.

max()

Return the maximum value contained in the bag.

min()

Return the minimum value contained in the bag.

OPERATIONAL METHODS

as_ipset()

Return a Net::Silk::IPSet containing the keys of the bag in cases where the keys are IP addresses.

inversion()

Return a new integer bag for which all values from the original bag are inserted as keys with values representing how many times that value was present in the bag. Hence, if two keys in the bag have a value of 5, the newbag would have a key of 5 with a value of 2.

intersect($item1, $item2, ...)

Return a new bag with keys present in the given items. Items can be other bags, hashes, arrays of keys, single keys, Net::Silk::IPSet, or Net::Silk::IPWildcard.

complement_intersect($item1, $item2, ...)

Return a new bag with keys not present in the given items. Items can be other bags, hashes, arrays of keys, single keys, Net::Silk::IPSet, or Net::Silk::IPWildcard.

ITERATION METHODS

iter_bag($sorted)
iter($sorted)

Return a sub ref iterator that returns key/value pairs as an array ref. In list context, returns all key/value pairs in a flattened list suitable for sending to a hash. Takes an optional parameter which, if present and true, causes results to be returned in key-sorted order. This is the type of iterator used when the bag is placed in the IO operator.

iter_keys()

Return a sub ref iterator that returns all keys of the bag that have non-zero values.

iter_vals()

Return a sub ref iterator that returns all non-zero values in the bag.

iter_group($other)

Return a sub ref iterator that returns keys and values from this bag and the given bag. For each key which is in either bag, the iterator returns a triple (key, value1, value2) where the first value is from this bag and the second from the given bag. The keys are returned in sorted order.

TIED HASH

Bag objects can be treated as though they are hash references. All corresponding hash functions work as expected.

OPERATORS

The following operators are overloaded and work with bag objects:

  -             &
  -=            &=
  +             ==
  +=            !=
  /             eq
  /=            ne
  *             ""
  *=            <>

SEE ALSO

Net::Silk, Net::Silk::RWRec, Net::Silk::IPSet, Net::Silk::Pmap, Net::Silk::IPWildcard, Net::Silk::Range, Net::Silk::CIDR, Net::Silk::IPAddr, Net::Silk::TCPFlags, Net::Silk::ProtoPort, Net::Silk::File, Net::Silk::Site, silk(7)

COPYRIGHT & LICENSE

Copyright (C) 2011-2016 by Carnegie Mellon University

Use of the Net-Silk library and related source code is subject to the terms of the following licenses:

GNU General Public License (GPL) Rights pursuant to Version 2, June 1991 Government Purpose License Rights (GPLR) pursuant to DFARS 252.227.7013

NO WARRANTY

See GPL.txt and LICENSE.txt for more details.