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 the PCP download
101 section. There are two variants: .zip and .exe. The latter is
102 a self-installing executable, the former a simple compressed PCP
103 image. Run the executable, follow the prompts, and a Startup
104 Menu item with several PCP options will be available - standard
105 DOS shell or POSIX shell (with suitable environment setup), the
106 Perl CPAN configuration tool, links to documentation and online
107 PCP internet resources, and the pmchart utility.
109 == B. Building from source
113 The PCP code base is targeted for many different operating
114 systems and many different combinations of related packages,
115 so a little planning is needed before launching into a build
118 Package dependencies come in several flavours:
120 (a) hard build dependencies - without these PCP cannot be
121 build from source, and the build will fail in various
122 ways at the compilation or packaging stages, e.g. gmake,
123 autoconf, flex, bison, ...;
125 (b) optional build dependences - if these components are not
126 installed the build will work, but the resultant packages
127 may be missing some features or entire applications, e.g.
128 extended authentication, secure connections, service
129 discovery, pmwebd, ...;
131 (c) QA dependencies - you can ignore these unless you want to
132 run the (extensive) PCP QA suite.
134 It is strongly recommended that you run the script:
136 and review the output before commencing a build.
138 1. Configure, build and install the package
140 The pcp package uses autoconf/configure and expects a GNU build
141 environment (your platform must at least have gmake).
143 If you just want to spin a .RPM, .DEB, .DMG, .EXE and/or tar
144 file, use the Makepkgs script in the top level directory.
145 This will configure and build the package for your platform and
146 leave binary and src packages in the build/<pkg-type> directory.
147 It will also leave binary and source tar file in the build/tar
150 $ ./Makepkgs --verbose
152 2. If you want to build the package and install it manually you will
153 first need to ensure the "user" pcp is created so that key parts
154 of the PCP installation can run as a user other than root.
155 For Debian this means the following (equivalent commands are
156 available on all distributions):
160 # useradd -c "Performance Co-Pilot" -g pcp -d /var/lib/pcp -M -r -s /usr/sbin/nologin pcp
162 Then use the following steps (use configure options to suit your
163 preferences, refer to the qa/admin/myconfigure script for some
164 guidance and see also section D below for additional details):
166 $ ./configure --prefix=/usr --libexecdir=/usr/lib --sysconfdir=/etc \
167 --localstatedir=/var --with-rcdir=/etc/init.d
172 Note 0: PCP services run as non-root by default. Create unprivileged
173 users "pcp" with home directory /var/lib/pcp, and "pcpqa" with home
174 directory such as /var/lib/pcp/testsuite, or as appropriate, or
175 designate other userids in the pcp.conf file.
177 Note 1: that there are so many "install" variants out there that we
178 wrote our own script (see "install-sh" in the top level directory),
179 which works on every platform supported by PCP.
181 Note 2: the Windows build is particularly involved to setup, this
182 is primarily due to build tools not being available by default on
183 that platform. See the PCP Glider scripts and notes in the pcpweb
184 tree to configure your environment before attempting to build from
187 == C. Post-install steps
189 You will need to start the PCP Collection Daemon (PMCD), as root:
192 # service pmcd start (or...)
193 # /etc/init.d/pmcd start (or...)
194 # /etc/rc.d/init.d/pmcd start
196 # /Library/StartupItems/pcp/pmcd start
198 $PCP_DIR/etc/pmcd start
200 # svcadm enable application/pcp/pmcd
202 Once you have started the PMCD daemon, you can list all performance
203 metrics using the pminfo(1) command, E.g.
205 # pminfo -fmdt (you don't have to be root for this, but you may need to
206 type rehash so your shell finds the pminfo command).
208 If you are writing scripts, you may find the output from pmprobe(1)
209 easier to parse than that for pminfo(1). There are numerous other
210 PCP client tools included.
212 PCP can be configured to automatically log certain performance metrics
213 for one or more hosts. The scripts to do this are documented in
214 pmlogger_check(1). By default this facility is not enabled. If you want
215 to use it, you need to
217 # determine which metrics to log and how often you need them
218 # edit $PCP_SYSCONF_DIR/pmlogger/control
219 # edit $PCP_SYSCONF_DIR/pmlogger/config.default
220 # (and any others in same dir)
221 # as root, "crontab -e" and add something like:
223 # -- typical PCP log management crontab entries
224 # daily processing of pmlogger archives and pmie logs
225 10 0 * * * $PCP_BINADM_DIR/pmlogger_daily
226 15 0 * * * $PCP_BINADM_DIR/pmie_daily
228 # every 30 minutes, check pmlogger and pmie instances are running
229 25,40 * * * * $PCP_BINADM_DIR/pmlogger_check
230 5,55 * * * * $PCP_BINADM_DIR/pmie_check
232 The pmie (Performance Metrics Inference Engine) daemon is _not_
233 configured to start by default. To enable it, you may want to (on
234 Linux platforms with chkconfig).
238 # edit the pmie control file (usually below $PCP_SYSCONF_DIR/pmie)
239 # edit the config file (usually $PCP_SYSCONF_DIR/pmie/config.default)
240 # set up cron scripts similar to those for pmlogger (see above)
243 Configure some optional Performance Metrics Domain Agents (PMDAs)
245 The default installation gives you the metrics for cpu, per-process,
246 file system, swap, network, disk, memory, interrupts, nfs/rpc and
247 others. These metrics are handled using the platform PMDA - namely
248 pmda_linux.so (Linux), pmda_darwin.dylib (Mac), or pmda_windows.dll
249 (Windows). It also gives you the PMCD PMDA, which contains metrics
250 that monitor PCP itself.
252 There are many other optional PMDAs that you can configure, depending
253 on which performance metrics you need to monitor, as follows:
254 Note: $PCP_PMDAS_DIR is normally /var/pcp/pmdas, see pcp.conf(4).
259 # cd $PCP_PMDAS_DIR/apache (i.e. cd /var/pcp/pmdas/apache)
261 # Check everything is working OK
262 # pminfo -fmdt apache
264 Other PMDAs in the pcp package include:
266 apache - monitor apache web server stats
267 cisco - monitor Cisco router stats
268 dbping - query any database, extract response times
269 elasticsearch - monitor an elasticsearch cluster
270 kvm - monitor kernel-based virtual machine stats
271 mailq - monitor the mail queue
272 memcache - monitor memcache server stats
273 mmv - export memory-mapped value stats from an application
274 mounts - keep track of mounted file systems
275 mysql - monitor MySQL relational databases
276 postgres - monitor PostGreSQL relational databases
277 process - keep an eye on critical processes/daemons
278 roomtemp - monitor room temp (needs suitable probe)
279 rsyslog - monitor the reliable system log daemon
280 sendmail - monitor sendmail statistics
281 shping - ping critical system services, extract response times
282 trace - for instrumenting arbitrary applications, see pmtrace(1)
283 txmon - transaction and QOS monitoring
286 simple - example src code if you want to write a new PMDA
287 trivial - even easier src code for a new PMDA.
289 The procedure for configuring all of these is to change to the
290 directory for the PMDA (usually below /var/lib/pcp/pmdas), and then
291 run the ./Install script found therein. None of these PMDAs are
292 configured by default - you choose the PMDAs you need and run the
293 Install script. Installation can be automated (defaults chosen) by
294 touching .NeedInstall in the appropriate pmdas directory and then
295 restarting the pmcd service via its startup script.
297 == D. Non-default build, install and run
299 To run build and run a version of PCP that is installed in a private
300 location (and does not require root privileges), first create the
301 pcp "user" as described in section B.2 above), then
303 $ ./configure --prefix=/some/path
305 This will populate /some/path with a full PCP installation. To use this
306 ensure the following are set in the environment:
308 $ export PCP_DIR=/some/path
310 Amend your shell's $PATH to include the PCP directories, found as
314 $ xtra=`grep '^PCP_BIN' etc/pcp.conf | sed -e 's/.*=//' | paste -s -d :`
317 Ensure the new libraries can be found:
319 $ export LD_LIBRARY_PATH=`grep '^PCP_LIB' etc/pcp.conf \
320 | sed -e 's/.*=//' | uniq | paste -s -d :`
322 Tell Perl where to find loadable modules:
324 $ export PERL5LIB=$PCP_DIR/usr/lib/perl5:$PCP_DIR/usr/share/perl5
326 Allow man(1) to find the PCP manual pages:
328 $ export MANPATH=`manpath`:$PCP_DIR/usr/share/man
330 If your version is co-exiting with a running PCP in a default
331 install, then alternative port numbers in your environment for pmcd
332 ($PMCD_PORT), pmlogger ($PMLOGGER_PORT) and pmproxy ($PMPROXY_PORT)