Customizing with the sample job EQAPRFSU

You need to create directories in z/OS® UNIX and copy sample configuration files from the installation directory to these directories for customization. The sample job EQAW.SEQASAMP(EQAPRFSU) is provided to help you complete these tasks.

Follow the instructions within the EQAPRFSU member and submit the job to customize your installation. The job performs the following tasks:
  • Create /etc/debug/* and populate it with sample configuration files.
  • Create /var/debug/* as work directories required to run the service.
  • Set the proper z/OS UNIX file permissions on the files and directories.
The eqaprof.env and dtcn.ports sample files are copied to /etc/debug by the sample job. Edit these files under /etc/debug and customize them to match your system environment.
eqaprof.env
Environment variables that control, for example:
  • Which port to use for the service
  • Whether security is enabled
  • What keystore file is used for encryption
  • The default data set name to be used for EQAUOPTS data set
  • Configurations to use IMS Transaction Isolation API
  • To enable or disable debug logs
  • To configure the number of requests per second to allow or deny into the API (rate limiting)
The following environment variables are available for Debug Profile Service:
Configuration paths for requisite products:
java_dir="java_directory"
Home directory of the 64-bit Java SDK. For example: java_dir="/usr/lpp/java/J11.0_64"
liberty_dir="liberty_directory"
Home directory of IBM z/OS Liberty Embedded. For example: liberty_dir="/usr/lpp/liberty_zos"
Note: Debug Profile Service now runs on IBM z/OS Liberty Embedded instead of Apache Tomcat on z/OS. If you use Apache Tomcat on z/OS previously, replace environment variables tomcat_outfile, tomcat_tmpdir, and tomcat_workdir with liberty_dir.
Environment variables that decide the URL of the service in the format of <protocol>://<hostname>:<port>/<context_path>/<endpoint>:
SECURE="AT-TLS|Y|N"
Enables or disables secure communication. For more information, see Enabling secure communication.
  • SECURE="N": For non-secured HTTP protocol.
  • SECURE="AT-TLS": For secured HTTPS protocol with an AT-TLS policy.
  • SECURE="Y": For secured HTTPS protocol with PKCS12, JCERACFKS (z/OS key ring), or JCECCARACFKS (z/OS key ring). You also need to specify the following keystore parameters:
    keystoreType="keystore_type"
    Type of certificate storage.
    keystoreFile="keystore_file"
    Path name of the keystore file where the server certificate is loaded or the path name of the z/OS key ring.
    keystorePass="password"
    Password to access the server certificate from the keystore file or the key ring.
    • For PKCS12, you can specify the environment variables as below:
      keystoreType="PKCS12"
keystoreFile="$EQAPROF_CFG_DIR/keystore.p12"
keystorePass="liberty"
    • For JCERACFKS, you can specify the environment variables as below:
      keystoreType="JCERACFKS"
keystoreFile="safkeyringjce://STCEQA/EQAPROF.Keyring"
keystorePass="password"
    • For JCECCARACFKS, you can specify the environment variables as below:
      
keystoreType="JCECCARACFKS"
keystoreFile="safkeyringjcecca://STCEQA/EQAPROF.Keyring"
keystorePass="password"
port="port_number"
Port number that Debug Profile Service listens to for incoming requests.
context_path="context_path"
Context path of the URI. context_path="/api/v1" is used as the default if not specified.
Other server configuration paths and files:
enableDebugLogger=true|false
  • enableDebugLogger=true enables debug log prints. This is the default option.
  • enableDebugLogger=false disables debug log prints.
enableRateLimit=true|false
  • enableRateLimit=true enables the rate limiter. This is the default option.
  • enableRateLimit=false disables the rate limiter.
requestsPerSec=request_number
Sets the number of requests per second to allow or deny into the API (rate limiting). For example: requestsPerSec=20.0
If not defined, the number defaults to the values defined in the API.
Environment variables to support the Debug Profile Service API:
default_dsname="naming_pattern"
Naming pattern that the API uses to work with EQAUOPTS data sets. For example, if you specify default_dsname="\&USERID.DLAYDBG.EQAUOPTS", the web server would generate a dataset name as # USRT001.DLAYDBG.EQAUOPTS if the user is USRT001.
dtcn_ports="dtcn_ports_path"
Path name of the configuration file that contains the list of CICS regions. For example: dtcn_ports="$EQAPROF_CFG_DIR/dtcn.ports"
Environment variables to enable the IMS Isolation API so that you can isolate IMS transactions to a private Message Processing Region (MPR). For more information about IMS Isolation API, see Scenario F: Enabling the Transaction Isolation Facility and Batch interface for the IMS Transaction Isolation Facility.
imsiso_dd_eqatipsb=library
A set of comma separated load libraries that the EQANBSWT Batch Message Processing (BMP) program will use. For example: imsiso_dd_eqatipsb=EQAW.SEQAMOD,IMS.SDFSRESL,CEE.SCEERUN
imsiso_dd_syslib=library
For example: imsiso_dd_syslib=SYS1.MACLIB
imsiso_dd_sysproc=library
The debugger's REXX library used to prepare JCL for cloning the MPR job. For example: imsiso_dd_sysproc=EQAW.SEQAEXEC
imsiso_dd_jcllib=library
A library that contains the EQAZPROC PROCLIB dataset member needed to analyze the JCL of an existing message region. For example: imsiso_dd_jcllib=EQAW.SEQATLIB
dtcn.ports
A list of CICS® region names, and their associated TCPIPSERVICE ports that run the DTCN API in the format of <REGIONNAME>:<HTTP_PORT>,HOST=<HOSTNAME>, where:
REGIONNAME
CICS region name
HTTP_PORT
Port number that DTCN API server in the CICS region listens to for incoming requests.
HOSTNAME
Optional: Fully Qualified Domain Name (FQDN) hostname or IP of the DTCN API server in the CICS region.
For example:
CICTS54A:6000
CICTS54B:6001
CICTS54C:6002,HOST=127.1.2.3
CICTS54D:6003,HOST=tempCICShost11.test.ibm.com
For more information on how to set up the CICS TCPIPSERVICE resource for the DTCN API, see Defining the CICS TCPIPSERVICE resource. The resource must be defined with SSL(NO).
Instead of providing the associated TCPIPSERVICE port for a region and using the DTCN API, you can specify a port value of -1 to use external CICS interface (EXCI). For more information, see Defining the CICS EXCI CONNECTION and SESSIONS resources.
keystore.p12
A sample keystore file that contains a self-signed SSL certificate that you can specify as the server certificate when the file type is PKCS12.

You can run the sample job EQAPRFSU more than once. If a file exists in the configuration directory, a backup is created for the existing file before a new one is copied over.