Customizing with the sample job EQARMTSU

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(EQARMTSU) is provided to help you complete these tasks.

Follow the instructions within the EQARMTSU 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 eqarmtd.env and eqahcc.env 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:

eqarmtd.env

Environment variables that control, for example:

Which internal and external ports to use for the service.
Where to locate the security keystore file for SSL encryption. You can use the sample keystore file from Debug Profile Service located in the /etc/debug directory.
Whether to allow headless code coverage collection, and how many requests per second as well as how many concurrent requests Code Coverage Service allows.

The following environment variables are available for Remote Debug Service:

java_dir="java_directory": Home directory of the 64-bit Java SDK. For example: java_dir="/usr/lpp/java/J11.0_64"

port_internal="port_number": Port number the service listens to for internal debug backend connections from the local z/OS machine. Secure this port with AT-TLS if encryption of localhost-localhost connections is desired.; This port is mandatory.
allow_unsecured_remote_connections="true": Allow the internal port number to also listen for unsecured incoming requests from remote debug clients.; Uncomment this line to enable listening for unsecured remote connections on port_internal.
port_external="port_number": Port number the service listens to for incoming requests from remote debug clients.; AT-TLS can be used to secure this port. This option is mutually-exclusive with port_external_secure.; You must specify either port_external or port_external_secure, but you cannot specify both.
port_external_secure="port_number": Port number the service listens to for secured incoming requests from remote debug clients. This port is encrypted by Java. Do not use AT-TLS to secure this port.; You must specify either port_external or port_external_secure, but you cannot specify both.; Values for TLS keystore and password must be specified when port_external_secure is specified.

keystoreFile="keystore_file"

The fully-qualified path name of the keystore file where the Remote Debug Service TLS server certificate is stored. This keystore can also contain self-signed or internal signing CA certificates that should be trusted when the Remote Debug Service makes authentication calls to the Debug Profile Service.

keystorePass="password"

Password to access the server certificate from the keystore file.

keystorePassFile="keystore_password_file"

Path name of the encrypted keystore password file generated using the z/OS Debugger Password File Generator tool. For more details on this tool, see Generating secure keystore passwords for Remote Debug Service.

Note:

Only specify either keystorePass or keystorePassFile. If both variables are specified, Remote Debug Service will use the encrypted password defined inside the keystore password file.
Specifying keystorePassFile is recommended over keystorePass to prevent storing a password in plaintext.

basicAuth="true"

Allow users to connect using Basic authentication (userid + password).

bearerAuth="true"

Allow users to connect using Bearer/Token authentication (JWT, including MFA).

debugProfileServiceBaseURI="https://localhost:8143/api/v1"

The base URL of the Debug Profile Service instance that will be used to validate JWT tokens used when Bearer/Token authentication is enabled. If the Debug Profile Service is secured and uses self-signed certificates or internal signing CAs, these certificates should be placed in the keystore used by the Remote Debug Service to indicate that they are trusted (see keystoreFile.)

You can comment or uncomment the following parameters:

Diagnostic tracing of service and debug connections:
```
eqarmtd_logdir="$EQARMTD_WRK_DIR/logs"
trace=true
```
Low level tracing of Remote Debug Service application and debug connections:
```
detailedTraceOptions="$EQARMTD_CFG_DIR/trace.options"
detailedTrace=true
```
File permissions in umask format used when you create files or directories
```
umask="u+rwx,go=rx"
```

Headless code coverage and Code Coverage Service options:

headless_cc=true
headless_cc_config=SharedServiceFiles/samples/eqahcc.env
ccs_maxRequestsPerSec=25
ccs_maxConcurRequests=20

eqahcc.env

Environment variables that control, for example:

Whether to start Code Coverage Service. To start Code Coverage Service, configure a port for it. Code Coverage Service automatically uses the same keystore information as Remote Debug Service for SSL encryption.
Code Coverage Service provides a simpler way for users to access the code coverage results that they generate, and eliminates the need for granting access at the file and directory levels.
Where code coverage results are stored. By default, the results are output to $HOME/CC/user_ID, where $HOME is the home directory of the user running Remote Debug Service. You can specify a different root location than $HOME/CC/. Ensure that the code coverage users know the path to this directory to access results and have the following authority:
- A minimum of read access to the parent directory to read their user ID subdirectory root_location/user_ID, where root_location is one of the following:
  - The value for the output property specified in eqahcc.env
  - $HOME/CC, where $HOME is the home directory of the user that is running Remote Debug Service
  The subdirectory and the results within inherit the permissions of the parent directory. You can add user access through group or public permissions. This is not required if users access results using Code Coverage Service.
- Enough authority to change the ownership of z/OS UNIX files. Remote Debug Service changes the owner of both the subdirectory and code coverage results to the user ID. When users do not have authority, results can still be created, but users can only manage any results based on file permissions. This is not required if users access results using Code Coverage Service.
Whether to support only connections from the local host.

For more details on headless code coverage options, see Starting and stopping the headless code coverage daemon. Not all options for headless code coverage are supported in Remote Debug Service. The eqahcc.env file provides all the supported options.

You can run the sample job EQARMTSU 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.