1PMPROXY(1)                  General Commands Manual                 PMPROXY(1)
2
3
4

NAME

6       pmproxy - proxy for performance metrics collector and querying
7

SYNOPSIS

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

DESCRIPTION

14       pmproxy  acts  as a protocol proxy, allowing Performance Co-Pilot (PCP)
15       monitoring clients to connect to one  or  more  pmcd(1)  and/or  redis-
16       server(1) instances via pmproxy.
17
18       In its default mode of operation, on platforms supporting this, pmproxy
19       provides the REST  API  for  all  PCP  services  (see  PMWEBAPI(3)  for
20       details)  and  interfaces to the fast, scalable time series query capa‐
21       bilities offered by PCP in  conjunction  with  a  redis-server(1)  (see
22       pmseries(1) for details).
23
24       pmproxy  can be deployed in a firewall domain, or on a cluster ``head''
25       node where the IP (Internet Protocol) address of the hosts  where  pmcd
26       and/or  redis-server  are  running may be unknown to the PCP monitoring
27       clients, but where the IP address of the host running pmproxy is  known
28       to these clients.  Similarly, the clients may have network connectivity
29       only to the host where pmproxy is running, while there is network  con‐
30       nectivity  from  that  host  to the hosts of interest where pmcd and/or
31       redis-server are running.
32
33       The behaviour of the PCP monitoring clients is controlled by either the
34       PMPROXY_HOST  environment  variable  or  through  the extended hostname
35       specification (see PCPIntro(1) for details).  If neither of these mech‐
36       anisms  is  used, clients will make their PMAPI(3) connections directly
37       to pmcd.  If the proxy hostname syntax is used or PMPROXY_HOST is  set,
38       then  this  should  be  the  hostname or IP address of the system where
39       pmproxy is running, and the clients will  connect  to  pmcd  or  redis-
40       server indirectly through the protocol proxy services of pmproxy.
41

OPTIONS

43       The options to pmproxy are as follows:
44
45       -A     Disable  service advertisement.  By default, pmproxy will adver‐
46              tise its presence on the network using any available  mechanisms
47              (such  as  Avahi/DNS-SD), assisting remote monitoring tools with
48              finding it.  These mechanisms are disabled with this option.
49
50       -c file, --config=file
51              Specify the path to an optional configuration file, with  format
52              as  described  in  the  ``CONFIGURATION''  section.  This option
53              implies pmproxy is running in timeseries mode.
54
55       -C dirname, --certpath=dirname
56              Specify the path to the Network  Security  Services  certificate
57              database,   for  (optional)  secure  connections.   This  option
58              implies pmproxy is running in deprecated mode.  The  default  is
59              /etc/pki/nssdb.   Refer  also  to the -P option.  If it does not
60              already exist, this database can be created using  the  certutil
61              utility.   This  process  and other certificate database mainte‐
62              nance information is provided in the PCPIntro(1) manual page and
63              the online PCP tutorials.
64
65       -d, --deprecated
66              By  default  pmproxy  prefers to run in the new timeseries mode,
67              providing REST APIs, asynchronous  network  I/O,  scalable  time
68              series,  and  secure connections using OpenSSL.  However, legacy
69              deployments may wish to use  the  original  synchronous  pmproxy
70              implementation  using  NSS  and  libpcp  networking; this can be
71              achieved using this option.  Note that the -d and -t options are
72              mutually exclusive.
73
74       -f, --foreground
75              By  default pmproxy is started as a daemon.  The -f option indi‐
76              cates that it should run in the foreground.  This is most useful
77              when trying to diagnose problems with establishing connections.
78
79       -h host, --redishost=host
80              Specify  an  alternate  Redis host to connect to for time series
81              querying, overriding  any  configuration  file  settings.   This
82              option implies pmproxy is running in timeseries mode.
83
84       -i ipaddress
85              This  option  is  usually  only used on hosts with more than one
86              network interface (very common for firewall  and  ``head''  node
87              hosts where pmproxy is likely to be deployed to arbitrate access
88              to an internal network).  If no -i options are specified pmproxy
89              accepts   PCP  client  connections  on  any  of  its  host's  IP
90              addresses.  The -i option is used to specify  explicitly  an  IP
91              address  that  PCP  client  connections  should  be accepted on.
92              ipaddress  should  be  in  the  standard   dotted   form   (e.g.
93              100.23.45.6).   The  -i  option  may  be  used multiple times to
94              define a list of IP addresses.  When one or more -i  options  is
95              specified,  attempted connections made on any other IP addresses
96              will be refused.
97
98       -l file, --log=file
99              By default a log file named pmproxy.log is written in  the  cur‐
100              rent directory.  The -l option causes the log file to be written
101              to a given file instead of the default.  If this file cannot  be
102              created  or  is  not writable, output is written to the standard
103              error instead.
104
105       -L bytes
106              PDUs  received  by  pmproxy  from  PCP  monitoring  clients  are
107              restricted to a maximum size of 65536 bytes by default to defend
108              against Denial of Service attacks.  The -L option may be used to
109              change the maximum incoming PDU size.
110
111       -M name, --certname=name
112              By default pmproxy will try to use a certificate called PCP Col‐
113              lector certificate in its server role.   The  -M  option  allows
114              this certficate name to be changed.  This option implies pmproxy
115              is running in deprecated mode.
116
117       -p port, --redisport=port
118              Specify an alternate Redis port number to connect  to  for  time
119              series  querying,  overriding  any  configuration file settings.
120              This option implies pmproxy is running in timeseries mode.
121
122       -P file, --passfile=file
123              Specify the path to a file containing the Network Security  Ser‐
124              vices  certificate  database password for (optional) secure con‐
125              nections, and for databases that are password  protected.   This
126              option  implies  pmproxy  is  running in deprecated mode.  Refer
127              also to the -C option.   When  using  this  option,  great  care
128              should be exercised to ensure appropriate ownership ("pcp" user,
129              typically) and permissions on this  file  (0400,  so  as  to  be
130              unreadable  by  any user other than the user running the pmproxy
131              process).
132
133       -s sockname, --socket=sockname
134              Specify the path to a local unix domain  socket  (for  platforms
135              supporting  this  socket  family  only).   The  default value is
136              $PCP_RUN_DIR/pmproxy.socket.  This  option  implies  pmproxy  is
137              running in timeseries mode.
138
139       -t, --timeseries
140              Operate  in  automatic  archive timeseries discovery mode.  This
141              mode of operation will enable the PMWEBAPI(3) REST APIs,  detect
142              system  archives  created  by pmlogger(1) and import them into a
143              redis-server(1) automatically, for fast,  scalable  time  series
144              querying described in pmseries(1).
145
146       -U user, --username=user
147              Assume  the identity of the given user before starting to accept
148              incoming packets from PCP monitoring clients.
149
150       -x file
151              Before the pmproxy logfile can be opened, pmproxy may  encounter
152              a  fatal  error which prevents it from starting.  By default the
153              output describing this error is sent  to  /dev/tty  but  it  may
154              redirected to file.
155

CONFIGURATION

157       When running in the timeseries mode of operation, runtime configuration
158       is   relatively    complex    and    typically    handled    via    the
159       $PCP_SYSCONF_DIR/pmproxy/pmproxy.conf file.  This file is in the common
160       ``ini'' format, with section headers and individual variables and  val‐
161       ues with each section.  The configuration file installed as part of PCP
162       documents every available section and option.
163
164       At a high level, the [pmproxy] section can be used to explicitly enable
165       or disable each of the different protocols.
166
167       The  [pmseries]  section  allows connection information for one or more
168       backing redis-server processes to be configured (hostnames and  ports).
169       Note  to access multiple (scalable) Redis servers, the servers variable
170       in this section can be a comma-separated list of  hostname:port  pairs.
171       Alternatively,  it  can  be  a  single  redis-server  host that will be
172       queried using the "CLUSTER INFO"  command  to  automatically  configure
173       multiple  backing hosts, described at ⟨https://redis.io/topics/cluster-
174       spec⟩.
175

STARTING AND STOPPING PMPROXY

177       Normally, pmproxy is started automatically at  boot  time  and  stopped
178       when  the system is being brought down.  Under certain circumstances it
179       is necessary to start or stop pmproxy manually.  To do  this  one  must
180       become superuser and type
181
182       # $PCP_RC_DIR/pmproxy start
183
184       to start pmproxy, or
185
186       # $PCP_RC_DIR/pmproxy stop
187
188       to  stop  pmproxy.   Starting pmproxy when it is already running is the
189       same as stopping it and then starting it again.
190
191       Normally pmproxy listens for PCP client connections on TCP/IP port num‐
192       ber  44322  (as  well  as  44323 with timeseries enabled) registered at
193https://www.iana.org/⟩.  Either the environment variable  PMPROXY_PORT
194       -p  command  line  option  may be used to specify alternative port num‐
195       ber(s) when PMPROXY_PORT or the -p command line option may be  used  to
196       specify  alternative  port  number(s)  when pmproxy is started; in each
197       case, the specification is a comma-separated list of one or more numer‐
198       ical  port numbers.  Should both methods be used or multiple -p options
199       appear on the command line, pmproxy will listen on the union of the set
200       of  ports specified via all -p options and the PMPROXY_PORT environment
201       variable.  If non-default ports are used with pmproxy  care  should  be
202       taken to ensure that PMPROXY_PORT is also set in the environment of any
203       client application that will connect to pmproxy, or that  the  extended
204       host specification syntax is used (see PCPIntro(1) for details).
205

DIAGNOSTICS

207       If  pmproxy  is  already  running the message "Error: OpenRequestSocket
208       bind: Address already in use" will appear.  This  may  also  appear  if
209       pmproxy  was  shutdown  with  an outstanding request from a client.  In
210       this case, a request socket has been left in the  TIME_WAIT  state  and
211       until the system closes it down (after some timeout period) it will not
212       be possible to run pmproxy.
213
214       In addition to  the  standard  PCP  debugging  options,  see  pmdbg(1),
215       pmproxy  currently  supports  the  debugging option context for tracing
216       client connections and disconnections.
217

FILES

219       PCP_PMPROXYOPTIONS_PATH
220              command  line   options   for   pmproxy   when   launched   from
221              $PCP_RC_DIR/pmproxy  All  the  command  line option lines should
222              start with a hyphen as the first character.
223       $PCP_SYSCONFIG_DIR/pmproxy
224              additional environment variables that will be set  when  pmproxy
225              executes.   Only  settings  of the form "PMPROXY_VARIABLE=value"
226              will be honoured.
227       ./pmproxy.log
228              (or $PCP_LOG_DIR/pmproxy/pmproxy.log when started automatically)
229              All messages and diagnostics are directed here
230       /etc/pki/tls
231              default  OpenSSL  certificate  database  directory,   used   for
232              optional  Secure  Socket Layer connections in timeseries mode of
233              operation.  These certificates can be created and queried  using
234              the openssl tool, amongst others.
235       /etc/pki/nssdb
236              default  Network Sercity Services (NSS) database directory, used
237              for optional Secure Socket Layer connections in deprecated  mode
238              of  operation.   This  database can be created and queried using
239              the NSS certutil tool, amongst others.  This is only  used  when
240              pmproxy is running in deprecated mode.
241

ENVIRONMENT

243       In addition to the PCP environment variables described in the PCP ENVI‐
244       RONMENT section below, there are  several  environment  variables  that
245       influence the interactions between a PCP monitoring client, pmproxy and
246       pmcd.
247
248       PMCD_PORT
249              For the PCP monitoring client this (or the default port  number)
250              is  passed to pmproxy and used to connect to pmcd.  In the envi‐
251              ronment of pmproxy PMCD_PORT is not used.
252
253       PMPROXY_HOST
254              For the PCP monitoring client this is the hostname or IP address
255              of the host where pmproxy is running.  In recent versions of PCP
256              (since version 3) this has been superseded by the extended host‐
257              name syntax (see PCPIntro(1) for details).
258
259       PMPROXY_PORT
260              For  the PCP monitoring client this is the port on which pmproxy
261              will accept connections.  The default is 44322, as well as 44323
262              with timeseries enabled.
263
264       PMCD_CONNECT_TIMEOUT, PMCD_RECONNECT_TIMEOUT and PMCD_REQUEST_TIMEOUT
265              (see  PCPIntro(1))  For the PCP monitoring client, setting these
266              environment variables will modify the timeouts used for interac‐
267              tions  between the client and pmproxy (independent of which pmcd
268              is being used).  For pmproxy these  same  environment  variables
269              control  the  timeouts between pmproxy and all pmcd(1) instances
270              (independent of which monitoring client is involved).
271
272       If set to the value 1,  the  PMPROXY_LOCAL  environment  variable  will
273       cause  pmproxy  to  run in a localhost-only mode of operation, where it
274       binds only to the loopback interface.
275
276       The PMPROXY_MAXPENDING variable can be  set  to  indicate  the  maximum
277       length to which the queue of pending client connections may grow.
278

PCP ENVIRONMENT

280       Environment variables with the prefix PCP_ are used to parameterize the
281       file and directory names used by PCP.  On each installation,  the  file
282       /etc/pcp.conf  contains  the  local  values  for  these variables.  The
283       $PCP_CONF variable may be used to specify an alternative  configuration
284       file, as described in pcp.conf(5).
285
286       For environment variables affecting PCP tools, see pmGetOptions(3).
287

SEE ALSO

289       PCPIntro(1),   pmcd(1),   pmdbg(1),  pmlogger(1),  pmseries(1),  redis-
290       server(1),  PMAPI(3),  PMWEBAPI(3),  pmGetOptions(3),  pcp.conf(5)  and
291       pcp.env(5).
292
293
294
295Performance Co-Pilot                  PCP                           PMPROXY(1)
Impressum