Man Linux: Main Page and Category List

NAME

       pmproxy - proxy for performance metrics collector daemon

SYNOPSIS

       pmproxy  [-f]  [-i ipaddress] [-l logfile] [-L bytes] [-U username] [-x
       file]

DESCRIPTION

       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.

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

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

STARTING AND STOPPING PMPROXY

       Normally, pmproxy is started automatically at  boot  time  and  stopped
       when the system is being brought down (see rc2(1M) and rc0(1M)).  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.isecom.info).  The environment
       variable PMPROXY_PORT may  be  used  to  specify  an  alternative  port
       number.   If  PMPROXY_PORT  is used, care should be taken to ensure the
       environment variable is set before pmproxy is started.

FILES

       PCP_PMPROXYOPTIONS_PATH
              command line  options  and  environment  variable  settings  for
              pmproxy  when  launched  from PCP_RC_DIR/pmproxy All the command
              line option lines should  start  with  a  hyphen  as  the  first
              character.   This  file  can  also  contain environment variable
              settings of the form "VARIABLE=value".
       ./pmproxy.log
              (or PCP_LOG_DIR/pmproxy/pmproxy.log when started automatically)
              All messages and diagnostics are directed here

ENVIRONMENT

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

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

       PCPIntro(1), pmcd(1), pmdbg(1), pcp.conf(4) and pcp.env(4).

DIAGNOSTICS

       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