This document contains information on setting up the Broker under UNIX. It assumes that you have successfully installed EntireX using the Software AG Installer.
This document covers the following topics:
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.
The Administration Service is started or stopped by the broker startup daemon etbsrv.
When the broker has been started successfully, the Administration Service waits for messages from other started brokers. This wait period lasts around 90 seconds.
After this wait period, all brokers are started that have an Autostart value of "yes" that have not already started.
When the Administration Service is restarted, it takes a maximum of 90 seconds until the current system status is displayed correctly.
Note:
The recommended way to set up TCP is to define
TCPPORT=nnnn and optionally
TCP-ADDRESS=x.x.x.x in the Broker attribute file (applies to broker instances other than the default broker, which
is defined during installation).
The EntireX Broker kernel uses getservbyname
to determine the TCP/IP port on which it will listen for incoming connections.
The specified name is the value of the BROKER-ID parameter in the attribute
file.
An entry for this value must be made either in the system-wide DNS, NIS or NIS+ database or the local machine's /etc/services file, for example:
etbnnn yyyyy/tcp # local host
where etbnnn is the BROKER-ID
and yyyyy is the intended port number. This is the
same place that local Broker stubs will obtain the port information. If
getservbyname fails, then a default port number of
1971 will be used. This is the same default port number that the stubs use.
The port number used by the Broker is displayed by the Administration tool. If more than one instance of the Broker uses the same port number, only one of these instances can run at a time.
If check box Turn on Autostart for default EntireX Broker is checked during installation, the default broker ETB001 is started.
To start the default broker
Enter command:
<Installation_Dir>/EntireX/bin/defaultbroker start
To stop the default broker
Enter command:
<Installation_Dir>/EntireX/bin/defaultbroker stop
Note:
Both commands require that you source the EntireX environment file
<Installation_Dir>/EntireX/INSTALL/exxenv[.csh].
Before starting the Broker, it must be configured to correctly use SSL or TLS as a transport mechanism:
Append "-SSL" to the TRANSPORT attribute. For example:
DEFAULTS = BROKER TRANSPORT = TCP-SSL
See also TRANSPORT.
Set the SSL or TLS attributes, for example:
DEFAULTS = SSL KEY-STORE = /opt/softwareag/EntireX/etc/ExxAppCert.pem KEY-PASSWD-ENCRYPTED = MyAppKey KEY-FILE = /opt/softwareag/EntireX/etc/ExxAppKey.pem VERIFY-CLIENT = N PORT=1958
where 1958 is the default but can be changed to any port number.
See also SSL-specific Attributes under Broker Attributes and SSL or TLS and Certificates with EntireX.
A default broker is always created during installation. This broker is started automatically by default. See also Broker Administration using System Management Hub.
Create a subdirectory called ETBnnn under $EXXDIR/etb if it does not yet exist, place the attribute file under ETBnnn and name it etbfile.
Example:
cd $EXXDIR/etb mkdir ETB002 cp /tmp/your attribute file ETB002/etbfile
The Broker can be started by executing shell script etbstart in the /opt/softwareag/EntireX/bin directory, using the syntax:
etbstart ETBnnn
where ETBnnn is the assigned Broker ID (for example ETB001).
The Broker can be stopped by executing the etbcmd utility in the /opt/softwareag/EntireX/bin directory using the syntax:
etbcmd -bbroker-id -dBROKER -cSHUTDOWN
Optional: The Broker can also be shutdown in any of the following ways:
etbcmd -blocalhost:port -dBROKER -cSHUTDOWN
etbcmd -bipaddress:port -dBROKER -cSHUTDOWN
etbcmd -bmachinename:port -dBROKER -cSHUTDOWN
The port number is needed only when Broker does not run on standard port.
See also Broker Shutdown Statistics and Setting up TCP/IP Transport.
Note:
The information given here is independent of hardware type and
platform.
To guarantee that a broker ID is unique on one machine, a named semaphore is created at
initialization. If this semaphore already exists for this broker ID,
initialization is terminated with message ETBE0168, "This instance of
broker already running". If as a result of an abnormal broker
termination this semaphore cannot be deleted completely, you can force a
restart of the Broker with Broker attribute FORCE=YES.
This section covers the following topics:
The Broker TRACE-LEVEL attribute determines the level of
tracing to be performed while Broker is running. The Broker has a master
TRACE-LEVEL specified in the Broker section of
the attribute file as well as several individual
TRACE-LEVEL settings that are specified in the
following sections of the attribute file. You can also modify the different
TRACE-LEVEL values while Broker is running,
without having to restart the Broker kernel for the change to take effect.
For temporary changes to
TRACE-LEVEL without restarting the Broker, use
the System Management Hub or the Broker command-line utility etbcmd.
| Individual Settings | Specified in Attribute File Section |
|---|---|
| Master trace level | DEFAULTS=BROKER |
| Persistent store trace level | DEFAULTS=ADABAS | CTREE | DIV
(currently not available for DIV)
|
| Conversion trace level | CONVERSION
parameter that can be defined in DEFAULTS=BROKER | SERVICE |
TOPIC
|
| Security trace level | DEFAULTS=SECURITY |
These individual TRACE-LEVEL values
determine the level of tracing within each subcomponent. If not specified, the
master TRACE-LEVEL is used.
| Trace Level | Description |
|---|---|
| 0 | No tracing. Default value. |
| 1 | Traces incoming requests, outgoing replies, and resource usage. |
| 2 | All of Trace Level 1, plus all main routines executed. |
| 3 | All of Trace Level 2, plus all routines executed. |
| 4 | All of Trace Level 3, plus Broker ACI control block displays. |
| 8 | All of Trace Level 4, plus Adabas Persistent Store Adabas control blocks. |
Note:
Trace levels 2 and above should be used only when requested by
Software AG support.
It is not always convenient to run with
TRACE-LEVEL defined, especially when higher
trace levels are involved. Deferred tracing is triggered when a specific
condition occurs - such as an ACI response code or a Broker subtask abend. Such
conditions cause the contents of the trace buffer to be written, showing trace
information leading up the specified event. If the specified event does not
occur, the Broker trace will contain only startup and shutdown information
(equivalent to TRACE-LEVEL=0). Operating the
trace in this mode requires the following additional attributes in the Broker
section of the attribute file. Values for
TRBUFNUM and
TRAP-ERROR are only examples.
| Attribute | Value | Description |
|---|---|---|
TRBUFNUM |
3 | Specifies the deferred trace buffer size = 3 * 64 K. |
TRMODE |
WRAP | Indicates trace is not written until an event occurs. |
TRAP-ERROR |
322 | Assigns the event ACI response code 00780322 "PSI: UPDATE failed". |
An optional feature of EntireX Broker is available to protect a Broker
running with SECURITY=YES against
denial-of-service attacks. An application that is running with invalid user
credentials will get a security response code. However, if the process is doing
this in a processing loop, the whole system could be affected. If
PARTICIPANT-BLACKLIST
is set to "YES", EntireX Broker maintains a
blacklist to handle such "attacks". If an application causes ten
consecutive security class error codes within 30 seconds, the blacklist handler
puts the participant on the blacklist. All subsequent requests from this
participant are blocked until the
BLACKLIST-PENALTY-TIME
has elapsed.
Here is a scenario illustrating another use of this feature that is not security-related.
An RPC server is to be shut down immediately, using Broker Command and Information
Services (CIS), and has no active request in the broker. The shutdown results
in the LOGOFF of the server. The next request that
the server receives will probably result in message 00020002 "User
does not exist", which will cause the server to reinitialize
itself. It was not possible to inform the server that shutdown was meant to be
performed.
With the blacklist, this is now possible. As long as the blacklist is not switched off, when a server is shut down immediately using CIS and when there is no active request in the broker, a marker is set in the blacklist. When the next request is received, this marker results in message 00100050 "Shutdown IMMED required", which means that the server is always informed of the shutdown.
