Author: Rajesh K. Jeyapaul, Neha Ghongade

Observability is a critical aspect of managing modern enterprise systems, and IBM Instana provides robust tools to monitor and analyze performance across diverse platforms, including mainframe environments. For IBM z/OS, installing the Instana agent through UNIX System Services (USS) ensures seamless integration and monitoring capabilities for WebSphere, Liberty, and JVM applications.

See the following list of supported sensors, which Instana agent can automatically discover on z/OS:

·       Java Virtual Machine

·       WebSphere Application Server

·       WebSphere Liberty

Note: Host metrics monitoring for z/OS is not supported with Instana agent. For more information, see Monitoring host metrics for z/OS.

See the following sections to learn more about installing the Instana agent on z/OS in two scenarios:

·       Online environments (connected to the internet)

·       Air-gapped environments (disconnected from the internet)

Prerequisites

Before installing the Instana Agent, make sure that the following prerequisites are met:

·       z/OS UNIX System Services (USS) is configured and active.

·       The target system supports z/OS V2R4 or higher.

·       You have access to Instana backend Server. For air-gapped the proxy node should have the connectivity to Instana to download the agent from the server.

·       gzip and sed tools.
This tools are available in the USS environment. If you’re installing on online environments, you must also have the curl tool.

You can run the zOS-Agent-Prereq.sh  script to confirm if all the required tools are available for the agent Installation.  To run the script, you must have pax and bash available on the system.

To run the script, complete the following steps:

1.     Download the following files and move them to the z/OS-USS layer by using SCP, SFTP, or by copying and pasting.

·       zOS-Agent-Prereq.sh script file from the Instana GitHub repository.

·       meta-main.XXX.zos.pax.Z file from the metaport GitHub repository.

2.     Switch to Bash shell by using the bash command. Then, run the zOS-Agent-Prereq.sh script with a user with root privilege by using the following commands:

a.     if you moved the script file to the z/OS-USS layer by using SCP or SFTP, then run the following command:

chmod +x ./zOS-Agent-Prereq.sh && chtag -R -tc 819 ./zOS-Agent-Preqreq.sh && ./zOS-Agent-Preqreq.sh

b.    If you copied and pasted the script file to the z/OS-USS layer instead of using SCP or SFTP, then run the following command:

chmod +x ./zOS-Agent-Prereq.sh && ./zOS-Agent-Prereq.sh

3.     When the script prompts, enter the path to the meta-main.XXX.zos.pax.Z file that you downloaded.

The script verifies the prerequisites for installing the Instana agent on a z/OS environment. If any prerequisites are missing, the script downloads them.

Installing in an online environment by using automated one-liner script

In a connected environment, the installation process is automated by using a script that pulls the necessary binaries directly from the Instana backend. To install the host agent by using the one-liner, complete the following steps:

1.      On the home page of the Instana UI, click Deploy Agent.

2.      On the agent deployment catalog page, click the tile z/OS - Automatic Installation (One-liner).

3.      Select the agent packaging mode (Dynamic or Static) that you want to deploy. To understand the difference between static agents and dynamic agents, see Host agent types.

4.     Copy the script to the z/OS-USS layer where you want to install the host agent, and then run the script to install the host agent.

The script is pre-filled with your agent key and host agent endpoint. If you change any option, then the script parameters are automatically updated. See the following sample script to install the agent with the Dynamic packaging option:

curl -o setup_agent.sh https://setup.instana.io/agent && chmod 700 ./setup_agent.sh && chtag -R -tc 819 ./setup_agent.sh -a <your_agent_key> -d <your_agent_key> -t dynamic -e <host-agent-endpoint>

Note: You must first switch to Bash shell by using the bash command before running the script. See One-liner script parameters to know more about agent One-liner script parameters.  

Installing in an air-gapped environment by using automated one-liner script

For secure environments with no internet connectivity, complete the following steps to install and configure the Instana agent:

1.     Download the agent locally

2.     Move the downloaded agent to z/OS – USS layer

3.     Start the agent

Downloading the agent locally

Download the agent package from the Instana UI by completing the following steps：

1.     On the home page of the Instana UI, click Deploy Agent.

2.     On the agent deployment catalog page, click the tile Linux - Archive (tar.gz).

3.     In the Packaging section, select the agent type Static.

4.     In the dropdown list, select the platform architecture (operating system - s390x). The archive file is automatically pre-configured with your Instana account settings so that you only need to extract and start the agent.

5.     Click the download icon to download the host agent package file (tar.gz) from your web browser.

Note : Above approach is subject to change.

Moving the downloaded agent to z/OS-USS layer:

Move the downloaded agent package from your system to the z/OS-USS layer by using SCP or SFTP. See the following example:

scp <path-to-file-instana-agent-linux-s390x.tar.gz> <Username>@<zOS-IP>:/<PATH-TO-COPY-FILE-ON-zOS-USS>

Starting the agent

After you move the agent package to the z/OS-USS layer, you can start the agent by using the setup_agent_airgapped.sh script. Download the setup_agent_airgapped.sh script file from the Instana GitHub repository and move it to z/OS-USS layer.

1.     Switch to Bash shell by using the bash command. Then, run the setup_agent_airgapped.sh script with a user with root privilege by using the following commands:

a.     If you moved the script file to the z/OS-USS layer by using SCP or SFTP, then run the following command:

chmod +x ./setup_agent_airgapped.sh && chtag -R -tc 819 ./setup_agent_airgapped.sh && ./setup_agent_airgapped.sh

b.    If you copied and pasted the script file to the z/OS-USS layer instead of using SCP or SFTP, then run the following command:

chmod +x ./setup_agent_airgapped.sh && ./setup_agent_airgapped.sh

Now the host agent is installed. View the agent on the infrastructure map by clicking View Deployed Agents.

Note: If you see any issues with installing the pax and gzip tools on IBM z/OS, you can manually start the agent instead of using the script. For more information, see Starting the agent manually section in either scenarios (Online/Air-gapped).

 If you notice any issue with the agent installation, raise a support ticket by going to with IBM Support portal and clicking Open a case. To check your existing tickets, click View your cases.