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 webMethods Product Documentation > webMethods Product Suite > Documentation by Product > System Requirements, Installation, and Upgrade on the Software AG Product Documentation website.
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:
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).
directory /opt/softwareag/EntireX/bin is added to the
list of directories in the PATH environment variable
the directory /opt/softwareag/EntireX/lib is added to
LD_LIBRARY_PATH (LIBPATH under
AIX, and SHLIB_PATH under HP-UX).
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 Security, 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.
To install the EntireX Mini Runtime
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 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.
Note:
Do not install the EntireX Mini Runtime over an already installed
EntireX version.
The EntireX Mini Runtime is delivered as archive exxminrt.cpz located in directory /opt/softwareag/EntireX/etc of the installation.
To update the EntireX Mini Runtime
Go to the directory where you installed the EntireX Mini Runtime.
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.
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).
To change the default port of the default broker
Stop the broker, using one of the following methods:
Use System Management Hub. See Stopping a Local Broker.
Source the EntireX environment file <Installation_Dir>/EntireX/INSTALL/exxenv[.csh] and enter command:
<Installation_Dir>/EntireX/bin/defaultbroker stop
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.
Start the broker, using one of the following methods:
Use System Management Hub. See Starting a Local Broker.
Enter command:
<Installation_Dir>/EntireX/bin/defaultbroker start
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.
To start the daemon
Enter the following command:
- /etc/init.d/sag<n>etbsrv start
where <n> is a sequential, installation-dependent number.
This ensures that etbsrv is always running and ready to receive
start/stop commands from System Management Hub agents. Note that the startup
script sag<n>etbsrv sources
the SAG environment file EntireX/INSTALL/exxenv.
To stop the daemon
Enter the following command:
- /etc/init.d/sag<n>etbsrv stop
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.
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.
Start the Broker by executing shell script etbstart in the /opt/softwareag/EntireX/bin directory:
etbstart ETBnn
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.
To verify the installation
Check that EntireX Broker is installed on the target node and is up and running.
Create and run a sample application (see below).
To create and run a sample application
Create and run a sample application provided in the directory /opt/softwareag/EntireX/examples/RPC/basic/example/CServer:
The following steps describe how to run the sample application locally:
Verify that the EntireX environment is adapted to your environment.
Verify that the EntireX Broker stub is installed in your EntireX environment.
Create an example RPC server with the following steps:
Change to directory /opt/softwareag/EntireX/examples/BrokerRPC/RPC/basic/example/CServer.
cd /opt/softwareag/EntireX/examples/RPC/basic/example/CServer
Create the server library with the command
make.
Add this directory to the LD_LIBRARY_PATH (LIBPATH under AIX and SHLIB_PATH under HP-UX).
Modify the configuration server.cfg file to set up the Broker address for your environment.
Start the RPC server with
../../../bin/rpcserver CFG=server.cfg
Create an example RPC client with the following steps:
Change to directory /opt/softwareag/EntireX/examples/RPC/basic/example/CClient.
cd /opt/softwareag/EntireX/examples/RPC/basic/example/CClient
Create the client with the command:
make
The client will be built in the current directory.
Start the RPC client with
client <your_broker>@RPC/SRV1/CALLNAT
Set <your_broker> to the configured Broker of the server configuration.
To verify broker stubs installation
Ensure that you have installed the EntireX Broker on the target node and that it is up and running.
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
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.
| 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 |
BROKER-ID |
| -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 |
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). |
This section describes the environment variables required for Developer's Kit.
To check the definitions of the environment variables
Enter the command printenv.
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. | ||||||
|
This points to the directory /opt/softwareag/EntireX/lib and /opt/softwareag/EntireX/examples/lib to load the shared library at runtime. |
This section covers the following topics:
Note:
You must set up EntireX Security for broker kernel and - if your
application(s) use API version 7 or below - also for broker stubs.
To set up EntireX Security for broker kernel under UNIX
Determine that all prerequisites for EntireX components have been met before setting up EntireX Security. See UNIX Prerequisites.
Insert the following statements into the DEFAULTS=BROKER section of the Broker attribute file:
SECURITY=YES
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.
Note:
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.
Note:
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.
To set up EntireX Security for broker stubs under UNIX
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.
Note:
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.
To use encrypted communication, set the environment variable
NA2_BKPRIV=1. For no encryption, set NA2_BKPRIV=0
(default).
 |
Warning: 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.
To install the Tutorial
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.
Invoke Natural, logon to library SYSETB and issue the CATALL command to catalog all the programs in the library.
