EntireX Broker Security Server for BS2000/OSD

The Broker Security Server authenticates users who log on to EntireX Broker, e.g. it performs a user ID and password check against the operating system. The user ID must exist under BS2000/OSD. Since the server reads information from the user catalog, it requires administrator rights at runtime. The Broker Security Server task therefore needs to run under a privileged user ID (TSOS).

User IDs and passwords are case-insensitive.

The Broker Security Server can handle multiple broker instances on BS2000/OSD.

This document covers the following topics:

Activating Authentication
Starting the Broker Security Server
Stopping the Broker Security Server
Tracing with the Broker Security Server
Broker Security Server Parameters

Activating Authentication

To activate authentication, switch on security in the broker attribute file. Add the following two parameters to ETB-ATTR or, if you use the delivered attribute file, switch the SECURITY parameter to "YES".

SECURITY =YES
ACCESS-SECURITY-SERVER=YES

The Broker Security Server requires administrator rights and must be run under a privileged user ID. Set up the correct broker load library in START-SECURITY-SERVER.

Note:
If ACCESS-SECURITY-SERVER is set to "NO", EntireX Broker itself will do the authentication. In that case EntireX Broker must run under a privileged user ID and the Broker Security Server is not needed.

Starting the Broker Security Server

To start the Broker Security Server

Set up the correct broker library within START-SECURITY-SERVER, because the server task does not usually run under same user ID where the module library resides.
Issue the following command from a privileged user ID (TSOS) to run the server:
```
/ENTER-PROCEDURE *LIB(LIB=$kkk.EXXnnn.JOBS,    - 
/                 ELE=START-SECURITY-SERVER),  - 
/                 JOB-NAME=SECUSERV,LOG=*NO
```
where $kkk is the user ID under which the broker library resides.

Stopping the Broker Security Server

To stop the Broker Security Server from a privileged user ID

Enter:
```
/INFORM-PROGRAM MSG='EOJ',JOB-IDENTIFICATION=*TSN(TSN=tsn)
```
where <tsn> is the BS2000/OSD task number associated with the server.

To stop the Broker Security Server from an operator console

Enter:
```
/INTR tsn,EOJ
```
where tsn is the BS2000/OSD task number associated with the server.

To stop the Broker Security Server from a non-privileged user ID

Enter the following SDF command:
```
/CALL-PROCEDURE (EXX811.JOBS, STOP-SECURITY-SERVER)
```
Note:
This works from all user IDs in the system.

Tracing with the Broker Security Server

The Broker Security Server comes with a trace facility that can be used to track the IDs of users logging on to EntireX Broker. It also produces some diagnostic messages that are helpful for problem analysis. By default, no tracing is performed.

To switch on tracing for Broker Security Server

Set up an SDF variable in the server's job control.
```
TRACE='ON'
```

To switch off tracing for Broker Security Server

Set the following in the server's job control.
```
TRACE='OFF'
```

See EntireX Broker Security Server for BS2000/OSD.

Broker Security Server Parameters

The Broker Security Server uses a global common memory pool for communicating with its clients (broker instances). This common memory pool is established and initialized by the Broker Security Server task. If the pool already exists, the Broker Security Server will not start. This is possible if a client did not disconnect correctly or the Broker Security Server is already running. The message SECE010 "Broker Security Server already active" message is issued. In such a situation, you can use the FORCE parameter to reconnect the Broker Security Server to the security common memory pool. The pool is initialized again, and open requests are deleted, which means that authentication for these clients will fail. The initialization process is indicated by message SECI004 "Running with FORCE = YES, the security CMP will be newly initialized".

Before you set FORCE=YES, make sure that no other Broker Security Server is running.

FORCE='NO/YES'