The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Net-Cisco-ObjectGroup-1.01
River stage zero No dependents
++
/ Net::Cisco::ObjectGroup

NAME

Net::Cisco::ObjectGroup - Generate Cisco ACL object groups

VERSION

This document refers to version 1.01 of Net::Cisco::ObjectGroup.

SYNOPSIS

 use Net::Cisco::ObjectGroup;
 my $og = Net::Cisco::ObjectGroup->new({
     type         => 'icmp'
     name         => 'friendly_icmp',
     description  => 'ICMP types we like', # optional
     pretty_print => 1,                    # optional
 });

 $g->push({icmp_type => 8}); # this is an echo request
 $g->push({group_object => $another_objectgroup_object});

 print $g->dump, "\n";
 # prints the object-group configuration commands to STDOUT, something like:
 
 object-group icmp friendly_icmp
   description ICMP types we like
   icmp-object echo
   group-object other_icmp_types

DESCRIPTION

Use this module to manage the presentation of Cisco PIX or FWSM Object Groups. Group entries are pushed into the object in a simple parmaterized fashion, and you can then dump the content in a format that is parsable by Cisco devices.

IMPORTANT NOTE

This module's error checking is only concerned with syntactic correctness. It makes no judgement of the semantic correctness of your group entries.

For instance, newer FWSM systems use netmasks specified in terms of host address network masks (e.g. 255.255.255.0), whereas older systems use wildcard bits (e.g. 0.0.0.255). Net::Cisco::ObjectGroup will not check that you use the correct type of mask, or even that your mask isn't something completely inappropriate (e.g. cabbages).

METHODS

Net::Cisco::ObjectGroup->new

Each object group that you manage must be created through this method, which takes at least two parameters: the type and the name of the object group. The parameters must be provided in a single hash reference argument, like so:

 my $g = Net::Cisco::ObjectGroup->new({
     type        => 'network',
     name        => 'my_new_object_group',
     description => 'used for something useful', # optional
 });

Optionally you may also provide a description of the group. For details of the types of object group available, and additional parameters to this method that they accept, see "GROUP TYPES", below.

Net::Cisco::ObjectGroup is actually a factory class, and this method returns an object of the type that you requested in the type parameter. All objects inherit from Net::Cisco::ObjectGroup::Base, and on success this method will return an instance of one of the following:

  • Net::Cisco::ObjectGroup::ICMP

  • Net::Cisco::ObjectGroup::Network

  • Net::Cisco::ObjectGroup::Protocol

  • Net::Cisco::ObjectGroup::Service

push

Use this method to add an entry to the object group. Although according to Cisco's documentation order of the content of an object group is not significant, this module will preseve the order of pushed entries, with new entries being added to the end of the list of items in the group.

Parameters are all passed within a single hash reference argument. Which keys of that hash you populate will depend on the type of the object group on which you are operating. Logic within the module should check that you are syntactically correct, but for brevity of this documentation you are referred to the many Cisco manuals containing object group syntax usage guidelines.

See "GROUP TYPES", below, for parameter specifics.

dump

This method generates and returns the object group as it would look in a Cisco configuration file.

The returned value is a scalar, with embedded newline characters and no terminating newline, so you will need to append that as required. Note that when submitting this to, for example, a Net::Appliance::Session session via cmd(), a newline will be automatically appended by that method.

Fully compatible Cisco commands are produced on the fly from the data stored in the Net::Cisco::ObjectGroup object, so you can dump and push repeatedly to your heart's content.

GROUP TYPES

Following Cisco configuration guidelines, there are four types of object group available to you. Each of them implements a push() object method to populate the group, with custom parameters as described below.

ICMP

The new method to Net::Cisco::ObjectGroup will also accept a pretty_print parameter, which if set to a true value, enables the substitution of some numeric ICMP types for their text aliases within the output from dump.

The push method for ICMP object groups accepts the following parameters:

icmp_type

Fill this value in your parameter hash with an ICMP type. As mentioned above, it is your responsibility to enter something that the Cisco device will parse (e.g. a recognised ICMP type name or IANA assigned number).

group_object

Use this parameter to refer to another ICMP object group in this group entry.

Network

The push method for Network object groups accepts the following parameters:

net_addr, netmask

At a minimum, if configuring a network address, you must pass the net_addr parameter. If netmask is omitted, then the net_addr is assumed to be a host address (32 bit netmask). Otherwise, specify a netmask in netmask.

group_object

Use this parameter to refer to another Network object group in this group entry.

Protocol

The new method to Net::Cisco::ObjectGroup will also accept a pretty_print parameter, which if set to a true value, enables the substitution of some protocol numbers for their text aliases within the output from dump.

The push method for Protocol object groups accepts the following parameters:

protocol

Fill this value in your parameter hash with a protocol type. As mentioned above, it is your responsibility to enter something that the Cisco device will parse (e.g. a recognised protocol name or IANA assigned number).

group_object

Use this parameter to refer to another Protocol object group in this group entry.

Service

The new method to Net::Cisco::ObjectGroup will also accept a pretty_print parameter, which if set to a true value, enables the substitution of some port numbers for their corresponding service names within the output from dump.

The new method for Service object groups requires the following additional parameter:

protocol

Service object groups must be specified with any of three possible IP protocol groups, tcp, udp or tcp-udp in this parameter.

The push method for Service object groups accepts the following parameters:

svc_op, svc, svc_hi

If specifying one or more services (rather than a group, as below), then at a minimum the svc_op and svc parameters must be completed. svc_op may be either eq or range, and if the latter then scv_hi must also contain the corresponding service to make a range.

As mentioned above, it is your responsibility to enter values for svc and svc_hi that the Cisco device will parse (e.g. a recognised service name or IANA assigned number).

group_object

Use this parameter to refer to another Service object group in this group entry.

You may encounter the following diagnostic messages from Protocol groups:

missing parameter "protocol" when creating service group

This is a required parameter to the new() class method when specifying an object group type of service (or port).

unrecognized protocol type:...

You have used an unrecognized value for the protocol parameter to new().

missing service operator

The svc_op parameter is missing in your call to push().

unrecognized service operator:...

You have used an unrecognized value for the svc_op parameter to push().

DIAGNOSTICS

must specify either group-object or...

At a minimum please supply an object group or other required parameter.

cannot specify both group-object and...

Likewise you should not specify both an object group and type-specific paramters.

bad group-object

Referenced object groups must be of the same type as the group they are referenced from.

missing parameter "type"

You forgot to specify the type parameter to Net::Cisco::ObjectGroup->new.

unrecognized object-group type:...

The group type must be one of icmp, network, protocol, service or port.

missing parameter "name"

You forgot to specify the name parameter to Net::Cisco::ObjectGroup->new.

bad object-group name:...

Object group names must be between one and 64 characters comprising only upper and lowercase letters, digits, underscore, period and hyphen.

bad description

The length of the description must not exceed 200 characters.

DEPENDENCIES

Other than the contents of the standard Perl distribution, you will need the following:

  • UNIVERSAL::require

  • Class::Data::Inheritable

  • Class::Accessor >= 0.25

BUGS

If you spot a bug or are experiencing difficulties that are not explained within the documentation, please send an email to oliver@cpan.org or submit a bug to the RT system (http://rt.cpan.org/). It would help greatly if you are able to pinpoint problems or even supply a patch.

SEE ALSO

Net::Cisco::AccessList::Extended, Net::Appliance::Session

AUTHOR

Oliver Gorwits <oliver.gorwits@oucs.ox.ac.uk>

COPYRIGHT & LICENSE

Copyright (c) The University of Oxford 2008.

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