/ 
Cisco-Conf-0.10
River stage zero No dependents
/ Cisco::Conf

NAME

Cisco::Conf - Perl module for configuring Cisco routers via TFTP

SYNOPSIS

  use Cisco::Conf;

  # Set the path of the main configuration file
  $configFile = '/usr/local/cisco/etc/config';

  # Add a new machine to the configuration file
  Cisco::Conf->Add($configFile,
		   {'name' => 'myrouter',
		    'description' => 'My Internet gateway',
		    'users' => ['root', 'joe'],
		    'host' => '192.168.1.1',
		    'username' => 'itsme',
		    'password' => 'secret',
		    'enable_password' => undef  # Prompt password
		   });

  # Remove a machine from the configuration file
  Cisco::Conf->Remove($configFile, 'myrouter');

  # Create a configuration object by reading it from the
  # configuration file
  $conf = Cisco::Conf->Read($configFile, 'myrouter');

  # Edit a machine's configuration (uses $ENV{'EDITOR'})
  $conf->Edit($editor, $file, $tmpDir);

  # Feed a machine's configuration into RCS
  $conf->RCS($file, "in");

  # Load a machine's configuration and save it in 'myfile'
  $conf->Load('myfile');

  # Strip comments from a machine configuration in $configuration
  $stripped = Cisco::Conf->Strip($configuration);

  # Read a configuration from 'myfile' and save it into the router
  $conf->Save('myfile', $write);

  # Return a list of all configurations that the current user may
  # access
  @list = Cisco::Conf->Info($configFile);

DESCRIPTION

This module offers a set of methods for creating and managing Cisco configurations. Configurations are stored as plain text files, including comments. Comments are indicated by an exclamation mark and may terminate any line. Example:

! Here come the interfaces
interface Ethernet 0   ! Local LAN
...

All methods throw a Perl exception in case of errors, thus you should encapsulate them with an eval, like this:

    $@ = '';
    eval {
        Cisco::Conf->Add('/usr/local/cisco/etc/configurations',
			 {'name' => 'myrouter',
			  ...
			 });
    };
    if ($@) {
	print STDERR "An error occurred: $@\n";
	exit 1;
    }

The following methods are offered by the module:

Add($configFile, \%attr)

(Class method) Adds a new configuration to the list of configurations in the file $configFile. A configuration is represented by the hash ref \%attr with a number of attributes, including

name

A symbolic and short name for the configuration, unique in the list of configurations.

description

A textual description of the configuration.

host

The routers host name or IP address

username
password
enable_password

The routers username, login and enable passwords. If these attributes are not present or have a value of undef, the methods will prompt for passwords.

file

File name where the machine configuration is stored, for example /usr/local/cisco/etc/mycisco.conf.

Only root may add or remove configurations.

Remove($configFile, $name)

(Class method) Removes configuration $name from the list of configurations in the file $configFile.

Only root may add or remove configurations.

Read($configFile, $name)

(Class method) Reads the configuration of the host $name from the configuration file $configFile and returns a Cisco::Conf instance representing the host.

Edit($editor, $file, $tmpDir)

(Instance method) Invoke the editor $editor to edit the configuration file. If $editor is not defined, use $ENV{'EDITOR'} or the first editor from the list of editors in the configuration file. (The editors attribute.)

For security reasons valid editors are restricted to those from the configuration file. Editing takes place in the directory $tmpDir, so that we can change the EUID to the users.

Example:

$self->Edit('emacs', 'myrouter.conf', '/tmp');

RCS($file, $inout)

(Instance method) Invoke the revision control system (RCS) by using the ci attribute from the config file

Example:

$self->RCS($file, "in");

Strip($configuration)

(Class method) Strips comments and empty lines from the machine configuration in the string $configuration and returns the resulting string.

Comments may appear on any line, beginning with an exclamation mark. Example:

! This is a comment
interface Ethernet 0  ! Another comment

Load($file)

(Instance method) Loads the current configuration from the host and saves it into the file $file. If such a file already exists, it will be overwritten silently: It is the calling functions task to emit a warning or do whatever appropriate.

You cannot choose arbitrary file names for $file: The location depends on the settings of your local TFTP server. In particular you have to *have* a local TFTP server running. :-) See tftpd(1) for details.

Note that the file mode of $file will be 0666, on other words, the file is readable and writeable for the world! You should change this as soon as possible.

Save($file, $write)

(Instance method) Reads a machines configuration from $file and save it into the router. Like with the Load method, possible locations of $file depend on your TFTP servers settings.

Note that the file mode of $file will be changed to 0444, on other words, the file is readable for the world! You should change this as soon as possible.

If the argument $write is TRUE, the configuration will be saved into the non-volatile memory by executing the command

write memory

Info($configFile)

(Class method) Read a list of all configurations in $configFile and return those configurations that are accessible by the current user.

EtcFile($config)

(Instance method) Returns a routers config file name.

TftpFile($config)

(Instance method) Returns a routers TFTP file name.

CREDITS

Esfandiar Tabari <Esfandiar_Tabari@hugoboss.com>

for giving me the contract that included the cisconf script. :-)

Tungning Cheng <cherng@bbn.com>

for fixing the nasty open file bug ...

Mike Newton <mike@delusion.org>

for adding the username and supporting the Rcs module.

AUTHOR AND COPYRIGHT

This module is

Copyright (C) 1998    Jochen Wiedmann
                      Am Eisteich 9
                      72555 Metzingen
                      Germany

                      Phone: +49 7123 14887
                      Email: joe@ispsoft.de

All rights reserved.

You may distribute this module under the terms of either the GNU General Public License or the Artistic License, as specified in the Perl README file.

SEE ALSO

cisconf(1)