2 Installing Eloquence on the HP-UX platform

Configuring the eloqdb6 server

The eloqdb6 is the Eloquence database server. Eloquence uses a client/server database approach. Previous Eloquence A.05.xx databases can be accessed using the eloqdb5 server.

In order to run the eloqdb6 server it is required to adapt your system configuration. This involves the following steps:

Configuring the eloqdb TCP service

It is recommended, that you define the eloqdb service names in your /etc/services file. This is optional, as you can specify the port number directly in the eloqsd.cfg configuration file.

Please add lines like below to your /etc/services file:

eloqdb     8102/tcp    # Eloquence A.06.00 eloqdb6 server
the first column specifies the service name (eg. eloqdb6) and the second column the associated port number and protocol (eg. 8102/tcp). The selected port numbers may not already be in use by another programs.

NOTE: All systems must use the same port numbers for the same service in order to communicate.

You can have more than one instance of the eloqdb6 server running on a single system, however they must use different services/port numbers.

NOTE: Multiple eloqdb6 instances are covered in detail in the section Setting up multiple eloqdb6 instances below.

Configuring the default eloqdb account and group

The eloqdb6 server requires you to specify an account and group name in the configuration file. Whenever it is started with root capabilities it will switch to the specified account/group instead. This is required, because for one it is generally not a good idea to run programs with root capabilities unless necessary. In addition, all data base volumes are owned by this user and are thus protected from illegal access from other users.

While you can specify any user or group account in the configuration file, we recommend to create a specific user account and group for Eloquence which is used by the eloqdb6 server.

We recommend to create the user account eloqdb and the group eloqdb which should have the account eloqdb as a member. You can configure this with SAM. The account should be marked "disabled" in SAM (which will result in an asterisk in the password) to prevent logins using the eloqdb account.

Configuring the eloqdb6 server startup

If you want to specify that the eloqdb6 server is started at system boot time, set the START_ELOQDB6 variable to 1 in the Eloquence startup/shutdown configuration file /etc/rc.config.d/eloquence6. Change the line defining the START_ELOQDB6 variable like this: 

START_ELOQDB6=1

Configuring the eloqdb6 server

The eloqsd server is configured by editing the eloqdb6.cfg configuration file. It is located in the /opt/eloquence6/etc directory. The eloqdb6.cfg configuration file provides complete inline documentation. The default configuration file is included at the end of this section for your reference.

The default configuration is not optimized for performance and does not handle a large number of concurrent connections. Therefore, you should adjust the following parameters in the eloqdb6.cfg configuration file to your requirements:

UID and GID must be set to the default eloqdb account as explained in the previous section Configuring the default eloqdb account and group.

If the EnableIPC configuration item is set, eloqdb6 is enabled to make use of shared memory for communication between client and server. This results in a 25% performance increase but may require configuring the HP-UX kernel to provide additional resources. For details, please refer to the previous section Configuring the HP-UX system.

The recommended setting is EnableIPC = 2.

This parameter specifies how many connections to the database server can be established concurrently. The default is 40 which means that a maximum of 40 users can access the database at the same time. Multiple programs accessing the database count as multiple connections, while accessing multiple databases from within the same program counts as one single connection.

The recommended minimum value is 64 (megabytes). A higher value is recommended. The current limit is approx. 1 gigabyte. The default and minimum buffer cache size is 5 Megabytes which may lead to bad performance.

Whenever the transaction journal exceeds this size (in megabytes), eloqdb6 performs an internal checkpoint operation to recycle the journal. The default size is 10 megabytes which probably causes the checkpoint to happen too often, causing a performance impact. It is recommended to set this parameter to 20 or higher.

NOTE: If the configuration of a running eloqdb6 server is changed, it must be restarted to activate the new configuration.

Creating the database environment

A database environment consists of at least a primary data volume and a transaction log volume. These must be created on a local disk before the eloqdb6 can be started for the first time.

On HP-UX, the size of a single volume file is currently limited to 2 gigabytes.

Additional data volumes can be created at any time to extend the available database storage. Additional transaction log volumes can be added as well, but it is unlikely that these will ever be used because the purpose of a log volume is to hold temporary data only.

The maximum number of volume files in a database environment is 255 which is equivalent to a maximum database storage size of 510 gigabytes (254 data volumes and 1 log volume).

It is recommended to choose a dedicated directory to hold all volume files belonging to a particular database environment. The following example assumes that the initial volumes are created in the /data/db directory:

  1. Change to the directory where the volumes shall be created:

cd /data/db

  1. Create the initial data volume:

dbvolcreate data.vol

  1. Create the initial transaction log volume:

dbvolextend -t log log.vol

Both files are created with their initial minimum size which is 2.5 megabytes. They will grow on demand until they reach their maximum size. The minimum and maximum size and the amount by which the files shall grow can be configured either at creation time or afterwards with the dbvolchange utility.

To view the available command line options, use:

dbvolcreate -help
dbvolextend -help
dbvolchange -help
The dbvolcreate and dbvolextend utilities automatically maintain the list of volume files in the [Volumes] section of the eloqdb6.cfg configuration file.

The eloqdb6 command line options

The eloqdb6 server supports the following command line options which can be used to temporarily override configured settings in the configuration file.

usage: eloqdb6 [options]
options:
 -help       = show usage (this list)
 -c name     = configuration file
 -d flags    = debug mode
 -l name     = log file name (or console/syslog/default)
 -f          = run in foreground
 -s name     = service name (tcp/ip transport)
 -F facility = syslog facility (USER/DAEMON/LOCAL0..LOCAL7)
 -I ident    = syslog identifier
OptionDescriptionEquiv.*
-c nameSpecifies the configuration file name 
-d flagsSpecifies the server log flags.LogFlags
-l nameSpecifies the server log file.LogFile
-fRun in foreground. This is used for debugging the eloqdb6 server. 
-s nameThe service name (as defined in /etc/services) or the port number where the server should listen for requests. The default value is eloqdb6.Service
-F facilityWhen logging to the syslog daemon, you can define a syslog facility (USER/DAEMON LOCAL0..LOCAL7)SysFacility
-I identWhen logging to the syslog daemon, you can define a syslog syslog identifier. The default is eloqdb6SysIdent

*Equivalent configuration file directive.

The eloqdb6 HTTP status display

When the ServiceHttp is defined in the eloqdb6.cfg configuration file, you can use a web browser such as Netscape or Mozilla to view the configuration and state of the eloqdb6 server in your network.

To access the eloqdb6 server, you need to provide a URL like below:

http://server:port/
where server is the host name or IP number of the system running the eloqdb6 server and port is the port number used for ServiceHttp in the eloqdb6.cfg file.

Setting up multiple eloqdb6 instances

Multiple instances of the eloqdb6 server can coexist on the same system. This makes sense if multiple database environments should be kept separate from each other, either to keep the databases in separate namespaces or simply to maintain discrete database storage.

The following steps are required to setup an additional eloqdb6 server instance:

  1. Each eloqdb6 instance needs a separate configuration file. You can copy either the configuration of any existing instance or the eloqdb6.cfg template file located in the newconfig/config subdirectory of your Eloquence installation.

In this example, we create a new configuration file named eloqdb6.instance.2.cfg in the default /etc/opt/eloquence6 configuration directory. This is not mandatory, the configuration file may have any name and can be located anywhere.

Please note that the cp command below must be entered as a single line:

cd /etc/opt/eloquence6
cp /opt/eloquence6/newconfig/config/eloqdb6.cfg
eloqdb6.instance.2.cfg

Next, the new configuration file must be edited. Besides the parameters mentioned in the previous section Configuring the eloqdb6 server, the following parameters must be adjusted:

* Section [Server], parameter Title

The server title is displayed when you list the eloqdb6 processes with ps. You should specify an unique title for each eloqdb6 instance to be able to distinguish the different instances in the process listing.

* Section [Server], parameter Service

Each instance requires an unique TCP service name or port number. You can either configure a dedicated service name in your local SERVICES file (please refer to the previous section Configuring the eloqdb6 TCP service for details) or simply enter an unique port number.

* Section [Server], parameter ServiceHttp

If you use the eloqdb6 HTTP status display, you are required to configure an unique TCP service name or port number for each eloqdb6 instance.

* Section [Server], parameter LogFile (optional)

By default, all eloqdb6 log messages are written to the syslog. Each log message is labeled with the process id of the originating eloqdb6 instance. However, it might be more convenient to configure a separate log file for each instance. This log file could be located within the dedicated, instance-specific directory (see below), for example:

LogFile = /data/db/instance.2/eloqdb6.log

NOTE: If you copied the configuration of an existing instance, it is required that you manually delete all volume references at the end of the file below the [Volumes] section header.

  1. Create the instance-specific database environment. You do this according to the previous section Creating the database environment, but you use the -c command line option to refer to the instance-specific configuration file:

* Create the instance-specific directory. We recommend to create a dedicated directory for each instance where the instance-specific files are located:

cd /data/db
mkdir instance.2
cd instance.2

* Create the initial data volume (the following command must be entered as a single line):

dbvolcreate
-c /etc/opt/eloquence6/eloqdb6.instance.2.cfg data.vol

* Create the initial transaction log volume (the following command must be entered as a single line):

dbvolextend
-c /etc/opt/eloquence6/eloqdb6.instance.2.cfg -t log log.vol

In this example, the argument to the -c command line option refers to the instance-specific configuration file located in the current directory.

  1. Create an entry for the new eloqdb6 instance at the end of the /etc/rc.config.d/eloquence6 startup/shutdown configuration file:

ELOQDB6_CFG[1]=eloqdb6.instance.2.cfg
ELOQDB6_START[1]=1
ELOQDB6_ID[1]=instance.2

Use the next available index if there is already an instance defined which uses the index [1]. ELOQDB6_CFG refers to the instance-specific configuration file. If this is located outside the default /etc/opt/eloquence6 directory, the absolute path must be provided. If you don't want this instance to be started at system boot time, set the ELOQDB6_START variable to 0.

The new eloqdb6 instance is now configured. You can control it using the /sbin/init.d/eloq6 startup/shutdown script as follows:

/sbin/init.d/eloq6 start instance.2
/sbin/init.d/eloq6 status instance.2
/sbin/init.d/eloq6 restart instance.2
/sbin/init.d/eloq6 stop instance.2
To access a database in an additional instance, specify the instance-specific service name or port number in addition to the database name. Those utilities which do not expect a database name instead provide the -h command line option. Also, the EQ_DBSERVER environment variable can be set to specify the default instance.

The following examples assume that an additional instance was configured to use the port number 8201. They illustrate different ways to address the same instance:

schema -h :8201 db.schema.txt
dbcreate :8201/db
EQ_DBSERVER=:8201
export EQ_DBSERVER
schema db.schema.txt
dbcreate db
Eloquence Installation and Configuration - 29 OCT 2004