PMDACISCO(1)

💖 PMDACISCO 💖

okay bestie, listen — this is a page from the General Commands Manual, and it's all about pmdacisco, a Performance Metrics Domain Agent (PMDA). no cap, it's giving router-whisperer energy. let's get into it 🦋

---

✨ 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 💅

so pmdacisco is a Performance Metrics Domain Agent (PMDA) that extracts performance metrics from one or more Cisco routers. literally its whole job. iconic.

here's the quick rundown of the pmdacisco command line options, bestie:

• -d — the performance metrics domain number you put here has to be unique and consistent. and i mean it — it is absolutely crucial. 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. don't play with this one 🚨
• -l — where the log file lives. by default, a log file named cisco.log gets written in the current directory of pmcd(1) when pmdacisco is started, i.e. $PCP_LOG_DIR/pmcd. if the log file can't be created or isn't writable, output goes to the standard error instead. rude but okay 💀
• -P — by default it's assumed that no user-level password is required to access the Cisco's telnet port. but if user-level passwords have been enabled on the Ciscos, those passwords must be specified to pmdacisco. if you pass it with the -P option, password becomes the default user-level password for all the Ciscos. also peep 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. default refresh is 120 seconds. so, every two minutes, we check in on the router. clingy? no. thorough. 🫶
• -s — the Cisco command prompt ends with the string prompt. default value is `>`. the only way pmdacisco can sync up sending commands with parsing 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. it's the vibe check, basically ✨
• -U — by default it's 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 INTERFACE IDENTIFICATION below 🌸
• -M — user account under which to run the agent. default is the unprivileged pcp account in current versions of PCP, but in older versions the superuser account (root) was used by default. glow-up arc fr fr 👑
• -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 that doesn't happen, the telnet connection is broken and no values are returned. this stops pmdacisco from tying up the Cisco's telnet ports waiting forever when the response from the router isn't what was 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. boundaries! we love to see it 💅

---

🎀 INTERFACE IDENTIFICATION 🎀

since every Cisco router can support multiple network interfaces and/or multiple communications protocols, you gotta tell pmdacisco which interfaces are being monitored. no mind-reading here, bestie.

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. the interface-spec has several components, 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. memorise the list or perish 🧚
• 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. that's the shortcut, and we love a shortcut 💖

• username — if there's a username login, and it's different from the default (see -U above), it may optionally be specified here by appending `@` and the username to the end of interface-spec.
• password — if there's a user-level password, and it's different from the default (see -P above), it may optionally be specified here by appending a question mark (`?`) and the password to the end of interface-spec.
• prompt — if the Cisco command prompt is different from the default (see -s above), it may optionally be 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. slay:

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. it's giving detective energy 🔍

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

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. very demure, very mindful 📝

---

⭐ 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. do not do it. i'm serious bestie 😭

the Install and Remove scripts notify pmcd(1) when the agent is installed or removed. so polite of them 🫶

---

🦋 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). it's the config lore, iykyk 📖

---

🔥 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 than for end-users. ngl, it's a little mysterious 💀

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:

• appl0 — initialization, worker process details, data refresh, timeouts
• appl1 — requests sent to Cisco device
• appl2 — lexical scanner and parser for output from Cisco device

---

🌸 SEE ALSO 🌸

pmcd(1), pcp.conf(5) and pcp.env(5). go read them, bestie, they're part of the cinematic universe 🌈

---

and that's the whole page, no skips, no cuts, all facts intact 💖 this one came from the Performance Co-Pilot (PCP) crew — that's the source and the version, right there in the corner where the footer usually lives — and yeah, it's PMDACISCO(1), general commands manual, serving looks as always. bye bestie, go monitor some routers 🎀👑