Chapter 3. Common Conventions and Arguments

This chapter deals with the user interface components that are common to most of the graphical tools and text-based utilities that make up the monitor portion of Performance Co-Pilot (PCP).

This chapter only contains information pertaining to features which are introduced by installing the pcp product. For additional information about common commands and arguments used by the PCP suite of tools (including those in pcp_eoe), see Chapter 3, “Common Conventions and Arguments” in Performance Co-Pilot for IRIX User's and Administrator's Guide.

These are the major sections in this chapter:

Many of the utilities provided with PCP conform to a common set of naming and syntactic conventions for command line arguments and options. This section outlines these conventions and their meaning. The options may be generally assumed to be honored for all utilities supporting the corresponding functionality.

In all cases, the man pages for each utility fully describe the supported command arguments and options.

Command line options are also relevant when starting PCP applications from the desktop using the Alt double-click method. This technique launches the pmrun program to collect additional arguments to pass along when starting a PCP application.

PerfTools Icon Catalog

The conventions and arguments described in this chapter are common to all tools and utilities in the PerfTools Icon Catalog group, shown in Figure 3-1.

Figure 3-1. PerfTools Icon Catalog Group

Icon Catalog Group

General PCP Tool Options

The following sections provide information relevant to most of the PCP tools. It is presented here in a single place for convenience.

Common Directories and File Locations

The following files and directories are used by the PCP tools as repositories for option and configuration files and for binaries:


Script to set PCP run-time environment variables.


PCP configuration and environment file.


Configuration file for Performance Metrics Collection Daemon (PMCD). Sets environment variables, including PATH.


The PMCD binary.


Command line options for PMCD.


Command line options for pmlogger launched from /etc/init.d/pcp.


The PMCD startup script.


Directory containing PCP tools such as pmkstat , pminfo, and oview.


Directory containing shareable PCP-specific files and repository directories.


Directory containing non-shareable (that is, per-host) PCP specific files and repository directories. There are some symbolic links from the /usr/pcp directory hierarchy pointing into the /var/pcp directory hierarchy.


PCP tools that are typically not executed directly by the end user such as pmbrand, pmnscomp, and pmlogger.


Miscellaneous PCP libraries and executables.


Performance Metric Domain Agents (PMDAs), one directory per PMDA.


An alternate repository for some PMDAs. Certain entries here are symbolic links into /var/pcp/pmdas.


Configuration files for PCP tools, typically with one directory per tool.


Demonstration data files and example programs.


PCP Tutorial, in HTML format.


By default, diagnostic and trace log files generated by PMCD and PMDAs. Also, the PCP archive logs are managed in one directory per logged host below here.


Files and scripts for the Performance Metrics Name Space (PMNS).

PCP Environment Variables

When you are using PCP tools and utilities and are calling PCP library functions, a standard set of defined environment variables are available in the /etc/pcp.conf file. These variables are generally used to specify the location of various PCP pieces in the file system and may be loaded into shell scripts by sourcing the /etc/pcp.env shell script. They may also be queried by C and C++ programs using the __pmGetConfig library function. If a variable is already defined in the environment, the values in the pcp.conf file do not override those values; that is, the values in pcp.conf serve only as installation defaults. For additional information, see the /etc/pcp.conf(4), /etc/pcp.env(4), and __pmGetConfig man pages.

The following environment variables are recognized by PCP (these definitions are also available on the PCPIntro (1) man page):


Many of the PMAPI client programs require that a valid software license be present on the host on which the client is running (the license is node-locked). In the case that such a valid license is present, but is due to expire within the next 30 days, a message or pop-up notifier appears informing the user of this condition. These warnings can be disabled by setting this variable in the environment.

Other variables are available and are explained in Chapter 2, “Installing and Configuring Performance Co-Pilot” in the Performance Co-Pilot User's and Administrator's Guide.

Running PCP Tools through a Firewall

In some production environments, the Performance Co-Pilot (PCP) monitoring hosts are on one side of a TCP/IP firewall, and the PCP collector hosts may be on the other side.

If the firewall service is being provided by a product that supports the sockd (SOCKS) protocols for packet forwarding through the firewall, then the PCP tool pmsocks may be used; see the pmsocks (1) man page. Otherwise, it is necessary to arrange for packet forwarding to be enabled for those TCP/IP ports used by PCP, namely 4321 (or the value of the PMCD_PORT environment variable) for connections to PMCD and a finite range of consecutive port numbers starting at 4330 (or the value of the PMLOGGER_PORT environment variable) to allow pmlc connections to pmlogger instances.

The pmsocks Command

The pmsocks command and its related files and scripts allow PCP clients running on hosts located on the internal side of a TCP/IP sockd firewall system to monitor remote hosts on the other side of the firewall system. The basic syntax is as follows, where tool is an arbitrary PCP application, typically a monitoring tool:

pmsocks tool args

The pmsocks script prepares the necessary environment variables and then executes the PCP tool specified in tool across the firewall. For example, this command runs dkvis with metrics fetched from remotehost on the other side of the firewall:

pmsocks dkvis -h remotehost 

The configuration file is/etc/pcp_socks.conf, and the network-specific information in this file is set to correspond with your network. Complete information on this customization can be found in the pmsocks(1) man page.