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, detect system
154 archives created by pmlogger(1) and import them into a redis-
155 server(1) automatically, for fast, scalable time series querying
156 described in pmseries(1).
157 -U username, --username=username
159 Assume the identity of the given username before starting to ac‐
160 cept incoming packets from PCP monitoring clients.
161 -x outfile
163 Before the pmproxy logfile can be opened, pmproxy may encounter a
164 fatal error which prevents it from starting. By default the out‐
165 put describing this error is sent to /dev/tty but it may redi‐
166 rected to outfile.
167 -?, --help
169 Display usage message and exit.
170
172 When running in the timeseries mode of operation, runtime configuration
173 is relatively complex and typically handled via the
174 $PCP_SYSCONF_DIR/pmproxy/pmproxy.conf file. This file is in the common
175 ``ini'' format, with section headers and individual variables and val‐
176 ues with each section. The configuration file installed as part of PCP
177 documents every available section and option.
178 At a high level, the [pmproxy] section can be used to explicitly enable
180 or disable each of the different protocols.
181 The [pmseries] section allows connection information for one or more
183 backing redis-server processes to be configured (hostnames and ports).
184 Note to access multiple (scalable) Redis servers, the servers variable
185 in this section can be a comma-separated list of hostname:port pairs.
186 Alternatively, it can be a single redis-server host that will be
187 queried using the "CLUSTER INFO" command to automatically configure
188 multiple backing hosts, described at https://redis.io/topics/cluster-
189 spec.
190
192 Normally, pmproxy is started automatically at boot time and stopped
193 when the system is being brought down. Under certain circumstances it
194 is necessary to start or stop pmproxy manually. To do this one must
195 become superuser and type
196 # $PCP_RC_DIR/pmproxy start
198 to start pmproxy, or
200 # $PCP_RC_DIR/pmproxy stop
202 to stop pmproxy. Starting pmproxy when it is already running is the
204 same as stopping it and then starting it again.
205 Normally pmproxy listens for PCP client connections on TCP/IP port num‐
207 ber 44322 (as well as 44323 with timeseries enabled) registered at
208 https://www.iana.org/. Either the environment variable PMPROXY_PORT or
209 the -p command line option may be used to specify alternative port num‐
210 ber(s) when pmproxy is started; in each case, the specification is a
211 comma-separated list of one or more numerical port numbers. Should
212 both methods be used or multiple -p options appear on the command line,
213 pmproxy will listen on the union of the set of ports specified via all
214 -p options and the PMPROXY_PORT environment variable. If non-default
215 ports are used with pmproxy care should be taken to ensure that PM‐
216 PROXY_PORT is also set in the environment of any client application
217 that will connect to pmproxy, or that the extended host specification
218 syntax is used (see PCPIntro(1) for details).
219
221 If pmproxy is already running the message "Error: OpenRequestSocket
222 bind: Address already in use" will appear. This may also appear if pm‐
223 proxy was shutdown with an outstanding request from a client. In this
224 case, a request socket has been left in the TIME_WAIT state and until
225 the system closes it down (after some timeout period) it will not be
226 possible to run pmproxy.
227 In addition to the standard PCP debugging options, see pmdbg(1), pm‐
229 proxy currently supports the debugging option context for tracing
230 client connections and disconnections.
231
233 PCP_PMPROXYOPTIONS_PATH
234 command line options for pmproxy when launched from
235 $PCP_RC_DIR/pmproxy All the command line option lines should start
236 with a hyphen as the first character.
237 $PCP_SYSCONFIG_DIR/pmproxy
239 Environment variables that will be set when pmproxy executes.
240 Only settings of the form "PMPROXY_VARIABLE=value" will be hon‐
241 oured.
242 ./pmproxy.log
244 (or $PCP_LOG_DIR/pmproxy/pmproxy.log when started automatically)
245 All messages and diagnostics are directed here
246 /etc/pki/tls
248 default OpenSSL certificate database directory, used for optional
249 Secure Socket Layer connections in timeseries mode of operation.
250 These certificates can be created and queried using the openssl
251 tool, amongst others.
252 /etc/pki/nssdb
254 default Network Sercity Services (NSS) database directory, used
255 for optional Secure Socket Layer connections in deprecated mode of
256 operation. This database can be created and queried using the NSS
257 certutil tool, amongst others. This is only used when pmproxy is
258 running in deprecated mode.
259
261 In addition to the PCP environment variables described in the PCP ENVI‐
262 RONMENT section below, there are several environment variables that in‐
263 fluence the interactions between a PCP monitoring client, pmproxy and
264 pmcd.
265 PMCD_PORT
267 For the PCP monitoring client this (or the default port number)
268 is passed to pmproxy and used to connect to pmcd. In the envi‐
269 ronment of pmproxy PMCD_PORT is not used.
270 PMPROXY_HOST
272 For the PCP monitoring client this is the hostname or IP address
273 of the host where pmproxy is running. In recent versions of PCP
274 (since version 3) this has been superseded by the extended host‐
275 name syntax (see PCPIntro(1) for details).
276 PMPROXY_PORT
278 For the PCP monitoring client this is the port on which pmproxy
279 will accept connections. The default is 44322, as well as 44323
280 with timeseries enabled.
281 PMCD_CONNECT_TIMEOUT, PMCD_RECONNECT_TIMEOUT and PMCD_REQUEST_TIMEOUT
283 (see PCPIntro(1)) For the PCP monitoring client, setting these
284 environment variables will modify the timeouts used for interac‐
285 tions between the client and pmproxy (independent of which pmcd
286 is being used). For pmproxy these same environment variables
287 control the timeouts between pmproxy and all pmcd(1) instances
288 (independent of which monitoring client is involved).
289 If set to the value 1, the PMPROXY_LOCAL environment variable will
291 cause pmproxy to run in a localhost-only mode of operation, where it
292 binds only to the loopback interface.
293 The PMPROXY_MAXPENDING variable can be set to indicate the maximum
295 length to which the queue of pending client connections may grow.
296
298 Environment variables with the prefix PCP_ are used to parameterize the
299 file and directory names used by PCP. On each installation, the file
300 /etc/pcp.conf contains the local values for these variables. The
301 $PCP_CONF variable may be used to specify an alternative configuration
302 file, as described in pcp.conf(5).
303 For environment variables affecting PCP tools, see pmGetOptions(3).
305
307 PCPIntro(1), pmcd(1), pmdbg(1), pmlogger(1), pmseries(1), redis-
308 server(1), PMAPI(3), PMWEBAPI(3), pmGetOptions(3), pcp.conf(5) and
309 pcp.env(5).
310Performance Co-Pilot PCP PMPROXY(1)