NAME
        pancho

SYNOPSIS
        options   [ --upload | --download | --commit ]
                  [ --filename <filename> ]
                  [ --list <list> ]
                  [ --host <hostname> ]
                  [ --server <ip/fqdn/hostname> ]
                  [ --string <snmp community> ]
		  [ --path <path within tftproot> ]
                  [ --regex <regular expression> ]
		  [ --reload ]
		  [ --start ]
                  [ --version ]
		  [ --verbose-help ]
                  [ --help ]

        requires  [ perl, net::snmp ]

DESCRIPTION
	pancho was written with the goal of allowing network
	admnistrators make a change to a group of cisco devices 
	without being required to log into each host.
        pancho also provides the flexibility to allow admins to
	use its function against a single host, a select group
	or the entire whole. in addition to changes to current
	configurations on remote devices, pancho is also capable
	of archiving device configurations manually or through
	automated runs.

OPTIONS
        -u, --upload
                specify that pancho send a configuration
                file TO the remote device(s).

        -d, --download
                specify that pancho retrieve a configuration
                file FROM the remote device(s).

        -c. --commit
                specify that pancho perform a 'write memory'
                or 'copy run start' on the remote device(s).

        -f, --filename
                specify the local filename that pancho should
                send to the remote device.

        -l, --list
                specify a local file that hold a list of device
                hostnames or ip addresses that pancho should
                perform actions against.

        --host
                specify an individual host on which pancho
		will perform actions.

        --server
                specify a tftp server that pancho will push
                or pull configurations to and from. this may
		be in the format of an ip address, a fully
		qualified domain name, or a hostname able to
		be resolved by the machine upon which pancho
		is being ran.

        --string
                specify a snmp read-write string.

	-p, --path
		specify a path within the tftproot.

        --regex
                specify a regular expression that pancho can
                use to filter out specific hosts from the
                host file that actions should be taken against.

	--reload
		request the remote node to immediately reload.

	--start
		change source/destination to startup-config or
		the nvram of the remote router. this will 
 		essentially cause the router to either execute
		a "copy tftp startup-config" or "copy startup-
		config tftp".

        --version
                display the current version of pancho.

        --help
               	short synopsis of flag options. 

USAGE
	getting started with pancho does not require much work,
	however some thought should be put into the process.
	pancho is capable of having a few default settings 
	predefined that take effect each time pancho is ran.

	open pancho in your favorite text editor and look for 
	the area near the beginning of the file that highlights
	three fields that can be updated with your specific 
	information. The field $community, $tftpserver and @devices
	all define their matching information. For $community 
	and $tftpserver, simply put the corresponding strings 
	between the quotes to the right of the equal sign.

	@devices takes a bit more work, however it should not
	prove too difficult. this field should be populated with
	the group of devices that you feel will be configured or
	archived most often on your network. the devices can be
	entered by hostname or by ip address within the parentheses
	to the right of the equal sign. at least one single space 
	should seperate each entry such that it may look like:

          @devices = qw( border1 172.16.254.20 edge.lunarmedia.net );

        at first glance, pancho appears to have a significantly
        long command line. however, many of the option flags
        seen above can be set as default such that the flags
        themselves would only be called to override the default
        settings. for example a default tftpserver may be set
        within the pancho configuration, however you will still
        be able to specify:

                --server 172.16.254.16

        in case you would like to push/pull your config to an
        alternate server.

        pancho can be set up to have a default group of nodes
        that it will affect when ran. this list can be altered
        by specifying the --host flag to indicate a single node
        or the --list flag which will let you direct pancho to
        read the group to be effected from a plain text file.
	this text file should have each node listed on its own
	line either by hostname or ip address.
        another method which allows pancho to further limit 
        the group of devices touched is the --regex option. this
        feature is very powerful in the hands of someone with
        a fair amount of knowledge concerning regular expressions
        and nodes grouped with logical naming conventions.

                --regex ^core.*

        would indicate that within the default list of nodes, or
        within the list obtained from an external text file, only
        those with a name beginning in "core" would be affected.

	using the --start flag will cause pancho to send/receive
	a configuration to/from a remote device's startup-config,
	or nvram, rather than from the machine's running-config.
	the caveat to the --start flag is that this operation can
	only be performed on devices using the newer cisco-copy-
	config mibs. this means that most ios revisions prior to
 	12.x will not allow it.

        the final optional flag is --filename. if unspecified,
        this value defaults to the hostname of the device being
        touched with an extension of ".cfg". the --filename flag
        argument should always be used when a single configuration 
        file will be uploaded to a group of devices. additionally,
	--filename may be used to specify an entire path to a 
	specific individual file within a subdirectory of the 
	tftproot:

		--filename /cfg/2500/tacacs_config.txt

	in situations where you are not specifying a specific filename
	but would like your configs to be written/read from a directory
	beneath the tftproot, --path allows you to specify an 
	alternative:

		--path /cfg/7200

        pancho's only mandatory flag is one of two options,
        --upload or --download. this specifies whether or not
        pancho will push a configuration to the device or pull
        the remote device's config down to the local tftp server.
        pancho lives remotely from the device and therefore views
        the world from that perspective. --upload signifies that
        a file will be uploaded TO the device. conversely,
        --download indicates that the config will be brought down
        FROM the device.

  	the --reload option is available strictly on devices that
	have the "snmp-server system-shutdown" parameter configured
	on the remote router. this is obviously a significantly 
	powerful option and is offered strictly for the ability to
	upload a configuration to startup-config and then initialize
	a reload to put the new config into effect.

        the final option of --commit is used to perform a remote
        "write memory" or "copy run start". this option can be
        used either individually, or in conjunction with --upload
        essentially committing to memory the changes as they are
        being made.

EXAMPLES
        in order to utilize pancho's full capacity for device 
        configuration, one needs to be familiar with cisco's
        'copy tftp run' or 'config net' syntax. in depth
        discussion on the procedure can be found on cisco's
        website at http://www.cisco.com.

        a summary of the process is as follows. a remote
        device will tftp a configuration file consisting of
        standard ios commands into its running-config. the
        device will merge the current running-config and the
        command options received from the text file and then
        apply the whole to its new running configuration.

        an example may better state the process.

        on the tftp server, we create a plain text file to
        update the access-list 5 on a group of remote devices.
        the plain text file, is as follows:

                !
                no access-list 5
                access-list 5 permit 10.6.21.64 0.0.0.31
                access-list 5 permit 10.12.71.0 0.0.0.255
                !
                end

        since we plan on completely rewriting access-list 5
        on the remote devices with this new acl, our first
        statement is 'no access-list 5' which allows us to
        start a new acl listing. the following acl statements
        will then build the new access-list.

        since cisco's 'copy tftp run' process first merges the
        current running-config and our plain text commands before
        it applies the newly created configuration, there will
        be no interruption in traffic being inspected by access-
        list 5. very different than just copying and pasting the
        same commands into the cisco command prompt which applies
        each statement with the hit of the carriage return
        allowing for the possibility of serious consequences.

        with knowledge of cisco's ios syntax, the possibilities for
        remote configuration are endless, and with pancho's
        capability for customization, an entire network may be
        updated or archived from a single point of management.

        the following a just a few of pancho's command line options
        in running syntax:

                update all devices with changes held in a flat file
                  pancho -u -f acl_update.txt

                archive all device configurations locally
                  pancho -d

                or to a remote tftp server
                  pancho -d --server ns1.lunarmedia.net 

		download a host's configuration to a directory
		within the tftproot called configs
		  pancho -d --host rsm716.pdx --path /configs

		commit changes on a group of hosts held within
		an external file
		  pancho --commit --list hostfile.txt

                update all border devices with a new motd using an
                alternate snmp community
                  pancho -u -f motd.txt --regex border --string f00B@r

CAVEATS
        pancho's power does come with some caveats that should not
        be considered lightly. pancho depends upon remote devices 
        having a read-write(rw) snmp community string configured.
        since read-write strings offer full snmp control to a machine
        the potential for exploit could be high.

        it is HIGHLY recommended, if not considered mandatory by this
        author that all devices using rw snmp strings should have an
        acl configured to limit what machines can gain such access to
        the device. again, full documentation can be found on cisco's
        website, however a short synopsis is as follows:

                ! access-list specifying nodes that will be capable
                ! of using snmp access to devices 
                access-list 10 permit host 10.10.220.78
                access-list 10 permit 192.168.96.4 0.0.0.3
                !
                ! apply access-list to snmp community
                snmp-server community 9Eck#0-A rw 10
                !

        pancho also relies on the tftp protocol and server. files held
        within the tftproot and its subdirectories are generally world
        readable. moreover the tftp protocol does not inherently provide
        any method for user authentication.
        because of this, it is generally good measure to try to limit
        the nodes which have access to the tftp mechanism. this can be
        achieved through a local firewall specifying remote nodes or
        subnets that can push/pull to and from the tftpserver. with remote
        devices all belonging to different subnets, this would at first
        seem tedious to set up and even worse to maintain. a common
        convention to combat this is to use loopback addresses from an
        aggregate on all remote devices. it is then possible to specify

                ip tftp source-interface Loopback 100

        and ensure that all tftp requests coming in from remote devices
        will have a predictable source address, that can be grouped into
        the aggregate. using this mechanism, a large group of devices 
        numbered with Loopback addresses having /32 masks can be consolidated
        into a larger aggregate with a shorter mask allowing for less
        configuration within the firewall rules.

	one final caveat when using pancho is the new grouping of cisco
	mibs, cisco-copy-config. these mibs deprecate those used previously
	with ios revision 11.x
	as a result pancho tries to compensate by allowing the administrator
	access to both sets of mibs. some functionality available through the
	newer set is not available through the older. the full details of 
	cisco's new oid, can be found at:

       	  http://www.cisco.com/warp/public/477/SNMP/copy_configs_snmp.shtml

COMMENTS
        Please send all comments regarding pancho to:

                pancho@lunarmedia.net

        Check for new releases of pancho at:

                http://pancho.lunarmedia.net/

BUGS

AUTHOR
        Charles J. Menzes <menzes@lunarmedia.net>
        Pancho Copyright(C) 2001

