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.