|
NAME | SYNOPSIS | DESCRIPTION | STARTING AND STOPPING PMPROXY | FILES | ENVIRONMENT | PCP ENVIRONMENT | SEE ALSO | DIAGNOSTICS | COLOPHON |
PMPROXY(1) General Commands Manual PMPROXY(1)
pmproxy - proxy for performance metrics collector daemon
pmproxy [-Af] [-C dirname] [-i ipaddress] [-l logfile] [-L bytes] [-M
certname] [-p port[,port ...] [-P passfile] [-U username] [-x file]
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
connections.
-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. 100.23.45.6). 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).
-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 http://www.iana.org/ ). 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).
PCP_PMPROXYOPTIONS_PATH
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.
$PCP_SYSCONFIG_DIR/pmproxy
additional environment variables that will be set when pmproxy
executes. Only settings of the form "PMPROXY_VARIABLE=value"
will be honoured.
./pmproxy.log
(or $PCP_LOG_DIR/pmproxy/pmproxy.log when started
automatically)
All messages and diagnostics are directed here
/etc/pki/nssdb
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.
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).
PMCD_PORT
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.
PMPROXY_HOST
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).
PMPROXY_PORT
For the PCP monitoring client this is the port on which
pmproxy will accept connections. The default is 44322.
PMCD_CONNECT_TIMEOUT, PMCD_RECONNECT_TIMEOUT and PMCD_REQUEST_TIMEOUT
(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).
PCPIntro(1), pmcd(1), pmdbg(1), pcp.conf(5) and pcp.env(5).
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 flags, see pmdbg(1),
pmproxy currently uses DBG_TRACE_CONTEXT for tracing client
connections and disconnections
This page is part of the PCP (Performance Co-Pilot) project.
Information about the project can be found at ⟨http://www.pcp.io/⟩.
If you have a bug report for this manual page, send it to
pcp@oss.sgi.com. This page was obtained from the project's upstream
Git repository ⟨git://git.pcp.io/pcp⟩ on 2017-07-05. 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 man-pages@man7.org
Performance Co-Pilot PCP PMPROXY(1)
Pages that refer to this page: pcpintro(1), pmfind(1), pmdiscoverservices(3), pmnewcontext(3), pmparsehostattrsspec(3), pmparsehostspec(3)