RCUG 2 Installing RootCause

Next Previous Index Top

RootCause User Guide

---

rcc-5

Installing RootCause

---

The RootCause product consists of two major components: the

RootCause Console and the

RootCause Agent. The RootCause Console component allows you to create probes and examine the trace data generated by the probes. The RootCause Agent is the component that performs the actual runtime tracing and generates the trace data.

Every user of RootCause will install the RootCause Console and the RootCause Agent on a local computer in order to be able to create probes and view probe data for the local computer as well as remote computers.

The RootCause Agent may then be installed on all

remote computers where RootCause will be deployed (i.e. where remote applications are to be traced by the RootCause product). Note that you may also install the RootCause Console component on any and all remote computers if you wish to develop probes and view their trace data

locally on the remote computers.

Getting Help

If something is missing, or you need a different media format, or you have any other installation or configuration problems, please contact OC Systems by internet at support@ocsystems.com or by telephone at (703)359-8160.

On-line Documentation

After you've installed RootCause, you can use your HTML browser and the Console's Help menu to view detailed information about use of the product.

The user guides for both RootCause and Aprobe are available in HTML format

at $APROBE/html/index.html

, and on the web at

[["http://www.ocsystems.com/sup_ug_index.html">http://www.ocsystems.com/sup_ug_index.html</A>.

The RootCause user guide is available in

PDF, in
$APROBE/RootCauseCpp.pdf

.

System Requirements

RootCause interacts very closely with the hardware, the operating system and the compiler

on your machine. Furthermore, RootCause itself requires a C compiler in order to generate probe actions. This section identifies the specific requirements in these areas. Read this carefully, and contact OC Systems if you have questions.

RootCause for Unix is currently supported on the AIX, Linux, and Solaris operating systems. On each operating system, specific compilers and Java versions are supported. Details are given below:

AIX

AIX Hardware requirements

• a POWER or PowerPC architecture workstation

• Approximately 120 megabytes of disk space for a RootCause Console installation; about 7 megabytes for the RootCause Agent alone.

• At least 128 megabytes of RAM.

• A display supporting 256 or more colors.

AIX Operating System Requirements

• AIX Version 5.1 or newer is required to run the RootCause Console Java GUI and any other tools that operate on a RootCause CHAPTER 3 - Terminology and Concepts [][["rcc-6.html#MARKER-9-482">workspace</A>.

• The underlying Aprobe command-line facility works on AIX versions 4.2 and newer.

AIX Compiler Requirements

A C compiler is required to build non-Java probes. This compiler is selected at installation time and may be one of the following:

• IBM C for AIX (xlc) version 3.1 or newer.

• GCC version 2.8.1 or higher

Probing of C/C++ applications is supported for applications compiled with any of the following compilers:

• IBM C,

  C++ for AIX (xlc, xlC) version 3.1 or newer.

• EGCS GCC version 2.95.x or 2.96.

• GCC version 3.x is only partially supported. In particular:
  GCC must be configured to generate stab format debug information, or programs compiled with the -gstabs option, in order for RootCause and Aprobe to resolve source line and variable references.

Probing of Ada applications is supported for applications compiled with:

• OC Systems PowerAda, version 5.0 or newer.

Linux

Linux Hardware requirements

Any modern Intel Pentium-based computer.

Approximately 120 megabytes of disk space for a RootCause Console installation; about 7 megabytes for the RootCause Agent alone.

At least 128 megabytes of RAM.

A display supporting 256 or more colors.

Linux Operating System Requirements

Red Hat Linux 7.1 or later, with a version 2.4 kernel or later.

Korn shell (/usr/bin/ksh

) must be installed in order to install RootCause.

Linux Compiler Requirements

A C compiler is required to build non-Java probes. This compiler is selected at installation time and may be one of the following:

• GCC version 2.95.x or 2.96.

Probing of C/C++ applications is supported for applications compiled with any of the following compilers:

• EGCS GCC version 2.95.x or 2.96.

• GCC version 3.x (the default on Red Hat 8) is only partially supported.
  In particular: GCC must be configured to generate stab format debug information, or progrrams compiled with the -gstabs option, in order for RootCause and Aprobe to resolve source line and variable references.

Probing of Ada applications is supported for applications compiled with:

• OC Systems PowerAda, version 5.0 or newer.

Solaris

Solaris Hardware requirements

• Sparc & UltraSparc, by Sun Microsystems

• Approximately 140 megabytes of disk space for a RootCause Console installation; about 7 megabytes for the RootCause Agent alone.

• At least 128 megabytes of RAM.

• A display supporting 256 or more colors.

Solaris Operating System Requirements

• Solaris 2.5.1 / SunOS 5.5.1 or higher

• We recommend Solaris 8 or newer since that supports the preferred Java interpreter used by the RootCause Console GUI.

Solaris Compiler Requirements

A C compiler is required to build non-Java probes. This compiler is selected at installation time and may be one of the following:

• Sun Workshop C version 4.2 or higher; or

• GCC version 2.8.1 or higher

• NOTE: /usr/ucb/bin/cc may not be used.

Probing of C/C++ applications is supported for applications compiled with any of the following compilers:

• Sun Workshop (Forte) C/

  C++, version 4.2 or newer.

• EGCS GCC version 2.95.x or 2.96.

• GCC version 3.x is only partially supported. In particular:
  GCC must be configured to generate stab format debug information, or programs compiled with the -gstabs option, in order for RootCause and Aprobe to resolve source line and variable references.

Probing of Ada applications is supported for applications compiled with:

• GNAT version 3.15 or newer.

Reading the CD

The

CD-ROM is mounted as a file system, and once mounted is read just like a hard disk. Depending on the configuration of your system, you may need root (superuser) privileges to access or change your CD device. If you don't have access to a CD-ROM device, you can request a downloadable version from

[["mailto:support@ocsystems.com">support@ocsystems.com</A>.

AIX

On AIX, insert the Aprobe CD-ROM into the CD drive. Then, on the system containing the CD drive, mount the CD as a filesystem. If the mount is already defined (it probably is) then you can just remount it:

$ /etc/mount /cd0

Otherwise you'll have to create a directory and mount it there, which will require root privileges:

$ mkdir /cd0
$ /etc/mount -r -v cdrfs /dev/cd0 /cd0

Linux

Linux should automatically mount the CD-ROM when you place it in the drive. You should see it at /dev/cd.

Solaris

Solaris should automatically mount the CD-ROM when you place it in the drive. You should see it at /cdrom/cdrom. If you have more than one CD drive in your system you will have /cdrom/cdrom0, /cdrom/cdrom1, etc. so just pick the correct one.

Installing From A Compressed Tar File

If your CD-ROM drive is on a separate machine from where you want to install you may copy the file rootcause_install_image.tar.Z from the CD to disk, then ftp that to the desired machine.

Or, you may have downloaded RootCause from OC Systems directly, in a file such as RCSol205.tar.Z.

In either case, you may perform the following steps:

1. Copy the .tar.Z file where you wish to install it.

2. Execute the command:

   uncompress -c rootcause_install_image.tar.Z | tar -xvf -

3. This will create a new directory, e.g., rootcause_install_image/.
   You may rename this if you prefer a different name.

4. Follow the instructions below, except that you may install "in place", by

   • starting in the top directory (e.g., rootcause_install_image/), and

   • specifying "." as the installation directory.

Preparing to Install

Once you can read the CD-ROM, the next step is to decide where to install its contents on your hard disk:

1. Examine the README file on the CD-ROM for updates to the installation process and the user guide.

2. Determine where on disk you want to install RootCause.

   • Choose a new directory which will be visible to all potential users, and which has sufficient disk space. For the full installation you will need about 140 Megabytes of space.

   • You do not need to have root privileges to do the installation unless you need those privileges to write into the selected directory.

   • RootCause should not be installed in place of an existing installation unless it is compatible (the first two digits of the version number match). Otherwise, existing probes and workspaces will need to be rebuilt.

3. Determine whether you're using RootCause for C++ or for Java. If you're reading this manual, you're probably using just C++

4. Determine which C compiler will be used during the installation.

   • See [["#MARKER-9-220">"System Requirements"</A> for a list of suitable compilers. A C compiler is required for building the probes that RootCause will create.

   • The installation script will prompt you to state or verify the full path name of the C compiler to be used during installation. This need not be the same compiler you will use to build your application(s). Rather it will be used just to compile the APC source code that describes the generated probes.

   • If a suitable C compiler is in your executable PATH, the install script will offer it as the default compiler. The GCC compiler will be chosen only if no supported cc compiler is found.

5. Have a RootCause license key ready. If possible, use your mouse to copy the key from another window on your screen so you can simply paste it at the prompt during installation.

   You can complete the RootCause installation process without a license key, but you'll have to install the key manually later (see [["#MARKER-9-263">"License Key Installation"</A>).

You are now ready to run the installation script and reply to its prompts about the installation directory, C compiler, and license key with the selections made above.

RootCause Console Installation

RootCause is shipped on CD-ROM. You install RootCause by loading the CD-ROM and running the install_rootcause script found on the CD-ROM, for example:

/cd0/install_rootcause

where /cd0 represents the CD-ROM directory described under [["#MARKER-9-239">"Reading the CD"</A>, or else

rootcause_install_image/install_rootcause

as described in [["#MARKER-9-245">"Installing From A Compressed Tar File"</A>

It will ask you to make a few choices, including the directory location where you wish to install RootCause. It also asks for the license that was supplied by OC Systems. If you do not have a license, contact [["mailto:support@ocsystems.com">support@ocsystems.com</A>.

If you have problems with installing RootCause, you may want to read further in this section, otherwise, you are ready to run the "RootCause Demo" [][["rcc-8.html#MARKER-9-707">"RootCause Demo"</A>.

RootCause Agent Installation

This section is only applicable if you want to install only the

RootCause Agent component without installing the RootCause Console. This means that you wish to

deploy RootCause to a

remote computer, and will be creating probes for the remote computer and viewing the remotely collected probe data using the RootCause Console component located on a

local computer.

The RootCause Agent installation package is contained in file
deploy/rootcause_agent.tar.Z located on the RootCause CD and also in a a RootCause Console installation.

To install the RootCause Agent on a remote computer, follow these steps:

1. Transfer file rootcause_agent.tar.Z to the remote computer.

2. Uncompress and un-tar the file, which will create the directory rootcause_agent:

   uncompress -c rootcause_agent.tar.Z | tar -xvf -

3. Run the install_rootcause script:

   rootcause_agent/install_rootcause

During RootCause Agent installation, you will be prompted for a writable directory into which the product will be installed. You may choose to install the product in place (i.e., under the rootcause_agent directory you just created), or install it into an entirely different directory. We recommend that you install the product on a local disk.

Note that you will not be prompted for a license during installation. When you create a deployable workspace (a .dply file) using the RootCause Console, it should contain an agent license (provided you have purchased one or more from OC Systems) that allows you to run the RootCause Agent product on remote computers.

Uninstalling RootCause

To uninstall RootCause, simply delete the entire $APROBE directory. The RootCause installation itself does not write to any other locations.

The ~/.rootcause (or ~/.rootcause_aix or ~/.rootcause_linux) directory, and the individual workspace (.aws) directories, are considered to be user data, not part of the RootCause installation itself. If you delete the ~/.rootcause* directory (or any directory referenced by the

$APROBE_HOME,

$APROBE_LOG or

$APROBE_REGISTRY environment variables) you must re-run the "setup" scripts as described in Chapter 4, "Getting Started"

[][["rcc-7.html#MARKER-9-508">Chapter 4, "Getting Started"</A>.

Licensing

The accompanying

license agreement describes the terms under which RootCause may be legally used. OC Systems protects its products from illegitimate use by implementing license agreement checks in its software.

Licensed use of RootCause is checked by the software using the

FLEXlm licensing system from Globetrotter Software.

RootCause is packaged as RootCause for Java and RootCause for C++. This is the user's guide for the

C++ version only. The differences in features between RootCause for Java and RootCause for C++ are determined solely by the license key(s) you are issued by OC Systems.

Obtaining License Keys

An demonstration license is generally provided in a cover letter or e-mail message included with the software. When you purchase the product, OC Systems will request additional system-specific information, and send you license keys generated from this information.

License Key Installation

License keys are shipped in either "decimal" or "text" format. The decimal license string can be supplied by the user when prompted during the RootCause product installation process (see [["#MARKER-9-248">"RootCause Console Installation"</A> above).

Entering an empty license string will postpone the license installation, which will have to be done manually by editing the

$APROBE/

licenses/

license.dat file and entering either the decimal or human-readable form of the license key.

For more information on the license key installation and license management refer to the FLEXlm End-User Manual that can be found in PDF or HTML format in $APROBE/licenses

or contact OC Systems as described in

[["#MARKER-9-211">"Getting Help"</A>.

---

Copyright 2006-2017 OC Systems, Inc.

Next Previous Index Top