1PMPROXY(1) General Commands Manual PMPROXY(1)
2
6 pmproxy - proxy for performance metrics collector and querying
7
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
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 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 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 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
43 The options to pmproxy are as follows:
44 -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 -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 -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 -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 -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 -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 -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 -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 -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 -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 -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 -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 -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 -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 -U user, --username=user
147 Assume the identity of the given user before starting to accept
148 incoming packets from PCP monitoring clients.
149 -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
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 At a high level, the [pmproxy] section can be used to explicitly enable
165 or disable each of the different protocols.
166 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
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 # $PCP_RC_DIR/pmproxy start
183 to start pmproxy, or
185 # $PCP_RC_DIR/pmproxy stop
187 to stop pmproxy. Starting pmproxy when it is already running is the
189 same as stopping it and then starting it again.
190 Normally pmproxy listens for PCP client connections on TCP/IP port num‐
192 ber 44322 (as well as 44323 with timeseries enabled) registered at
193 ⟨https://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
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 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
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
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 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 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 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 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 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 The PMPROXY_MAXPENDING variable can be set to indicate the maximum
277 length to which the queue of pending client connections may grow.
278
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 For environment variables affecting PCP tools, see pmGetOptions(3).
287
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).
292Performance Co-Pilot PCP PMPROXY(1)