Setting up Broker Instances

This document contains information on setting up the Broker under Windows. It assumes that you have successfully installed EntireX using the Software AG Installer. It covers the following topics:

Startup Service for Broker Administration

When installation is complete, the service is running and ready to be used. It is also registered to start up at boot time.

Start of instruction setTo start the service

  • From the Administrative Tools > Services menu, start the Software AG EntireX Broker Admin 10.9.

Start of instruction setTo stop the service

  • From the Administrative Tools > Services menu, stop the Software AG EntireX Broker Admin 10.9.

Starting and Stopping the Default Broker

If check box Turn on Autostart for default EntireX Broker is checked during installation, the default broker ETB001 is started.

Start of instruction setTo start the default broker

  • From the Windows start menu, choose Software AG > Start EntireX Default Broker.

Start of instruction setTo stop the default broker

  • From the Windows start menu, choose Software AG > Stop EntireX Default Broker.

Running Broker with SSL/TLS Transport

The Broker can use Secure Sockets Layer/Transport Layer Security (SSL/TLS) as the transport medium. The term "SSL" in this section refers to both SSL and TLS. RPC-based clients and servers as well as ACI clients and servers are always SSL clients. The broker is always the SSL server. For an introduction see SSL/TLS, HTTP(S), and Certificates with EntireX in the platform-independent Administration documentation.

Before starting the Broker, it must be configured to correctly use SSL as a transport mechanism:

Start of instruction setTo set up SSL

  1. To operate with SSL, certificates need to be provided and maintained. Depending on the platform, Software AG provides sample certificates, but we strongly recommend that you create your own. See SSL/TLS Sample Certificates Delivered with EntireX in the EntireX Security documentation.

  2. Modify broker-specific attributes.

    Append "-SSL" to the TRANSPORT attribute. For example:


    See also TRANSPORT.

  3. Set the SSL attributes, for example:

     KEY-STORE = "C:\SoftwareAG\EntireX\etc\ExxAppCert.pem"
     KEY-FILE = "C:\SoftwareAG\EntireX\etc\ExxAppKey.pem"

    where 1958 is the default but can be changed to any port number.

    See also SSL/TLS-specific Attributes and SSL/TLS, HTTP(S), and Certificates with EntireX.

  4. Make sure the SSL clients connecting to the broker are prepared for SSL connections as well. See Using SSL/TLS with EntireX Components.

Starting and Stopping an Additional Broker

A default broker is always created during installation. This broker is started automatically by default.

  1. Create a subdirectory called ETBnnn under <Install_Dir>\EntireX\config\etb. If it does not yet exist, place the attribute file under ETBnnn and name it ETBnnn.atr.


    cd <Install_Dir>\EntireX\config\etb
    mkdir ETB002
    copy C:\tmp\your attribute file ETB002\ETBnnn.atr
  2. The broker can be started by executing command utility etbsrv in the <Install_Dir>\EntireX\bin directory, using the syntax:

    etbsrv BROKER START ETBnnn
  3. The broker can be stopped by executing the command utility etbsrv in the <Install_Dir>\EntireX\bin directory using the syntax:

    etbsrv BROKER STOP ETBnnn

    Optional: The broker can also be shut down 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 the broker is not running on the standard port.

    See also Broker Shutdown Statistics.

The information given here is independent of hardware type and platform.

Uniqueness Test for Broker ID

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.

Tracing EntireX Broker

This section covers the following topics:

Broker TRACE-LEVEL Attribute

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.

Individual Settings Specified in Attribute File Section Note
Master trace level DEFAULTS=BROKER 1,2
Persistent store trace level DEFAULTS=ADABAS | CTREE | DIV 1
Conversion trace level DEFAULTS=SERVICE; Trace option of the service-specific broker attribute CONVERSION.  
Security trace level DEFAULTS=SECURITY 1
Transport trace level DEFAULTS=TCP | SSL 1
Application Monitoring trace level DEFAULTS=APPLICATION-MONITORING  


  1. For temporary changes to the master or individual TRACE-LEVEL without restarting the Broker, use the Broker command-line utility etbcmd.
  2. For temporary changes to the master TRACE-LEVEL without restarting the broker, use Command Central. See Changing the Trace Level Temporarily.

Attribute File Trace Setting

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.

Trace levels 2 and above should be used only when requested by Software AG Support.

Deferred Tracing

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".

Dynamically Switching On or Off the EntireX Broker Trace

The following methods are available to switch on or off the EntireX Broker trace dynamically. You do not need to restart the broker for the changes to take effect.

  • etbcmd
    Run command utility etbcmd with option -c TRACE-ON or - c TRACE-OFF. See etbcmd.

  • Command Central
    Use Command Central. See Updating the Trace Level under Administering the EntireX Broker using the Command Central GUI | Command Line.

Trace File Handling

Attributes MAX-TRACE-FILES and TRACE-FILE-SIZE are used to avoid a constantly growing ETB.LOG file. The trace is written to file ETB.LOG until TRACE-FILE-SIZE has been reached and a new file is opened. The number of files defined in MAX-TRACE-FILES is kept in addition to the current ETB.LOG file.

Example: If you define MAX-TRACE-FILES=9 and TRACE-FILE-SIZE=100M, the current ETB.LOG will be closed after 100 MB have been written. A maximum of nine backup files plus the current ETB.LOG file are kept.

Protecting a Broker against Denial-of-Service Attacks

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.

Server Shutdown Use Case

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.

Enabling SSL and Authentication for JMX

When using the Attach Manager (etbsrv), the commands issued are sent locally via a JMX interface to the Broker Administration Service. By default, this communication is not encrypted. To enable SSL-encrypted JMX communication with authentication, strictly follow the steps described here:

Step 1: Shutdown/Stop Broker Administration Service

Shutdown/stop the Broker Administration Service.

Select the Windows service Administration Tools > Services > Software AG EntireX Broker Admin 10.9 <installation_number>, and from the context menu choose Stop.

Step 2: Create Backup of the Config File

Create a backup of the file <Install_Dir>\EntireX\etc\brokeradminwrapper.conf that will be modified in the next steps, for example C:\SoftwareAG\EntireX\etc\brokeradminwrapper.conf.

Step 3: Create a JMX Remote Password File

Start of instruction setTo create a JMX remote password file

  1. Create a new empty file called jmxremote.password at a location of your choice.

  2. Add the following line containing a role and its password to the file you just created:

    controlRole R&D

    Look at your Java installation, which contains the file jmxremote.password.template file (for Java 11, look at %JAVA_HOME%\conf\management). You can copy this template to a location of your choice, rename it to jmxremote.password, and uncomment the last line controlRole R&D by removing the character "#".

  3. We strongly recommend changing the default password (R&D)! If you change the password after you started the Broker Administration Service, make sure to restart the service.

  4. Set the appropriate owner and permissions of jmxremote.password. Make sure you execute the following commands as administrator.

    • Set the owner of the file to the user that starts the Broker Administration Service with the following command:

      icacls .\jmxremote.password /setowner <Username>
    • Restrict permissions of jmxremote.password so that only the file owner set in the previous step can access the file:

      cacls .\jmxremote.password /P <Username>:F

Step 4: Edit the Config File

Edit <Install_Dir>\EntireX\etc\brokeradminwrapper.conf by replacing existing* properties with the following:<PATH_TO_PASSWORD_FILE><PATH_TO_KEYSTORE><KEYSTORE_PASSWORD>

Do not touch, which sets entirex.home property.

After copying and pasting these properties, replace

  • <PATH_TO_PASSWORD_FILE> with the path to the password file you specified in Step 3, for example C:\SoftwareAG\EntireX\jmxremote.password.

  • <PATH_TO_KEYSTORE> with the path to your keystore, for example C:\SoftwareAG\EntireX\etc\ExxJavaAppCert.p12

  • <KEYSTORE_PASSWORD> with the password for your keystore.

We recommend you do not use the default EntireX keystore. For more information see SSL/TLS, HTTP(S), and Certificates with EntireX in the platform-independent Administration documentation.

Step 5: Create a New Properties File

Start of instruction setTo create a new properties file

  1. Create a new file at <Install_Dir>\EntireX\config.

  2. Add the line


    where <ROLE> is the first word from your jmxremote.password file defined in Step 3.
    By default, this is controlRole.

  3. Add the line


    where <PASSWORD> is the second word from your jmxremote.password defined in step 3.
    By default, this is R&D.


    1. This (clear text) password is encrypted when etbsrv is executed. Only the encrypted password value will be visible in the properties file.
    2. To change the password afterwards, delete the property entirex.brokeradmin.client.jmx.password.e and set entirex.brokeradmin.client.jmx.password to match your new password.
    3. If you change the password here, you also need to change the jmxremote.password file as described under Step 3.
  4. Add the line


    where <PATH_TO_TRUSTSTORE> is the path to your SSL trust store, for example C:\SoftwareAG\EntireX\etc\ExxCACert.p12.

    We recommend you do not use the default EntireX keystore. For more information see SSL/TLS, HTTP(S), and Certificates with EntireX in the platform-independent Administration documentation.

Step 6: (Re)Start the Broker Administration Service

Start or restart the Broker Administration Service.

Select the Windows service Administration Tools > Services > Software AG EntireX Broker Admin 10.9 <installation_number>, and from the context menu choose Start or Restart.

Step 7: Test the New Configuration

Start of instruction setTo test the new configuration

  • Run <Install_Dir>\EntireX\bin\etbsrv, for example with parameters BROKER STATUS:

    .\etbsrv.bat BROKER STATUS

    If the call is successful and the broker status is output as shown in the example below, you have successfully enabled SSL-encrypted JMX communication with authentication.