This document contains information on setting up the Broker under z/VSE. It assumes that you have completed the relevant steps described under Installing EntireX under z/VSE. It covers the following topics:

• Setting up TCP/IP Transport

• Running Broker with SSL/TLS Transport

• Setting up Entire Net-Work/Adabas SVC Transport

• Starting and Stopping the Broker

• Tracing EntireX Broker

• Protecting a Broker against Denial-of-Service Attacks

---

Setting up TCP/IP Transport

The recommended way to set up the TCP/IP communicator is to define PORT=nnnn and optionally HOST=x.x.x.x|host_name under TCP/IP-specific Attributes.

However, if no port number is specified in the broker attribute file, the broker kernel will use default port number of 1971. This is the same default port number that the stubs use.

Running Broker with SSL/TLS Transport

Establishing an SSL connection on z/VSE requires BSI's Automatic Transport Layer Security (ATLS). This is a facility similar to Application Transparent - Transport Layer Security (AT-TLS) under z/OS. ATLS is supported by the BSI stack only. Together with SSL parameters (to provide certificates), define ATLS rules for socket interception in the ATLS daemon startup job BSTTATLS . If the rules match, the socket connection is turned into an SSL connection. Refer to your IBM documentation for further information. For an overview, refer to the IBM Redbook Enhanced Networking on IBM z/VSE; for a more detailed description, refer to BSI SSL Installation, Programming and User's Guide.

The figure below illustrates client and server TCP communication:

• EntireX applications - including RPC servers - act as TCP clients, establishing TCP outbound connections

• EntireX Broker acts as a TCP server, establishing a TCP inbound connection

	BSI TCP/IP Stack, either BSTTINET (IPv4) or BSTT6NET (IPv6).
	Automatic Transport Layer Security daemon (BSTTATLS) intercepts inbound and outbound TCP connections and converts them to SSL connections.
	BSTTATLS is associated with the BSI TCP/IP stack.
	A client application using a TCP connection.
	A server application using a TCP connection.

Sample ATLS Daemon Configuration

* Converting inbound EntireX Broker connection 
* Converts listen port 1971 to SSL listen port 1972
OPTION SERVER 
ATTLS 1971 AS 2071 SSL
*
* Converting outbound client connection
* Converts connect to 192.168.2.100:1972:TCP to 192.168.2.100:2072:SSL
OPTION CLIENT
ATTLS 1972 TO 192.168.2.100 AS 2072 SSL

// SETPARM SUBTASK=8

See also BSI SSL Installation, Programming and User's Guide.

For additional information see also Using the BSI TCP/IP Stack under Hints for Setting up Broker JCL in z/VSE in the z/VSE Installation documentation and SSL/TLS and Certificates with EntireX.

Setting up Entire Net-Work/Adabas SVC Transport

To set up EntireX Net-Work communication mechanism

1. Ensure that appropriate values are supplied in the broker attribute file section DEFAULTS=NET, paying particular attention to the IUBL parameter - which specifies the maximum send/receive buffer length that can be sent between an application and Broker kernel within a single request - and NABS, which governs the total amount of storage available concurrently for all users communicating over this transport mechanism. See Adabas SVC/Entire Net-Work-specific Attributes.

2. Ensure that communication with the broker is possible by running the installation verification programs (BCOC, BCOS) using transport type NET. See Verifying the Installation of the Broker in the z/VSE Installation documentation.

Starting and Stopping the Broker

Starting the Broker

To start the broker

• Run job RUNETB.J.

  If the UPSI bit is not set (see Broker installation step Step 4: Customize the EntireX Broker Startup Job Control (RUNETB.J)) you will be prompted on the console with following message: Broker V9.6.0.00 ready for communication: ETB00001.

Stopping the Broker

To stop the broker

• Use the following console command:

  task_id  ETBSTOP

  If the console prompt is suppressed, enter an MSG command before the console command:

  MSG partition_id

Tracing EntireX Broker

This section covers the following topics:

• Broker TRACE-LEVEL Attribute

• Attribute File Trace Setting

• Deferred Tracing

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
Conversion trace level	DEFAULTS=SERVICE; Trace option of the service-specific broker attribute CONVERSION.
Security trace level	DEFAULTS=SECURITY	1
Transport trace level	DEFAULTS=NET | TCP	1
Application Monitoring trace level	DEFAULTS=APPLICATION-MONITORING

Notes:

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 operator command TRACE.

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.

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

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.