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

VERSION
    This document refers to version 0.04 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 2006. All Rights Reserved.

    This program is free software; you can redistribute it and/or modify it
    under the terms of version 2 of the GNU General Public License as
    published by the Free Software Foundation.

    This program is distributed in the hope that it will be useful, but
    WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
    Public License for more details.

    You should have received a copy of the GNU General Public License along
    with this program; if not, write to the Free Software Foundation, Inc.,
    51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA

