Outline: 1) Install Perl 5.005_03 or later. 2) Decide where Orca's binaries, raw data, RRD and HTML directories will reside. Make sure performance concerns are handled. 3) Determine which Perl modules need compiling and installing. Optionally download newer versions of these modules. 4) Configure Orca. 5) Make Orca and any necessary Perl modules. 6) Test if the Perl modules properly compiled. 7) Install any necessary Perl modules. 8) Doing an upgrade from Orca 0.23 or older? Follow these steps. 9) Install Orca. 10) [Solaris Only and Optional] Install orcallator. a) Install the SE toolkit. b) Apply a patch to the SE 3.0 toolkit if necessary. c) Examine Orca/orcallator programs. d) Install orcallator boot and halt time start/stop scripts in /etc/rc?.d/. e) Run start_orcallator on all systems. f) Edit orcallator.cfg. 11) Run Orca. 1) Install Perl 5.005_03 or later. This step is too large to go into here. The bottom line is to follow the instructions at http://www.perl.com/pub/language/info/software.html or download a binary package from http://aspn.activestate.com/ASPN/Downloads/ActivePerl/ if you happen to run Linux, Solaris or Windows. 2) Decide where Orca's binaries, raw data, RRD and HTML directories will reside. Make sure performance concerns are handled. First choose the location where Orca will be installed. By default, Orca will install into the following structure: $prefix Prefix, set with --prefix $prefix/bin Binaries, set with --bindir $prefix/lib Libraries, set with --libdir $prefix/man Manual pages, set with --mandir $prefix/var/orca Data storage directory, set with --with-var-dir $prefix/var/orca/rrd RRD directory, set with --with-rrd-dir The HTML output directory is not set by default and must be specified by the Orca administrator. By default $prefix is set to /usr/local. The -- arguments shown above should be given to the configure script described below which configures Orca. If you want to change the installation location of Orca, say into /opt/orca, you would do so by passing --prefix=/opt/orca to the configure script. Because Orca is extremely IO intensive, I recommend the following architecture. Choose one host that can locally mount all the RRD data files and the directory containing the HTML and image files that are viewed by Orca users. If these two locations must be on separate hosts and one directory must be NFS mounted to the Orca host, then I recommend that the RRD data file be local instead of the HTML and image files, since the RRD files are much more read/write intensive. If you are going to use the orcallator.se Orca addon to monitor your Sun Solaris systems, then you will in addition need to decide where to have orcallator store its data files. By default, these data files are written to once every 5 minutes, so IO is not an issue. The issue here is that orcallator needs to run as root and all of the orcallator output files from all your hosts need to be written into the same NFS shared directory that Orca can read. It is not too important that the directory that orcallator writes into be mounted locally on the machine that Orca will run on, since Orca will only read each file every five minutes. If you are running orcallator on a system running a web, proxy, or Squid server, you can have orcallator watch the logs generated by these programs. In this case, note the location of the log file for the configure script. 3) Configure Orca. --prefix=DIR --with-var-dir=DIR --with-rrd-dir=DIR --with-html-dir=DIR Now that you have decided where the RRD, HTML, and optionally the orcallator data files and the web server access logs, are located, the configure script can be passed the following arguments: --prefix=ORCA_PREFIX_DIRECTORY --with-var-dir=VAR_DIR_LOCATION --with-rrd-dir=RRD_DIR_LOCATION --with-html-dir=HTML_DIR_LOCATION If you choose nothing else, the --with-html-dir must always be used, otherwise configure will fail. --with-ncsa-log=LOG_FILENAME --with-proxy-log=LOG_FILENAME --with-squid-log=LOG_FILENAME If you use a web, proxy, or Squid server, you can have orcallator gather statistics from the log file. Use this table to determine the appropriate configure command line option to use. LOG_FILENAME should be the location of the log file to monitor. Note that Apache and NCSA servers use the Common Log Format. Log Type Configure Option ----------------------------------------------------------- Common Log Format --with-ncsa-log Common Log Format with Proxy Information --with-proxy-log Squid Log Format --with-squid-log Configure will let you use only one of these options. --with-warn-email Orca has a `warn_email' configuration setting which is set to an email address where Orca should send its warning messages. By default this address is `root@localhost'. You can use this configure option to change the default email address to use in the Orca configuration scripts in this distribution. The configure script will find where your version of Perl and some other assorted programs are located. It will also determine if you have the necessary Perl modules to run Orca. If it does not find the required modules, the modules that are included with the Orca distribution will be built. Configure will also determine if you run one of the operating systems where a shared librrd.so library will be built and installed in $libdir. 4) Determine which Perl modules need compiling and installing. Optionally download newer versions of these modules. The Orca distribution includes the following Perl modules. Some of them are required for Orca to execute and some are included as modules that may be needed to help process data loaded by Orca (such as Date::Parse) or to profile Orca for performance improvements (Devel::DProf). Here, the module version refers to the $VERSION variable in the Perl module that is loaded by Perl and the package version refers to the version number in the file name of the .tar.gz that includes the Perl module. Module Required Required Package Version Name Module Package Included With Version Version Orca ------------------------------------------------------------------- Data::Dumper >= 2.101 >= 2.101 2.101 Date::Parse Not required by Orca 2.24 Devel::DProf Not required by Orca 19990108 Digest::MD5 >= 2.23 >= 2.23 2.23 Math::IntervalSearch >= 1.05 >= 1.05 1.05 RRDs >= 1.000411 >= 1.0.41 1.0.41 Storable >= 2.06 >= 2.06 2.06 Time::HiRes Not required by Orca 1.42 All seven of these modules are included with the Orca distribution in the packages directory. When you configure Orca in step 3), configure will determine if you need any of these modules compiled and installed. configure will then modify the packages/Makefile file to only build those modules that need to be installed. All of the modules except for Date::Parse and Math::IntervalSearch require a C compiler and generate shared libraries by default. If you wish to download and install modules that have been updated since this Orca package has been assembled, please use the following information. Data::Dumper http://www.perl.com/CPAN/authors/id/G/GS/GSAR/Data-Dumper-2.101.tar.gz % gunzip -c Data-Dumper-2.101.tar.gz | tar xvf - % cd Data-Dumper-2.101 % perl Makefile.PL % make % make test % make install Date::Parse http://www.perl.com/CPAN/authors/id/G/GB/GBARR/TimeDate-1.14.tar.gz % gunzip -c TimeDate-1.14.tar.gz | tar xvf - % cd TimeDate-1.14 % perl Makefile.PL % make % make test % make install Devel::DProf http://www.perl.com/CPAN/authors/id/I/IL/ILYAZ/modules/DProf-19990108.tar.gz % gunzip -c DProf-19990108.tar.gz | tar xvf - % cd DProf-19990108 % perl Makefile.PL % make % make test % make install Digest::MD5 http://www.perl.com/CPAN/authors/id/G/GA/GAAS/Digest-MD5-2.23.tar.gz % gunzip -c Digest-MD5-2.23.tar.gz | tar xvf - % cd Digest-MD5-2.23 % perl Makefile.PL % make % make test % make install Math::IntervalSearch http://www.perl.com/CPAN/authors/id/B/BZ/BZAJAC/Math-Interpolate-1.05.tar.gz % gunzip -c Math-Interpolate-1.05.tar.gz | tar xvf - % cd Math-Interpolate-1.05 % perl Makefile.PL % make % make test % make install RRDs http://people.ee.ethz.ch/~oetiker/webtools/rrdtool/pub/ RRDs is the Perl module that comes with RRDtool, a package written by Tobias Oetiker. % gunzip -c rrdtool-?.??.??.tar.gz | tar xvf - % cd rrdtool-?.??.?? % sh configure --verbose % make % cd perl-shared % make test % make install For large installations, I recommend that RRDs be compiled with optimization turned on. Storable http://www.perl.com/CPAN/authors/id/A/AM/AMS/Storable-2.06.tar.gz % gunzip -c Storable-2.06.tar.gz | tar xvf - % cd Storable-2.06 % perl Makefile.PL % make % make test % make install Time::HiRes http://www.perl.com/CPAN/authors/id/J/JH/JHI/Time-HiRes-1.42.tar.gz % gunzip -c Time-HiRes-1.42.tar.gz | tar xvf - % cd Time-HiRes-1.42 % perl Makefile.PL % make % make test % make install 5) Make Orca and any necessary Perl modules. To make Orca and these Perl modules run the following command: % make [ To optimize: make CFLAGS=-O or CFLAGS=-O3 ] 6) Test if the Perl modules properly compiled. To check if the Perl modules were properly compiled run the following command: % make test_modules 7) Install any necessary Perl modules. To automatically install these modules into Perl run the following command: % make install_modules This command will pass UNINST=1 down to the Perl Makefile's so that any old installed Perl modules are properly deleted. Otherwise, the Perl installation may have the old and new modules installed and due to Perl's module search order, Perl may use the older module instead of the newer installed module. If you do not wish to delete older Perl modules, then run this command: % make install_modules UNINST=0 8) Doing an upgrade from Orca 0.23 or older? Follow these steps. Due to various changes to Orca between releases, many of the RRD, HTML and image filenames that Orca creates have changed names. There are two separate issues. The first is that the naming scheme for all generated HTML and image (either PNG or GIF) files have changed. Unless you want to leave files with old names around wasting disk space, I recommend you cd into your HTML directories and delete all files there. The second issue is that the RRD data files have also changed names and unless you want to reload all of your source data files and waste more disk space on unused RRD files, I suggest that you run following command: % make upgrade This will look through the all of the directories that Orca will install into and use (namely the $prefix, $exec_prefix, $bindir, $libdir, $ORCALLATOR_DIR, and $RRD_DIR directories) and perform any necessary file renaming. If you have some new directories that are not included in the above list directories that make upgrade will cover, you can run the src/upgrage_installation program with a list of directories to parse and rename. If you want to see what upgrage_installation will rename without actually doing the rename, give it the -n option before any directory names. Here is a description of the various differences between versions. 0.23 -> 0.24 The following substitutions are now done to create any RRD, HTML and image files. orcallator -> o orca -> o _percent -> _pct _number -> _num _times -> _X # -> _num_ * -> _X_ 0.20 -> 0.21 Between version 0.20 and 0.21 of Orca, a major name change occurred in all of the installed and generated files. Any filenames containing percollator, percol, and perc had the name orcallator substituted in place. Filenames containing the word percent are properly protected and will not be renamed to contain the word orcallatorent. Percollator.se has been renamed to orcallator.se and its output files are now named orcallator. The default percollator.cfg has been renamed to orcallator.cfg and the version of orcallator.cfg included here now looks for data filenames of the form orcallator-1999-05-08 and percol-1999-05-8. If you are running an Orca installation 0.20 or older and want to rename all of the files and directories in your Orca installation to the new scheme, then kill any running percollator.se's before installing and running the following commands 9) Install Orca. Run the following command to install Orca: % make install This may also install librrd.so in your $libdir. 10) [Solaris Only and Optional] Install orcallator. a) Install the SE toolkit. Get the SE toolkit and use the installation instructions at http://www.setoolkit.com/ If you are running 2.6 or greater, then download SE 3.2 or greater. Otherwise you will need SE 3.0. The web site http://www.sun.com/sun-on-net/performance/se3/ is an older SE web site that contains other useful information. b) Apply a patch to the SE 3.0 toolkit. If you are running any other release of SE, then do not install the patch. By default the SE toolkit will install into /opt/RICHPse. Run this command: % cd /opt/RICHPse % patch -s < THIS_DIR/patches/p_netstat_class.se.diff c) Examine Orca/orcallator programs. Orca's installation scripts also installs several programs and configuration files necessary to have Orca monitor many different statistics of your Sun Solaris systems. The following tools are installed in the $prefix/bin directory: start_orcallator - start orcallator on a system stop_orcallator - stop orcallator on a system restart_orcallator - restart orcallator on a system orcallator_column - print selected columns from orcallator output orcallator_running - run to see if any orcallators are not running d) Install orcallator boot and halt time start/stop scripts in /etc/rc?.d/. If you wish to have orcallator run when the machine boots, you can install the included S99orcallator file into the proper /etc/*.d/ directories. To make installing this easier, you can say % make orcallator_run_at_boot from either the top level Makefile or the orcallator/Makefile. It will remove any old orcallator files and install S99orcallator into /etc/init.d/orcallator, /etc/init.d/rc0.d/K01orcallator, /etc/init.d/rc1.d/K01orcallator and /etc/rc3.d/S99orcallator. e) Run start_orcallator on all systems. Log in as root on all the systems you want to watch and run: % $prefix/bin/start_orcallator Orcallator will not generate an output data file until the first update interval, which will be between 2.5 to 7.5 minutes after orcallator is started. f) Edit orcallator.cfg. You need to edit the installed orcallator.cfg file and remove all unneeded references. In particular, you'll want to change warn_email, which is the email address that receives emails when orcallator generated files are out of date, which may signify a orcallator program that has died and is no longer gathering data. 11) Run Orca. Log into the system that will run Orca and run the command: % cd $prefix % ./bin/orca -v CONFIG_FILE If you are using orcallator.se, then this command will be % cd $prefix % ./bin/orca -v lib/orcallator.cfg