EntireX Version 9.7

Post-installation Steps under UNIX

Under UNIX and Windows, EntireX is now installed using the Software AG Installer, which you download from the Software AG Empower website at http://empower.softwareag.com/. You can view the documentation for the Software AG Installer under http://documentation.softwareag.com > webMethods Product Line > webMethods Product Suite 9.7 > System Requirements, Installation, and Upgrade.

This document assumes you have already installed EntireX using the Software AG Installer. It covers installation instructions for components not included in the Software AG Installer; instruction on how to verify the installation and set up EntireX Security. It covers the following topics:

Shell Environment Settings

EntireX requires some shell environment variables to be set for proper operation. The installation provides two shell scripts exxenv and exxenv.csh in the EntireX/INSTALL directory. Source one of these scripts from within the .profile of the EntireX users.

Sourcing this script, which includes additional environment scripts, defines the following variables:

Variable Description
EXXDIR Identifies the base installation directory for EntireX (typically /opt/softwareag/EntireX)
EXXVERS Identifies the product version. This variable is deprecated and is set to "." for reasons of backward compatibility.
ETBLNK Identifies the absolute path to the broker stubs library if EntireX Broker has been installed: $EXXDIR/lib/broker.so.
JAVA_HOME Identifies the Java directory in the installation.

In addition, the script modifies the environment variables PATH, LD_LIBRARY_PATH (LIBPATH under AIX, and SHLIB_PATH under HP-UX).

Top of page

EntireX Mini Runtime

The EntireX Mini Runtime is a set of components that may be used for the deployment of applications using the Broker ACI, the Broker RPC, and - under Windows only - DCOM Wrapper objects and the Broker ActiveX Control. Unlike the full EntireX Runtime, the Mini Runtime does not include Java capabilities.

The file exxminrt.cpz is always copied during installation. Its target path is /opt/softwareag/EntireX/etc.

Installing the Mini Runtime

Start of instruction setTo install the EntireX Mini Runtime

This command unpacks the Mini Runtime files in a directory EntireX, which in turn contains subdirectories INSTALL, lib and userexits. The INSTALL subdirectory contains setup files exxminrtenv and exxminrtenv.csh that set up the environment required by the Mini Runtime. After unpacking the Mini Runtime, these two setup files must be adapted manually: set the environment variable EXXDIR to the directory to which you unpacked the Mini Runtime.

Make sure that you set the file permissions correctly so that all users who need to access the Mini Runtime have the appropriate access rights.

Do not install the EntireX Mini Runtime over an already installed EntireX version.

Updating the Mini Runtime

The EntireX Mini Runtime is delivered as archive exxminrt.cpz located in directory /opt/softwareag/EntireX/etc of the installation.

Start of instruction setTo update the EntireX Mini Runtime

  1. Go to the directory where you installed the EntireX Mini Runtime.

  2. For Linux, enter command

    zcat < <path-to-minrt>/exxminrt.cpz | cpio -idvB -H newc

    For other UNIX platforms, enter command

    zcat < <path-to-minrt>/exxminrt.cpz | cpio -idmvcB

This command replaces all updated files of the EntireX Mini Runtime. It also replaces the two setup files exxminrtenv and exxminrtenv.csh, so either make a backup of these files or readapt them manually after the update by setting environment variable EXXDIR to the directory to which you unpacked the Mini Runtime.

Top of page

Broker Instance Created Automatically during Installation

If check box Turn on Autostart for default EntireX Broker is checked, the installation starts the default broker ETB001. This broker instance listens on the TCP/IP and SSL ports defined in the custom panel during installation. Default port numbers are 1971 (TCP/IP) and 1958 (SSL).

Start of instruction setTo change the default port of the default broker

  1. Stop the broker, using one of the following methods:

  2. Edit the configuration file config/entirex.configand change the TCP/IP and SSL port numbers to a different value. For other broker instances, see PORT under Broker Attributes.

  3. Start the broker, using one of the following methods:

Top of page

Startup Daemon 'etbsrv'

This daemon runs in the background for the System Management Hub agents to administer broker instances. It is installed as etbsrv in the directory /opt/softwareag/EntireX/bin.

Start of instruction setTo start the daemon

Start of instruction setTo stop the daemon

It is also registered to startup at boot time, therefore the installation generates additional scripts in a location that depends on the operating system

Operating System Location
Solaris, Linux /etc/init.d
AIX /etc
HP-UX /sbin/init.d

See also Broker Administration using System Management Hub.

Top of page

Verifying the EntireX Installation

EntireX Broker

To verify successful installation, you can use the etbcmd utility in the directory /opt/softwareag/EntireX/bin. It checks whether the Broker is up and running and responds to various requests as described below.

  1. Start the Broker by executing shell script etbstart in the /opt/softwareag/EntireX/bin directory:

    etbstart ETBnn
  2. Execute:

    etbcmd -b<broker-id> -cPING -dBROKER

    If successful, the message PING broker broker-id successfully performed is returned.

In a Natural environment, you can also verify correct installation under UNIX by installing the EntireX Broker Tutorial. See Installing the Natural-based EntireX Broker Tutorial under UNIX.

Developer's Kit

Start of instruction setTo verify the installation

  1. Check that EntireX Broker is installed on the target node and is up and running.

  2. Create and run a sample application (see below).

Start of instruction setTo create and run a sample application

Broker Stubs

Start of instruction setTo verify broker stubs installation

  1. Ensure that you have installed the EntireX Broker on the target node and that it is up and running.

  2. Ensure that the variable ETBLNK is set to /opt/softwareag/EntireX/lib/broker.s[o|l] and that the ETB_TRANSPORT variable is set correctly, by entering the command:

    env | grep ET
  3. Enter the commands to run the test programs. In the following example, both programs are run on the local node. The Broker ID is ETB048 and the REPEATS value is 100 (see convClt Parameters below). The value -2 indicates that the Broker is Version 2.1.1 or above.

    cd /opt/softwareag/EntireX/examples/ACI/conversational/C
    convSvr -i100 -bETB048 -2&
    convClt -i100 -bETB048 -2

If you have problems, check that environment variable ETBLNK refers to the Broker shared library in directory /opt/softwareag/EntireX/lib. If not, rerun SAGINST. If you receive error 02150148, verify that the Broker is running on the target machine.

convClt Parameters

Parameter Description ACI Field
-alocale locale_string,environment LOCALE-STRING, ENVIRONMENT
-bbrokerid Broker ID (same as the database ID). This is an EntireX Broker configuration parameter. For example:
convSrv -bETB045
-cclass Server class (part of the server definition). SERVER-CLASS
-eencryptionlevel Values: 0,1,2. Force encrypted communication for client - broker - server. See Encryption under Writing Applications using EntireX Security. ENCRYPTION-LEVEL
-ginput_file_name Use a file as send buffer.  
-irepeats The number of requests that are accepted by the example program before it deregisters. For example:
convSrv -i10
-l Silent mode. Suppress output for every incoming request.  
-ntoken Specify the security token, if desired. TOKEN
-ppacketsize convClt only. The size, in bytes, of the packets that will be transmitted (i.e. size of the send buffer). For example:
convClt -p10000
-rcompression_level Compression level. Values: N|Y|0-9. COMPRESSLEVEL
-sserver Name of server. SERVER-NAME
-uuserid User ID. With a secure broker, this will be used to perform authentication. USER-ID
-vservice Name of service (part of the server definition). The fully qualified server name used by the example program to register. The default is ACLASS, ASERVER, ASERVICE. Values must be configured in the EntireX Broker. SERVICE
-wpassword Password. With a secure broker, this will be used to perform authentication. PASSWORD
-xsslparms SSL parameters. For example:
-x"TRUST_STORE=C:\SoftwareAG\EntireX\ etc\ExxCACert.pem&VERIFY_SERVER=NO"
-1..9 Specify the API version (note that certain features might depend on a specific minimum level). API-VERSION

convSrv Parameters

Most convClt parameters apply to convSrv, too. The following table lists additional parameters or parameters that have a different meaning.

Parameter Description ACI Field
-goutput_file_name Name of output file for receive buffer (if not running in silent mode).  

Environment Variables

This section describes the environment variables required for Developer's Kit.

Start of instruction setTo check the definitions of the environment variables

If the definitions are not correct, set them as described.

Environment Variable Description
EXXDIR This is the top level directory. It is set during the installation procedure.
PATH This points to the directories /opt/softwareag/EntireX/examples/bin and /opt/softwareag/EntireX/bin.
CLASSPATH This points to the current directory and to /opt/softwareag/EntireX/classes/entirex.jar, which contains the class libraries and package for EntireX Java ACI, Java Wrapper, XML/SOAP Wrapper and EntireX Broker Agents.
LD_LIBRARY_PATH (Solaris and Linux)
This points to the directory /opt/softwareag/EntireX/lib and /opt/softwareag/EntireX/examples/lib to load the shared library at runtime.

Top of page

Setting up EntireX Security under UNIX

This section covers the following topics:

You must set up EntireX Security for broker kernel and - if your application(s) use API version 7 or below - also for broker stubs.

Setting up EntireX Security for Broker Kernel

Start of instruction setTo set up EntireX Security for broker kernel under UNIX

  1. Determine that all prerequisites for EntireX components have been met before setting up EntireX Security. See UNIX Prerequisites.

  2. Insert the following statements into the DEFAULTS=BROKER section of the Broker attribute file:

  3. Modify the DEFAULTS=SECURITY section of the Broker attribute file according to your requirements. These parameters are used to determine whether you will use UNIX local security or LDAP-based authentication. See Security-specific Attributes under Broker Attributes. If you are using LDAP-based authentication, authorization rules are not available to you.

UNIX authentication utilizes the /etc/passwd and /etc/shadow files. Functions used are: getspnam() and/or getpwnam(). These functions usually do not return the encrypted password to ordinary processes; therefore, USRSEC employs a daemon process to perform these functions.

The daemon process (sagssxauthd2) must be owned by the "root" user (usually uid = 0) and have the setuid flag enabled. This process will automatically be started at the first authentication request and terminated when the kernel is shut down. In addition if sagssxauthd2 is terminated while the Broker kernel is running, a new sagssxauthd2 will be started automatically, if required.

Setting up EntireX Security for Broker Stubs

If you are running your application(s) at ACI version 7 or below, the following steps are required to install EntireX Security for the broker stubs in all environments where applications execute either as clients or servers. See List of Components per Platform for where EntireX Security for broker stubs is supported.

These steps are not required if you are running your application(s) at ACI version 8 or above.

Start of instruction setTo set up EntireX Security for broker stubs under UNIX

  1. Copy the module secuexit.s[o|l] (depending on platform) from the directory /opt/softwareag/EntireX/examples/lib to the directory /opt/softwareag/EntireX/lib.

    Secuexit.dll is needed for backward compatibility if your applications issue any commands using ACI version 7 or below. Applications using ACI version 8 or above do not require this additional component in the stub.

  2. To use encrypted communication, set the environment variable NA2_BKPRIV=1. For no encryption, set NA2_BKPRIV=0 (default).

If stub tracing level is "> 1", unencrypted contents of the send/receive buffers are exposed in the trace.

Setting of EntireX Security for Broker stubs is now complete. Now you can set up the security components for the Broker stubs on the remaining operating systems where your application components are located.

Top of page

Natural Considerations

Installing the Natural-based EntireX Broker Tutorial under UNIX

Start of instruction setTo install the Tutorial

  1. Use the Natural utility SYSOBJH to load all objects contained in SYSETB.TRA in directory /opt/softwareag/EntireX/etc. See Object Handler in the Natural Tools and Utilities documentation for more information.

  2. Invoke Natural, logon to library SYSETB and issue the CATALL command to catalog all the programs in the library.

Top of page