Parameters for configuration

This topic contains the following groups of parameters and configuration samples:

Global configuration parameters

The global configuration parameters apply to every Security Administrator address space. Global configuration parameters are not defined within a parameter group.
They can be placed inside a SCOPE block to define different values for different address spaces.

Parameter	Description
CustomerID customerName	Customer name This parameter is required.
CustomerKey customerKey	Authorization key for Security Administrator in your installation The key allows Security Administrator to run on your system or systems so the key provided by BMC must be specified correctly using this mandatory parameter. Customer keys comprise eight-character segments separated by hyphens, such as the following: 00000000-00000000-00000000-00000000 If the key exceeds the space available on one line, it can be continued on the next line provided the key is separated after a hyphen. For example: 00000000- 00000000
ClassName FACILITY \| class	Class in which the RACF resources are defined By default, the Security Administrator RACF resources are defined in the FACILITY class. If during product installation you placed the Security Administrator resources in a different class, you should specify it here.
MessageLevel type type type	Type of messages to be output You can specify as many MessageLevel parameters as required or specify multiple types on a single line. The available types are:
Error	Output error messages
Info	Output information messages
HTTPTrace	Traces HTTP traffic generated by user interactions with the Security Administrator browser interface
RACFTrace	Traces all RACF commands and their output responses
TCPTrace	Traces all TCP communications including SSL exchanges when using HTTPS protocol
BufTrace	Traces data in all traced exchanges as well as protocol information
XCFTrace	Traces data sent and received across XCF communications
DLLTrace	Traces DLL calls
SQLTrace	Traces SQL calls
AppTrace	Turns on specific tracing for Security Administrator The recommended settings for normal use are: MessageLevel Error Info\|
Activate component	Component to be activated during Security Administrator initialization For Security Administrator supplied solutions, 'server' should be specified as the component if the HTTP Server interface is defined. 'Activate RACFGUI' should also be defined to start the product.
SMFRecordType type	Type type, specified as a decimal number between 128 and 255
SyslogId ID	ID used in the name field of any SyslogD record written by this instance of Security Administrator The default value is enterpriseConnector.
AuditLogPath pathName	Fully qualified path of the Audit Log file in the HFS or ZFS file system The file will be created the first time the Security Administrator server is started. The Security Administrator server address space must have read/write access to the directory and file.
AuditLogRetention numberOfDays	Number of days that Audit Log records are held in the database before being deleted by Security Administrator
AuditLogOptions Database \| option	Additional Audit Log options to control the type of audit log output If no options are specified, the audit log is written to the SQL database on the path defined on the AuditLogPath statement.
FILE	Sequential file in the AuditLogPath to which the Audit Log is written A new file is opened each day.
SYSOUT class	SYSOUT file with the class to which the Audit Log is written The class may be specified as Default.
DEST destName	Optionally specifies a DEST for the dynamically allocated SYSOUT file
Database	SQL database to which the Audit Log is written This is the default.
AFUNIXPath pathName	Fully qualified path name of the directory where AF-UNIX sockets files will be stored

HTTP server configuration

The parameters described in this section are relevant to the Security Administrator implementations where the HTTP Server is used to support browser-based connections.

The server supports HTTP and HTTPS (TLS/SSL), but only with a limited set of ciphers. For secure (TLS/SSL) connections, BMC strongly recommends this is implemented using the IBM AT-TLS component of TCPIP where full TLS/SSL ciphers are supported.

If the HTTP Server is to be used, an "Activate Server" configuration statement must be coded in Global configuration parameters.

The HTTP server parameters must be defined within an HTTPServer group:

Parameter	Description
HTTPServer	Heads a block of HTTP Server definitions
Protocol HTTPS \| HTTP	This mandatory parameter specifies whether Security Administrator uses HTTPS or HTTP in exchanges between logged-on users and the Security Administrator server on z/OS. Best practice BMC recommends the use of the IBM AT-TLS option for securing connections. You should specify HTTP if AT-TLS is used.
Port nnnnn	This mandatory parameter defines the port on which the Security Administrator server listens for incoming browser connections. Any available and valid port number may be used. You must select an appropriate and currently unused port number since without it users will be unable to log on and use Security Administrator.
Keyring RACF_keyring_name \| HFS_path HFS_stash	This parameter is only relevant if you specified HTTPS for the Protocol parameter above. For connections secured through AT-TLS, the certificate to be used is defined in the AT-TLS policy. Security Administrator supports both RACF and HFS-based keyrings for private keys and certificates. If you are using these in your Installation, specify this parameter to tell Security Administrator where to obtain certificate/password data. Best practice BMC recommends the use of the IBM AT-TLS option for securing connections. You should specify HTTP if AT-TLS is used.
Label certificate_labelname	This parameter is only relevant if you specified HTTPS for the Protocol parameter above. For connections secured through AT-TLS, the certificate to be used is defined in the AT-TLS policy. Specify the label of the certificate to be used by Security Administrator. If this parameter is omitted, Security Administrator uses the default label in the keyring. This parameter is case-sensitive and if specified must exactly match the label as originally defined irrespective of the keyring type. For HFS keyrings, if only a single certificate exists, it is assumed to be the default certificate. RACF keyrings have no default certificate unless one of the certificates was added with the 'DEFAULT' keyword. This may mean that for RACF keyrings, the Label parameter will be mandatory. Best practice BMC recommends the use of the IBM AT-TLS option for securing connections. You should specify HTTP if AT-TLS is used.
Buffersize size	Overrides the default maximum buffer size (4096 bytes) for receiving HTTP header data
EndHTTPServer	Terminates the block of HTTP server definitions

REST API configuration

The parameters described in this section are relevant to the BMC AMI Resident Security Server (RSS) implementations where a REST API has been supplied.

The REST API only supports HTTP. For secure (TLS/SSL) connections, BMC strongly recommends this is implemented using the IBM AT-TLS component of TCPIP where full TLS/SSL ciphers are supported.
The REST API parameters must be defined within a RESTApi group:

Parameter	Description
RESTApi	Heads a block of REST API definitions.
IPAddress ipaddress	This parameter defines the IP address on which the RSS REST API listens for incoming transactions. If this parameter is omitted, transactions will be accepted on any valid IP address available on the LPAR on which RSS is running.
Port nnnnn	This mandatory parameter defines the port on which the RSS REST API listens for incoming transactions. Any available and valid port number may be used. You must select an appropriate and currently unused port number since without it users will be unable to log on and use RSS.
AppName name	This mandatory parameter defines the name of the application to process incoming REST API transactions. The name must match the name of an application that is defined on the CustomApp configuration statement.
EndRESTApi	Terminates the block of REST API definitions.

Remote server configuration

These parameters are used to specify the details of remote RSS running on another LPAR or Sysplex. They are typically used by RSS applications to replicate commands or requests to remote RSS instances.

The servers must be defined within a 'Servers' block:

Parameter

Description

Servers

Heads a block of Server definitions

name protocol IPaddress:port

Defines a server entry where:

Parameter	Description
name	Name of the remote RSS This name is used for display purposes and does not have to match any other value.
protocol	Protocol, either HTTP or HTTPS, used by the target RSS system (and therefore specified on its protocol parameter)
IPaddress	IP address of the target RSS
port	Port number on which the target RSS is listening for inbound connections Use a colon to separate the port number from the IP address.

EndServers

Terminates the block of Server definitions

Event target configuration

These parameters are used to specify the details of external systems to receive events generated by Security Administrator. Every event generated by Security Administrator is assigned a severity. Multiple target systems can be defined to receive events, filtered by severity.

Security Administrator also supports routing events to the MVS Console and the local Syslog Daemon as well as external SIEM systems.

The target systems must be defined within an 'EventTarget' block. One EventTarget block is required for each target system:

Parameter	Description
EventTarget	Heads a block of definitions for a single target system
Name targetName	Assigns a name to this target system This name is only used for reference purposes and does not have to match any name on the target system. There are two reserved names for use by Security Administrator: Console: Events written to MVS console Syslog: Events written to Syslog Daemon
Severity severity severity severity	Specifies one or more event severity filters for events forwarded to this target system The severity is set by Security Administrator when generating the event/alert. The severity name follows the priority value defined in the Syslog RFC 5424. Valid Severity names are: Emergency Critical Alert Error Warning Notice Info Debug
Format Console \| Syslog \| JSON	Defines the format in which the event will be forwarded to the target system
Host Local \| Ipaddress	Defines the IP address of the target system to which the event is to be set Local should be specified (with Format Syslog) to write the event to the z/OS SyslogD daemon
Port portNumber	Defines the port on the target system to which the event will be sent
Protocol UDP \| TCP	Defines whether the event will be sent to the target system using the TCP or UDP protocol
Encoding ASCII	Defines whether the event text will be converted to ASCII before sending to the target system
EndEventTarget	Terminates the definition of a single target system

SyslogD server configuration

These parameters are required when Security Administrator is to operate as a SyslogD server. The configuration of a remote SyslogD server (on z/OS or other operating systems) can specify these details to forward SyslogD messages to Security Administrator for post-processing.

The SyslogD server definitions must be defined within a 'SyslogServer' block:

Parameter	Description
SyslogServer	Heads a block of Syslog Server definitions.
IPaddress ipAddress	Defines the IP address on which the Security Administrator SyslogD server will listen. This must be a valid IP address on the LPAR on which Security Administrator is running. If there is already a SyslogD server running on the LPAR, a VIPA or application-specific VIPA address can be used to route specific SyslogD messages to Security Administrator.
Port port	Defines the UDP port on which the Security Administrator SyslogD server will listen. This must normally be defined as 514.
EndSyslogServer	Terminates the block of Server definitions.

Custom app configuration

A custom app configuration defines a custom application that works with the RSS.

The parameters define the name of the application and the application DLL to be loaded.
The custom application parameters must be defined within a CustomApp group:

Parameter	Description
CustomApp	Heads a block of custom app definitions
AppName Name	Name for this application The name defined may be referenced by other configuration statements.
AppMenu menuLabel	Name of the application-supports requests coming in via the RSS HTTP server The name defined will be displayed on the main menu following a successful login to the server.
DLL dllName	Name of the DLL for this application This DLL must reside in the STEPLIB of the RSS started task.
EndCustomApp	Terminates the block of custom app definitions

Custom server configuration

A Custom Server configuration is used to define a custom RSS. server application. These parameters define the protocol used by the server and any additional parameters required by the server. The custom server parameters must be defined within a CustomServer group:

Parameter	Description
CustomServer	Heads a block of custom server definitions
Protocol protocol	Protocol used by the custom server The values supported are defined in the specific custom server definition.
Port portNumber	Port number on which the custom server listens for incoming connections Any available and valid port number may be used.
Keyring racfKeyringName \| hfsPath hfsStash	Relevant if the custom server wishes to communicate over TLS or SSL, for connections secured through AT-TLS, the certificate to be used is defined in the AT-TLS policy RSS supports both RACF and HFS based keyrings for private keys and certificates. If you are using these in your Installation, specify this parameter to tell RSS where to obtain certificate/password data. Best practice BMC recommends the use of the IBM AT-TLS option for securing connections. You should specify HTTP if AT-TLS is used.
Label certificate_labelname	This parameter is only relevant if the custom server wishes to communicate over TLS or SSL. For connections secured through -AT-TLS, the certificate to be used is defined in the AT-TLS policy. Specify the label of the certificate to be used by RSS. If this parameter is omitted, RSS uses the default label in the keyring. This parameter is case-sensitive and if specified must exactly match the label as originally defined irrespective of the keyring type. For HFS keyrings, if only a single certificate exists, it is assumed to be the default certificate. RACF keyrings have no default certificate unless one of the certificates was added with the 'DEFAULT' keyword. This may mean that for RACF keyrings, the Label parameter will be mandatory. Best practice BMC recommends the use of the IBM AT-TLS option for securing connections. You should specify HTTP if AT-TLS is used.
ServerID name	This mandatory parameter assigns a name to this RSS custom server. If multiple custom servers are defined, this name must be unique.
Handler DLLname	This mandatory parameter specifies the name of the DLL routine to handle the custom server operations. This DLL will be supplied as part of the custom project.
EndCustomServer	Terminates the block of custom server definitions.

AutoStart configuration

These optional parameters can be used to control the automatic starting and stopping of other RSS address spaces when the Server address space is started. This option would typically be used where RSS TSO address spaces are required to perform REXX services on behalf of the Server address space.

The definitions must be defined within an 'AutoStart' block:

Parameter	Description
AutoStart	Heads a block of Auto Start definitions
Start * \| LPAR procName procStep	Procedure to be automatically started and the LPAR within the Sysplex on which it is to be started An '' specified for the LPAR represents the system on which RSS is running. The procName* must be a member of the PROCLIB concatenation. The started task will be started on the system specified with the step name specified.
EndAutoStart	Terminates the block of Auto Start definitions

Email configuration

These optional parameters can be used when a RSS application wishes to generate emails. Emails can be sent directly to an SMTP server or can be routed via the JES spool and processed by standard IBM email systems such as SMTP and CSSMTP.
The parameters define the default email settings which, except for the SMTPServer address, may be overridden in the application.

The definitions must be defined within an 'EmailProfile' block:

Parameter	Description
EmailProfile	Heads a block of email default definitions
SMTPServer IPAddress	When RSS sends direct to an SMTP server, this parameter defines the IP address of the server
SysoutClass class \| Default	Target sysout class or Default Default is the equivalent of 'SYSOUT=*' in JCL. This parameter is used when RSS directs emails to the JES spool.
SysoutDest sysId	Destination system This must be a valid JES node name on which the IBM SMTP/CSSMTP job is running. This parameter is the equivalent of the JCL 'DEST=' statement. This parameter is used when RSS directs emails to the JES spool.
SysoutWriter writerName	External writer name for the IBM SMTP/CSSMTP job This parameter is the equivalent of the JCL DEST=(dest,writerName) statement. This parameter is used when RSS directs emails to the JES spool.
FromEmail originEmailAddress	Email address to be used as the origin or sender email address
FromName name	Name of the email sender
Subject subjectText	Default email subject text.
EmailCustomField fieldName	Name of the RACF custom field that contains the email address of the user This custom field is used by various RSS applications to determine the email address for a specific user.
EndEmailProfile	Terminates the block Email definitions

Alias table

The alias table is optional and defines alias definitions used by RSS applications and REXX procedures. The alias name is used by the application to translate a generic name into a system-specific value.

The alias definitions must be defined within an 'AliasTable' block:

Parameter	Description
AliasTable	Heads a block of Alias definitions.
Alias AliasName SpecificName	Defines an alias name and the specific name it will be translated into. The alias names are defined by the application or REXX procedure using this feature.
EndAliasTable	Terminates the block of Alias definitions.

Variable map

The variable map is optional and can be used to map variable names in incoming JSON or XML streams into REXX variable names. This is typically used with the REST API of RSS when REXX procedures are used to handle the incoming transactions.

Within the block, multiple variable mappings can be defined. Multiple variable map blocks can be defined to map variables from different transaction types.
The variable maps must be defined within a 'VariableMap' block:

Parameter	Description
VariableMap name	Heads a block of variable map definitions. The name field defines a name for this instance which can be referenced by the application when matching transaction types to variables.
Incomingvariable REXXvariable	Maps the fully qualified incoming variable name specified into the REXXvariable name specified.
EndVariableMap	Terminates the block of variable map definitions.

Security Administrator parameters

For the Security Administrator product, some additional configuration parameters are required. These parameters are used to specify specific Security Administrator settings and are not required for other RSS components:

Parameter	Description
racfGUIParms	Heads a block of Security Administrator definitions.
ChangeRef None \| Optional \| Mandatory	This parameter controls the presence of a Change Reference input field on every Command Confirmation window displayed by the on-line browser interface. By default, and when 'ChangeRef None' is specified, there is no provision of a Change Reference input field on the Command Confirmation window. If you specify Optional for this parameter, an input area is provided on the Change Confirmation window into which you can optionally enter an installation-specific change reference for the command that Security Administrator is about to issue. The command will still be issued even when the Change Reference field is left blank. To provide the Change Reference input area but ensure that every command issued by Security Administrator has an associated reference keyed, specify Mandatory for this parameter. When the ChangeRef parameter is mandatory, you will not be able to issue the command until the input field has been completed with a change reference. When keyed, the Change Reference field contents are written into the Audit Log along with a record of the associated command that was issued.
SearchLimit nnnnn	When you use the icon provided on the search results panel to list user names for multiple user IDs, for performance reasons a default limit of 5000 is placed on the maximum number of names to be processed. This default value can be modified by specifying your required value using the SearchLimit parameter.
EndracfGUIParms	Ends a block of Security Administrator parameters
TSOProfile	Heads a block of TSO definitions
TSOCommand command	TSO command, up to 80 characters, that is issued at TSO/E logon time, for example, ISPF
TSOProcedure procedure	Name of the logon procedure when logging on through the TSO/E logon panel The name must be at least 1 and up to 8 alphanumeric characters and begin with an alphabetic character, for example, TSOPROC.
TSORegionMax nnnnnnn	Maximum region size in kilobytes that the user can request at logon time The value must be an integer between 0 and 2096128.
TSORegion nnnnnnn	Minimum region size in kilobytes if the user does not request a region size at logon The specified value must be an integer between 0 and 2096128.
OMVSProgram path	z/OS Unix Shell Program path This is the first program started when the TSO OMVS command is entered or when a batch job is started using the BPXBATCH program. The path is from 1 to 1023 characters and all characters are allowed. For example: OMVSProgram /bin/sh
OMVSPath path	User's z/OS Unix initial directory path name This is the current working directory for the user's process when the user logs on to TSO. Example: -OMVSPath /u/tsgxx
EndTSOProfile	Ends a block of TSO Profile definitions

Sample configuration parameters

Here is an illustration of sample RSS configuration data set members using some of the parameters described in the preceding sections.

The sample uses different members to illustrate how multiple members are used, but all configuration parameters could be saved in a single member.

Sample global member

*********************************************
* Global Parameters                         *
*********************************************
CustomerIDACUSTOMER
CustomerKey8271483C-EF344D5B-39B7467C-2A4F6D32
MessageLevelError Info
SMFRecordType230

ActivateServer

AuditLog/var/log/auditlog
AuditLogRetention 30

*********************************************
* Server Parameters                         *
*********************************************
ScopeServer.SYS1
IncludeSRVSYS1
ScopeServer.SYS2
IncludeSRVSYS2
*********************************************
* Server Settings                           *
*********************************************
ScopeServer
IncludeSRVLIST
IncludeCUSTAPP
IncludeRESTAPI
Include SYSLOGD
IncludeTARGETS
IncludeVARMAP
IncludeEMAILDEF

Sample HTTP server member (SRVSYS1)

*********************************************
* HTTP Server Configuration                 *
*********************************************
HTTPServer
  ProtocolHTTPS
  Port8181
  KeyRingRSMECRING
  LabelECSYS1
EndHTTPServer

Sample REST API Member (RESTAPI)

*********************************************
* REST API Configuration                    *
*********************************************
RESTAPI
  IPAddress192.168.1.25
  Port8182
  AppNameDEMOAPP
EndRESTAPI

Sample server list member (SRVLIST)

*********************************************
* Remote Servers List                       *
*********************************************
Servers
  Developmenthttps 192.168.152.43:8181
  Productionhttps 192.168.145.22:8181
  DRSitehttps 192.168.120.23:8181
EndServers

Sample event targets member (TARGETS)

*********************************************
* Event Targets                             *
*********************************************
*********************************************
* Send to MVS Console                        *
*********************************************
EventTarget
NameConsole
SeverityEmergency Critical
EndEventTarget

*********************************************
* Send to SyslogD                           *
*********************************************
EventTarget
NameSyslog
HostLocal
FormatSyslog
SeverityEmergency Critical Alert Error
EndEventTarget

*********************************************
* Send to Splunk                            *
*********************************************
EventTarget
NameSplunk
Host192.168.130.65
Port8000
ProtocolUDP
FormatSyslog
EncodingASCII
SeverityEmergency Critical Alert Error Warning
EndEventTarget

Sample SyslogD member (SYSLOGD)

*********************************************
* SyslogD Server Configuration              *
*********************************************
SyslogDServer
  IPAddress192.168.152.43
  Port514
EndSyslogDServer

Sample custom app member (CUSTAPP)

*********************************************
* Custom Application Defintion              *
*********************************************
CustomApp
  AppNameDEMOAPP
  DLLDEMODLL
EndCustomApp

Sample AutoStart member (AUTOLOG)

*********************************************
* Autostart Table                           *
*********************************************
AutoStart
Start * ECTSO
  StartRSM1 ECTSO TSO2
  StartRSM2 ECTSO TSO3
EndAutoStart

Sample email defaults (EMAILDEF)

*********************************************
* Email Defaults                            *
*********************************************
EmailProfile
  SysoutClass B
  SysoutDest RSMN
  SysoutWriterSMTP
  FromEmailRSS@abcbank.com
  FromNameResident Security Server
  EmailCustomFieldEMAIL
  SubjectSystem Alert
EndEmailProfile

Sample alias table (ALIASTAB)

*********************************************
* IAM Alias Table                           *
*********************************************
AliasTable
Alias Production RSM1
  AliasDevelopment RSM2
  AliasTest        RSM3
EndAliasTable

Sample variable map (VARMAP)

*********************************************
* Variable for Transaction ADDUSER *
*********************************************
VariableMap
User.name REXXvar1
User.emailREXXvar2
User.deptREXXvar3
EndVariableMap

Sample Security Administrator member (racfGUI)

*********************************************
* racfGUI Configuration *
*********************************************
racfGUIParms
ChangerefOptional
EndracfGUIParms