Table Of Contents

Previous topic

Monitoring Configuration

Next topic

Implementation

Installation

System Requirements

The agent is supported on the following systems:

  • Red Hat Enterprise Linux™ 3 on x86 and x86_64 [1] [2]
  • Red Hat Enterprise Linux™ 4 on x86 and x86_64 [1]
  • Red Hat Enterprise Linux™ 5 on x86 and x86_64 [1]
  • Red Hat Enterprise Linux™ 6 on x86 and x86_64 [1]
  • Debian 6.0 on x86 and x86_64 [1]
  • Ubuntu 10.04LTS on x86 and x86_64 [1]
  • SUSE Linux Enterprise Server™ 11 on x86 and x86_64
  • Solaris™ 9 on SPARC™ [2]
  • Solaris™ 10 on SPARC™, x86 and x86_64 [1]
  • AIX™ 5.3 (TL 07 and up) on Power™
  • Windows™(XP, Server 2003, Vista, 7, Server 2008) 32 and 64 bit
  • Apple™ OS X 10.5 on x86

Footnotes

[1](1, 2, 3, 4, 5, 6, 7) On x86_64 the agent runs as a 32-bit application and the OS needs to have the adequate 32-bit compatible userland support installed. Refer to X86 64 Bit Platforms for details.
[2](1, 2) These platforms have reached their end-of-life date as specified by their original vendors and are only supported on a best effort basis. It is possible that not all agent functionality will be available.

AIX Specifics

On AIX the agent cannot be installed in an alternate directory (e.g. by using the --prefix parameter during installation). The agent must be installed in the default /opt/abilisoft.com/ location.

When using the Oracle monitor on AIX there are some extra requirements on the platform:

  • The system must support 64k pages and load the agent in this configuration. AIX only supports 64k pages from 5300-04 and upwards on a Power5+ CPU with a 64-bit kernel. The experienced sysadmin could try to run with 16M pages which is supported since AIX 5100-02 on Power4 CPUs.
  • The system must be configured not to load shared library text used by the agent in the global loader space. It must be loaded as private text instead.

X86 64 Bit Platforms

On x86 64 bit platforms the agent runs as a 32-bit application. While all the binaries required by the agent are installed autonomously in the prefix (e.g. /opt/abilisoft.com) the application does require that the OS provides a 32 bit runtime. Sometimes the necessary packages are not installed by default when imaging a 64bit UNIX OS but can be easily installed with the package manager. Specifically RHEL 6 does not install the 32-bit runtime by default and requires you to install the following packages using yum:

  • glibc.i686
  • krb5-libs.i686
  • zlib.i686

Consult your OS vendor’s documentation to understand the best way to add these packages.

Windows Specifics

Windows installation is generally very easy and performed using an MSI installer, however the user performing the installation must have full administration rights. In complex, heavily controlled and administered environments the following points should be noted:

  • The user performing the installation should have strong Windows administration skills, preferably someone with an understanding of the specific system administration mechanisms and policies on the customer site.
  • It is important that the user doing the install has full local and domain administration privileges, full control of the Program Files directory and rights to install and run a Windows service.
  • The user doing the install must ensure that if there is a Group Policy Object (GPO) implemented that would stop the Agent service from starting then it must be properly configured; it may be set up to only allow white listed applications.
  • If Active Directory is running, there could be an Active Directory Group Policy that might stop the Agent service from starting.
  • If the Windows Data Execution Prevention (DEP) feature is enabled it will stop all non-trusted services from running. The Agent service must be added to the DEP’s list, or the DEP should be turned off. Note this cannot be done via an installer provided; the implementer must change the DEP settings. Note that group policies can also affect the DEP settings.
  • For DB Monitoring on Windows, the Abilisoft Agent can use Windows ADO when monitoring a datasource. ADO requires that a suitable data service (e.g. via OBDC) is installed and defined and the Agent manifest must be configured with the correct connection string depending on the data service defined.

Installing the Agent (UNIX)

The UNIX installation archive is named:

asagent_<VERSION>_<ARCH>.tar.gz

Make sure you have an archive that matches the platform you want to install to (although the installer will detect a mismatch and tell you).

Unpack the archive as follows:

$ tar -xzof asagent_<VERSION>_<ARCH>.tar.gz

Navigate to the directory extracted and invoke the installer:

$ cd asagent_<VERSION>_<ARCH>
$ ./install.sh

You will see output similar to this:

I: Host platform: x86-ubuntu10.04 (use --platform if incorrect)
I: Installing asagent
I: done!

Obviously the reported platform may differ. Running install.sh with the --help argument will display details on available command line options. The installer will automate the installation of MA onto a UNIX system into its default location of /opt/abilisoft.com/, unless --prefix is used which will cause MA to be installed into the location specified by the --prefix option parameter. For example:

$ ./install.sh --prefix=/home/fred/myagent

will install MA into the /home/fred/myagent directory. If the directory path specified does not exist then it will be created as long as the installer has the necessary write access to the file-system. For simplicity you can also install MA in the same directory as the installer by using the --inplace or -i option; this is equivalent to specifying --prefix=..

When executing install.sh you should do so as the user who will run the agent, as some files are given more secure access permissions (0600) in order to protect sensitive data.

When installing multiple Abilisoft products you can use the --notp option to skip installation of the thirdparty bundle, however be sure that a compatible thirdparty bundle is installed in the same prefix. For example, if you have installed Abilisoft UP or Abilisoft Reef then you may install MA with the --notp option as the thirdparty bundle provided by those products is compatible.

Specifying --profile option will update the /etc/profile file so that PATH and MANPATH variables are updated simplifying access to MA binaries and manual pages. When this option is used, make sure you source /etc/profile or log out and in again to activate the changes. Alternatively you can source the tools/env.sh file in the current shell which will have the same effect:

$ . /opt/abilisoft.com/asagent/tools/env.sh

Nothing particularly special is happening here. As with the --profile option, the PATH and MANPATH environment variables are updated so that MA binaries and manual pages can be easily accessed, for example:

$ asagent

will start the agent and:

$ man asagent

will display the asagent manual page. When these environment variables are not updated in the current shell you can still invoke installed applications by using the full pathname to their installed binaries, for example:

$ /opt/abilisoft.com/asagent/bin/asagent

Manual pages can still be accessed by specifying the full man page path, for example:

$ man /opt/abilisoft.com/asagent/share/man/man8/asagent.8

The installer detects the platform automatically to ensure the package being installed is suitable. However, specifying the --platform option with a suitable ARCH-OS argument will tell the installer not to detect the platform and to use the one specified in ARCH-OS instead.

The installer detects if an existing MA installation exists and will abort installation if this is the case. To force the removal of an old instance of MA (in the same prefix) before installation, use the --force option.

Traditionally an init script is used to automatically start a program at system boot time and to stop it at system shutdown. MA is shipped with such a script and it can be automatically installed to /etc/init.d/ using the --initd parameter. The appropriate symbolic links will also be created. This will start MA in run-levels 3, 4 and 5 and stop it in all other run-levels. If you prefer you can install the init script manually, after installation it can be found here:

/opt/abilisoft.com/asagent/etc/init.d/abilisoft.com-asagent

Refer to the asagent section for full details on running the agent.

Installing database extensions

Under Unix the extra database thirdparty software for monitoring Oracle and DB2 isn’t installed by default and is available as seperate archives.

The database installation archives are named:

<PKGNAME>_<VERSION>_<PLATFORM>.tar.gz

There are currently three packages available: cxoracle10, cxoracle11 and pydb2 which incorporate the database client libraries for Oracle 10g, 11g and DB2 v9.5 for asagent respectively. It should be noted that the cxoracle10 package can be used to connect to Oracle servers 9i, 10g and 11g while the cxoracle11 package can be used to connect to Oracle servers 10g and 11g.

Make sure you have an archive that matches the platform you want to install to (although the installer will detect any mismatch and tell you).

Unpack the archive as follows:

$ tar -xzof <PKGNAME>_<VERSION>_<PLATFORM>.tar.gz

Navigate to the directory extracted and invoke the installer:

$ cd <PKGNAME>
$ ./install.sh

Run install.sh with the --help argument to get details on all the command line options.

Note that on AIX the cxoracle11 and pydb2 packages must have asynchronous I/O (AIO) enabled on the server. You can check the AOI enabled state using the smitty aio command and selecting the Change / Show Characteristics of Asynchronous I/O menu item. If the STATE to be configured at system restart is listed as defined AIO is not enabled, it must be set to available to be enabled.

Note

After changing the state the system must be restarted.

This procedure is not required for the cxoracle10 package.

Installing the Agent (Windows)

The Windows installer is delivered as an MSI package named:

asagent_<VERSION>_x86-win32.msi

The MSI can be executed by double-clicking the MSI installer icon, via a management service like SMS or running it from the command line as follows:

c:\> msiexec /i asagent_<VERSION>_x86-win32.msi

Note

You can use the /quiet option for an unattended installation

There are many command line installation options, any of the agent’s runtime configuration settings can be defined during the installation procedure. Refer to MSI Command Line Options for details of MSI command line options.

Follow the installation prompts, using the defaults are recommended. The agent will be installed as a Windows service and in general a reboot will not be required.

Once installed you will need to run the agent; refer to the asagent section for details on running the agent.

Windows 64 bit

Note that for installations on 64 bit Windows platforms the default agent installation directory is C:\Program Files (x86)\Abilisoft.com.

Un-installing or Upgrading (UNIX)

Un-installing

Make sure the agent is not running, i.e. execute the command:

$ asagent --stop

If the agent has been using monitoring and runtime configuration in the default location of $AS_HOME/etc then take a backup copy.

Note

It is possible to configure your agent to get runtime and monitoring configuration from a source outside the installation directory. Refer to Using Configuration Outside the Installation Directory for details.

Simply delete the directory /opt/abilisoft.com using the command:

$ rm -rf /opt/abilisoft.com

Upgrading

To upgrade asagent, perform the un-installation procedure followed by the installation procedure. Take care to back up any configurations before upgrading.

Un-installing or Upgrading (Windows)

Un-installing

Open the Windows Control Panel navigate to the ‘Add/Remove Programs’ screen. Right-click Abilisoft asagent and select Un-install. The asagent service will be stopped (if running) and the software un-installed.

Upgrading

To upgrade asagent, perform the un-installation procedure followed by the installation procedure. Take care to back up any configurations before upgrading.

Environment Variables

There are two key environment variables that are essential to the operation of the Agent:

$AS_HOME

This specifies the installed directory of the Agent, by default it is /opt/abilisoft.com/asagent.

On Windows it is not required to have this environment variable set since the registry key HKEY_LOCAL_MACHINE\SOFTWARE\abilisoft\mtm\as_home will be used if present. This key is automatically created during the windows installation by the MSI. The usual value for this variable on windows is C:\Program Files\Abilisoft.com\asagent.

Using the UNIX Shell

Most UNIX systems will have an sh compatible shell available. As a quick refresher there are several ways in which you can set environment variables using an interactive shell:

$ VAR=value

Will set the variable in the current shell only, which means any process started from the shell will not have this environment variable. To make the variable available to the children of the shell it must be exported:

$ VAR=value
$ export VAR

Lastly it is also possible to set an environment variable for just one child process created by the shell, e.g. using the echo command:

$ VAR=value echo The value is: $VAR

This manual may use any of these techniques in examples, but in each case any technique which sets a variable in the environment of the agent is appropriate.

$AS_HOME/etc

This directory contains the Agent runtime configuration file asagent.conf. This is a standard INI file format; sections are used for various groups of settings. An example is shown below:

[settings]
loglevel = DEBUG
manifest_uri = http://example.com/asagent/manifests/default.xml

This configuration mode can also be used on Windows if preferred, however configuration settings are stored in the Registry by default.

$AS_HOME/var/log

Agent log files are written here by default (although one can configure them to be written elsewhere). The current log file has a *.log extension, rolled log files have a *.log.1, *.log.2 etc extensions. The number of rolled logs can be configured.

Man Pages

UNIX man pages are available as well:

maql (1)               command line remote asagent client
asagent.conf (5)       asagent runtime configuration file
asagent (8)            Abilisoft Monitoring Agent