Customize the zRemote module

You can customize the zRemote module to enable optional features and optimize its performance.

User configuration files

The following configuration files are retained in the event of a zRemote update or uninstallation. You can make changes here.

zRemote module user configuration

The zRemote module user configuration file (zremoteagentuserconfig.conf) allows you to override the default configuration defined in ruxitagent.conf.

Watchdog user configuration

Dynatrace version 1.277+ The watchdog user configuration file (watchdoguserconfig.conf) allows you to override the default configuration defined in oneagentzwatchdog.ini.

Available parameters for configuration:

Organize LPARs with host groups

Host groups are helpful when you want to organize multiple LPARs connecting to a single zRemote module. An LPAR can be assigned to a host group by setting the [HostGroup] attribute in the zremoteagentuserconfig.conf file. An LPAR can belong to only one host group.

To assign an LPAR to a host group, specify the group name in between a pair of [HostGroup] attributes. The [HostGroup] attribute pair can occur anywhere in the zremoteagentuserconfig.conf file.

[HostGroup]
<LPAR_Name1>=<HostGroupName>
<LPAR_Name2>=<HostGroupName>
[HostGroup]

The LPAR name is the 8 characters logical partition name defined in the LPARNAME() parameter in IEASYMxx member in z/OS.

The following requirements apply to the <HostGroupName> string:

[HostGroup]
LPARA=TEST_HOST
LPARB=TEST_HOST
LPARC=TEST_HOST
[HostGroup]

[HostGroup]
LPARA=TEST_HOST
LPARB=PROD_HOST
LPARC=PERF_HOST
[HostGroup]

Fetch full SQL statements from Db2 databases

Dynatrace can provide insight into SQL statements based on tracing of Db2 and DL/I database calls. These SQL statements are shown in Dynatrace, for example, as:

The string represents the program name (DBRM name), the line number, and the section number.

zRemote module version 1.241+ Dynatrace can provide deeper insight into Db2 database calls by fetching the full SQL statements from the Db2 catalog. With the SQL statement fetch feature enabled, the SQL statements are shown in Dynatrace, for example, as:

Enable SQL statement fetch

The SQL statement fetch feature is disabled by default. To enable it

Enable secure zLocal-zRemote connection

zRemote module version 1.267+

By default, the zLocal and zRemote use a proprietary communication protocol via plain sockets. You can configure them to communicate via TLS by configuring AT-TLS for the zLocal and setting the SSL flags for the zRemote as shown below.

AT-TLS configuration for the zLocal

Depending on your requirements, there are different ways to configure AT-TLS for zLocal. For more details, refer to Application Transparent Transport Layer Security data protection in IBM documentation. You can use the example AT-TLS configuration below as a template.

TTLSRule                       <client-rule>
{
    RemoteAddr                 <ALL | specific-ip-addr>
    RemotePortRange            <zdclistenerport>
    Direction                  Outbound
    TTLSGroupActionRef         <group-action>
    TTLSEnvironmentActionRef   <environment-action>
    TTLSConnectionActionRef    <connection-action>
}

TTLSGroupAction                <group-action>
{
    TTLSEnabled                On
   Trace                       <trace-level>
}

TTLSEnvironmentAction          <environment-action>
{
    HandshakeRole              Client
    TTLSKeyringParmsRef        <keyring-parms>
    TTLSCipherParmsRef         <cipher-parms>
}

TTLSKeyringParms               <keyring-parms>
{
#   A certificate matches that of the zRemote's certificate
#   must be loaded into RACF and connected to the Keyring here.
    Keyring                    <pub-key-or-certificate>
}

TTLSCipherParms                <cipher-parms>
{
    ...
    V3CipherSuites             TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
    V3CipherSuites             TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
    V3CipherSuites             TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
    V3CipherSuites             TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
    ...
}

TTLSConnectionAction           <connection-action>
{
    TTLSConnectionAdvancedParmsRef  <connection-advanced-parms>
}

TTLSConnectionAdvancedParms    <connection-advanced-parms>
{
    SSLv2                      Off
    SSLv3                      Off
    TLSv1                      Off
    TLSv1.1                    Off
    TLSv1.2                    On
    TLSv1.3                    On
}

SSL/TLS settings for the zRemote

To enable SSL/TLS for the zRemote

# Must be true to enable secure connection; all other SSL settings are ignored if false
sslEnabled=true

# Absolute paths to your private key (with the pass-phrase stripped) and certificate PEM files.
# Beginning with zRemote module version 1.301.0, multiple private-key/certificate pairs delimited
# by a semicolon can be specified. For example:
# sslPrivateKey=<private-key-1.pem; private-key-2.pem; ...; private-key-n.pem>
# sslCertificate=<certificate-1.pem; certificate-2.pem; ...; certificate-n.pem>

sslPrivateKey=<private-key.pem>
sslCertificate=<certificate.pem>

# Optional: TLS cipher suites allowed according to OpenSSL
# Example: sslCiphers=ECDHE-RSA-AES128-SHA256:ECDHE-RSA-AES256-SHA384:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384
sslCiphers=<cipher-suites>

Ignore invalid connection attempts

If a specific process regularly pings the zRemote module to detect its availability, and these pings reach the zRemote listener port, the zRemote module logs an invalid connection attempt. These invalid connection attempts increase the zRemote log size over time.

To ignore connection attempts from specific processes, list their IP addresses (separated by semicolons) in the zremoteagentuserconfig.conf file, for example:

ignoreHandshakeEndpoints=192.168.0.1;10.0.0.2

Opt out of new IMS MPR process ID calculation

zRemote module version 1.253+

The IMS message processing region (MPR) process IDs could change, resulting in new process and service entities in Dynatrace. To prevent this process ID change, we’ve introduced a more stable ID calculation with the consequence that all IMS MPR process and service entities will change once but then remain stable after an update of the zRemote module with version 1.253.

To opt out of the new IMS MPR process ID calculation, set the flag useOldImsPgiCalc in the zremoteagentuserconfig.conf file to true.

useOldImsPgiCalc=true