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] [-v]
12 [-?]
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 -v Increase the verbosity of pmwebd as it logs to its standard out‐
138 put/error.
139 -? Show pmwebd invocation help and exit.
141
143 pmwebd is suitable for direct exposure to trusted networks only, due to
144 several security limitations. Most or all of these limitations may be
145 worked around by use of a web application firewall (for example, an
146 Apache HTTP proxy), which would add the constraints and capabilities
147 absent within pmwebd. Such configuration is beyond the scope of this
148 document.
149 encryption/confidentiality
151 pmwebd does not currently support HTTPS (SSL/TLS), so the HTTP
152 traffic is not protected against network-level attacks.
153 authentication
155 The PMAPI layer does not possess a mandatory authentication
156 mechanism, so any remote connection can access any metric ex‐
157 posed by suchly connected PMAPI contexts. However, a new host-
158 context string may use authentication clauses of the longer host
159 URLs, for example pcps://hostname?method=plain&us‐
160 er=userid&pass=password. Use of resulting pmwebapi contexts
161 later requires matching HTTP PLAIN authentication; see below.
162 inbound admission control
164 pmwebd does not impose access control on the origin or rate of
165 its incoming requests. It may be possible for some clients to
166 starve others.
167 outbound admission control
169 pmwebd does not impose access control on outbound connections
170 when a new PMAPI context is created for a PMCD. (Without the -P
171 option, connections to UNIX-domain / local PMCDs are blocked.)
172 This enables hypothetical use of a pmwebd instance to be used as
173 a network proxy/scanner. For an archive type context, the files
174 must be located under the pmwebd current directory, or another
175 directory specified by -A. One may entirely disable remotely
176 specified PMAPI context creation using the -N option; in this
177 case, specify a static set of contexts using the -h, -a, and/or
178 -L options. You may assign them arbitrary context numbers with
179 the -c option.
180 context ownership
182 Authenticated PCP contexts are protected by requiring the same
183 HTTP PLAIN/simple userid/password credentials for related /pmapi
184 requests. However, unauthenticated contexts for different web
185 clients are kept distinct only by the assignment of large pseu‐
186 dorandom identifiers. It may be possible to find these by
187 brute-force search or other techniques, thereby letting a web
188 client impersonate another. For more privacy of the permanent
189 contexts, use the -c option to reset their starting web context
190 identifiers to a number much different from 1. On the other
191 hand, context ownership is not that precious, since there exist
192 no state-destructive operations for them, except perhaps metric
193 store or instance profile settings.
194
196 The pmwebd server may be started automatically at boot time and stopped
197 when the system is being brought down. Users may also run customized
198 pmwebd instances (under separate -p PORT numbers), for example for
199 their own archive farms. For management fo the system pmwebd, become
200 superuser and type
201 # $PCP_RC_DIR/pmwebd start
203 to start pmwebd, or
205 # $PCP_RC_DIR/pmwebd stop
207 to stop pmwebd. Starting pmwebd when it is already running is the same
209 as stopping it and then starting it again.
210
212 $PCP_PMWEBDOPTIONS_PATH
213 command line options and environment variable settings for
214 pmwebd when launched from $PCP_RC_DIR/pmwebd This file is inter‐
215 preted as a Bourne Shell script, expecting variable settings of
216 the form "OPTIONS=value" and possibly others.
217 $PCP_LOG_DIR/pmwebd/pmwebd.log
218 Log file for system pmwebd service.
219 $PCP_LOG_DIR
220 Default directory for -A option: a base directory containing PCP
221 archives.
222 $PCP_SHARE_DIR/webapps
223 Default directory for -R option: a base directory containing web
224 applications.
225
227 Environment variables with the prefix PCP_ are used to parameterize the
228 file and directory names used by PCP. On each installation, the file
229 /etc/pcp.conf contains the local values for these variables. The
230 $PCP_CONF variable may be used to specify an alternative configuration
231 file, as described in pcp.conf(5).
232
234 PCPIntro(1), PMAPI(3), PMWEBAPI(3), pmSpecLocalPMDA(3), pcp.conf(5),
235 pcp.env(5) http://graphite.readthedocs.org/ and pmns(5).
236Performance Co-Pilot PCP PMWEBD(1)