2 Installing the Oracle AD4J Console

This chapter provides procedures for installing the Oracle AD4J Console. It covers the following:

Installing the AD4J Console on Unix
Installing the AD4J Console on Windows
Post-Installation Tasks

Installing the AD4J Console on Unix

This section covers the procedure to install the AD4J Console on the supported Unix platforms (i.e. Linux and Solaris). It describes the following:

Prerequisites
Installation Procedure
Uninstalling the AD4J Console on Unix

Prerequisites

Before you begin the installation process, do the following:

Determine the host system on which you want to deploy the console. Oracle recommends the use of a dedicated host for the console.
Install JDK 1.4.2 or later on that host. It must be a 32 bit JVM.

Note: You can a 32 bit JVM on a 64 bit operating system.
Have access to Oracle 9i (or later) database for use as a repository. This database may be local or remote.
Create a database user for the Oracle AD4J repository. Assign appropriate default and temporary tablespace and permissions to the user so that database objects can be created in these tablespaces.
Assign an appropriate table space for user (temp and default).
Have adequate space for the heap analysis features. You need about 5 times the heap size space for every heap snapshot.
Install the Oracle client on the console machine. This is required only for heap analysis features.
Depending on the platform, download jamserv-lnx.zip or jamserv-sun.zip.
Determine the http port you will use to access the console (the default is 3500).
Determine the TCP/IP port that agents will use to establish a connection with the console (the default is 3600).
Collect the requisite information for the DB Repository. See Collecting Database Repository Details for details.
Decide the location at which the console is to be installed. After installation, you must use the following URL to access the console: http://consolehost:<port_no>.You must download the agent to be deployed on the monitored JVMs. To log in, you must use the default console setup credentials , admin as the user name and welcome as the password. After you log in, you must change the default password. You can perform operations on the console only the password has been changed.

Installation Procedure

The installation procedure includes the following steps:

Collecting Database Repository Details
Extracting Files
Running the Configuration Script
Understanding Console Parameters
Starting Up and Initializing the Console
Specifying the Database Connection Details
Creating the Database Tables
Viewing JVM Console Diagnostics
Running the jamserv-win.msi File
Selecting the Installation Location
Setting the Console Parameters
Specifying the Port Information

Collecting Database Repository Details

You will need to collect the following information about the database:

DB server name (E.g. localhost)
Database name (E.g. orcl)
DB Listener Port (E.g. 1521)
Repository User Name
Repository User Password

Extracting Files

Unzip the archive file you have downloaded. Run the following command to extract the files at any location where the AD4J console is to be installed:

unzip jamserv-<platform>.zip

where <platform> can be lnx or sun. This creates a jamserv directory with the following sub-directories:

Table 2-1 File install and configuration

Console application files	jam
Configuration files	conf
Binaries and Shell scripts	bin
Sun binaries	bin/sun
Linux binaries	bin/lnx
Log files	logs
Library files	lib
Cache for JSP pages	cache
Trace files	trace

Running the Configuration Script

Now, run the following command to execute the configuration script from the jamserv directory:

./configure.sh <JDK_Home> [Agent_Port] [HTTP_Port]

The following table describes the parameters used in the command mentioned above.

Table 2-2 Configuration

Parameter	Default Value	Description
JDK_Home	None	The directory where Java is installed
HTTP_Port	3500	The HTTP port to access Oracle AD4J
Agent_Port	3600	The port that Oracle AD4J agents (this is not an HTTP port) use to communicate with the console.

Note:

Only the first parameter JDK_Home is mandatory. The rest are optional. So, if you choose 3500 as the default HTTP port and 3600 as the console port, and your JDK_Home is in /opt/jdk142, then run the following command:

./configure.sh /opt/jdk142

The configure.sh file creates self-signed certificates to enable secure access (HTTPS) to the console on port 3443. When the certificates and the certification authority (CA) are created, it prompts you with the following questions twice, once when creating the certification authority (CA) and again when creating the certificates.

Table 2-3 Certification Authority

Country Name	(2 letter code) [XY]:
State or Province Name	(full name) [CA]:
Locality Name	(For example, city) [Unknown]:
Organization Name	(For example, company) [Unknown]:
Organizational Unit Name	(For example, section) [Certificate Authority]:
Common Name	(For example, CA name) [mymachine01]:
Email Address	(For example, name@FQDN) [myname@aupt01]:

The following illustrates the configure.sh command output. Note that configure.sh prompts you for these questions twice.

Figure 2-1 configure.sh Command Output

It is important that when creating the certificate (second set of prompts), the Common Name and prompt #5 reflect the server name you will use in the URL to access. While the install script tries to determine the host name, you must ensure that the domain is correct.

For example, for HTTPS port, if the server name is console01, then you must specify https://console01:XXXX.

For HTTPS port, you cannot specify https://console01.mydomain.com:XXXX or http://124.25.113.10:XXXX where XXXX is the HTTPS port for the Apache listener.

However, for HTTP port, you can specify all the above names.The HTTPS port (default 3443) can, however, be changed by changing the following files:

jamserv/conf/httpd.conf
jamserv/conf/ssl.conf

It is strongly recommended that you replace this out-of-box certificate with a certificate issued by a well-known certificate authority.

Note:

To disable HTTP access and ensure secure access to the console, remove the Listen 80 command in the jamserv/conf/httpd.conf file.

Understanding Console Parameters

Before you initialize the console, you must understand the console parameters specified in the jamserv/conf/zone.properties file. The console parameters are described in the following table:

Table 2-4 Console Parameters

Parameter	Default	Description
jamport	None	Port where console listens for connections from agents.
jamloglevel	3	How much information should console log. High value provides greater debug information but can adversely affect the performance.
jamtimeout	20	Max seconds to wait for JVM to respond.
jamlooptimeout	15	Max seconds to wait for JVM to respond for multiple JVM requests.
jampropfilepath	None	When the console starts up for the first time, it creates a property file adminDB.properties where it stores information about the repository DB. This parameter specifies the directory where the file should be created. This file contains sensitive information including username, password. It should be a secure location.
jamtracefilepath	None	Directory where to put the trace files.

Starting Up and Initializing the Console

Run the following command to start the console:

jamserv/bin/apachectl start

Note:

If you see a 500 HTTP Error in your web browser after you run this command, it indicates that the Jserv process was not automatically started. To start it manually, enter the following command:

jamserv/bin/jservctl

To view details about the error messages, access the jamserv/logs/error.log file. The file provides details about the following:

Class path used by the Oracle AD4J Console
Parameters (default and non-default) in use
Build version of the console
Console is ready for connections from agents

Specifying the Database Connection Details

The adminDB.properties file stores connection details about the repository database. The file resides in the location specified by the start up parameter - jampropfilepath.

To modify the file, do the following:

Click Setup.

The console displays the JAM Console Diagnostics page.
Click the adminDB.properties link.

The console displays the Console Repository Database Information page (Figure 2-2).

Figure 2-2 Console Repository Database Information
Modify the settings.
Restart the console to see the changed settings in effect.

Creating the Database Tables

After you specify the database connection details, create the database objects in the repository by following these steps:

Click Setup.
Click Repository DB.

The console displays the Maintain Repository Database page (Figure 2-3).

Figure 2-3 Maintain Repository Database
To create the repository objects, click Go.
To run the diagnostics, click Setup.

The console is now configured and ready to accept any incoming JVM Connections.

Viewing JVM Console Diagnostics

Whenever you click Setup, the console runs the diagnostics. Here, you can view details about the configuration of the console and also the errors (if any).

For example, if a database connection cannot be established for some reason, it would show up here along with some debug information.

To view JVM console diagnostics, click Setup.

The console displays the following page.

Figure 2-4 AD4J Console Diagnostics

Uninstalling the AD4J Console on Unix

To deinstall the Oracle AD4J console from UNIX platforms, go to the location where you extracted the contents of the jamserv.zip file, and delete the jamserv directory completely.

Installing the AD4J Console on Windows

This section provides installation procedures for installing the Oracle AD4J console on Microsoft Windows platforms, such as Microsoft Windows Itanium, and Microsoft Windows x86_64. It covers the following:

Prerequisites
Installation Procedure
Uninstalling the AD4J Console on Windows

Prerequisites

Before you start the installation process, do the following:

You must be running Microsoft Windows 2000, XP, or 2003.
You must download jamserv-win.msi. This is the Microsoft Windows Installer package along with the web listener, client database drivers and utilities, JDK HOME, and postgreSQL database.
You must decide on the location where you want to install the console.
After installation, you must use the following URL to access the console:

http://consolehost:<port_no>
You must download the agent to be deployed on the monitored JVMs.
To log in, you must use the default console setup credentials , admin as the user name and welcome as the password. After you log in, you must change the default password. You can perform operations on the console only the password has been changed.

Installation Procedure

The installation procedure includes the following steps:

Running the jamserv-win.msi File
Selecting the Installation Location
Setting the Console Parameters
Specifying the Port Information

Running the jamserv-win.msi File

As a first step, run the jamserv-win.msi file to invoke the installation wizard. The Welcome screen is displayed. Click Next to continue with the installation.

Note:

Run the upgrade-win.zip if you are upgrading an existing installation.

Selecting the Installation Location

On the Select Installation Folder screen, select a directory where you can install the console. The installer creates a subdirectory called jamserv. To continue, click Next.

Setting the Console Parameters

In the Database Dir field in the Configure JAM Console Parameters screen, select an alternate drive or different location with sufficient space where the database files can be placed. You can specify the path manually or click Browse to select the folder.

If you are using the local built-in database, we recommend that you to select an alternate drive because the database can grow to several gigabytes.

Inside this directory, the installer automatically creates a sub-directory titled pgdata.

Figure 2-5 Set Console Parameters

Specifying the Port Information

After selecting the database directory, you can accept the default values for other parameters. The http port is the port you use in the URL to access the console. The Oracle AD4J Port is what you will provide the Oracle AD4J Agents along with the hostname so that the agents can connect to the console. The Jserv port is used internally by the Console and need not be changed.

You will see the screen scroll as all the files are extracted and the Oracle AD4J Console service installed and started.

Figure 2-6 Installing Oracle AD4J Console Service 1

Figure 2-7 Installing Oracle AD4J Console Service 2

The Installer creates self-signed certificates to enable secure http (https) access on port 443 to the console. When the certificates and the certification authority (CA) are created, you are prompted with the following questions twice. Once when creating the certification authority (CA) and again when creating the certificates.

Table 2-5 Prompted Questions

Country Name	(2 letter code) [XY]:
State or Province Name	(full name) [CA]:
Locality Name	(e.g., city) [Unknown]:
Organization Name	(e.g., company) [Unknown]:
Organizational Unit Name	(e.g., section) [Certificate Authority]:
Common Name	(e.g., CA name) [mymachine01]:
Email Address	(e.g., name@FQDN) [myname@mycompany.com]:

The following is the install output. Note that install prompts you for these questions twice.

Figure 2-8 Install Output

It is important that when creating the certificate (second set of prompts), the Common Name and prompt #5 reflect the server name you use in the URL to access. While the install script tries to determine the host name, you must ensure that the domain is accurate.

For example: If the server name is console01, you can only specify https://console01:XXXX.

You cannot specify https://console01.mydomain.com:XXXX or http://123.123.123.123:XXXX where XXXX is the https port for the Apache listener. You can, however, specify all the above names on the http port

The HTTPS port (default 443) can be changed by changing the following files:

jamserv/conf/httpd.conf

jamserv/conf/ssl.conf

It is strongly recommended that you replace this out-of-box certificate with a certificates issued by a well-known certificate authority.

The installation is now complete and shortcuts to stop and start the console service, load the heaps, and uninstall the product are also available.

Uninstalling the AD4J Console on Windows

To uninstall the AD4J Console on Windows, from the Start menu, click Programs, and JAM Console. Then click Uninstall JADE to uninstall the console.

Post-Installation Tasks

This section covers the following:

Accessing the AD4J Console for the First Time
Setting Up the Console and Diagnostics
Deploying the Agent on Monitored JVMs and Databases

Accessing the AD4J Console for the First Time

If you want to access the console from the host where you installed it, then use the following URL:

http://localhost:3500 or http://localhost:80 (on Windows)

If you want to access the console from a different host, then use the following URL:

http://hostname:3500 or http://hostname:80 (on Windows)

Here, hostname is the host on which you installed the console.

When you access the Oracle AD4J console for the first time, it does the following:

Runs diagnostics
Prompts you for the database connection details for the repository and stores it in the admin.DBProperties file
Creates the necessary DB objects in the repository

Setting Up the Console and Diagnostics

The console must be accessible from the URL http://localhost if accessing from the machine where it was installed. From another machine, it must be accessible from http://hostname where the host name is the machine on which your console is installed. The default password for the admin user is welcome.

When you access the Oracle AD4J console for the first time, it will run Diagnostics.Whenever you click on the Setup tab, it will run Diagnostics. Here, you can see information about the configuration of the console and the errors (if any). For example, if a database connection cannot be established for some reason, it would show up here along with some debug information.

Figure 2-9 AD4J Console Diagnostics

Deploying the Agent on Monitored JVMs and Databases

The agents can be downloaded from the Download Agent screen. To display this screen, select the Setup tab from the console and click Download Agent.

Figure 2-10 Downloading Agents

If you are running the console on a machine with DHCP, and the agent is running on the same machine, you can use the WAR file for deployment on local machine. Otherwise, use the WAR file for deployment on remote machine.