Abstract

An administration Web GUI has generally always been made available by IBM for Informix Dynamic Server (IDS):

  • Informix Server Administrator (ISA) – written in Perl – was in the installation media up to IDS 11.70.
  • Open Admin Tool (OAT) – written in PHP – co-existing with ISA from IDS 11.10 and was included in Informix Client SDK for Linux and 32-bit Windows up to IDS 12.10.FC9. OAT can still be used with the latest IDS versions but is not secure as it uses Flash and outdated Apache 2.4.2.
  • InformixHQ (HQ) – written in Java – is an HTML5 Web GUI provided with IDS 12.10.FC13 or 14.10.FC1 onwards, and has most of the functionality of OAT, and more.

The Guide describes HQ as “a modern web console for visualizing, monitoring, and managing your Informix server instances”. It is now the only supported tool for control of some Informix internal features, such as tasks scheduled within the database engine. It does not replace AGS Server Studio & Sentinel which has a full SQL development environment and more mature monitoring capabilities.

This article contains recommendations for installation and configuration of HQ. Examples use the latest freely downloadable IDS Developer Edition Docker image (currently 14.10.FC3DE) from Docker Hub.

Content

HQ comprises two pure Java applications (server and agent). The server program contains an embedded Jetty Web server. Java Runtime Environment (JRE) 1.8 (requires subscription for commercial use) must be installed and PATH set accordingly. Type “java -version” to check this. There will be an agent per IDS instance, but you only need one server accessing all of them.

Only IDS 12.10 and 14.10 are fully supported with HQ as it uses the BSON data type. Once you have installed IDS, you should find directory “$INFORMIXDIR/hq” exists unless it’s an older 12.10 version. However, you should replace it with that directory from one of the following versions (at time of writing) if yours is older:

HQ 1.1.0 – IDS 14.10.FC2
HQ 1.1.1 – IDS 14.10.FC3

Otherwise, essential features will be missing, such as control of the Task Scheduler. If necessary, assuming you have appropriate support & maintenance, acquire the latest IDS 14.10 installer for your platform, install it somewhere else, and either run HQ from there or move the “hq” sub-directory into your actual $INFORMIXDIR.

We firstly need to get the HQ server running. It is more convenient to run it on a machine where IDS is already installed, but you could host it on an entirely separate machine if preferred.

In the “hq” directory as user “informix”, create a copy of the server properties file, and make one mandatory change (plus any others you need) as in this example:

Copy to Clipboard

That is usually the only parameter to be changed if you are happy running unencrypted HTTP on port 8080.

Then create the following shell script in the “hq” directory:

Copy to Clipboard

The line export LANG=en_US.utf8 is a work-around to the following defect in HQ 1.1.0 – fixed in 1.1.1 – preventing agents from starting if your default LANG is different (not just DE_DE):

IT30390 “EXCEPTION WHEN RUNNING INFORMIX informixhq-AGENT ON AIX WHEN LANG=DE_DE IS SET”

If the IDS version used for HQ is 14.10.FC3 onwards – or you have replaced HQ with 1.1.1 or a future versi on – and you want it to run with the system’s LANG setting, comment out that line.

The line [ "$env" != "" ] && . ${env}_env.sh is necessary if the script will be used to start agents for more than one IDS instance running on that same machine, which of course will need different values in environment variables INFORMIXSERVER and ONCONFIG. If so, create symbolic links named “${INFORMIXSERVER}_env.sh” to your own environment scripts, or modify the line to use those directly.

You can then start the server with:

Copy to Clipboard

Note that log files are deliberately truncated by the script when starting services as a simple measure to control their size over the longer term.

At this point, we have only created one properties file (excluding those containing “example”), so it will only start the server. Check that the Java process is running with “ps” and look at the new log file created.

Connect to HQ in a Web browser using a URL such as this (depending on the server properties chosen):

Copy to Clipboard

Log in as follows (using your own password if you chose a different one):

Copy to Clipboard

Once logged in, you can confirm the version by pressing the “i” icon in the top right corner:


We can now define the IDS instance and connection details using “Add Server” (see above). If you have a large number of them, you have the option of adding groups first, and then servers within them. In this example, we will be adding just one in the default Root Group. The completed example is:

  • Server ID is auto-generated sequentially, cannot be altered, and does not relate to IDS SERVERNUM.
  • Server Name is whatever you prefer and doesn’t have to match $INFORMIXSERVER, though often will.
  • Hostname can be any name or IP address on which IDS is running a native (not DRDA) TCP listener.
  • Port number can be looked up from the $INFORMIXSQLHOSTS file (default $INFORMIXDIR/etc/sqlhosts).
  • If you have the password, username “informix” is the simplest solution as it always has the required privileges, but that might undermine security.

If another user is chosen, the Adding Servers documentation page states the requirements for monitoring and admin privileges. Note that “Privilege to run SQL Admin API commands” means executing this as “informix”:

Copy to Clipboard

Documentation on the GRANT statement describes how to achieve the other requirements, except for DBSA which normally means adding the user to OS group “informix”. For all functionality, this SQL will also be necessary:

Copy to Clipboard

As always, try to describe privileges using Roles rather than user names directly, which can make it easier to set up multiple users with the same settings, and is considered more secure and best practice.

Before connecting an agent, it is advisable to create a dedicated database to store captured metrics. One database can be shared for agents connected to any number of instances: a separate set of tables is created for each with names containing the HQ Server ID. If you follow the recommendations in this article, the total space allocated shouldn’t exceed 100MB per agent/instance. Best practice has been followed in this example by creating a new database in a dedicated dbspace in advance.

The next step is to define the agent repository for the IDS server you have already added. Navigate as shown below, click on the “Select” button to choose the IDS instance containing the desired database, then select its name underneath, and press “Save”. It will now look something like this:

Note above that the Docker IDS instance is called “informix”, which is a somewhat confusing.

The “Deploy Agent” facility is not recommended for several reasons including:

  1. The server must be connected as user “informix” due to directory permissions.
  2. SSH must be allowed to the agent machine.
  3. Distinct properties and log file names for multiple instances are not supported.
  4. You cannot customise properties.

We will now go through achieving that manually. In the “hq” directory, create the agent properties file and change settings as required. To reduce load, the ping frequency (how often the agent checks the IDS instance is online) has been reduced in this example to once a minute rather than every second.

Copy to Clipboard

On a real system where the HQ server is on another machine and/or there are several Informix instances, the following defaults will need changing:

Copy to Clipboard

If you have more than one IDS instance on the same machine and therefore need to run multiple agents from the same directory, do this for each:

Copy to Clipboard

You will also need to make this change to keep log files separately and consistently named:

Copy to Clipboard

You can then start the agent(s):

Copy to Clipboard

In our simple case with the HQ server and one agent in the same Docker container, you should now have something like these files:

Copy to Clipboard

In a real case with two agents/instances connecting to an HQ server elsewhere:

Copy to Clipboard

Note that the HQ server saves entered configuration details in a local H2 database file ” h2db.mv.db”. Whenever you have made any changes, you should make a backup by copying this and other edited files to another system.

Should you wish to have HQ server and agents start automatically after reboot, add this line to whichever script starts IDS:

Copy to Clipboard

Back in the Web browser, it should now recognise that the agent is connected: