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