Under UNIX and Windows, EntireX is now installed using the Software AG Installer, which you download from the Software AG Empower website at Empower. You can view the documentation for the Software AG Installer under Cross-Product Guides > Software AG Installer and Update Manager Using the Software AG Installer> in the Software AG Documentation. Alternatively, you can install and configure EntireX using Command Central; see Installing EntireX using Command Central.
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:
See also General Installation Information for topics that apply to multiple operating systems.
EntireX requires some shell environment variables to be set for proper operation. The installation provides the shell script exxenv in the EntireX/INSTALL directory. Source this script from within the .profile of the EntireX users.
Sourcing this script, which includes additional environment scripts, defines the following variables:
|Identifies the base installation directory for EntireX (typically /opt/softwareag/EntireX)
|Identifies the product version. This variable is deprecated and is set to "." for reasons of backward compatibility.
|Identifies the absolute path to the broker stubs library if EntireX Broker has been installed: $EXXDIR/lib/broker.so.
|Identifies the Java directory in the installation.
In addition, the script modifies the environment variables
LIBPATH under AIX).
directory /<Install_Dir>/EntireX/bin is added to the
list of directories in the
PATH environment variable
the directory /<Install_Dir>/EntireX/lib is added to
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 port defined in the custom panel during installation. Default port numbers are 1971 (TCP/IP) and 1958 (SSL), but only the TCP/IP port is enabled by default.
To change the default port of the default broker
Stop the broker, using one of the following methods:
Use Command Central to stop the broker. See Administering EntireX Components with Command Central or the separate Command Central documentation and online help for details.
Edit the configuration file, using one of the following methods:
Start the broker, using one of the following methods:
Use Command Central to start the broker. See Administering EntireX Components with Command Central or the separate Command Central documentation and online help for details.
When installation is complete, the daemon is running and ready to be used by
script located in directory <Installation_Dir>/EntireX/bin. This script can be used, for example, to start or stop the broker.
To start the daemon
Enter the following command:
- <Installation_Dir>/EntireX/bin/sagexx107 start
To stop the daemon
Enter the following command:
- <Installation_Dir>/EntireX/bin/sagexx107 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:
|Recent Linux versions use systemd instead of init scripts.
If you installed EntireX Broker on a UNIX system and did not use sudo, perform the following:
Restart the Administration Service with the following command:
where <number> matches the number in the sagexx107 script in your <Software AG_directory>/EntireX/bin directory.
This section describes how to verify the installation of the following EntireX components:
The following methods are available to verify successful broker installation:
To verify the broker installation
If you have not already created a default broker, create one using Command Central. See Creating a Broker Instance under Administering EntireX Broker using the Command Central GUI.
Start the broker using Command Central. See Starting a Broker Instance under Administering EntireX Broker using the Command Central GUI.
Use one of the following methods to check if the broker is running:
etbinfo to query the broker for information.
Start a Command Prompt session, change your directory to the EntireX
bin directory and use the following
etbinfo -blocalhost -dBROKER -pbroker.pro
This assumes that you use the default port 1971. Otherwise use the command:
port -dBROKER -pbroker.pro
port is the port number of your broker.
This should display a formatted report with information about the broker. If the broker is not active, you get response 02150148 "EntireX Broker not active".
etbcmd -bETB048 -cPING -dBROKER
The broker ID is ETB0248. If successful, the message
PING broker ETB048 successfully performed is returned.
If the broker is not active, you get response 02150148 "EntireX Broker not active".
Use the verification of Broker Stubs. This also verifies EntireX Broker installation.
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
/<Install_Dir>/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. The Broker ID is ETB048 and
REPEATS value is 100. The parameters are described under Sample Programs for Client (
bcoc) and Server (
bcos-i100 -bETB048 -2&
bcoc-i100 -bETB048 -2
If you receive error 02150148 "EntireX Broker not active", verify that the broker is running on the target machine.
bcos are client and server programs provided for test purposes. They are delivered as executables in the <Install_Dir>/Entirex/bin/ directory.
If you have problems, check that environment variable
ETBLNK refers to the broker shared library in directory /<Install_Dir>/EntireX/lib. If the broker is not active, you get 02150148 "EntireX Broker not active".
|Broker ID (same as the database ID). This is an EntireX Broker
configuration parameter. Example:
|Server class (part of the server definition). Default is
ACLASS. Value must be configured in the Broker Attributes.
service it forms the fully qualified server name.
|Use a file as send buffer.
|Display usage information.
num_uows is not specified, the number of messages sent.
num_uows is specified, the number of UOWs and messages therein sent. Example:
|Using conversational mode.
|Silent mode. Suppress output.
|Specify the security token, if desired.
|The size, in bytes, of the packets that will be
transmitted. Used to specify send and receive length in the broker API. Example:
|Compression level. Values:
|Name of server. Default is
ASERVER. Value must be configured in Broker Attributes.
service it forms the fully qualified server name.
|Set the wait time.
|User ID. With a secure broker, this will be used to perform authentication.
|Name of service (part of the server definition). The default is
Value must be configured in Broker Attributes.
server it forms the fully qualified server name.
|Password. With a secure broker, this will be used to perform authentication.
|SSL parameters. For example:
See also SSL/TLS Parameters for SSL Clients.
|Delay between messages in seconds.
|Test unit of work.
|By default, if omitted, the highest possible API version is used. Note that if you specify the API version, certain features might depend on a minimum API version.
bcoc parameters apply to
bcos, too. The following table lists additional parameters or parameters that have a different meaning.
|Name of output file for receive buffer (if not running in silent mode).
num_uows is not specified, the number of messages accepted. If
num_uows is specified, the number of UOWs and messages therein that are accepted before deregistration.
|Test unit of work.
This section describes the environment variables required for EntireX.
To check the definitions of the environment variables
Enter the command
If the definitions are not correct, set them as described.
|This is the top level directory. It is set during the installation procedure.
|This points to the directories /<Install_Dir>/EntireX/examples/bin and /<Install_Dir>/EntireX/bin.
|This points to the current directory and to /<Install_Dir>/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 /<Install_Dir>/EntireX/lib and /<Install_Dir>/EntireX/examples/lib to load the shared library at runtime.
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.
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:
Modify the security-specific section of the broker attribute file according to your requirements. See Security-specific Attributes. These parameters are used to determine whether you will use UNIX local security or LDAP-based authentication.
If you are using LDAP-based authentication, define your authorization rules in LDAP and reference these with Security-specific attribute
UNIX authentication utilizes the /etc/passwd and /etc/shadow files. Functions used are:
These functions usually do not return the encrypted password to ordinary
processes; therefore, USRSEC employs a daemon process to perform these
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.
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 Platform Coverage 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 /<Install_Dir>/EntireX/examples/lib to the directory /<Install_Dir>/EntireX/lib.
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.
The EntireX Mini Runtime is a set of components that can 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 EntireX Mini Runtime is provided as a separate package in the Software AG Installer.
If you need the EntireX Mini Runtime with your application, you may have to extend the path variable
LD_LIBRARY_PATH (UNIX and Linux) or
LIBPATH (AIX) to <inst_root>/EntireX/lib before starting your application.