Example: Installing and configuring Distributed Gateway in interactive mode

Edit online

Run the installation script and respond to prompts to install and configure Z APM for Instana DG onto a distributed Linux® system. This example uses Instana as an APM vendor.

Before you begin

Installing Z APM Connect DG
Configuring Z APM Connect DG
Configuring security between the Z APM Connect DG machine and z/OS® machine

Procedure

Note: The user ID used to install Z APM Connect DG is the only ID that can manage the application.

I. Installing Z APM Connect DG

Create an installation directory if it does not exist. /opt/ibm/ is used as an example in the following steps.
```
mkdir -p /opt/ibm
```
Download 6.1.1-TIV-INSTANA-FP00007-standalone.tar.gz from IBM® Fix Central.

Attention: For performance considerations, do not install Z APM Connect DG on the same Linux system as an Instana server.
Move the installation package to the installation directory and navigate to that directory.
```
mv ./6.1.1-TIV-INSTANA-FP00007-standalone.tar.gz /opt/ibm/
cd /opt/ibm
```
Run the following command to extract it.
```
tar -xvzf 6.1.1-TIV-INSTANA-FP00007-standalone.tar.gz
```
The following files are extracted from this installation package.
```
├── images
│   ├── kafka+3.7.0.tar
│   ├── redis+6.2.14.tar
│   ├── zapm-instana-exporter+6.1.1-7.tar
│   ├── zapm-transaction-processor+6.1.1-7.tar
└── zapmctl
```
Note: If you install from the Z APM package, this directory might contain images for other APM vendors. However, those images will not be used for Instana support and you can safely ignore them.
Run the following command to load the required Docker images into the local repository.
```
sudo ./zapmctl install
```
The installation is successfully completed when the following messages are shown in the command line.
```
Wrote APM vendor selection to "/root/opt/ibm/config/ibm_zapm.cfg"
Loading images from directory "/root/opt/ibm/images"
Loaded image kafka:3.7.0.
Loaded image redis:6.2.14.
Loaded image zapm-transaction-processor:6.1.1-7.
Loaded image zapm-instana-exporter:6.1.1-7.

Installation complete. The Distributed Gateway will now be configured.
```
A log file that is named zapmctl.log is created in the <install-dir> directory to report on the processing of Z APM for Instana DG.
Note: If you install from the Z APM package instead of Instana on z/OS, you will be asked to select which APM vendor to integrate for this installation. In that case, be sure to select Instana.
```
Please select which APM vendor you will integrate with for this installation:
1) AppDynamics
2) Instana
> 
```

When the installation is completed, you are prompted to continue to configure Z APM for Instana DG to connect to the Instana server.

II. Configuring Z APM Connect DG

Use the sudo ./zapmctl configure command to configure Z APM for Instana DG. This command allows you to set up secure communications between the Z APM for Instana DG and any Z APM for Instana z/OS agents, and walks you through setting up all APM Connections you want to configure.

Respond to interactive prompts on the command line to configure Z APM for Instana DG to connect to an Instana server.
Optional: If you want to configure Z APM for Instana DG to another Instana server, respond with 1 and respond to interactive prompts to finish the configuration.
Optional: If you want to update the existing configuration, respond with 2 and respond to interactive prompts to specify new configuration values. Any values specified here overwrite the previous specified values.

After you finish Instana server configuration, respond with 4 to exit. You will be prompted to configure security between the Z APM for Instana DG machine and z/OS machine.

If you respond with n, you can use the sudo ./zapmctl configure security command to secure communications later.

III. Configuring security between the Z APM for Instana DG machine and z/OS machine

Note: If using TLS and the Instana server uses a self-signed or internally-signed certificate, you need to add the signing CA certificate to validate the connection to the Instana server. The certificate can be copied to <install_dir>/certs/HOSTNAME.pem, where hostname exactly matches the hostname of the Instana server. Otherwise, you are prompted to import the certificate during configuration if the Instana server's certificate is unable to be verified. The certificate must be in Base64 encoded .pem format.

Respond with y to start importing matching keystores and truststores.
```
Would you like to use TLS to secure connections to z/OS?
Please enter (y)es or (n)o
> 
```
Note: A keystores and truststores must already exist to be imported into Z APM for Instana DG. Only JKS keystore type is supported.
1. Enter the filepath to Kafka truststore.
2. Enter the filepath to Kafka keystore.
3. Enter the filepath to Connection Manager truststore.
4. Enter the filepath to Connection Manager keystore.
When the Import complete. is shown, you successfully imported all the necessary truststores and keystores.

Results

You successfully install and configure Z APM for Instana DG.

If you run into any issues and need to troubleshoot the Z APM for Instana 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, see Subcommand: start and Subcommand: logs.

What to do next

To start Z APM Connect DG, run the sudo ./zapmctl start command. For more information, see Subcommand: start.

If you configured the security for the Z APM Connect DG machine (acting as the TLS server), continue to configure the security at the TLS client side. For more information, see Configuring secure communications between z/OS components and Z APM Connect Distributed Gateway Linux machine.

When Z APM Connect DG is started, if you need to stop it, run the sudo ./zapmctl stop command. For more information, see Subcommand: stop.