INSTALL

Outline:

 1) Install Perl 5.005_03 or later.

 2) Configure Orca.
    a) Overview of the 'configure' script.
    b) Decide where Orca's binaries, raw data, RRD and HTML
       directories will reside.  Make sure performance concerns are
       handled.
    c) Find out where Orca's input files are located.
    d) Other 'configure' command line options.
    e) Run the configure script to configure Orca.

 3) Make Orca and any necessary Perl modules.

 4) Test if the the Perl modules were properly compiled.

 5) Doing an upgrade from Orca 0.23 or older?  Follow these steps.

 6) Install Orca and any Perl modules Orca requires.

 7) [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/init.d/ and /etc/rc?.d/.
    e) Run start_orcallator on all systems.
    f) Edit orcallator.cfg.

 8) [Systems with System Statistics in /proc, i.e. Linux] Install procallator.

 9) 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/download.csp

    or download a binary package from

       http://aspn.activestate.com/ASPN/Downloads/ActivePerl/

    if you happen to run Linux, Solaris or Windows.

    If you run Solaris, you can also get a binary Perl package from

        http://www.sunfreeware.com/

 2) Configure Orca.

    Orca is configured when the user runs the 'configure' script
    located in the same directory as this INSTALL file.

    a) Overview of the 'configure' script.

       The 'configure' shell script attempts to guess correct values
       for various system-dependent variables used during compilation.
       It uses those values to create a 'Makefile' in each directory
       of the package.  It may also create one or more '.h' files
       containing system-dependent definitions.  Finally, it creates a
       shell script 'config.status' that you can run in the future to
       recreate the current configuration, and a file 'config.log'
       containing compiler output (useful mainly for debugging
       'configure').

       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 Perl modules, the modules that
       are included with the Orca distribution will be built.

       The 'configure' script will also determine if you run one of
       the operating systems where a shared RRDtool library
       (librrd.so) will be built and installed in $libdir.

       The configure script takes a number of optional command line
       arguments that customize its behavior.  All command line
       arguments begin with the -- characters.  To see the command
       line arguments that 'configure' takes, run it as

          ./configure --help

       or if you are using 'csh' on an old version of System V, you
       might need to type

          sh ./configure --help

       instead to prevent 'csh' from trying to execute 'configure'
       itself.

       Take a look through the available options, the important ones
       are be discussed below.

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

       By default $prefix is set to /usr/local.  The -- arguments
       shown above should be given to the 'configure'.  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, we 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.

       Orca requires a separate data gathering process to measure and
       save the data that Orca will plot.  You need to decide where
       these data gathering processes will save its data files.  Most
       data gatherers take a measurement and write to their data files
       once every 5 minutes, so IO is not an issue.  The issue here is
       that most data gatherers need to run as root and all of the
       data 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 data gatherer writes into be
       mounted locally on the machine that Orca will run on, since
       Orca will only read each file every five minutes.

       The HTML output directory is not set by default and must be
       specified by the Orca administrator with the

          --with-html-dir=DIR

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

       The HTML output directory will normally be accessible by a web
       server so that Orca's files can be viewed in a browser.  It is
       less important that this directory be locally mounted than the
       RRD directory, as this directory sees much less IO than the RRD
       directory.  Orca is smart enough not to update plots that do
       not need to be updated even when new data is loaded.  For
       example, Orca's daily plots do not need to be updated but once
       a day, so even though measurements may be taken every five
       minutes, only a measurement taken in the new day will cause
       Orca to generate an updated plot.

    c) Find out where Orca's input files are located.

       If you are running a Solaris system and use a web, proxy, or
       Squid server, you can have the Solaris 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.

       --with-ncsa-log=LOG_FILENAME
       --with-proxy-log=LOG_FILENAME
       --with-squid-log=LOG_FILENAME

       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

       The 'configure' script will let you use only one of these
       options.

    d) Other 'configure' command line 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.

    e) Run the configure script to 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

    Now run the configure script like

      ./configure [flags]

    with the appropriate flags you want.

 3) 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 ]

 4) Test if the the Perl modules were properly compiled.

    To check if the Perl modules were properly compiled run the
    following command:

    % make check

 5) 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 orca/upgrade_installation program with a list of directories
    to parse and rename.  If you want to see what upgrade_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

 6) Install Orca and any Perl modules Orca requires.

    Run the following command to install Orca and all the Perl modules
    Orca uses.

    % make install

    This will install the Perl modules into $libdir/perl, so it should
    not overwrite or clobber any existing Perl modules that you
    already have on your system.

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

 7) [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/init.d/ and /etc/rc?.d/.

       If you want to have orcallator run when the machine boots, you
       can manually copy data_gatherers/orcallator/S99orcallator into
       /etc/init.d/orcallator and set up symbolic links from that file
       to the appropriate K* and S* files in /etc/rc?.d/.

       To make installing this easier, there are several make targets
       available for different operating systems.

       For systems with chkconfig, which are normally RedHat based
       ones, run

       % make orcallator_run_at_boot

       from either the top of the Orca source tree or from the
       data_gatherers/orcallator directory.  This will first delete
       any existing start and stop scripts in the locations it will
       install files into.  By default, it will copy S99orcallator
       into /etc/init.d/orcallator and create symbolic links to
       /etc/init.d/rc0.d/K01orcallator, /etc/init.d/rc1.d/K01orcallator,
       /etc/init.d/rc2.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 will probably want to edit orcallator.cfg to customize
       various parameters for your site.

       To change the HTML header and footer's on each web page, modify
       the html_page_header and html_page_footer configuration values.
       You may also want to edit the html_top_title, which is the
       title of the top level HTML page.

       You may want to change warn_email, which is the email address
       that is sent mail when Orca sends out warning messages, such as
       when the input data files (say generated by orcallator) are out
       of date, which may signify a orcallator program that has died
       and is no longer gathering data.

 8) [Systems with System Statistics in /proc, i.e. Linux] Install procallator.
    a) Install procallator boot and halt time start/stop scripts in
       /etc/init.d/ and /etc/rc?.d/.

       If you want to have procallator run when the machine boots, you
       can manually copy data_gatherers/procallator/S99procallator
       into /etc/init.d/procallator and set up symbolic links from
       that file to the appropriate K* and S* files in /etc/rc?.d/.

       To make installing this easier, there are several make targets
       available for different operating systems.

       For systems with chkconfig, which are normally RedHat based
       ones, run

       % make procallator_run_at_boot_using_chkconfig

       from either the top of the Orca source tree or from the
       data_gatherers/procallator directory.  This uses Linux's
       chkconfig's script to install the start and stop scripts in the
       approprirate locations.  By default, procallator is started in
       run levels 2, 3, 4 and 5.

    b) Run start_procallator on all systems.

       Log in as root on all the systems you want to watch and run:

       % /etc/rc.d/init.d/procallator start

       Procallator will not generate an output data file until the
       first update interval, which will be between 2.5 to 7.5 minutes
       after procallator is started.

    c) Edit procallator.cfg.

       You need to edit the installed procallator.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 procallator generated files are out of date, which may
       signify a procallator program that has died and is no longer
       gathering data.

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