NAME Net::Appliance::Phrasebook - Network appliance command-line phrasebook VERSION This document refers to version 0.05 of "Net::Appliance::Phrasebook", released Monday Oct 02, 2006. SYNOPSIS use Net::Appliance::Phrasebook; my $pb = Net::Appliance::Phrasebook->new( platform => 'IOS', source => '/a/file/somewhere.yml', # optional ); print $pb->fetch('a_command_alias'), "\n"; DESCRIPTION If you use Perl to manage interactive sessions with with the command-line interfaces of networked appliances, then you might find this module useful. "Net::Appliance::Phrasebook" is a simple module that contains a number of dictionaries for the command-line interfaces of some popular network appliances. It also supports the use of custom phrasebooks, and of hiearchies of dictionaries within phrasebooks. TERMINOLOGY This module is based upon Data::Phrasebook. A *phrasebook* is a file which contains one or more dictionaries. A *dictionary* is merely an associative array which maps keywords to values. In the case of this module, the values happen to be command line interface commands, or related data, that help in the remote management of network appliances. METHODS "new" This method accepts a list of named arguments (associative array). There is one required named argument, which is the class of device whose dictionary you wish to access. The named argument is called "platform". One further, optional argument to "new" is the filename of a phrasebook. If this is not provided, "Net::Appliance::Phrasebook" will use its own internal phrasebook (see "SUPPORTED SYSTEMS"). This named argument is called "source". The "new" constructor returns a query object, or "undef" on failure. "load" This is an alias for the "new()" constructor should you prefer to use it. "fetch" Pass this method a single keyword, and it will return the corresponding value from the dictionary. It will die on lookup failure, because that's what Data::Phrasebook does when there is no successful hit for the given keyword in available dictionaries. SUPPORTED SYSTEMS You can select the *platform* that most closely reflects your device. There is a hierarchy of platforms, so any entry in a given "lineage" will use itself and its "ancestors", in order, for lookups: ['FWSM3', 'FWSM', 'PIXOS'] ['Aironet', 'IOS'] For example the value "FWSM" (for Cisco Firewall Services Modules with software versions up to 2.x) will fetch commands from the "FWSM" dictionary and then the "PIXOS" dictionary, before failing. Below is the list of built-in dictionaries, and of course you are able to supply your own via the "new" object method and an external file. "IOS" err_str : regular expression for error messages from the device paging : the command used on Cisco IOS to control page length prompt : a regular expression for Cisco IOS platform CLI prompts "Aironet" This is currently a synonym for "IOS". "PIXOS" err_str : regular expression for error messages from the device paging : the command used on Cisco PIXOS to control page length prompt : a regular expression for Cisco PIXOS platform CLI prompts "FWSM" This is currently a synonym for "PIXOS". "FWSM3" This is currently a synonym for "PIXOS", apart from... paging : the command used on Cisco FWSM running software version of 3.x or later to control page length CUSTOM PHRASEBOOKS Phrasebooks must be written in YAML, with each dictionary being named within the top-level associative array in the stream. Please see Data::Phrasebook::Loader::YAML for more detail on the format of the content of a YAML phrasebook file. In the world of network appliances, vendors will sometimes change the commands used in or even the appearance of the command line interface. This might happen between software version releases, or as a new product line is released. However, typically there is an ancestry to all these interfaces, so we can base a new product's dictionary on an existing dictionary whilst overriding some entries with new values. If you study the source to this module, you'll see that the bundled phrasebook makes uses of such platform families to avoid repetition. It is recommended that when creating new phrasebooks you follow this pattern. When doing so you must pass an array reference to the "platform" argument of "new" and it will be used as a list of dictionaries to find entries in, in order. Note that the array reference option for the "platform" argument will only work when used with a named external source data file. DIAGNOSTICS "missing argument to Net::Appliance::Phrasebook::new" You forgot to pass the required "platform" argument to "new". "unknown platform: foobar, could not find phrasebook" You asked for a dictionary "foobar" that does not exist in the internal phrasebook. DEPENDENCIES Other than the the contents of the standard Perl distribution, you will need the following: * Data::Phrasebook::Loader::YAML >= 0.06 * Data::Phrasebook >= 0.26 * List::MoreUtils * Class::Data::Inheritable * YAML >= 0.62 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 Data::Phrasebook, Net::Appliance::Session, Data::Phrasebook::Loader::YAML AUTHOR Oliver Gorwits "" 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