1PMWEBD(1) General Commands Manual PMWEBD(1)
2
6 pmwebd - web access to PCP
7
9 pmwebd [-p port] [-4] [-6] [-t timeout] [-R resdir] [-c number] [-h
10 hostname] [-a archive] [-C] [-P] [-L] [-N] [-G] [-X] [-i min-interval]
11 [-J [-K spec] [-A archivesdir] [-S] [-l logfile] [-U username] [-x
12 file] [-v] [-?]
13
15 pmwebd is a network daemon that binds a subset of the Performance Co-
16 Pilot (PCP) client API (PMAPI(3)) to RESTful web applications using the
17 HTTP (PMWEBAPI(3)) protocol. Web clients request a URI with the prefix
18 /pmapi to access the bindings. pmwebd creates PCP contexts as
19 requested by a dynamic pool of remote clients, and maintains them as
20 long as the clients regularly reconnect to request PMAPI operations.
21 Otherwise, PCP contexts are closed after a timeout. Permanent contexts
22 may be requested on the command line.
23 In addition to the API binding, pmwebd may be optionally configured as
25 a simple HTTP file server, in order to feed the web application itself
26 to a web browser. URIs not matching the /pmapi prefix are mapped to
27 files under the configured resource directory, if the -R option was
28 given.
29 In addition, pmwebd may be optionally configured as a server of a sub‐
31 set of the graphite 0.9.12 web API, for URLs with the /graphite prefix,
32 in order to expose PCP archives to interactive data-graphing web appli‐
33 cations.
34 The options to pmwebd are as follows.
36 -p port
38 Set the TCP port number on which pmwebd will listen for HTTP
39 requests. The default is 44323.
40 -4 or -6
42 Listen only on IPv4 or IPv6. By default, pmwebd will listen on
43 both protocols, if possible.
44 -A archdir
46 Limit remote access to archives to only those beneath the given
47 directory. For performance, symbolic links to other directories
48 may not be followed. By default, only files beneath the initial
49 pmwebd working directory may be accessed.
50 -R resdir
52 Activate file serving beneath the given resource directory. All
53 regular files there may be read and transcribed to remote
54 clients. By default, file serving is disabled.
55 -G Activate servicing of a subset of the graphite webapi. This
57 exposes all PCP archives under the -A directory to remote
58 clients. By default, graphite webapi serving is disabled. To
59 use the graphite and/or grafana web applications included with
60 pmwebd, use both -G and -R, and connect your web browser to
61 http://127.0.0.1:43323/
62 -X Disable encoding of common characters for metric names, which
64 allows shorter graphite metric names.
65 -i min-interval
67 Set the minimum sampling interval for graphite time series in
68 seconds. The default is 60. Smaller values give higher preci‐
69 sion (but not necessarily accuracy) data, but may cost extra
70 processing time at pmwebd or the web browser; and vice versa.
71 -J When constructing graphite metric names, use the stored hostname
73 instead of a archive pathname as the first component. This vir‐
74 tually unifies all archives found with the same hostname into a
75 single time series. The host name is canonicalized: any symbol
76 characters other than _ (underscore), space, - (hyphen), and /
77 (slash) are replaced by _ (underscore).
78 -t timeout
80 Set the maximum timeout (in seconds) after the last operation on
81 a pmapi web context, before it is closed by pmwebd. A smaller
82 timeout may be requested by the web client. The default is 300.
83 -c number
85 Reset the next PMWEBAPI permanent context identifier as given.
86 The default is 1.
87 -h hostname or -a archive or -L
89 Assign the next permanent PMWEBAPI context identifier to a PMAPI
90 connection to the given host (with an extended syntax as given
91 in PCPIntro(1)), or archive file, or the PM_CONTEXT_LOCAL.
92 -C Mandatory authentication mode, where all host specifications at
94 context creation time must be accompanied by credentials (user‐
95 name and password). These are then passed to pmcd(1) when cre‐
96 ating the context. In addition, subsequent PMAPI context opera‐
97 tions require matching HTTP Basic authentication credentials.
98 This setting is incompatible with the permissive mode of opera‐
99 tion.
100 -P Run in permissive mode, allowing Unix domain socket connections
102 and/or local PMDA contexts. By default these are not allowed
103 due to the automatic authentication that is performed on the
104 server in these modes. Only enable this option if you under‐
105 stand the risks involved, and are sure that all remote pmwebd
106 accesses will be from benevolent users. If enabled, unauthenti‐
107 cated remote PMWEBAPI(3) clients will be able to access poten‐
108 tially sensitive performance metric values which an unauthenti‐
109 cated PMAPI(3) client usually would not be able to. Refer to
110 CVE-2012-3419 for additional details.
111 -N Disable creation of new PMWEBAPI contexts via HTTP requests,
113 leaving only permanent ones accessible.
114 -K spec
116 When fetching metrics from a local context, the -K option may be
117 used to control the DSO PMDAs that should be made accessible.
118 The spec argument conforms to the syntax described in pmSpecLo‐
119 calPMDA(3). More than one -K option may be used.
120 -l logfile
122 By default, logging goes to standard output/error file handles.
123 The verbosity flag -v affects the amount of traffic. The -l op‐
124 tion causes the log file to be written to logfile instead. If
125 the log file cannot be created or is not writable, output is
126 written to the standard error instead.
127 -U username
129 If invoked as root, assume the identity of username before
130 starting to accept incoming requests from web clients.
131 -S Disable service advertisement. By default, pmwebd will adver‐
133 tise its presence on the network using any available mechanisms
134 (such as Avahi/DNS-SD), assisting remote monitoring tools with
135 finding it. These mechanisms are disabled with this option.
136 -x file
138 Before the pmwebd logfile can be opened, pmwebd may encounter a
139 fatal error which prevents it from starting. By default, the
140 output describing this error is sent to /dev/tty but it may
141 redirected to file.
142 -v Increase the verbosity of pmwebd as it logs to its standard out‐
144 put/error.
145 -? Show pmwebd invocation help and exit.
147
149 pmwebd is suitable for direct exposure to trusted networks only, due to
150 several security limitations. Most or all of these limitations may be
151 worked around by use of a web application firewall (for example, an
152 Apache HTTP proxy), which would add the constraints and capabilities
153 absent within pmwebd. Such configuration is beyond the scope of this
154 document.
155 encryption/confidentiality
157 pmwebd does not currently support HTTPS (SSL/TLS), so the HTTP
158 traffic is not protected against network-level attacks.
159 authentication
161 The PMAPI layer does not possess a mandatory authentication
162 mechanism, so any remote connection can access any metric ex‐
163 posed by suchly connected PMAPI contexts. However, a new host-
164 context string may use authentication clauses of the longer host
165 URLs, for example pcps://hostname?method=plain&us‐
166 er=userid&pass=password. Use of resulting pmwebapi contexts
167 later requires matching HTTP PLAIN authentication; see below.
168 inbound admission control
170 pmwebd does not impose access control on the origin or rate of
171 its incoming requests. It may be possible for some clients to
172 starve others.
173 outbound admission control
175 pmwebd does not impose access control on outbound connections
176 when a new PMAPI context is created for a PMCD. (Without the -P
177 option, connections to UNIX-domain / local PMCDs are blocked.)
178 This enables hypothetical use of a pmwebd instance to be used as
179 a network proxy/scanner. For an archive type context, the files
180 must be located under the pmwebd current directory, or another
181 directory specified by -A. One may entirely disable remotely
182 specified PMAPI context creation using the -N option; in this
183 case, specify a static set of contexts using the -h, -a, and/or
184 -L options. You may assign them arbitrary context numbers with
185 the -c option.
186 context ownership
188 Authenticated PCP contexts are protected by requiring the same
189 HTTP PLAIN/simple userid/password credentials for related /pmapi
190 requests. However, unauthenticated contexts for different web
191 clients are kept distinct only by the assignment of large pseu‐
192 dorandom identifiers. It may be possible to find these by
193 brute-force search or other techniques, thereby letting a web
194 client impersonate another. For more privacy of the permanent
195 contexts, use the -c option to reset their starting web context
196 identifiers to a number much different from 1. On the other
197 hand, context ownership is not that precious, since there exist
198 no state-destructive operations for them, except perhaps metric
199 store or instance profile settings.
200
202 The pmwebd server may be started automatically at boot time and stopped
203 when the system is being brought down. Users may also run customized
204 pmwebd instances (under separate -p PORT numbers), for example for
205 their own archive farms. For management fo the system pmwebd, become
206 superuser and type
207 # $PCP_RC_DIR/pmwebd start
209 to start pmwebd, or
211 # $PCP_RC_DIR/pmwebd stop
213 to stop pmwebd. Starting pmwebd when it is already running is the same
215 as stopping it and then starting it again.
216
218 $PCP_PMWEBDOPTIONS_PATH
219 command line options and environment variable settings for
220 pmwebd when launched from $PCP_RC_DIR/pmwebd This file is inter‐
221 preted as a Bourne Shell script, expecting variable settings of
222 the form "OPTIONS=value" and possibly others.
223 $PCP_LOG_DIR/pmwebd/pmwebd.log
224 Log file for system pmwebd service.
225 $PCP_LOG_DIR
226 Default directory for -A option: a base directory containing PCP
227 archives.
228 $PCP_SHARE_DIR/webapps
229 Default directory for -R option: a base directory containing web
230 applications.
231
233 Environment variables with the prefix PCP_ are used to parameterize the
234 file and directory names used by PCP. On each installation, the file
235 /etc/pcp.conf contains the local values for these variables. The
236 $PCP_CONF variable may be used to specify an alternative configuration
237 file, as described in pcp.conf(5).
238
240 PCPIntro(1), PMAPI(3), PMWEBAPI(3), pmSpecLocalPMDA(3), pcp.conf(5),
241 pcp.env(5) http://graphite.readthedocs.org/ and pmns(5).
242Performance Co-Pilot PCP PMWEBD(1)