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