3 A.1 Linux Installation (rpm, deb)
4 .2 Mac OS X Installation
6 .4 Solaris Installation
7 .5 Windows Installation
8 B. Building from source
10 D. Non-default build, install and run
12 This document describes how to configure and build the open source PCP
13 ("pcp") package from source, and how to install and finally run it.
15 == A.1 Linux Installation
17 If you are using Debian, or a Debian-based distribution like Ubuntu,
18 PCP is included in the distribution (as of late 2008). Run:
20 If you are using a RPM based distribution and have the binary rpm:
22 ... and skip to the final section (below) - "Post-install steps".
24 Special note for Ubuntu 8.04, 8.10, 9.04, 9.10 and 10.04
26 I've had to make the changes below to /usr/bin/dpkg-buildpackage.
27 Without these two changes, my pcp builds produce bad binaries with a
28 bizarre array of failure modes!
30 #kenj# my $default_flags = defined $build_opts->{noopt} ? "-g -O0" : "-g
32 my $default_flags = defined $build_opts->{noopt} ? "-g -O0" : "-g -O0";
33 my %flags = ( CPPFLAGS => '',
34 CFLAGS => $default_flags,
35 CXXFLAGS => $default_flags,
36 FFLAGS => $default_flags,
37 #kenj# LDFLAGS => '-Wl,-Bsymbolic-functions',
41 Without these changes, we see QA failures for 039, 061, 072, 091, 135,
42 147 and 151 ... and the QA 166 goes into a loop until it fills up the
47 == A.2 Mac OS X Installation
49 Installing PCP from the DMG file is as simple as clicking on the icon
50 in a Finder window, and following the prompts from the installer.
52 == A.3 AIX Installation
54 At this stage, noone is making available pre-built AIX packages.
55 A port to AIX has been done, and merged, however - building from
56 the source is currently the only option. The packaging work is also
57 begun on this platform (see the build/aix/ directory in the sources).
59 == A.4 Solaris Installation
61 Prebuild Solaris packages are available from PCP download section.
63 At this stage the package are distributed as SVR4 package datastream
64 and are build on Open Solaris 5.11.
66 You can install the package using 'pkgadd' command, e.g.:
70 During the installation the following three services are registered
71 with the Solaris' service management facility:
73 # svccfg list \*/pcp/\*
75 application/pcp/pmlogger
77 application/pcp/pmproxy
79 On the new installation all services are disabled, during the upgrade
80 from the previous version of PCP the state of the services is
83 Use of 'svcadm' command to enable or disable is preferred over explicit
84 invocation of the pmcd start script.
86 Use 'svcs' command to check the state of the services, e.g.:
88 # svcs -l application/pcp/pcp
89 fmri svc:/application/pcp/pcp:default
90 name Performance Co-Pilot Collector Daemon
94 state_time 20 March 2012 11:33:27 AM EST
95 restarter svc:/system/svc/restarter:default
96 dependency require_all/none svc:/system/filesystem/local:default (online) svc:/milestone/network:default (online)
98 == A.5 Windows Installation
100 Download the native Windows version of PCP from bintray.com/pcp
101 which provides a .msi - the system-wide %PATH setting must be
102 manually setup to point to the installation location (C:\Glider
105 == B. Building from source
109 The PCP code base is targeted for many different operating
110 systems and many different combinations of related packages,
111 so a little planning is needed before launching into a build
114 Package dependencies come in several flavours:
116 (a) hard build dependencies - without these PCP cannot be
117 build from source, and the build will fail in various
118 ways at the compilation or packaging stages, e.g. gmake,
119 autoconf, flex, bison, ...;
121 (b) optional build dependences - if these components are not
122 installed the build will work, but the resultant packages
123 may be missing some features or entire applications, e.g.
124 extended authentication, secure connections, service
125 discovery, pmwebd, ...;
127 (c) QA dependencies - you can ignore these unless you want to
128 run the (extensive) PCP QA suite.
130 It is strongly recommended that you run the script:
132 and review the output before commencing a build.
134 1. Configure, build and install the package
136 The pcp package uses autoconf/configure and expects a GNU build
137 environment (your platform must at least have gmake).
139 If you just want to build a .RPM, .DEB, .DMG, .MSI[*] and/or tar
140 file, use the "Makepkgs" script in the top level directory.
141 This will configure and build the package for your platform and
142 leave binary and src packages in the build/<pkg-type> directory.
143 It will also leave binary and source tar file in the build/tar
146 $ ./Makepkgs --verbose
147 $ ./Makepkgs --verbose --target mingw64
149 [*] Windows builds require https://fedoraproject.org/wiki/MinGW
150 cross-compilation. Currently packaging is no longer performed,
151 although previously MSI builds were possible. Work on tackling
152 this short-coming would be most welcome.
154 2. If you want to build the package and install it manually you will
155 first need to ensure the "user" pcp is created so that key parts
156 of the PCP installation can run as a user other than root.
157 For Debian this means the following (equivalent commands are
158 available on all distributions):
162 # useradd -c "Performance Co-Pilot" -g pcp -d /var/lib/pcp -M -r -s /usr/sbin/nologin pcp
164 Then use the following steps (use configure options to suit your
165 preferences, refer to the qa/admin/myconfigure script for some
166 guidance and see also section D below for additional details):
168 $ ./configure --prefix=/usr --libexecdir=/usr/lib --sysconfdir=/etc \
169 --localstatedir=/var --with-rcdir=/etc/init.d
174 Note 0: PCP services run as non-root by default. Create unprivileged
175 users "pcp" with home directory /var/lib/pcp, and "pcpqa" with home
176 directory such as /var/lib/pcp/testsuite, or as appropriate, or
177 designate other userids in the pcp.conf file.
179 Note 1: that there are so many "install" variants out there that we
180 wrote our own script (see "install-sh" in the top level directory),
181 which works on every platform supported by PCP.
183 Note 2: the Windows build is particularly involved to setup, this
184 is primarily due to build tools not being available by default on
185 that platform. See the PCP Glider scripts and notes in the pcpweb
186 tree to configure your environment before attempting to build from
189 == C. Post-install steps
191 You will need to start the PCP Collection Daemon (PMCD), as root:
194 # service pmcd start (or...)
195 # /etc/init.d/pmcd start (or...)
196 # /etc/rc.d/init.d/pmcd start
198 # /Library/StartupItems/pcp/pmcd start
200 $PCP_DIR/etc/pmcd start
202 # svcadm enable application/pcp/pmcd
204 Once you have started the PMCD daemon, you can list all performance
205 metrics using the pminfo(1) command, E.g.
207 # pminfo -fmdt (you don't have to be root for this, but you may need to
208 type rehash so your shell finds the pminfo command).
210 If you are writing scripts, you may find the output from pmprobe(1)
211 easier to parse than that for pminfo(1). There are numerous other
212 PCP client tools included.
214 PCP can be configured to automatically log certain performance metrics
215 for one or more hosts. The scripts to do this are documented in
216 pmlogger_check(1). By default this facility is not enabled. If you want
217 to use it, you need to
219 # determine which metrics to log and how often you need them
220 # edit $PCP_SYSCONF_DIR/pmlogger/control
221 # edit $PCP_SYSCONF_DIR/pmlogger/config.default
222 # (and any others in same dir)
223 # as root, "crontab -e" and add something like:
225 # -- typical PCP log management crontab entries
226 # daily processing of pmlogger archives and pmie logs
227 10 0 * * * $PCP_BINADM_DIR/pmlogger_daily
228 15 0 * * * $PCP_BINADM_DIR/pmie_daily
230 # every 30 minutes, check pmlogger and pmie instances are running
231 25,40 * * * * $PCP_BINADM_DIR/pmlogger_check
232 5,55 * * * * $PCP_BINADM_DIR/pmie_check
234 The pmie (Performance Metrics Inference Engine) daemon is _not_
235 configured to start by default. To enable it, you may want to (on
236 Linux platforms with chkconfig).
240 # edit the pmie control file (usually below $PCP_SYSCONF_DIR/pmie)
241 # edit the config file (usually $PCP_SYSCONF_DIR/pmie/config.default)
242 # set up cron scripts similar to those for pmlogger (see above)
245 Configure some optional Performance Metrics Domain Agents (PMDAs)
247 The default installation gives you the metrics for cpu, per-process,
248 file system, swap, network, disk, memory, interrupts, nfs/rpc and
249 others. These metrics are handled using the platform PMDA - namely
250 pmda_linux.so (Linux), pmda_darwin.dylib (Mac), or pmda_windows.dll
251 (Windows). It also gives you the PMCD PMDA, which contains metrics
252 that monitor PCP itself.
254 There are many other optional PMDAs that you can configure, depending
255 on which performance metrics you need to monitor, as follows:
256 Note: $PCP_PMDAS_DIR is normally /var/pcp/pmdas, see pcp.conf(5).
261 # cd $PCP_PMDAS_DIR/apache (i.e. cd /var/pcp/pmdas/apache)
263 # Check everything is working OK
264 # pminfo -fmdt apache
266 Other PMDAs in the pcp package include:
268 apache - monitor apache web server stats
269 cisco - monitor Cisco router stats
270 dbping - query any database, extract response times
271 elasticsearch - monitor an elasticsearch cluster
272 kvm - monitor kernel-based virtual machine stats
273 mailq - monitor the mail queue
274 memcache - monitor memcache server stats
275 mmv - export memory-mapped value stats from an application
276 mounts - keep track of mounted file systems
277 mysql - monitor MySQL relational databases
278 postgres - monitor PostGreSQL relational databases
279 process - keep an eye on critical processes/daemons
280 roomtemp - monitor room temp (needs suitable probe)
281 rsyslog - monitor the reliable system log daemon
282 sendmail - monitor sendmail statistics
283 shping - ping critical system services, extract response times
284 trace - for instrumenting arbitrary applications, see pmtrace(1)
285 txmon - transaction and QOS monitoring
288 simple - example src code if you want to write a new PMDA
289 trivial - even easier src code for a new PMDA.
291 The procedure for configuring all of these is to change to the
292 directory for the PMDA (usually below /var/lib/pcp/pmdas), and then
293 run the ./Install script found therein. None of these PMDAs are
294 configured by default - you choose the PMDAs you need and run the
295 Install script. Installation can be automated (defaults chosen) by
296 touching .NeedInstall in the appropriate pmdas directory and then
297 restarting the pmcd service via its startup script.
299 == D. Non-default build, install and run
301 To run build and run a version of PCP that is installed in a private
302 location (and does not require root privileges), first create the
303 pcp "user" as described in section B.2 above), then
305 $ ./configure --prefix=/some/path
307 This will populate /some/path with a full PCP installation. To use this
308 ensure the following are set in the environment:
310 $ export PCP_DIR=/some/path
312 Amend your shell's $PATH to include the PCP directories, found as
316 $ xtra=`grep '^PCP_BIN' etc/pcp.conf | sed -e 's/.*=//' | paste -s -d :`
319 Ensure the new libraries can be found:
321 $ export LD_LIBRARY_PATH=`grep '^PCP_LIB' etc/pcp.conf \
322 | sed -e 's/.*=//' | uniq | paste -s -d :`
324 Tell Perl where to find loadable modules:
326 $ export PERL5LIB=$PCP_DIR/usr/lib/perl5:$PCP_DIR/usr/share/perl5
328 Allow man(1) to find the PCP manual pages:
330 $ export MANPATH=`manpath`:$PCP_DIR/usr/share/man
332 If your version is co-exiting with a running PCP in a default
333 install, then alternative port numbers in your environment for pmcd
334 ($PMCD_PORT), pmlogger ($PMLOGGER_PORT) and pmproxy ($PMPROXY_PORT)