1PMPROXY(1) General Commands Manual PMPROXY(1)
2
6 pmproxy - proxy for performance metrics collector and querying
7
9 pmproxy [-AdfFt?] [-c conffile] [-C certdb] [-h host[,host ...] [-i
10 ipaddress] [-l logfile] [-L bytes] [-M certname] [-p port[,port ...]
11 [-P passfile] [-r port[,port ...] [-s sockname] [-U username] [-x out‐
12 file]
13
15 pmproxy acts as a protocol proxy, allowing Performance Co-Pilot (PCP)
16 monitoring clients to connect to one or more pmcd(1) and/or redis-
17 server(1) instances via pmproxy.
18 In its default mode of operation, on platforms supporting this, pmproxy
20 provides the REST API for all PCP services (see PMWEBAPI(3) for de‐
21 tails) and interfaces to the fast, scalable time series query capabili‐
22 ties offered by PCP in conjunction with a redis-server(1) (see pm‐
23 series(1) for details).
24 pmproxy can be deployed in a firewall domain, or on a cluster ``head''
26 node where the IP (Internet Protocol) address of the hosts where pmcd
27 and/or redis-server are running may be unknown to the PCP monitoring
28 clients, but where the IP address of the host running pmproxy is known
29 to these clients. Similarly, the clients may have network connectivity
30 only to the host where pmproxy is running, while there is network con‐
31 nectivity from that host to the hosts of interest where pmcd and/or re‐
32 dis-server are running.
33 The behaviour of the PCP monitoring clients is controlled by either the
35 PMPROXY_HOST environment variable or through the extended hostname
36 specification (see PCPIntro(1) for details). If neither of these mech‐
37 anisms is used, clients will make their PMAPI(3) connections directly
38 to pmcd. If the proxy hostname syntax is used or PMPROXY_HOST is set,
39 then this should be the hostname or IP address of the system where pm‐
40 proxy is running, and the clients will connect to pmcd or redis-server
41 indirectly through the protocol proxy services of pmproxy.
42
44 The available command line options are:
45 -A Disable service advertisement. By default, pmproxy will advertise
47 its presence on the network using any available mechanisms (such
48 as Avahi/DNS-SD), assisting remote monitoring tools with finding
49 it. These mechanisms are disabled with this option.
50 -c conffile, --config=conffile
52 Specify the path to an optional configuration conffile, with for‐
53 mat as described in the ``CONFIGURATION'' section. This option
54 implies pmproxy is running in timeseries mode.
55 -C certdb, --certdb=certdb
57 Specify the path to the Network Security Services certificate
58 database, for (optional) secure connections. This option implies
59 pmproxy is running in deprecated mode. The default is
60 /etc/pki/nssdb. Refer also to the -P option. If it does not al‐
61 ready exist, this database can be created using the certutil(1)
62 utility. This process and other certificate database maintenance
63 information is provided in the PCPIntro(1) manual page and the on‐
64 line PCP tutorials.
65 -d, --deprecated
67 By default pmproxy prefers to run in the new timeseries mode, pro‐
68 viding REST APIs, asynchronous network I/O, scalable time series,
69 and secure connections using OpenSSL. However, legacy deployments
70 may wish to use the original synchronous pmproxy implementation
71 using NSS and libpcp networking; this can be achieved using this
72 option. Note that the -d and -t options are mutually exclusive.
73 -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 -F, --systemd
80 Like -f, the -F option runs pmproxy in the foreground, but also
81 does some housekeeping (like create a ``pid'' file and change user
82 id). This is intended for use when pmproxy is launched from sys‐
83 temd(1) and the daemonizing has already been done by systemd(1)
84 and does not need to be done again by pmproxy, which is the case
85 when neither -f nor -F is specified.
86 At most one of -f and -F may be specified.
88 -h host, --redishost=host
90 Specify an alternate Redis host to connect to for time series
91 querying, overriding any configuration file settings. This option
92 implies pmproxy is running in timeseries mode.
93 -i ipaddress, --interface=ipaddress
95 This option is usually only used on hosts with more than one net‐
96 work interface (very common for firewall and ``head'' node hosts
97 where pmproxy is likely to be deployed to arbitrate access to an
98 internal network). If no -i options are specified pmproxy accepts
99 PCP client connections on any of its host's IP addresses. The -i
100 option is used to specify explicitly an IP address that PCP client
101 connections should be accepted on. ipaddress should be in the
102 standard dotted form (e.g. 100.23.45.6). The -i option may be
103 used multiple times to define a list of IP addresses. When one or
104 more -i options is specified, attempted connections made on any
105 other IP addresses will be refused.
106 -l logfile, --log=logfile
108 By default a log file named pmproxy.log is written in the current
109 directory. The -l option causes the log file to be written to a
110 given logfile instead of the default. If this logfile cannot be
111 created or is not writable, output is written to the standard er‐
112 ror instead.
113 -L bytes
115 PDUs received by pmproxy from PCP monitoring clients are re‐
116 stricted to a maximum size of 65536 bytes by default to defend
117 against Denial of Service attacks. The -L option may be used to
118 change the maximum incoming PDU size.
119 -M certname, --certname=certname
121 By default pmproxy will try to use a certificate called PCP Col‐
122 lector certificate in its server role. The -M option allows this
123 certificate certname to be changed. This option implies pmproxy
124 is running in deprecated mode.
125 -p port, --port=port
127 Specify an alternate port number to listen on for client connec‐
128 tions. The default value is 44322.
129 -P passfile, --passfile=passfile
131 Specify the path to a passfile containing the Network Security
132 Services certificate database password for (optional) secure con‐
133 nections, and for databases that are password protected. This op‐
134 tion implies pmproxy is running in deprecated mode. Refer also to
135 the -C option. When using this option, great care should be exer‐
136 cised to ensure appropriate ownership ("pcp" user, typically) and
137 permissions on this file (0400, so as to be unreadable by any user
138 other than the user running the pmproxy process).
139 -r port, --redisport=port
141 Specify an alternate Redis port number to connect to for time se‐
142 ries querying, overriding any configuration file settings. This
143 option implies pmproxy is running in timeseries mode.
144 -s sockname, --socket=sockname
146 Specify the path to a local unix domain socket (for platforms sup‐
147 porting this socket family only). The default value is
148 $PCP_RUN_DIR/pmproxy.socket. This option implies pmproxy is run‐
149 ning in timeseries mode.
150 -t, --timeseries
152 Operate in automatic archive timeseries discovery mode. This mode
153 of operation will enable the PMWEBAPI(3) REST APIs, dynamiclly and
154 automatically detect active system archives being written by pm‐
155 logger(1) and import them into a redis-server(1), for fast, scal‐
156 able time series querying described in pmseries(1). Note that in
157 this mode of operation, pmproxy only "log-tails" and ingests ac‐
158 tively growing archives, e.g. as written by one or more pmlog‐
159 ger(1) instances. When an archive is first discovered (usually
160 but not limited to pmproxy startup), all metadata is loaded and
161 sent to the configured redis-server(1) however note that only new
162 archive metric value data from the tail end of each archive is in‐
163 gested. Compressed archives never grow and so are ignored. See
164 the --load option to pmseries(1) for a supported mechanism for
165 manually loading all of the metric value data from previously col‐
166 lected (inactive) archives, whether compressed or not. It would
167 be normal, though not mandated, for a set of archives being manu‐
168 ally loaded to cover the same time period, e.g. archive data for a
169 particular week for one or more hosts in the same data-centre.
170 -U username, --username=username
172 Assume the identity of the given username before starting to ac‐
173 cept incoming packets from PCP monitoring clients.
174 -x outfile
176 Before the pmproxy logfile can be opened, pmproxy may encounter a
177 fatal error which prevents it from starting. By default the out‐
178 put describing this error is sent to /dev/tty but it may redi‐
179 rected to outfile.
180 -?, --help
182 Display usage message and exit.
183
185 When running in the timeseries mode of operation, runtime configuration
186 is relatively complex and typically handled via the
187 $PCP_SYSCONF_DIR/pmproxy/pmproxy.conf file. This file is in the common
188 ``ini'' format, with section headers and individual variables and val‐
189 ues with each section. The configuration file installed as part of PCP
190 documents every available section and option.
191 At a high level, the [pmproxy] section can be used to explicitly enable
193 or disable each of the different protocols.
194 The [redis] section allows connection information for one or more back‐
196 ing redis-server processes to be configured (hostnames and ports).
197 Note to access multiple (scalable) Redis servers, the servers variable
198 in this section can be a comma-separated list of hostname:port pairs.
199 Alternatively, it can be a single redis-server host that will be
200 queried using the "CLUSTER INFO" command to automatically configure
201 multiple backing hosts, described at https://redis.io/topics/cluster-
202 spec.
203 In earlier versions of PCP (before 6) an alternative configuration set‐
205 ting section was used for this purpose - Redis servers were specified
206 in the [pmseries] section and this is still accepted as a fallback for
207 backwards compatibility.
208
210 Normally, pmproxy is started automatically at boot time and stopped
211 when the system is being brought down. Under certain circumstances it
212 is necessary to start or stop pmproxy manually. To do this one must
213 become superuser and type
214 # $PCP_RC_DIR/pmproxy start
216 to start pmproxy, or
218 # $PCP_RC_DIR/pmproxy stop
220 to stop pmproxy. Starting pmproxy when it is already running is the
222 same as stopping it and then starting it again.
223 Normally pmproxy listens for PCP client connections on TCP/IP port num‐
225 ber 44322 (as well as 44323 with timeseries enabled) registered at
226 https://www.iana.org/. Either the environment variable PMPROXY_PORT or
227 the -p command line option may be used to specify alternative port num‐
228 ber(s) when pmproxy is started; in each case, the specification is a
229 comma-separated list of one or more numerical port numbers. Should
230 both methods be used or multiple -p options appear on the command line,
231 pmproxy will listen on the union of the set of ports specified via all
232 -p options and the PMPROXY_PORT environment variable. If non-default
233 ports are used with pmproxy care should be taken to ensure that PM‐
234 PROXY_PORT is also set in the environment of any client application
235 that will connect to pmproxy, or that the extended host specification
236 syntax is used (see PCPIntro(1) for details).
237
239 If pmproxy is already running the message "Error: OpenRequestSocket
240 bind: Address already in use" will appear. This may also appear if pm‐
241 proxy was shutdown with an outstanding request from a client. In this
242 case, a request socket has been left in the TIME_WAIT state and until
243 the system closes it down (after some timeout period) it will not be
244 possible to run pmproxy.
245 In addition to the standard PCP debugging options, see pmdbg(1), pm‐
247 proxy currently supports the debugging option context for tracing
248 client connections and disconnections.
249
251 PCP_PMPROXYOPTIONS_PATH
252 command line options for pmproxy when launched from
253 $PCP_RC_DIR/pmproxy All the command line option lines should start
254 with a hyphen as the first character.
255 $PCP_SYSCONFIG_DIR/pmproxy
257 Environment variables that will be set when pmproxy executes.
258 Only settings of the form "PMPROXY_VARIABLE=value" will be hon‐
259 oured.
260 ./pmproxy.log
262 (or $PCP_LOG_DIR/pmproxy/pmproxy.log when started automatically)
263 All messages and diagnostics are directed here
264 /etc/pki/tls
266 default OpenSSL certificate database directory, used for optional
267 Secure Socket Layer connections in timeseries mode of operation.
268 These certificates can be created and queried using the openssl
269 tool, amongst others.
270 /etc/pki/nssdb
272 default Network Sercity Services (NSS) database directory, used
273 for optional Secure Socket Layer connections in deprecated mode of
274 operation. This database can be created and queried using the NSS
275 certutil tool, amongst others. This is only used when pmproxy is
276 running in deprecated mode.
277
279 In addition to the PCP environment variables described in the PCP ENVI‐
280 RONMENT section below, there are several environment variables that in‐
281 fluence the interactions between a PCP monitoring client, pmproxy and
282 pmcd.
283 PMCD_PORT
285 For the PCP monitoring client this (or the default port number)
286 is passed to pmproxy and used to connect to pmcd. In the envi‐
287 ronment of pmproxy PMCD_PORT is not used.
288 PMPROXY_HOST
290 For the PCP monitoring client this is the hostname or IP address
291 of the host where pmproxy is running. In recent versions of PCP
292 (since version 3) this has been superseded by the extended host‐
293 name syntax (see PCPIntro(1) for details).
294 PMPROXY_PORT
296 For the PCP monitoring client this is the port on which pmproxy
297 will accept connections. The default is 44322, as well as 44323
298 with timeseries enabled.
299 PMCD_CONNECT_TIMEOUT, PMCD_RECONNECT_TIMEOUT and PMCD_REQUEST_TIMEOUT
301 (see PCPIntro(1)) For the PCP monitoring client, setting these
302 environment variables will modify the timeouts used for interac‐
303 tions between the client and pmproxy (independent of which pmcd
304 is being used). For pmproxy these same environment variables
305 control the timeouts between pmproxy and all pmcd(1) instances
306 (independent of which monitoring client is involved).
307 If set to the value 1, the PMPROXY_LOCAL environment variable will
309 cause pmproxy to run in a localhost-only mode of operation, where it
310 binds only to the loopback interface.
311 The PMPROXY_MAXPENDING variable can be set to indicate the maximum
313 length to which the queue of pending client connections may grow.
314
316 Environment variables with the prefix PCP_ are used to parameterize the
317 file and directory names used by PCP. On each installation, the file
318 /etc/pcp.conf contains the local values for these variables. The
319 $PCP_CONF variable may be used to specify an alternative configuration
320 file, as described in pcp.conf(5).
321 For environment variables affecting PCP tools, see pmGetOptions(3).
323
325 PCPIntro(1), pmcd(1), pmdbg(1), pmlogger(1), pmseries(1), redis-
326 server(1), PMAPI(3), PMWEBAPI(3), pmGetOptions(3), pcp.conf(5) and
327 pcp.env(5).
328Performance Co-Pilot PCP PMPROXY(1)