NAME

       pmdacisco, parse, probe - Cisco router performance metrics
       domain agent (PMDA)


SYNOPSIS

       $PCP_PMDAS_DIR/cisco/pmdacisco [-d  domain]  [-l  logfile]
       [-P   password]  [-r  refresh]  [-U  username]  [-x  port]
       host:interface-spec [...]
       $PCP_PMDAS_DIR/cisco/parse  [options]  host:interface-spec
       [...]
       $PCP_PMDAS_DIR/cisco/probe  [-P  password]  [-U  username]
       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  consis­
            tent.   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 Cis­
            cos.  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.

       -U   By default, it is assumed that no username  login  is
            required to access the Cisco's telnet port.  If user­
            name login has been enabled on the Ciscos,  then  the
            corresponding   usernames   must   be   specified  to

            will  be  used  as the default username login for all
            Ciscos.  See also the INTERFACE  IDENTIFICATION  sec­
            tion below.

       -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  estab­
       lished,  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 connec­
       tion is broken and no values are returned.  This  prevents
       pmdacisco tying up the Cisco's telnet ports waiting indef­
       initely 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 inter­
       faces and/or multiple communications protocols, it is nec­
       essary  to tell pmdacisco which interfaces are to be moni­
       tored.

       The host:interface-spec  arguments  on  the  command  line
       define  a  particular  interface  on  a  particular  Cisco
       router.  host should be a hostname or  a  ``dot-notation''
       IP address that identifies the telnet port of a particular
       Cisco router.  There are several components of the  inter­
       face-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,  GigabitEthernet,  HSSI, serial or
              Vlan.

       interface
              Depending on the model  of  the  Cisco,  this  will
              either  be  an integer, e.g. s0, or an integer fol­
              lowed 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.

              If there is a user-level password, and it  is  dif­
              ferent  to  the  default  (see -P above), it may be
              optionally specified here by appending  a  question
              mark  (``?'') and the password to the end of inter­
              face-spec.

       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.

       The  following  are examples of valid interface-spec argu­
       ments.
                 my-router:e1/2
                 123.456.789.0:s0
                 wancisco:f2/3?trust_me
                 cisco34.foo.bar.com:e2?way2cool
                 mycisco:s2/2.1@mylogin
                 yourcisco:E0/0?yourpassword@youlogin


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.  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 exe­
       cuted directly.  The Install  and  Remove  scripts  notify
       pmcd(1) when the agent is installed or removed.

       $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 configuration file,
       as described in pcp.conf(4).


SEE ALSO

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


Man(1) output converted with man2html