README: libcisco 1.0
June 23, 2002

Copyright (C) June 2002 Andy Ziegelbein
All rights reserved
-------------------

Contents
========

    1. Introduction to libcisco 1.0
    2. Requirements
    3. Documentation
    4. Licensing
    5. Support and bug fixes


1. Introduction to libcisco 1.0
===============================

libcisco 1.0 is a library of Tcl procedures used for automating configuration
management tasks on Cisco networking equipment.  These tasks are performed by
making changes through the CLI of the target system (e.g. a privileged EXEC
session under IOS).  At the time of this writing, the libraries support
automation over a telnet session only.  Future support of SSH and possibly
direct console connections using tip/minicom or other command-line terminal
emulators is planned.

The following equipment has been tested with these libraries:

    - Cisco 7500 Series Routers
    - Cisco 3600/2600/1600 Series Routers
    - Cisco 2500 Series Routers
    - Cisco AS5300 Universal Access Servers
    - Catalyst Lightstream ATM Switches
    - Catalyst 5000 Route Switch Modules
    - Catalyst 5000 LAN Emulation Modules
    - Catalyst 6000 LAN Emulation Modules
    - Catalyst 6000 Family Multilayer Switch Feature Cards
    - Catalyst 6000 Family Switches
    - Catalyst 5000/5500 Family Switches
    - Catalyst 4000 Series Switches
    - Catalyst 3500 Series XL Switches
    - Catalyst 2900 Series XL Switches
    - Catalyst 1900 Series Switches

libcisco represents a complete rewrite of a set of scripts and library
functions that were started in 1999.  The original libraries were developed
for my former employer and enhanced over the years.  In the beginning of 2002
I started work on libcisco.  This time the work was done completely on my own
personal time.   So while this is only the first release of libcisco, it is
the product of nearly three years of development experience on the subject.

Note: at least two other libraries exist which provide similar functionality
in different scripting environments--Perl and Python.

Joshua Keroes has written a Perl module called "Net::Telnet::Cisco" if you
prefer programming in Perl.  This project is hosted on SourceForge.  See the
following URL for more information:

    http://sourceforge.net/projects/nettelnetcisco

Brian Landers has written a nice Python library called "netdevicelib" which
is very similar in concept to this library.  If you prefer scripting in Python,
or are more interested in learning an object-oriented scripting language than
Tcl (string-based command language), I would encourage you to check out his
library.  It also has a project page hosted on SourceForge:

    http://sourceforge.net/projects/netdevicelib


2. Requirements
===============

1.  UNIX.  Any variant should work but the library has been tested under only
    Red Hat Linux at the time of this writing.

2.  Tcl 8.3+

    How do I know if I have Tcl 8.3 or later?
    -----------------------------------------
    Try looking through your path or file system for 'tclsh', 'tclsh8.3',
    'protclsh', or 'protclsh83'.  If you locate a 'tclsh' or 'protclsh' file,
    the version of the interpreter may be obtained by running the interpreter.
    At the interpreter prompt, "%", type 'info tclversion' to obtain the
    version number.

    # tclsh
    % info tclversion
    8.3
    % 

3.  Expect 5.3+ Tcl library

    How do I know if I have the Expect 5.3 library or later?
    --------------------------------------------------------
    Start an interactive Tcl shell by running the interpreter (usu. 'tclsh')
    and type 'package require Expect'.  This will load the highest version
    of the Expect library found on your system.  If the library is found the
    version number of the library will be returned.

    # tclsh
    % package require Expect
    5.32.2
    % 

4.  Telnet client

    This library expects that a command-line telnet client be in the PATH
    at the time of execution.  The basic telnet client packaged with your
    UNIX OS should suffice.


3. Documentation
================

This release of libcisco includes documentation in HTML and NROFF format.
The documentation files are located in the "doc" directory.  A couple example
scripts have been included with this distribution.  These scripts are intended
to be used as a learning aide only.  The example scripts are located in the
"examples" directory.  For a more advanced look at how to create your own
procedures, see the "libusr*.tcl" files included with this distribution.


4. Licensing
============

The libcisco library is licensed under the GNU Lesser General Public License.
A copy of this license should be included with this distribution in a file
named "LICENSE".  If you received this distribution without the LICENSE
file, you may find an on-line copy of the license file at the following URL:

    http://www.gnu.org/copyleft/lesser.html


5. Support and bug fixes
========================

All known bugs in libcisco should be posted to the SourceForge project website
for libcisco.

I am very interested in receiving your comments, bug reports, and requests
for enhancements.  I prefer that all such information be submitted using
the tools made available at the SourceForge web site for this project.
However, if you have difficulty accessing/posting to this web site or would
simply like your request to be private, you may send me e-mail at the following
address:

    andy@packetz.org

           or

    aziegelb@users.sourceforge.net

