Installing BES/BDOC on HP-UX

This document describes procedures for installing either BES or the Borland Deployment Op-Center (BDOC) on HP-UX 11i/11.11 (32 and 64 bit).

Important: For BES/BDOC 6.0 Release Notes, go to http://info.borland.com/devsupport/bes/relnotes/6_0.html.

Preparing for installation

Before installing on HP-UX you should:

• check platform requirements
• check system requirements
• check JDK requirements

Platform and system requirements

For the latest platform information and system requirements go to http://www.borland.com/techpubs/bes/platforms.

JDK requirements

The installation package for HP-UX does not ship any version of the Java Development Kit (JDK). For information on Java products for HP-UX go to http://www.hp.com/products1/unix/java/.

Before installing on HP-UX, you must have the following:

• an existing JDK (1.4.2 is supported)

Important: Make sure to put the JDK bin directory into the path variable.

To check the location of your JDK and the version, use the following syntax:

$which java

/opt/local/bin/java

$java -version

java version "1.4.2"

Licensing and Registration

BES and BDOC MUST be licensed before they will run. For information on how to license your product, go to http://www.borland.com/devsupport/bes/faq/6.0/licensing/index.html.

Installing BES/BDOC on HP-UX

To install the BES/BDOC on HP-UX:

1. If you are downloading BES/BDOC from the web site, extract the installer .bin file from the archive.

   BES archives:

   • BDP60_HP64.tar
   • BDP60_HP32.tar

   BDOC archives:

   • BDOC60_HP64.tar
   • BDOC60_HP32.tar
2. Go to the directory where you downloaded the installer and invoke the appropriate command to launch the installer.

   BES:

   • BDP60_HP64.bin
   • BDP60_HP32.bin

   BDOC:

   • BDOC60_HP64.bin
   • BDOC60_HP32.bin

To install from a CD-ROM:

1. Enter the following command to mount the CD-ROM:

   $ cd /mnt/cdrom

2. Enter the appropriate command to launch the installer.

   BES:

   • $ BDP60_HP64.bin
   • $ BDP60_HP32.bin

   BDOC:

   • $ BDOC60_HP64.bin
   • $ BDOC60_HP32.bin

Note: To run in console mode execute the following command:

<install file>.bin -i

.
3. When the installer launches, follow the onscreen installation panels.

Required kernel configuration

HP-UX kernels are typically underconfigured for real world applications, and must be re-tuned.

HP-UX 11.0 is configured by default to allocate only 64 threads to any particular process. The typical symptom of this configuration problem is that the Management Agent and other processes emit errors regarding memory problems or errors regarding an inability to allocate additional threads. You may get the following errors/exceptions:

ias is throwing java.lang.OutOfMemory

Unable to allocate threads

This can be corrected by reconfiguring the kernel using the SAM utility. Borland recommends a minimum configuration of 512 threads per process. You should test your application under load to the verify this meets your requirements.

Change user/group privileges from nobody to a valid non-privileged user/group combination

If you are starting BES/BDOC as root user/group, BES/BDOC automatically switches root to "nobody". HP-UX does not support user/group=nobody. You must change nobody to another valid non-privileged user/group combination for your system. Note, you only need to do this if you are starting from a privileged (root) account.

To change this property directly in the agent.config file:

1. Go to <install_dir>/var/domains/base/adm/properties/agent.config.
2. Change agent.superuser.user=nobody to agent.superuser.user=xxx where xxx is the user name.
3. Change agent.superuser.group=nobody to agent.superuser.group=xxx where xxx is the group name.

File ownership and the iaschangeowner script

Some files and directories, such as log files, properties, sessionSwap, realms, etc., are not created at installation. Instead, they are created at runtime, the first time the server is started. Permissions on these files and directories are granted based on the user running the server at this initial time. For example, if you run the server for the first time as usernameA, some files or directories will be owned by usernameA. Any subsequent running of the server by any other user (including root) will result in error due to permission problems. File ownership must be changed in order to allow any other users to write to these files.

Changing ownership of a server instance

To change ownership use the iaschangeowner script (UNIX only) in the .bin directory of your installed BES or BDOC.

The following directories (and their contents) are affected by the iaschangeowner script:

• <install_dir>/var/templates/configurations/examples
• <install_dir>/var/domains/base/configurations
• <install_dir>/var/domains/base/adm
• <install_dir>/var/repository
• <install_dir>/var/templates

Usage

Below are usage parameters for iaschangeowner.

• -r <install_dir>: the root directory of installation
• -o <new owner>: the user id of the new owner, such as nobody, root, etc.
• -g <new group>: the group id of the new group
• [+a|-a]: configures Apache Web Server to run suid root (a+ or to run as the user UID and group GUID (-a).

Usage example

The following is an example using the iaschangeowner script to change the user name and group:

% iaschangeowner -r /opt/BES -o jsmith -g admin

Failure to change permissions prior to changing server owners will result in errors similar to the following:

<install_root>/sk.txt: cannot create

Configuring Apache to run on a privileged port

Running Apache on a privileged port requires that the executable is owned by root and that the suid bit is set. Apache is dynamically linked and the dynamic loader must resolve and load dependencies. Unix loaders will not typically search libarary paths that are not secure and will not respect environment variables such as LD_LIBRARY__PATH or LIBPATH for setuid programs.

Note: Ownership is not changed on any files or directories when invoking $CMD with the a+ or a-, except on the Apache httpd daemon.

The iaschangeowner script has been modified to make privileged port access as simple as possible. The httpd daemon must be owned by root and must be associated with the root primary group. Consult your system documentation or your administrator for detailed information on these permissions. Typically you can identify the appropriate values using id:

## on Linux, AIX and HP-UX

/> id -n -g root

sys

## on Solaris /> id -a root

sys

The parameters passed to iaschangeowner must match these values. iaschangeowner is using this call internally and will fail if the values don't match.

Invoking CMD +a causes soft links to be created in $SECURE_DIR to appropriate libraries within the specified installation. httpd owner and group affiliation is assigned from the -o and -g parameters passed to $CMD. httpd will be configured to run suid.

Invoking $CMD -a causes soft links to be removed from $SECURE_DIR. httpd owner and group affiliation is assigned from the -o and -g parameters passed to $CMD. httpd permissions will be returned to the installation default.

Configuring Apache httpd.conf to listen on correct port

Important: Use the following only if you do not plan to use mod_iiop. If you want to use mod_iiop, go to Using mod_iiop to access a privileged port below.

The file <inst_root>/var/domains/base/configurations/<configuration_name>/mos/apache/conf/httpd.conf must be edited to listen at the correct port (typically 80) and to indicate what UID and GID to run as. In the following example, elise and elgroup are used:

Listen 80

User elise

Group elgroup

To reverse the changes, give appropriate parameters to the UID and GID, and eidt httpd.conf back to its original state.

Using mod_iiop to access a privileged port

To access a privileged port using mod_iiop, you cannot use BES/BDOC to start or stop the httpd daemon.

You must change the httpd ownership to root and to the appropriate group:

chown root httpd

The httpd daemon can now be started by root using mod_iiop. See your system documentation for more information on starting httpd at boot time.

Installing BES/BDOC on HP-UX using silent installation

Before invoking the silent installation process, you must first create a text file that contains the properties for configuration settings, such as install directory, server name and JDK home.

The text file looks like this (for a BES installation):

INSTALLER_UI=silent

USER_INSTALL_DIR=/opt/BES/HP64/BES

USER_SHORTCUTS=/dev/null

OSAGENT_PORT=14000

MANAGEMENT_PORT=42424

SERVER_NAME=beshp

JVM_JDK_HOME=/jdk/jdk1.4.2

INSTALL_TYPE_1=Borland Enterprise Server (BES)

CONFIGURATION_SETUP=Yes

After you've created the text properties file, save it as <propertiesfile>.fil where <propertiesfile> is the name of your file. Now you can invoke the silent installation process using the values specified in the properties file.

Note: All properties and values are case-sensitive.

Note: ALWAYS use a forward slash (/).

To invoke the silent installation process:

1. Open a command-line shell.
2. Go to the directory where you downloaded the installer and invoke the silent installation process by entering the following command. Make sure to specify the full path name of the propertiesfile file:

   HP32/Install_HP32.bin -f <path to properties file>

   or

   HP64/Install_HP64.bin -f <path to properties file>

   where <path to properties file> is the full path of the propertiesfile file.
3. If installing from CD-ROM:
   • Insert the CD into the CD-ROM drive.
   • Open a command-line shell.
   • Go to the CD-ROM directory.
   • Invoke the silent installation process by entering the following command. Make sure to specify the full path name of the propertiesfile file:

     HP32/Install_HP32.bin -f <path to properties file> or HP64/Install_HP64.bin -f <path to properties file>

     where <path to properties file> is the full path of the propertiesfile file.

Silent install properties file

This properties file applies to silent installation of BES/BDOC on HP-UX. The property file is a plain text file.

Properties file for silent installation

Uninstalling BES/BDOC

To uninstall the Borland Enterprise Server:

1. Make sure there are no background processes like osagent running during the uninstall.
2. Invoke the uninstaller which is available in <install_root>/UninstallerData/uninstall.
3. After you run the uninstall program, check the installation directory and remove any unnecessary files and sub directories.

   Note: Uninstalling does not remove files and folders that were created after the installation.