NAME

Net::Autoconfig - Perl extension for provisioning or reconfiguring network devices.

SYNOPSIS

  use Net::Autoconfig::Device;

  %data = (
            hostname => dev1,
            username => user1,
            password => pass1,
            enable_password => enable1,
            snmp_community  => public1,
            snmp_version    => 2c,
          );
  $device = Net::Autoconfig::Device->new(%data);
  $device = Net::Autoconfig::Device->new();

  $device->hostname("device1");
  $device->set('fu' => 'bar');
  $device->set(%data);

  $hostname = $device->hostname
  $hostname = $device->get("hostname");

  %all_device_data = $device->get;

  There are a lot of built-in access/mutator methods.  Beyond
  those values, you can add whatever you want to the
  device object.

DESCRIPTION

Net::Autoconfig uses the concept of devices. Each device contains all relevent information internally. By default, the device type/model/vendor is discovered automatically. If there is a specific module for that paticular vendor/model, then that module will be used. If not, then it will use the default methods contained in this module.

Methods

Public Methods

new()

Creates a new Net::Autoconfig::Device object. Additional info can be configured after the object has been created. Pass an array with ( key1 => value1, key2 => value2, ...) to initialize the object with those key values.

 Default values:
 auto_discover      = TRUE
 snmp_version       = 2c
 access_method      = ssh
 access_cmd         = /usr/bin/ssh
 invalid_cmd_regex  = '[iI]nvalid command'

autodiscover()

Enabled by default. Can be disabled by setting 'auto_discover' = FALSE (0, "", etc)

Try to discover the vendor and model number of the device. It uses the following (in order) to determine the device type: 1. if vendor and model are specified in the device config file 2. if a snmp community is specified, it will use that (preferred method) 3. if a session is open to the device, use the CLI (intermittent)

get()

Get the value of the specified attribute, or get a hash ref of all of the attribute => value pairings. This provides a mechanism for getting attributes that are either part of the module, or that you have defined. Returns undef if an attribute does not exist.

set()

Set the value of an attribute. If the attribute does not yet exist, create it.

This method is used by passing an array to the method. The method then adds/overwrites existing key => value pairs to the object. You can create or modify any variable inside the object using this method.

Returns undef for success Returns TRUE for failure

accessor/mututaor methods

If any of these methods are passed undef, then the value for that variable is returned. If passed anything that is not undef, then set the device variable to that. Some of these methods do some sanity checking, other allow you to set the values to whatever you want.

model()

The device class in perl module format.

E.g. A cisco device would have "Net::Autoconfig::Device::Cisco"

vendor()

The vendor name.

E.g. A hp device would have "HP". A Cisco device would have "Cisco".

hostname()

The hostname of the device.

username()

The username to access the device.

password()

The password used to access the device.

provision()

Whether this device is to be configured via a console server.

admin_status()

TRUE means that admin priviledges have been obtained on the device.

FALSE means that admin priviledges have not been obtained.

enable_password()

The password to obtain administrative priviledges on the device.

console_username()

The username to connect to the console server. This is only to gain access to the console server, not the device attached to it. You're welcome to make them the same, but they don't have to be. If not specified, it will use the device username.

console_password()

The password to connect to the console server. This is used in conjuction with console_username to gain access to the console server. If not specified, it will use the device password.

console_hostname()

The hostname of the console server. This is different than the hostname. The hostname can be tty5@console1. console_hostname would be "console1"

console_tty()

The tty/interface on the console that the device connects to. If the hostname were tty5@console1, The console_tty would be "tty5".

snmp_community()

The snmp version 2 community string.

snmp_version()

The snmp version to use. Currently only supports version 2.

session()

Returns a reference to the current session.

access_method()

How are we going to connect to the device.

E.g. ssh

access_cmd()

What command are we going to use to connect to the device.

E.g. /usr/bin/ssh

disable_paging()

Attempts to disable the pagination of command output. I.e. having to hit the spacebar to see the next chunk of the output. Script don't interact will with paginated data. This method tries a compromise, it will not work as well as an overloaded method in a sub-class.

end_session()

Terminates the session.

error_end_session($error_message);

Terminates the session and gives an error message that you specify.

lookup_model()

This trys to determine the vendor and model of the device. This is usually called from auto_discover(). If auto_discover is not false, then this will cause a loop.

Returns the vendor specific module, or "Net::Autoconfig::Device" if nothing more specific is found.

identify_vendor()

This method actually calls does the heavy lifting of determining the device type. It sets the vendor variable of the device.

Returns: Success = undef Failure = error message

identify_model()

This method actually calls does the heavy lifting of determining the device model(s). It sets the device model to an array ref containing all device models that this device matches. The list goes from most specific to least specific.

Example: [ 'hp2626' 'hp2600' 'hp_switch' ]

Returns: Success = undef Failure = error message

snmp_get_description()

Uses SNMP to get the sysDescr from the device.

Returns: success = the output/string from the system description failure = undef

console_get_description()

Uses the cli (if a session exists) to get some information about the device. It parses the data and returns something useful that the identify_vendor and identify_model methods can use.

Returns: success = a string that can identify the device failure = undef

connect()

Will try to connect to a device using default methods. This method should be overloaded by a sub class. It tries to take into account the idiosyncrasies of both HP and Cisco switches, but it could fail.

console_connect()

Will try to connect to a console server. Assumes the hostname is in the following format:

 terminal_line@console_server_hostname

This procedure works for Avocent Cyclades console servers. This will connect to the console server using (ssh or telnet):

 ssh -l username:termineal_line console_server_hostname

You should call connect() after using this method.

get_admin_rights()

This method tries to gain administrative rights on the device. (aka enable mode). It works for both Cisco and HP devices, but the overridden methods in the sub-classes have a higher percentage chance of working.

configure()

Given a configruration in a template file, execute the commands on the CLI using Expect. Using the given command template, configure the device.

 $template = Net::Autoconfig::Template->new("filename");
 $device->configure( $template->{$device->model} );
 $device->configure( $template->{$device->hostname} );

It will notify you (via the logs) if a specific command failed to execute correctly. If a command does not execute correctly, it disconnects from that device. If an optional command fails, it notifys you, but continues execute commands on the device.

Returns: success = undef failure = TRUE

access_method()

If ssh or telnet are passed, then it sets the method to ssh or telnet. If anything else is passed, it sets the method to user_defined.

access_cmd()

Checks to see if the passed value is ssh, telnet or something else that has an absolute path. If ssh or telnet are passed, the default locations for these are used, /usr/bin/ssh or /usr/bin/telnet. If the absolute file path is specified, use that instead.

This will also set the access method to ssh, telnet or user defined. If a non-standard ssh or telent location is specified, it will still set the method to ssh or telnet. If it is something else, then it will set the method to user defined.

Device File Format (Colon Format)

The file format used for describing objects was created by me, with commentary and input of Stephen Fromm, to be easy to type and readable. All "commands" are sandwitched between colons, ":", hense the name, "colon format".

Devices or default devices begin with "default" or the name of the device. The device ends with a :end: statement. There must be an :end: statement per device/default definition. Any subsequent device or default statement overrides the previous one. I.e. you can start with one default statement, define some devices, define a new default, and then define some more devices. You can manually set the hostname hostname = blah or it will take the part between the colons and use that as the hostname. You decide.

Whitespace is irrelavent if it comes at the beginning or end of a line. I.e. if you want to use tabs to make the definitions look pretty, go ahead. If you want to line-up the "=" signs, go ahead.

Example: :default: netmask = 255.255.255.0 username = some_user password = some_password enable_password = secret_password snmp_community = public access_vlan = 10 voice_vlan = 20 mgmt_vlan = 30 :end:

 :cisco_switch_1:
 :end:

 :cisco_switch_1:
 model = c2960
 :end:

 :hp_switch_1:
 some_crazy_variable = some_crazy_value
 :end:

SEE ALSO

    Net::Autoconfig

AUTHOR

Kevin Ehlers <kevin@uoregon.edu>

COPYRIGHT AND LICENSE

Copyright (C) 2008 by Kevin Ehlers, University of Oregon. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.

DISCLAIMER OF WARRENTY

THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.