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

NAME

6       pmproxy - proxy for performance metrics collector and querying
7

SYNOPSIS

9       pmproxy  [-AFft?]  [-C dirname] [-h host[,host ...]  [-i ipaddress] [-l
10       logfile] [-L bytes] [-M certname] [-p port[,port  ...]   [-P  passfile]
11       [-r port[,port ...]  [-U username] [-x 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 available command line options are:
44
45       -A   Disable service advertisement.  By default, pmproxy will advertise
46            its presence on the network using any available  mechanisms  (such
47            as  Avahi/DNS-SD),  assisting remote monitoring tools with finding
48            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 as
52            described  in  the ``CONFIGURATION'' section.  This option implies
53            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 implies
58            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 maintenance
62            information is provided in the PCPIntro(1)  manual  page  and  the
63            online PCP tutorials.
64
65       -d, --deprecated
66            By default pmproxy prefers to run in the new timeseries mode, pro‐
67            viding REST APIs, asynchronous network I/O, scalable time  series,
68            and secure connections using OpenSSL.  However, legacy deployments
69            may wish to use the original  synchronous  pmproxy  implementation
70            using  NSS  and libpcp networking; this can be achieved using this
71            option.  Note that the -d and -t options are mutually exclusive.
72
73       -f, --foreground
74            By default pmproxy is started as a daemon.  The  -f  option  indi‐
75            cates  that  it should run in the foreground.  This is most useful
76            when trying to diagnose problems with establishing connections.
77
78       -F, --systemd
79            Like -f, the -F option runs pmproxy in the  foreground,  but  also
80            does some housekeeping (like create a ``pid'' file and change user
81            id).  This is intended for use when pmproxy is launched from  sys‐
82            temd(1)  and  the  daemonizing has already been done by systemd(1)
83            and does not need to be done again by pmproxy, which is  the  case
84            when neither -f nor -F is specified.
85
86            At most one of -f and -F may be specified.
87
88       -h host, --redishost=host
89            Specify  an  alternate  Redis  host  to connect to for time series
90            querying, overriding any configuration file settings.  This option
91            implies pmproxy is running in timeseries mode.
92
93       -i ipaddress
94            This  option is usually only used on hosts with more than one net‐
95            work interface (very common for firewall and ``head''  node  hosts
96            where  pmproxy  is likely to be deployed to arbitrate access to an
97            internal network).  If no -i options are specified pmproxy accepts
98            PCP  client connections on any of its host's IP addresses.  The -i
99            option is used to specify explicitly an IP address that PCP client
100            connections  should  be  accepted  on.  ipaddress should be in the
101            standard dotted form (e.g. 100.23.45.6).  The  -i  option  may  be
102            used multiple times to define a list of IP addresses.  When one or
103            more -i options is specified, attempted connections  made  on  any
104            other IP addresses will be refused.
105
106       -l file, --log=file
107            By  default a log file named pmproxy.log is written in the current
108            directory.  The -l option causes the log file to be written  to  a
109            given file instead of the default.  If this file cannot be created
110            or is not writable,  output  is  written  to  the  standard  error
111            instead.
112
113       -L bytes
114            PDUs   received   by  pmproxy  from  PCP  monitoring  clients  are
115            restricted to a maximum size of 65536 bytes by default  to  defend
116            against  Denial  of Service attacks.  The -L option may be used to
117            change the maximum incoming PDU size.
118
119       -M name, --certname=name
120            By default pmproxy will try to use a certificate called  PCP  Col‐
121            lector  certificate in its server role.  The -M option allows this
122            certificate name to be changed.  This option  implies  pmproxy  is
123            running in deprecated mode.
124
125       -p port, --port=port
126            Specify  an  alternate port number to listen on for client connec‐
127            tions.  The default value is 44322.
128
129       -P file, --passfile=file
130            Specify the path to a file containing the  Network  Security  Ser‐
131            vices  certificate database password for (optional) secure connec‐
132            tions, and for databases that are password protected.  This option
133            implies  pmproxy is running in deprecated mode.  Refer also to the
134            -C option.  When using this option, great care should be exercised
135            to  ensure  appropriate ownership ("pcp" user, typically) and per‐
136            missions on this file (0400, so as to be unreadable  by  any  user
137            other than the user running the pmproxy process).
138
139       -r port, --redisport=port
140            Specify  an  alternate  Redis  port  number to connect to for time
141            series querying, overriding any configuration file settings.  This
142            option implies pmproxy is running in timeseries mode.
143
144       -s sockname, --socket=sockname
145            Specify the path to a local unix domain socket (for platforms sup‐
146            porting  this  socket  family  only).   The   default   value   is
147            $PCP_RUN_DIR/pmproxy.socket.   This option implies pmproxy is run‐
148            ning in timeseries mode.
149
150       -t, --timeseries
151            Operate in automatic archive timeseries discovery mode.  This mode
152            of  operation will enable the PMWEBAPI(3) REST APIs, detect system
153            archives created by pmlogger(1) and  import  them  into  a  redis-
154            server(1)  automatically,  for fast, scalable time series querying
155            described in pmseries(1).
156
157       -U user, --username=user
158            Assume the identity of the given user before  starting  to  accept
159            incoming packets from PCP monitoring clients.
160
161       -x file
162            Before  the pmproxy logfile can be opened, pmproxy may encounter a
163            fatal error which prevents it from starting.  By default the  out‐
164            put  describing  this  error  is sent to /dev/tty but it may redi‐
165            rected to file.
166

CONFIGURATION

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

STARTING AND STOPPING PMPROXY

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

DIAGNOSTICS

217       If  pmproxy  is  already  running the message "Error: OpenRequestSocket
218       bind: Address already in use" will appear.  This  may  also  appear  if
219       pmproxy  was  shutdown  with  an outstanding request from a client.  In
220       this case, a request socket has been left in the  TIME_WAIT  state  and
221       until the system closes it down (after some timeout period) it will not
222       be possible to run pmproxy.
223
224       In addition to  the  standard  PCP  debugging  options,  see  pmdbg(1),
225       pmproxy  currently  supports  the  debugging option context for tracing
226       client connections and disconnections.
227

FILES

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

ENVIRONMENT

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

PCP ENVIRONMENT

294       Environment variables with the prefix PCP_ are used to parameterize the
295       file and directory names used by PCP.  On each installation,  the  file
296       /etc/pcp.conf  contains  the  local  values  for  these variables.  The
297       $PCP_CONF variable may be used to specify an alternative  configuration
298       file, as described in pcp.conf(5).
299
300       For environment variables affecting PCP tools, see pmGetOptions(3).
301

SEE ALSO

303       PCPIntro(1),   pmcd(1),   pmdbg(1),  pmlogger(1),  pmseries(1),  redis-
304       server(1),  PMAPI(3),  PMWEBAPI(3),  pmGetOptions(3),  pcp.conf(5)  and
305       pcp.env(5).
306
307
308
309Performance Co-Pilot                  PCP                           PMPROXY(1)
Impressum