1PMPROXY(1) General Commands Manual PMPROXY(1)
2
6 pmproxy - proxy for performance metrics collector and querying
7
9 pmproxy [-AdfFt?] [-c conffile] [-h host[,host ...] [-i ipaddress]
10 [-l logfile] [-L bytes] [-p port[,port ...] [-r port[,port ...] [-s
11 sockname] [-U username] [-x outfile]
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 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 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 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
43 The available command line options are:
44 -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 -c conffile, --config=conffile
51 Specify the path to an optional configuration conffile, with for‐
52 mat as described in the ``CONFIGURATION'' section. This option
53 implies pmproxy is running in timeseries mode.
54 -d, --deprecated
56 By default pmproxy prefers to run in the new timeseries mode, pro‐
57 viding REST APIs, asynchronous network I/O, scalable time series,
58 and secure connections using OpenSSL. However, legacy deployments
59 may wish to use the original synchronous pmproxy implementation
60 using libpcp networking; this can be achieved using this option.
61 Note that the -d and -t options are mutually exclusive.
62 -f, --foreground
64 By default pmproxy is started as a daemon. The -f option indi‐
65 cates that it should run in the foreground. This is most useful
66 when trying to diagnose problems with establishing connections.
67 -F, --systemd
69 Like -f, the -F option runs pmproxy in the foreground, but also
70 does some housekeeping (like create a ``pid'' file and change user
71 id). This is intended for use when pmproxy is launched from sys‐
72 temd(1) and the daemonizing has already been done by systemd(1)
73 and does not need to be done again by pmproxy, which is the case
74 when neither -f nor -F is specified.
75 At most one of -f and -F may be specified.
77 -h host, --redishost=host
79 Specify an alternate Redis host to connect to for time series
80 querying, overriding any configuration file settings. This option
81 implies pmproxy is running in timeseries mode.
82 -i ipaddress, --interface=ipaddress
84 This option is usually only used on hosts with more than one net‐
85 work interface (very common for firewall and ``head'' node hosts
86 where pmproxy is likely to be deployed to arbitrate access to an
87 internal network). If no -i options are specified pmproxy accepts
88 PCP client connections on any of its host's IP addresses. The -i
89 option is used to specify explicitly an IP address that PCP client
90 connections should be accepted on. ipaddress should be in the
91 standard dotted form (e.g. 100.23.45.6). The -i option may be
92 used multiple times to define a list of IP addresses. When one or
93 more -i options is specified, attempted connections made on any
94 other IP addresses will be refused.
95 -l logfile, --log=logfile
97 By default a log file named pmproxy.log is written in the current
98 directory. The -l option causes the log file to be written to a
99 given logfile instead of the default. If this logfile cannot be
100 created or is not writable, output is written to the standard er‐
101 ror instead.
102 -L bytes
104 PDUs received by pmproxy from PCP monitoring clients are re‐
105 stricted to a maximum size of 65536 bytes by default to defend
106 against Denial of Service attacks. The -L option may be used to
107 change the maximum incoming PDU size.
108 -p port, --port=port
110 Specify an alternate port number to listen on for client connec‐
111 tions. The default value is 44322.
112 -r port, --redisport=port
114 Specify an alternate Redis port number to connect to for time se‐
115 ries querying, overriding any configuration file settings. This
116 option implies pmproxy is running in timeseries mode.
117 -s sockname, --socket=sockname
119 Specify the path to a local unix domain socket (for platforms sup‐
120 porting this socket family only). The default value is
121 $PCP_RUN_DIR/pmproxy.socket. This option implies pmproxy is run‐
122 ning in timeseries mode.
123 -t, --timeseries
125 Operate in automatic archive timeseries discovery mode. This mode
126 of operation will enable the PMWEBAPI(3) REST APIs, dynamiclly and
127 automatically detect active system archives being written by pm‐
128 logger(1) and import them into a redis-server(1), for fast, scal‐
129 able time series querying described in pmseries(1). Note that in
130 this mode of operation, pmproxy only "log-tails" and ingests ac‐
131 tively growing archives, e.g. as written by one or more pmlog‐
132 ger(1) instances. When an archive is first discovered (usually
133 but not limited to pmproxy startup), all metadata is loaded and
134 sent to the configured redis-server(1) however note that only new
135 archive metric value data from the tail end of each archive is in‐
136 gested. Compressed archives never grow and so are ignored. See
137 the --load option to pmseries(1) for a supported mechanism for
138 manually loading all of the metric value data from previously col‐
139 lected (inactive) archives, whether compressed or not. It would
140 be normal, though not mandated, for a set of archives being manu‐
141 ally loaded to cover the same time period, e.g. archive data for a
142 particular week for one or more hosts in the same data-centre.
143 -U username, --username=username
145 Assume the identity of the given username before starting to ac‐
146 cept incoming packets from PCP monitoring clients.
147 -x outfile
149 Before the pmproxy logfile can be opened, pmproxy may encounter a
150 fatal error which prevents it from starting. By default the out‐
151 put describing this error is sent to /dev/tty but it may redi‐
152 rected to outfile.
153 -?, --help
155 Display usage message and exit.
156
158 When running in the timeseries mode of operation, runtime configuration
159 is relatively complex and typically handled via the
160 $PCP_SYSCONF_DIR/pmproxy/pmproxy.conf file. This file is in the common
161 ``ini'' format, with section headers and individual variables and val‐
162 ues with each section. The configuration file installed as part of PCP
163 documents every available section and option.
164 At a high level, the [pmproxy] section can be used to explicitly enable
166 or disable each of the different protocols.
167 The [redis] section allows connection information for one or more back‐
169 ing redis-server processes to be configured (hostnames and ports).
170 Note to access multiple (scalable) Redis servers, the servers variable
171 in this section can be a comma-separated list of hostname:port pairs.
172 Alternatively, it can be a single redis-server host that will be
173 queried using the "CLUSTER INFO" command to automatically configure
174 multiple backing hosts, described at https://redis.io/topics/cluster-
175 spec.
176 In earlier versions of PCP (before 6) an alternative configuration set‐
178 ting section was used for this purpose - Redis servers were specified
179 in the [pmseries] section and this is still accepted as a fallback for
180 backwards compatibility.
181
183 Normally, pmproxy is started automatically at boot time and stopped
184 when the system is being brought down. Under certain circumstances it
185 is necessary to start or stop pmproxy manually. To do this one must
186 become superuser and type
187 # $PCP_RC_DIR/pmproxy start
189 to start pmproxy, or
191 # $PCP_RC_DIR/pmproxy stop
193 to stop pmproxy. Starting pmproxy when it is already running is the
195 same as stopping it and then starting it again.
196 Normally pmproxy listens for PCP client connections on TCP/IP port num‐
198 ber 44322 (as well as 44323 with timeseries enabled) registered at
199 https://www.iana.org/. Either the environment variable PMPROXY_PORT or
200 the -p command line option may be used to specify alternative port num‐
201 ber(s) when pmproxy is started; in each case, the specification is a
202 comma-separated list of one or more numerical port numbers. Should
203 both methods be used or multiple -p options appear on the command line,
204 pmproxy will listen on the union of the set of ports specified via all
205 -p options and the PMPROXY_PORT environment variable. If non-default
206 ports are used with pmproxy care should be taken to ensure that PM‐
207 PROXY_PORT is also set in the environment of any client application
208 that will connect to pmproxy, or that the extended host specification
209 syntax is used (see PCPIntro(1) for details).
210
212 If pmproxy is already running the message "Error: OpenRequestSocket
213 bind: Address already in use" will appear. This may also appear if pm‐
214 proxy was shutdown with an outstanding request from a client. In this
215 case, a request socket has been left in the TIME_WAIT state and until
216 the system closes it down (after some timeout period) it will not be
217 possible to run pmproxy.
218 In addition to the standard PCP debugging options, see pmdbg(1), pm‐
220 proxy currently supports the debugging option context for tracing
221 client connections and disconnections.
222
224 $PCP_PMPROXYOPTIONS_PATH
225 command line options for pmproxy when launched from
226 $PCP_RC_DIR/pmproxy All the command line option lines should start
227 with a hyphen as the first character.
228 $PCP_SYSCONFIG_DIR/pmproxy
230 Environment variables that will be set when pmproxy executes.
231 Only settings of the form "PMPROXY_VARIABLE=value" will be hon‐
232 oured.
233 ./pmproxy.log
235 (or $PCP_LOG_DIR/pmproxy/pmproxy.log when started automatically)
236 All messages and diagnostics are directed here
237 /etc/pki/tls
239 default OpenSSL certificate database directory, optionally used
240 for Secure Socket Layer connection in timeseries mode of opera‐
241 tion. These certificates can be created and queried using the
242 openssl tool, amongst others.
243
245 In addition to the PCP environment variables described in the PCP ENVI‐
246 RONMENT section below, there are several environment variables that in‐
247 fluence the interactions between a PCP monitoring client, pmproxy and
248 pmcd.
249 PMCD_PORT
251 For the PCP monitoring client this (or the default port number)
252 is passed to pmproxy and used to connect to pmcd. In the envi‐
253 ronment of pmproxy PMCD_PORT is not used.
254 PMPROXY_HOST
256 For the PCP monitoring client this is the hostname or IP address
257 of the host where pmproxy is running. In recent versions of PCP
258 (since version 3) this has been superseded by the extended host‐
259 name syntax (see PCPIntro(1) for details).
260 PMPROXY_PORT
262 For the PCP monitoring client this is the port on which pmproxy
263 will accept connections. The default is 44322, as well as 44323
264 with timeseries enabled.
265 PMCD_CONNECT_TIMEOUT, PMCD_RECONNECT_TIMEOUT and PMCD_REQUEST_TIMEOUT
267 (see PCPIntro(1)) For the PCP monitoring client, setting these
268 environment variables will modify the timeouts used for interac‐
269 tions between the client and pmproxy (independent of which pmcd
270 is being used). For pmproxy these same environment variables
271 control the timeouts between pmproxy and all pmcd(1) instances
272 (independent of which monitoring client is involved).
273 If set to the value 1, the PMPROXY_LOCAL environment variable will
275 cause pmproxy to run in a localhost-only mode of operation, where it
276 binds only to the loopback interface.
277 The PMPROXY_MAXPENDING variable can be set to indicate the maximum
279 length to which the queue of pending client connections may grow.
280
282 Environment variables with the prefix PCP_ are used to parameterize the
283 file and directory names used by PCP. On each installation, the file
284 /etc/pcp.conf contains the local values for these variables. The
285 $PCP_CONF variable may be used to specify an alternative configuration
286 file, as described in pcp.conf(5).
287 For environment variables affecting PCP tools, see pmGetOptions(3).
289
291 PCPIntro(1), pmcd(1), pmdbg(1), pmlogger(1), pmseries(1), redis-
292 server(1), PMAPI(3), PMWEBAPI(3), pmGetOptions(3), pcp.conf(5) and
293 pcp.env(5).
294Performance Co-Pilot PCP PMPROXY(1)