PMPROXY(1)                 General Commands Manual                PMPROXY(1)

NAME         top

       pmproxy - proxy for performance metrics collector daemon

SYNOPSIS         top

       pmproxy [-Aft] [-C dirname] [-i ipaddress] [-l logfile] [-L bytes]
       [-M certname] [-p port[,port ...]  [-P passfile] [-U username] [-x

DESCRIPTION         top

       pmproxy acts as a protocol proxy for pmcd(1), allowing Performance
       Co-Pilot (PCP) monitoring clients to connect to one or more pmcd(1)
       instances via pmproxy.

       Normally pmproxy is deployed in a firewall domain, or on a ``head''
       node of a cluster where the IP (Internet Protocol) address of the
       hosts where pmcd(1) is running may be unknown to the PCP monitoring
       clients, although the IP address of the host where pmproxy is running
       is known to these clients.  Similarly, the clients may have network
       connectivity only to the host where pmproxy is running, while there
       is network connectivity from that host to the hosts of interest where
       pmcd(1) is running.

       The behaviour of the PCP monitoring clients is controlled by either
       the PMPROXY_HOST environment variable or through the extended
       hostname specification (see PCPIntro(1) for details).  If neither of
       these mechanisms is used, clients will make their connections
       directly to pmcd(1).  If the proxy hostname syntax is used or
       PMPROXY_HOST is set, then this should be the hostname or IP address
       of the system where pmproxy is running, and the clients will connect
       to pmcd(1) indirectly through the protocol proxy services of pmproxy.

       The options to pmproxy are as follows.

       -A     Disable service advertisement.  By default, pmproxy will
              advertise its presence on the network using any available
              mechanisms (such as Avahi/DNS-SD), assisting remote monitoring
              tools with finding it.  These mechanisms are disabled with
              this option.

       -C dirname
              Specify the path to the Network Security Services certificate
              database, for (optional) secure connections.  The default is
              /etc/pki/nssdb.  Refer also to the -P option.  If it does not
              already exist, this database can be created using the certutil
              utility.  This process and other certificate database
              maintenance information is provided in the PCPIntro(1) manual
              page and the online PCP tutorials.

       -f     By default pmproxy is started as a daemon.  The -f option
              indicates that it should run in the foreground.  This is most
              useful when trying to diagnose problems with establishing

       -i ipaddress
              This option is usually only used on hosts with more than one
              network interface (very common for firewall and ``head'' node
              hosts where pmproxy is most likely to be deployed).  If no -i
              options are specified pmproxy accepts PCP client connections
              on  any of its host's IP addresses.  The -i option is used to
              specify explicitly an IP address that PCP client connections
              should be accepted on.  ipaddress should be in the standard
              dotted form (e.g.  The -i option may be used
              multiple times to define a list of IP addresses.  When one or
              more -i options is specified, attempted connections made on
              any other IP addresses will be refused.

       -l logfile
              By default a log file named pmproxy.log is written in the
              current directory.  The -l option causes the log file to be
              written to logfile instead of the default.  If the log file
              cannot be created or is not writable, output is written to the
              standard error instead.

       -L bytes
              PDUs received by pmproxy from PCP monitoring clients are
              restricted to a maximum size of 65536 bytes by default to
              defend against Denial of Service attacks.  The -L option may
              be used to change the maximum incoming PDU size.

       -M certname
              By default, pmproxy will try to use a certificate called PCP
              Collector certificate in its server role. The -M option allows
              this to be changed.

       -P passfile
              Specify the path to a file containing the Network Security
              Services certificate database password for (optional) secure
              connections, and for databases that are password protected.
              Refer also to the -C option.  When using this option, great
              care should be exercised to ensure appropriate ownership
              ("pcp" user, typically) and permissions on this file (0400, so
              as to be unreadable by any user other than the user running
              the pmproxy process).

       -t, --timeseries
              Operate in automatic archive timeseries discovery mode.  This
              (experimental) mode of operation will detect system archives
              created by pmlogger(1) and import into a redis-server(1)
              automatically, for fast, scalable timeseries queries.

       -U username
              Assume the identity of username before starting to accept
              incoming packets from PCP monitoring clients.

       -x file
              Before the pmproxy logfile can be opened, pmproxy may
              encounter a fatal error which prevents it from starting.  By
              default, the output describing this error is sent to /dev/tty
              but it may redirected to file.


       Normally, pmproxy is started automatically at boot time and stopped
       when the system is being brought down.  Under certain circumstances
       it is necessary to start or stop pmproxy manually.  To do this one
       must become superuser and type

       # $PCP_RC_DIR/pmproxy start

       to start pmproxy, or

       # $PCP_RC_DIR/pmproxy stop

       to stop pmproxy.  Starting pmproxy when it is already running is the
       same as stopping it and then starting it again.

       Normally pmproxy listens for PCP client connections on TCP/IP port
       number 44322 (registered at ).  Either the
       environment variable PMPROXY_PORT -p command line option may be used
       to specify alternative port number(s) when PMPROXY_PORT or the -p
       command line option may be used to specify alternative port number(s)
       when pmproxy is started; in each case, the specification is a comma-
       separated list of one or more numerical port numbers.  Should both
       methods be used or multiple -p options appear on the command line,
       pmproxy will listen on the union of the set of ports specified via
       all -p options and the PMPROXY_PORT environment variable.  If non-
       default ports are used with pmproxy care should be taken to ensure
       that PMPROXY_PORT is also set in the environment of any client
       application that will connect to pmproxy, or that the extended host
       specification syntax is used (see PCPIntro(1) for details).

FILES         top

              command line options for pmproxy when launched from
              $PCP_RC_DIR/pmproxy All the command line option lines should
              start with a hyphen as the first character.
              additional environment variables that will be set when pmproxy
              executes.  Only settings of the form "PMPROXY_VARIABLE=value"
              will be honoured.
              (or $PCP_LOG_DIR/pmproxy/pmproxy.log when started
              All messages and diagnostics are directed here
              default Network Security Services (NSS) certificate database
              directory, used for optional Secure Socket Layer connections.
              This database can be created and queried using the NSS
              certutil tool, amongst others.

ENVIRONMENT         top

       In addition to the PCP environment variables described in the PCP
       ENVIRONMENT section below, there are several environment variables
       that influence the interactions between a PCP monitoring client, pmcd
       and pmcd(1).

              For the PCP monitoring client this (or the default port
              number) is passed to pmproxy and used to connect to pmcd(1).
              In the environment of pmproxy PMCD_PORT is not used.

              For the PCP monitoring client this is the hostname or IP
              address of the host where pmproxy is running.  In recent
              versions of PCP (since version 3) this has been superseded by
              the extended hostname syntax (see PCPIntro(1) for details).

              For the PCP monitoring client this is the port on which
              pmproxy will accept connections.  The default is 44322.

              (see PCPIntro(1)) For the PCP monitoring client, setting these
              environment variables will modify the timeouts used for
              interactions between the client and pmproxy (independent of
              which pmcd(1) is being used).  For pmproxy these same
              environment variables control the timeouts between pmproxy and
              all pmcd(1) instances (independent of which monitoring client
              is involved).

       If set to the value 1, the PMPROXY_LOCAL environment variable will
       cause pmproxy to run in a localhost-only mode of operation, where it
       binds only to the loopback interface.

       The PMPROXY_MAXPENDING variable can be set to indicate the maximum
       length to which the queue of pending client connections may grow.


       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).

SEE ALSO         top

       PCPIntro(1), pmcd(1), pmdbg(1), pmlogger(1), redis-server(1),
       pcp.conf(5) and pcp.env(5).

DIAGNOSTICS         top

       If pmproxy is already running the message "Error: OpenRequestSocket
       bind: Address already in use" will appear.  This may also appear if
       pmproxy was shutdown with an outstanding request from a client.  In
       this case, a request socket has been left in the TIME_WAIT state and
       until the system closes it down (after some timeout period) it will
       not be possible to run pmproxy.

       In addition to the standard PCP debugging options, see pmdbg(1),
       pmproxy currently supports the debugging option context for tracing
       client connections and disconnections.

COLOPHON         top

       This page is part of the PCP (Performance Co-Pilot) project.
       Information about the project can be found at ⟨⟩.
       If you have a bug report for this manual page, send it to  This page was obtained from the project's upstream
       Git repository ⟨⟩ on
       2019-07-28.  (At that time, the date of the most recent commit that
       was found in the repository was 2019-07-26.)  If you discover any
       rendering problems in this HTML version of the page, or you believe
       there is a better or more up-to-date source for the page, or you have
       corrections or improvements to the information in this COLOPHON
       (which is not part of the original manual page), send a mail to

Performance Co-Pilot                 PCP                          PMPROXY(1)

Pages that refer to this page: pcpintro(1)pcp-kube-pods(1)pmfind(1)pmseries(1)pmdiscoverservices(3)pmnewcontext(3)pmparsehostattrsspec(3)pmparsehostspec(3)pmwebapi(3)