Subcommand: install

Edit online
The install subcommand is used to load the required Z APM Connect Distributed Gateway Docker images into the local image registry. It can also be used to initialize a new configuration file to be used by the Z APM Connect Distributed Gateway.

Syntax

Read syntax diagramSkip visual syntax diagram sudo ./zapmctl install--help-h
Read syntax diagramSkip visual syntax diagram sudo ./zapmctl install--update
Read syntax diagramSkip visual syntax diagram sudo ./zapmctl install --image-dir-dimage-dir--config-file-cconfig-file--force-f--import-i --kafka-keystorekafka keystore path--kafka-truststorekafka truststore path--connmgr-keystoreconnmgr keystore path--connmgr-truststoreconnmgr truststore path --secure-s--fqdnFQDN--log-level-llog-level--add-hosthostname:ip--apmapm-vendor-eZAPM_SMF_DELIMITER="DELIMITER"
Table 1. Flags and command line arguments of the install subcommand
Flags (optional) Arguments Description
-h | --help N/A Prints the usage message and a description of any available options.
-d | --image-dir image-dir Specifies the directory containing the images to load. If unspecified, the default directory <install_dir>/images is used.
-c | --config-file config-file Specifies the target path and filename to initialize a configuration file. If unspecified, the default path and filename INSTALL_DIR/config/ibm_zapm.cfgis used.
-f | --force N/A Bypasses any confirmation prompts. Use with caution.
-i | --import N/A Specifies to import the keystores.
--update N/A Updates images and any required changes to existing configuration file. For more information, see Subcommand: install --update.
--kafka-keystore kafka keystore path Specifies the filepath to the kafka jks keystore.
--kafka-truststore kafka truststore path Specifies the filepath to the kafka jks truststore.
--connmgr-keystore connmgr keystore path Specifies the filepath to the connection manager jks keystore.
--connmgr-truststore connmgr truststore path Specifies the filepath to the connection manager jks truststore.
-s | --secure N/A Specifies that communications between the Z APM Connect DG and z/OS should be secured with TLS.
--fqdn FQDN Specifies the fully qualified domain name.
-l | --log-level log-level Specifies the log level for the Z APM Connect DG. The default value is DEBUG. Valid options are ERROR, WARN, INFO, DEBUG, or TRACE.
Note: Output higher than INFO may produce a large amount of output and is not recommended for production.
--add-host hostname:ip Adds additional host mappings inside the Distributed Gateway container. The argument must take the form [hostname]:[IP address]. This flag can be repeated any number of times to add additional hosts.
--apm apm-vendor Specify which APM vendor should be used for transaction tracking.
-e ZAPM_SMF_DELIMITER="DELIMITER" (For tracking flows into Db2 for z/OS via JDBC) Specify a custom delimiter to replace the default "|" delimiter. This custom delimiter can be any non-alphanumeric character, such as "=", "~", or others. The choice of the delimiter should match the "db2CorrelationDelimiter" set at the Instana agent level to ensure compatibility.

Successful installation

Upon successful completion, the Z APM Connect DG will be installed, fully configured, and started. The following message should be displayed once started successfully:
Distributed Gateway started successfully.

If you run into any issues and need to troubleshoot the Z APM Connect DG installation and configuration, see Troubleshooting Z APM Connect Distributed Gateway. Logs for the application at different logging levels can be used to generate helpful information for identifying and solving issues with the application. For more information about how use the install subcommand to change the log level and retrieve the logs, see Subcommand: start and Subcommand: logs.