Customize the zRemote module

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

Persistent configuration

All features of the zRemote module must be defined in the zremoteagentuserconfig.conf file in order to persist them during the zRemote update process.

Location of the zremoteagentuserconfig.conf file:

LinuxWindows

plaintext
/var/lib/dynatrace/zremote/agent/conf/zremoteagentuserconfig.conf

plaintext
C:/ProgramData/dynatrace/zremote/agent/conf/zremoteagentuserconfig.conf

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.

plaintext
[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 LPAR name is also displayed in the Properties and tags section on the host screen.

The following requirements apply to the <HostGroupName> string:

Can contain only alphanumeric characters, hyphens (-), underscores (_), and dots (.)
Must not start with dt.
Maximum length is 100 characters

Combining three LPARs to a single host group

In this example, we add three LPARs—LPARA, LPARB, and LPARC to a single host group TEST_HOST.

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

Assigning three LPARs to different host groups

In this example we assign each LPAR to a separate host group.

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

In host settings, only the General, Monitoring, and Detected processes menus are applicable for a z/OS host group.
Store your host group settings only in the zremoteagentuserconfig.conf file and migrate your host group settings from the ruxitagent.conf file.
Host group settings take effect during zRemote start up. You must restart the zRemote module after defining host group in the zremoteagentuserconfig.conf file.

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:

FETCH (PROGNAME;165;3)
CLOSE (PROGNAME;441;2)

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

Example for captured SQL statements

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:

FETCH (GETTAB INTO : H , : H , : H , : H , : H)
CLOSE (GETTAB)

Example for captured SQL statements with enabled SQL statement fetch feature

Enable SQL statement fetch

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

Install and configure the IBM Data Server Driver for ODBC and CLI software on Linux or Windows. Further reading: IBM Db2 ODBC CLI driver Download and Installation information.

In the installation step take note of the location of the CLI driver library:
- libdb2.so for Linux
- db2app64.dll for Windows
Before configuring the driver, it might be necessary to contact the DBA requesting the database connectivity information (such as database credentials, location, and IP and port). In the configuration step, take note of the Db2 aliases (or DSN).

Both are required in the next steps.
- The zRemote module supports only 64-bit CLI driver.
- Be sure to test the CLI driver configuration to ensure good Db2 connections, for example:
```
plaintext
\<cli-driver-path\>/bin/db2cli validate -connect -database \<db-location\>:\<ip\>:\<port\> -user \<id\> -passwd \<pw\>
\<cli-driver-path\>/bin/db2cli validate -connect -dsn \<db-alias\>
```
- To configure the CLI driver, you need Db2 credentials that grant access to Db2 connections (from distributed using DDF/DRDA) and grants to select on CATALOG, specifically on SYSPACKSTMT.
In the zremoteagentuserconfig.conf file of the zRemote module, define the CLI driver library and Db2 alias group (similar as defining host groups), for example:
```
plaintext
# Linux
cli_driver_lib=/opt/IBM/CLIDRIVER/lib/libdb2.so
# ... or Windows
cli_driver_lib=C:/IBM/CLIDRIVER/bin/db2app64.dll

[DbAlias]
dbHost1.dbName1=alias1
dbHost2.dbName2=alias2
dbHostN.dbNameN=aliasN
[DbAlias]
```
where dbHost is the z/OS SMF ID and dbName is the Db2 subsystem name. All is case sensitive.
optional Define sqlStmtCacheFileName=/tmp/sqlStmtCacheFileName, as an example, to cache the fetched SQL statements to a file and use it upon a zRemote module restart, thus reducing Db2 interactions. Be sure to use the appropriate fully qualified file name.
Restart the zRemote module.
- The zRemote module will only enable the SQL statement fetch feature if the CLI driver can be loaded successfully and there is at least one DB2 alias defined.
- If the Db2 alias is later found to be invalid, the feature is disabled.

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.

Example of an AT-TLS configuration

plaintext
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

Open the zremoteagentuserconfig.conf file.
Set sslEnabled to true.
Specify the absolute paths to your private key (sslPrivateKey) and certificate (sslCertificate) PEM files.
optional Define specific TLS cipher suites. For information about allowed cipher suite names and their string format, refer to OpenSSL documentation.

Show configuration template

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

# Absolute paths to your private key and certificate PEM files
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:

plaintext
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.

plaintext
useOldImsPgiCalc=true