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  de‐
20       tails) and interfaces to the fast, scalable time series query capabili‐
21       ties offered by PCP in conjunction  with  a  redis-server(1)  (see  pm‐
22       series(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 re‐
31       dis-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 pm‐
39       proxy is running, and the clients will connect to pmcd or  redis-server
40       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 al‐
60            ready exist, this database can be created using the certutil util‐
61            ity.   This process and other certificate database maintenance in‐
62            formation is provided in the PCPIntro(1) manual page and  the  on‐
63            line 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  in‐
111            stead.
112
113       -L bytes
114            PDUs  received  by  pmproxy  from  PCP  monitoring clients are re‐
115            stricted 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 se‐
141            ries 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
167       -?, --help
168            Display usage message and exit.
169

CONFIGURATION

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

STARTING AND STOPPING PMPROXY

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

DIAGNOSTICS

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

FILES

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

ENVIRONMENT

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

PCP ENVIRONMENT

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

SEE ALSO

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