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
From the Windows start menu, choose .
To stop the default broker
From the Windows start menu, choose .
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 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:
To set up SSL
To operate with SSL, certificates need to be provided and maintained. Depending on the platform, Software AG provides default certificates, but we strongly recommend that you create your own. See SSL/TLS Sample Certificates Delivered with EntireX in the EntireX Security documentation.
Modify broker-specific attributes.
Append "-SSL" to the TRANSPORT attribute. For example:
DEFAULTS = BROKER TRANSPORT = TCP-SSL
See also TRANSPORT.
Set the SSL attributes, for example:
DEFAULTS = SSL KEY-STORE = "C:\SoftwareAG\EntireX\etc\ExxAppCert.pem" KEY-PASSWD-ENCRYPTED = MyAppKey KEY-FILE = "C:\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/TLS-specific Attributes and SSL/TLS and Certificates with EntireX.
Make sure the SSL clients connecting to the broker are prepared for SSL connections as well. See Using SSL/TLS with EntireX Components.
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.
| 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 |
Notes:
TRACE-LEVEL without restarting the Broker, use the Broker command-line utility etbcmd.
TRACE-LEVEL without restarting the broker, use Command Central. See Changing the Trace Level Temporarily.
| 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. |
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". |
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.
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.
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.