Outline:

 1) Install Perl 5.004_01 or later.

 2) Decide where Orca's binaries, RRD, HTML, and orcallator 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) Doing an upgrade from Orca 0.23 or older?  Follow these steps.

 8) Install any necessary Perl modules.

 9) Install Orca.

10) Set the Unix process file descriptor limit to at least 256.

11) [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.

12) Run Orca.




 1) Install Perl 5.004_01 or later.

    This step is too large to go into here.  The bottom line is to follow
    the instructions at

       http://language.perl.com/info/software.html

 2) Decide where Orca's binaries, RRD, HTML, and orcallator 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/rrd        RRD directory, set with --with-rrd-dir
    $prefix/var/orca/orcallator Orcallator directory, set with --with-orcallator-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 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) Determine which Perl modules need compiling and installing.
    Optionally download newer versions of these modules.

    Orca requires the following Perl modules at the specified versions:

    Name			Required Version	Included With Orca
    -----------------------------------------------------------------------
    Data::Dumper		2.101 or greater	2.101
    Digest::MD5			2.00 or greater		2.09
    Math::IntervalSearch	1.05 or greater		1.05
    RRDs			1.0.7.2 or greater	1.0.7.2
    Storable			0.6.3 or greater	0.6.7

    All five of these modules are included with the Orca distribution
    in the packages directory.  When you configure Orca in step 4),
    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 Math::IntervalSearch require a 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/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

    Digest::MD5

      http://www.perl.com/CPAN/authors/id/GAAS/Digest-MD5-2.09.tar.gz

      % gunzip -c Digest-MD5-2.09.tar.gz | tar xvf -
      % cd Digest-MD5-2.09
      % perl Makefile.PL
      % make
      % make test
      % make install

    Math::IntervalSearch

      ftp://ftp.gps.caltech.edu/pub/blair/Perl/Math-Interpolate-1.05.tar.gz
      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://ee-staff.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                                [ To optimize: make CFLAGS=-O ]
      % 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/RAM/Storable-0.6.7.tar.gz

      % gunzip -c Storable-0.6.7.tar.gz | tar xvf -
      % cd Storable-0.6.7
      % perl Makefile.PL
      % make
      % make test
      % make install

 4) Configure Orca.

    Now that you have decided where the RRD, HTML, and optionally the
    orcallator data files and the web server access logs, are located,
    run the configure script with the following arguments:

    % ./configure --prefix=ORCA_PREFIX_DIRECTORY \
                  --with-rrd-dir=RRD_DIR_LOCATION \
                  --with-html-dir=HTML_DIR_LOCATION \
                  --with-orcallator-dir=ORCALLATOR_DIR_LOCATION \
                  --with-TYPE-log=LOG_LOCATION

    If you choose nothing else, the --with-html-dir must always be used,
    otherwise configure will fail.

    If you use a web, proxy, or Squid server, you can have orcallator
    gather statistics from the log file.  Use this table to decide which
    configure option to use:

    Log Type                                    Configure Option
    -----------------------------------------------------------------
    NCSA/Common Log Format                      --with-ncsa-log=FILE
    Common Log Format with Proxy Information    --with-proxy-log=FILE
    Squid Log Format                            --with-squid-log=FILE

    Configure will let you use only one of these --with-TYPE-log options.

    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.

 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) 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.
    Two separate issues exist.

    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

 8) Install any necessary Perl modules.

   To automatically install these modules into Perl run the following
   command:

   % make install_modules

 9) Install Orca.

    Run the following command to install Orca:

    % make install

    This may also install librrd.so in your $libdir.

10) Set the Unix process file descriptor limit to at least 256.

    Orca is designed to run with a minimum of 256 available file
    descriptors.   If under Unix your processes have a file descriptor
    limit less than 256, then Orca may possibly fail.

    To check your default file descriptor limit, on many Unix systems
    you can run

    % ulimit -n

    If this number is less than 256, then you'll need to increase your
    limit.  This can be accomplished using the limit or ulimit command
    in your shell, depending upon which shell you use.  See man (1)
    ulimit or man (1) limit.

    If you are running a C shell equivalent, such as csh or tcsh, then
    you can run

    % limit descriptors 256

    If you have a Bourne shell equivalent, such as sh, ksh, bash, you
    can run

    % ulimit -n 256

    This command should either be placed in a .login, .profile, .cshrc
    file or run just before Orca is run.

11) [Solaris Only and Optional] Install orcallator.
    a) Install the SE toolkit.

       Perform the installation instructions as listed on the web page

         http://www.sun.com/sun-on-net/performance/se3/

       If you are running 2.6 or greater, then download SE 3.1 or greater.
       Otherwise you will need SE 3.0.

    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.

12) 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
