PMDACISCO(1)						      General Commands Manual						      PMDACISCO(1)

NAME

       pmdacisco - Cisco router performance metrics domain agent (PMDA)

SYNOPSIS

       $PCP_PMDAS_DIR/cisco/pmdacisco  [-d  domain]  [-l  logfile]  [-U  username]  [-P password] [-r refresh] [-s prompt] [-M username] [-x port]
       host:interface-spec [...]
       $PCP_PMDAS_DIR/cisco/parse [options] host:interface-spec [...]
       $PCP_PMDAS_DIR/cisco/probe [-P password] [-s prompt] [-U username] [-x port] host

DESCRIPTION

       pmdacisco is a Performance Metrics Domain Agent (PMDA) which extracts performance metrics from one or more Cisco routers.

       A brief description of the pmdacisco command line options follows:

       -d   It is absolutely crucial that the performance metrics domain number specified here is unique and consistent.  That is,  domain  should
	    be different for every PMDA on the one host, and the same domain number should be used for the same PMDA on all hosts.

       -l   Location  of  the  log  file.  By default, a log file named cisco.log is written in the current directory of pmcd(1) when pmdacisco is
	    started, i.e.  $PCP_LOG_DIR/pmcd.  If the log file cannot be created or is not writable, output  is  written  to  the  standard  error
	    instead.

       -P   By	default,  it  is  assumed that no user-level password is required to access the Cisco's telnet port.  If user-level passwords have
	    been enabled on the Ciscos, then those passwords must be specified to pmdacisco.  If specified with the -P option,	password  will	be
	    used as the default user-level password for all Ciscos.  See also the INTERFACE IDENTIFICATION section below.

       -r   pmdacisco will refresh the current values for all performance metrics by contacting each Cisco router once every refresh seconds.  The
	    default refresh is 120 seconds.

       -s   The Cisco command prompt ends with the string prompt.  The default value is ``>''.	The only way pmdacisco can synchronize the sending
	    of	commands  and  the  parsing of output is by recognizing prompt as a unique string that comes at the end of all output, i.e. as the
	    command prompt when waiting for the next command.

       -U   By default, it is assumed that no username login is required to access the Cisco's telnet port.  If username login has been enabled on
	    the  Ciscos,  then the corresponding usernames must be specified to pmdacisco.  If specified with the -U option, username will be used
	    as the default username login for all Ciscos.  See also the INTERFACE IDENTIFICATION section below.

       -M   User account under which to run the agent.	The default is the unprivileged "pcp" account in current versions of  PCP,  but  in  older
	    versions the superuser account ("root") was used by default.

       -x   Connect to the Cisco via TCP port number port rather than the default 23 for a telnet connection.

       For  each interface, once the telnet connection is established, pmdacisco is willing to wait up to 5 seconds for the Cisco to provide a new
       snapshot of the requested information.  If this does not happen, the telnet connection is broken and no values are returned.  This prevents
       pmdacisco  tying  up  the  Cisco's telnet ports waiting indefinitely when the response from the router is not what is expected, e.g. if the
       format of the ``show int'' output changes, or the command is in error because an interface is no longer configured on the router.

INTERFACE IDENTIFICATION

       As each Cisco router can support multiple network interfaces and/or multiple communications protocols, it is necessary  to  tell  pmdacisco
       which interfaces are to be monitored.

       The  host:interface-spec  arguments on the command line define a particular interface on a particular Cisco router.  host should be a host-
       name or a ``dot-notation'' IP address that identifies the telnet port of a particular Cisco router.  There are several  components  of  the
       interface-spec as follows.

       protocol
	      One  of the abbreviations a, B, E, e, f, G, h, s or Vl respectively for ATM, BRI (ISDN), FastEthernet, Ethernet, FDDI, GigabitEther-
	      net, HSSI, serial or Vlan.

       interface
	      Depending on the model of the Cisco, this will either be an integer, e.g. s0, or an integer followed by a slash (``/'') followed	by
	      a subinterface identification in one of a variety of syntactic forms, e.g. e1/0, G0/0/1 or s4/2.1.

	      To  discover  the  valid	interfaces on a particular Cisco, connect to the telnet port (using telnet(1)) and enter the command "show
	      int" and look for the interface identifiers following the keywords ``Ethernet'', ``Fddi'', ``Serial'', etc.

	      Alternatively run the probe command.

       username
	      If there is a username login, and it is different to the default (see -U above), it may be optionally specified  here  by  appending
	      ``@'' and the username to the end of interface-spec.

       password
	      If there is a user-level password, and it is different to the default (see -P above), it may be optionally specified here by append-
	      ing a question mark (``?'') and the password to the end of interface-spec.

       prompt If the Cisco command prompt is different to the default (see -s above), it may be optionally specified here by appending an exclama-
	      tion mark (``!'') and the prompt to the end of interface-spec.

       The following are examples of valid interface-spec arguments.
		 my-router:e1/2
		 123.456.789.0:s0
		 wancisco:f2/3?trust_me
		 somecisco:G1/0!myprompt
		 cisco34.foo.bar.com:e2?way2cool
		 mycisco:s2/2.1@mylogin
		 yourcisco:E0/0@yourlogin?yourpassword
		 mycisco:E0/0@mylogin?mypassword!myprompt

HELPER UTILITIES

       The probe command may be used to discover the names of all interfaces for a particular Cisco router identified by host.	The -P argument is
       the same as for pmdacisco.

       The parse command takes exactly the same arguments as pmdacisco, but executes outside the control of any pmcd(1) and  so  may  be  used	to
       diagnose problems with handling a particular Cisco router and/or one of its interfaces.

       Additional  diagnostic  verbosity  may  be  produced using the -D appl0,appl1,appl2 command line option.  appl0 logs connect and disconnect
       events, login progress, high-level flow of control and extracted statistics.  appl1 traces all commands sent to the  Cisco  device.   appl2
       logs tokenizing and parsing of the output from the Cisco device.  Diagnostics are generated on standard error as each sample is fetched and
       parsed.

INSTALLATION

       If you want access to the names, help text and values for the Cisco performance metrics, do the following as root:

	    # cd $PCP_PMDAS_DIR/cisco
	    # ./Install

       If you want to undo the installation, do the following as root:

	    # cd $PCP_PMDAS_DIR/cisco
	    # ./Remove

       pmdacisco is launched by pmcd(1) and should never be executed directly.	The Install and Remove scripts notify pmcd(1) when  the  agent	is
       installed or removed.

FILES

       $PCP_PMCDCONF_PATH
		 command line options used to launch pmdacisco
       $PCP_PMDAS_DIR/cisco/help
		 default help text file for the Cisco metrics
       $PCP_PMDAS_DIR/cisco/Install
		 installation script for the pmdacisco agent
       $PCP_PMDAS_DIR/cisco/Remove
		 undo installation script for the pmdacisco agent
       $PCP_LOG_DIR/pmcd/cisco.log
		 default log file for error messages and other information from pmdacisco

PCP ENVIRONMENT

       Environment  variables  with  the prefix PCP_ are used to parameterize the file and directory names used by PCP.  On each installation, the
       file /etc/pcp.conf contains the local values for these variables.  The $PCP_CONF variable may be used to specify an alternative	configura-
       tion file, as described in pcp.conf(5).

SEE ALSO

       pmcd(1), pcp.conf(5) and pcp.env(5).

Performance Co-Pilot							PCP							      PMDACISCO(1)