NAME

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

SYNOPSIS

use Net::Autoconfig;

$autoconfig  = Net::Autoconfig->new();
$devices     = load_devices('path/to/device.cfg');
$template    = load_template('path/to/template.cfg');

$autoconifg->autoconfig($devices, $template);

DESCRIPTION

Net::Autoconfig was created to fill the void of having a utility to configure / provision devices in an automated way. The reason for its existence came about from having to deploy 150 new switches that were almost identically configured, except for the names, ip addresses and vlans. The devices had to be unpacked, firmware upgraded, given an initial configuration, and then given their final configuration. This process is error-prone and takes a long time. Using this module enabled one person to configure all 150 switches within a week.

This module will also configure switches that are currently reachable via the network. This makes it easy to upgrade all of the firmware or configurations on a large number of devices without having to do it manually. It provides the flexibility to not have to edit / write a script to do this for each separate device type or configuration revision. There are other modules that can do this, but this is vendor agnositc. I.e. it works on Cisco and HP devices. It can be extended to handle other vendors products relatively easily.

The module uses a new file format. I call it the colon format. I made it based on the fact that I didn't want to type very much. It's designed to be flexible without being overly complicated. See Device Fileformat and Template Fileformat below for more information.

The device types are auto discovered (if SNMP is enabled. It will try to use the command line if that's available and SNMP is not enabled. However, that might not work.) The other option is to manually set the vendor and device type in the config file.

FEATURES

1. Multivendor support

As of right now, it supports both Cisco and HP devices. It would be realtively easy to add support for another vendor's products.

2. Variable Interpolation

You can define your own variables in the template files. As long as those match a variable in the device file, the variable in the template will be replaced with the value from the device file.

3. Parallel device configuration

By default, it will configure up to 128 devices at the same time. This decreases the amount of time taken to configure a lot of deivces. This value can be changed. The absolute maximum number of simultaneous children is 256. If this is too few, it's fairly easy to change the value in the module.

4. Syslog style logging

This script will log to a file or to the screen. Using a config file, you can specify the level of logging that you want. This allows for more or less verbosity.

5. Console server support

This script will connect to a console server and configure devices that are attached to its ports. This is very useful when doing the intial configuration on devices.

6. Dynamic device/vendor discovery

If given a SNMP community and version, it will attempt to discover what type of device it is connecting to. If applicable, it will use a module that is specific to those devices. I.e it will handle that device's idiosyncrasies.

EXPORT

This module is object oriented. It does not export any functions.

METHODS

new( @options )

Create a new Net::Autoconfig object. You can pass any parameters you want, but only the following ones will have an effect.

bulk_mode
log_level
max_children

init_logging()

Initialize logging for the module. Right now, it loads the default config file.

load_devices("filename")

Return an array ref of all of the devices in the specified file. The file needs to be in colon format. You can specify any key => value pair that you want. There are some predefined ones, but you can safely ignore those if you want.

Devices are returned in the same order as they appear in the device configuration file.

Note: Versions prior to 1.12 returned a hash ref.

See the documenation on Net::Autoconfig::Device for information regarding the fileformat.

load_template("filename")

Open a template file and return a Net::Autoconfig::Template. This will be used with the autoconfig function. The template file is in colon format. The configurations are specified via class, hostname, or vendor type. Any field that is left blank in a command will be replaced with what is in the default command. If the default command is omitted, then the script will use it's own defaults.

See the documenation on Net::Autoconfig::Template for information regarding the fileformat.

Returns a Net::Autoconfig::Template device.

autoconfig($devices, $template)

Takes an array ref of devices and a Net::Autoconfig::Template object. It will try to configure a general per-class-type set of commands first and then a set of commands specific to that device. Any combination of command sets are permissable. It will send a notification if any commands fail for a paticular device.

Note: Prior to version 1.12, $devices was a hash ref

bulk_mode(TRUE/FALSE/undef)

Bulk mode is enabled by default.

Will set the bulk mode (aka parallel processing) flag if passed a TRUE or FALSE value. It will return the current bulk_mode status if passed nothing (i.e. undef).

max_children($value/undef)

Max_children is 64 by default.

If passed undef, it returns the current maximum number of simultaneous processes to run if bulk_mode is enabled. If passed a value, it sets the maximum number of children to that value. The absolute maximum number of child processes is 256. If that is too few, you can modify that value in the module.

logfile($filename/undef)

Access/Mutator method.

Sets the location of the logfile if passed the filename.

Returns the location of the logfile if passed undef.

log_level($level/undef)

*Note: This value currently has no effect on the operation of this module.

Set the log level using the logging.conf file.

If passed a value, it will set the log level to that value. Possible values are: 0 - Fatal - Least logging 1 - Errors 2 - Warnings 3 - Info (this is the default) 4 - Debug 5 - Trace - Most logging

If passed undef, it returns the current log level.

get_report()

This has not been implemented yet, but you are free to call it to see what it does. :-)

LOGGING

For the log file format, see Log::Log4perl. A helpful logfile should be included with the module installation. Make sure the filename is called "logging.conf" and is located in the current working directory from where the script is executed.

SEE ALSO

Look at the YAML documentation on cpan.org for more information
regarding the configuration files.

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.

A WORD OF CAUTION

Using this module, it is very easy to cause a complete network outage very quickly due to a miss-configuration or a typo. Please be very careful about what you do, and test on a single device to make sure it works correctly. Neither the author nor the University of Oregon will be held accountable or responsible if this software is used inappropriately or without careful consideration for what it is capable of doing.

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.

LIMITATION OF LIABILITY

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

cpanm Net::Autoconfig

perl -MCPAN -e shell
install Net::Autoconfig