# pmdacisco

## NAME



           **pmdacisco** - Cisco router performance metrics domain agent (PMDA)
    


## SYNOPSIS



           **$PCP_PMDAS_DIR/cisco/pmdacisco**[**-D** _debug_] [**-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**[**-D** _debug_] [**-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 hostname 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, 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 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 appending 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 exclamation 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 tokenising 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 configuration file, as described in pcp.conf(5).
    


## DEBUGGING OPTIONS



           The **-D** or **--debug** option enables the output of additional
           diagnostics on _stderr_ to help triage problems, although the
           information is sometimes cryptic and primarily intended to provide
           guidance for developers rather end-users.  _debug_ is a comma
           separated list of debugging options; use pmdbg(1) with the **-l**
           option to obtain a list of the available debugging options and
           their meaning.
    
           Debugging options specific to **pmdacisco** are as follows:
           ┌────────┬───────────────────────────────────────────────────────┐
           │ **Option** │ **Description** │
           ├────────┼───────────────────────────────────────────────────────┤
           │ **appl0** │ initialization, worker process details, data refresh, │
           │        │ timeouts                                              │
           ├────────┼───────────────────────────────────────────────────────┤
           │ **appl1** │ requests sent to Cisco device                         │
           ├────────┼───────────────────────────────────────────────────────┤
           │ **appl2** │ lexical scanner and parser for output from Cisco      │
           │        │ device                                                │
           └────────┴───────────────────────────────────────────────────────┘
    


* * *