diff options
Diffstat (limited to 'INSTALL')
| -rw-r--r-- | INSTALL | 310 |
1 files changed, 310 insertions, 0 deletions
@@ -0,0 +1,310 @@ +== INSTALL == + +A.1 Linux Installation (rpm, deb) + .2 Mac OS X Installation + .3 AIX Installation + .4 Solaris Installation + .5 Windows Installation +B. Building from source +C. Post-install steps +D. Non-default build, install and run + +This document describes how to configure and build the open source PCP +("pcp") package from source, and how to install and finally run it. + +== A.1 Linux Installation + +If you are using Debian, or a Debian-based distribution like Ubuntu, +PCP is included in the distribution (as of late 2008). Run: + # apt-get install pcp +If you are using a RPM based distribution and have the binary rpm: + # rpm -Uvh pcp-*.rpm +... and skip to the final section (below) - "Post-install steps". + +Special note for Ubuntu 8.04, 8.10, 9.04, 9.10 and 10.04 + +I've had to make the changes below to /usr/bin/dpkg-buildpackage. +Without these two changes, my pcp builds produce bad binaries with a +bizarre array of failure modes! + +#kenj# my $default_flags = defined $build_opts->{noopt} ? "-g -O0" : "-g +-O2"; +my $default_flags = defined $build_opts->{noopt} ? "-g -O0" : "-g -O0"; +my %flags = ( CPPFLAGS => '', + CFLAGS => $default_flags, + CXXFLAGS => $default_flags, + FFLAGS => $default_flags, + #kenj# LDFLAGS => '-Wl,-Bsymbolic-functions', + LDFLAGS => '', + ); + +Without these changes, we see QA failures for 039, 061, 072, 091, 135, +147 and 151 ... and the QA 166 goes into a loop until it fills up the +root filesystem. + +-- Ken + +== A.2 Mac OS X Installation + +The only unusual step in installing PCP on Mac OS X is the additional +dependency on the developer tools (XCode package). The specific need +PCP has is to have a C preprocessor available for managing the metric +namespace, which on Mac OS X is a frontend to gcc and not installed by +default. + +Once this is installed, installing PCP from the DMG file is as simple +as clicking on the icon in a Finder window, and following the prompts +from the installer. + +== A.3 AIX Installation + +At this stage, noone is making available pre-built AIX packages. +A port to AIX has been done, and merged, however - building from +the source is currently the only option. The packaging work is also +begun on this platform (see the build/aix/ directory in the sources). + +== A.4 Solaris Installation + +Prebuild Solaris packages are available from PCP download section. + +At this stage the package are distributed as SVR4 package datastream +and are build on Open Solaris 5.11. + +You can install the package using 'pkgadd' command, e.g.: + + # pkgadd -d pcp-X.Y.Z + +During the installation the following three services are registered +with the Solaris' service management facility: + + # svccfg list \*/pcp/\* + application/pcp/pmcd + application/pcp/pmlogger + application/pcp/pmie + application/pcp/pmproxy + +On the new installation all services are disabled, during the upgrade +from the previous version of PCP the state of the services is +preserved. + +Use of 'svcadm' command to enable or disable is preferred over explicit +invocation of the pmcd start script. + +Use 'svcs' command to check the state of the services, e.g.: + + # svcs -l application/pcp/pcp + fmri svc:/application/pcp/pcp:default + name Performance Co-Pilot Collector Daemon + enabled false + state disabled + next_state none + state_time 20 March 2012 11:33:27 AM EST + restarter svc:/system/svc/restarter:default + dependency require_all/none svc:/system/filesystem/local:default (online) svc:/milestone/network:default (online) + +== A.5 Windows Installation + +Download the native Windows version of PCP from the PCP download +section. There are two variants: .zip and .exe. The latter is +a self-installing executable, the former a simple compressed PCP +image. Run the executable, follow the prompts, and a Startup +Menu item with several PCP options will be available - standard +DOS shell or POSIX shell (with suitable environment setup), the +Perl CPAN configuration tool, links to documentation and online +PCP internet resources, and the pmchart utility. + +== B. Building from source + +1. Configure, build and install the package + + The pcp package uses autoconf/configure and expects a GNU build + environment (your platform must at least have gmake). + + If you just want to spin a .RPM, .DEB, .DMG, .EXE and/or tar + file, use the Makepkgs script in the top level directory. + This will configure and build the package for your platform and + leave binary and src packages in the build/<pkg-type> directory. + It will also leave binary and source tar file in the build/tar + directory. + + $ ./Makepkgs --verbose + +2. If you want to build the package and install it manually you will + first need to ensure the "user" pcp is created so that key parts + of the PCP installation can run as a user other than root. + For Debian this means the following (equivalent commands are + available on all distributions): + + $ su root + # groupadd -r pcp + # useradd -c "Performance Co-Pilot" -g pcp -d /var/lib/pcp -M -r -s /usr/sbin/nologin pcp + + Then use the following steps (use configure options to suit your + preferences, refer to the qa/admin/myconfigure script for some + guidance and see also section D below for additional details): + + $ ./configure --prefix=/usr --libexecdir=/usr/lib --sysconfdir=/etc \ + --localstatedir=/var --with-rcdir=/etc/init.d + $ make + $ su root + # make install + + Note 0: PCP services run as non-root by default. Create unprivileged + users "pcp" with home directory /var/lib/pcp, and "pcpqa" with home + directory such as /var/lib/pcp/testsuite, or as appropriate, or + designate other userids in the pcp.conf file. + Note 1: that there are so many "install" variants out there that we + wrote our own script (see "install-sh" in the top level directory), + which works on every platform supported by PCP. + Note 2: the Windows build is particularly involved to setup, this + is primarily due to build tools not being available by default on + that platform. See the PCP Glider scripts and notes in the pcpweb + tree to configure your environment before attempting to build from + source under Win32. + +== C. Post-install steps + + You will need to start the PCP Collection Daemon (PMCD), as root: + + Linux, AIX: + # service pmcd start (or...) + # /etc/init.d/pmcd start (or...) + # /etc/rc.d/init.d/pmcd start + Mac OS X: + # /Library/StartupItems/pcp/pmcd start + Windows: + $PCP_DIR/etc/pmcd start + Solaris: + # svcadm enable application/pcp/pmcd + + Once you have started the PMCD daemon, you can list all performance + metrics using the pminfo(1) command, E.g. + + # pminfo -fmdt (you don't have to be root for this, but you may need to + type rehash so your shell finds the pminfo command). + + If you are writing scripts, you may find the output from pmprobe(1) + easier to parse than that for pminfo(1). There are numerous other + PCP client tools included. + + PCP can be configured to automatically log certain performance metrics + for one or more hosts. The scripts to do this are documented in + pmlogger_check(1). By default this facility is not enabled. If you want + to use it, you need to + + # determine which metrics to log and how often you need them + # edit $PCP_SYSCONF_DIR/pmlogger/control + # edit $PCP_SYSCONF_DIR/pmlogger/config.default + # (and any others in same dir) + # as root, "crontab -e" and add something like: + + # -- typical PCP log management crontab entries + # daily processing of pmlogger archives and pmie logs + 10 0 * * * $PCP_BINADM_DIR/pmlogger_daily + 15 0 * * * $PCP_BINADM_DIR/pmie_daily + # + # every 30 minutes, check pmlogger and pmie instances are running + 25,40 * * * * $PCP_BINADM_DIR/pmlogger_check + 5,55 * * * * $PCP_BINADM_DIR/pmie_check + + The pmie (Performance Metrics Inference Engine) daemon is _not_ + configured to start by default. To enable it, you may want to (on + Linux platforms with chkconfig). + + # su root + # chkconfig pmie on + # edit the pmie control file (usually below $PCP_SYSCONF_DIR/pmie) + # edit the config file (usually $PCP_SYSCONF_DIR/pmie/config.default) + # set up cron scripts similar to those for pmlogger (see above) + + + Configure some optional Performance Metrics Domain Agents (PMDAs) + + The default installation gives you the metrics for cpu, per-process, + file system, swap, network, disk, memory, interrupts, nfs/rpc and + others. These metrics are handled using the platform PMDA - namely + pmda_linux.so (Linux), pmda_darwin.dylib (Mac), or pmda_windows.dll + (Windows). It also gives you the PMCD PMDA, which contains metrics + that monitor PCP itself. + + There are many other optional PMDAs that you can configure, depending + on which performance metrics you need to monitor, as follows: + Note: $PCP_PMDAS_DIR is normally /var/pcp/pmdas, see pcp.conf(4). + + Web Server metrics + + # su root + # cd $PCP_PMDAS_DIR/apache (i.e. cd /var/pcp/pmdas/apache) + # ./Install + # Check everything is working OK + # pminfo -fmdt apache + + Other PMDAs in the pcp package include: + + apache - monitor apache web server stats + cisco - monitor Cisco router stats + dbping - query any database, extract response times + elasticsearch - monitor an elasticsearch cluster + kvm - monitor kernel-based virtual machine stats + mailq - monitor the mail queue + memcache - monitor memcache server stats + mmv - export memory-mapped value stats from an application + mounts - keep track of mounted file systems + mysql - monitor MySQL relational databases + postgres - monitor PostGreSQL relational databases + process - keep an eye on critical processes/daemons + roomtemp - monitor room temp (needs suitable probe) + rsyslog - monitor the reliable system log daemon + sendmail - monitor sendmail statistics + shping - ping critical system services, extract response times + trace - for instrumenting arbitrary applications, see pmtrace(1) + txmon - transaction and QOS monitoring + + sample - for testing + simple - example src code if you want to write a new PMDA + trivial - even easier src code for a new PMDA. + + The procedure for configuring all of these is to change to the + directory for the PMDA (usually below /var/lib/pcp/pmdas), and then + run the ./Install script found therein. None of these PMDAs are + configured by default - you choose the PMDAs you need and run the + Install script. Installation can be automated (defaults chosen) by + touching .NeedInstall in the appropriate pmdas directory and then + restarting the pmcd service via its startup script. + +== D. Non-default build, install and run + + To run build and run a version of PCP that is installed in a private + location (and does not require root privileges), first create the + pcp "user" as described in section B.2 above), then + + $ ./configure --prefix=/some/path + + This will populate /some/path with a full PCP installation. To use this + ensure the following are set in the environment: + + $ export PCP_DIR=/some/path + + Amend your shell's $PATH to include the PCP directories, found as + follows: + + $ cd /some/path + $ xtra=`grep '^PCP_BIN' etc/pcp.conf | sed -e 's/.*=//' | paste -s -d :` + $ PATH=$xtra:$PATH + + Ensure the new libraries can be found: + + $ export LD_LIBRARY_PATH=`grep '^PCP_LIB' etc/pcp.conf \ + | sed -e 's/.*=//' | uniq | paste -s -d :` + + Tell Perl where to find loadable modules: + + $ export PERL5LIB=$PCP_DIR/usr/lib/perl5:$PCP_DIR/usr/share/perl5 + + Allow man(1) to find the PCP manual pages: + + $ export MANPATH=`manpath`:$PCP_DIR/usr/share/man + + If your version is co-exiting with a running PCP in a default + install, then alternative port numbers in your environment for pmcd + ($PMCD_PORT), pmlogger ($PMLOGGER_PORT) and pmproxy ($PMPROXY_PORT) |