Installing the host agent on IBM i

Ensure that the following prerequisites are met:

• Make sure that you install the following licensed programs in your system:

  • 5770-SS1 option 30, QSHELL
  • 5770-SS1 option 33, PASE
  • 5770-JV1, IBM Developer Kit for Java: Option 17 for Java 8 or option 19 (On IBM i 7.5 and earlier) for Java 11.

• Install some open source packages in IBM Portable Application Solutions Environment (PASE) for i. For more information about open source packages on IBM i, see RPM pile for IBM i releases in standard support. You can use the Open Source Package Management in IBM i Access Client Solutions (ACS) to install these packages in PASE. The necessary packages are installed by default. You must also install the following packages:

  • Bash
  • Tar-GNU (to extract the agent archive).

Check whether the local monitoring of IBM i can meet your goal by viewing the following list of supported sensors, which can be automatically discovered on IBM i. If not, use the remote monitoring of IBM i. For more information, see Monitoring IBM i instances.

• IBM i
• DB2 for IBM i
• Java virtual machine
• OS Process
• WebSphere Application Server
• WebSphere Liberty
• Automation Action Script

To collect the metrics for WebSphere Liberty, you must enable the monitor-1.0 feature. To enable this feature, open the server.xml file, which is located in the <websphere-liberty_install_dir>/usr/servers/<specific_server>/ directory, and then add the following lines to the file:

<featureManager ...>
    ...
    <feature>monitor-1.0</feature>
    ...
</featureManager>

IBM i 7.6 introduces multi-factor authentication (MFA) for user profiles. The Instana agent can run by a user profile with or without MFA enabled. For more information, see Starting the host agent.

To monitor Java-based technologies, the Instana agent must switch to the user profile that is running the Java job, if the job is running by a different user than the agent. In general, the Instana agent can switch to an MFA enabled user profiles without the need of that profile's TOTP. However, the agent cannot switch to a user profile whose access to the QIBM_RUN_UNDER_USER_NO_AUTH function usage ID is denied. By default, all user profiles (with or without MFA) are allowed access to this function usage ID, enabling the Instana agent to attach to their JVMs. For more information, see QIBM_RUN_UNDER_USER_NO_AUTH function usage ID.

For more information about IBM i remote monitoring with MFA, see Note for MFA.

To install the host agent on IBM i, complete the following steps:

1. Download the agent archive to your local system:

   1. From the navigation bar of the Instana UI, click More > Agents > Install Agents.

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

   3. Select the agent packaging mode, Dynamic or Static. For more information about dynamic and static host agents, see host agent types .

   4. Click the download link for IBM i to download the tar.gz file.

2. Create a target IFS directory (for example, /opt/instana/) on the IBM i system by running the following command:

   MKDIR DIR('/opt/instana')
   

3. Move the agent archive into the directory that you created in step 2. You can use FTP or the IFS interface of ACS to move the agent archive.

4. Extract the agent archive on the IBM i system by running the following commands:

   CALL QP2TERM
   

   cd <instana-directory>
   

   /QOpenSys/pkgs/bin/tar -xzf instana-agent-ibmi-ppc.tar.gz
   

   After you extract the agent archive, a new directory <instana-directory>/instana-agent is created. For example, /opt/instana/instana-agent.

5. Configure the agent to point to your Instana backend by using the *instanaAgentDir*/etc/instana/com.instana.agent.main.sender.Backend.cfg file. This file contains the configurations that are used by the host agent to communicate with the Instana backend, including the host and key. For more information, see Configuring the Instana Backend.

The host agent is now installed and configured on your IBM i system.

After you install the host agent, you can administer the host agent, such as checking the status of the agent or starting the agent.

You can also configure the agent as you require. For more information, see Configuring the host agent.

You can use Ansible to automate the installation of the host agent on multiple IBM i nodes by using the following playbook. You can run this playbook on a UNIX-like server where Ansible is installed in it. This playbook automatically creates the destination directory, copies and extracts the agent archive, and starts the agent on all your IBM i systems.

For more information about the prerequisites and management of IBM i systems with Ansible, see Power IBM i collection for Ansible. For more IBM i examples, see Automate your IBM i tasks with Ansible.

To automate the installation of the host agent by using Ansible, complete the following steps:

1. Save the following playbook configuration as a YAML file, such as playbook.yml, in a directory of your system.

   ---
   - hosts: ibmi
     collections:
     - ibm.power_ibmi
     tasks:
     - name: Create Instana Directory
       ansible.builtin.file:
         path: /opt/instana
         state: directory
     - name: Remove Old Instana Agent files
       ansible.builtin.file:
         path: '{{ item }}'
         state: absent
       with_items:
         - /opt/instana/instana-agent
         - /opt/instana/instana-agent-ibmi-ppc.tar.gz
     - name: Copy Agent Tar to System
       ansible.builtin.copy:
         src: ./instana-agent-ibmi-ppc.tar.gz
         dest: /opt/instana/
     - name: Extract Instana Agent
       shell:
         cmd: tar -xzf /opt/instana/instana-agent-ibmi-ppc.tar.gz
     - name: Run Instana Agent in QUSRWRK
       ibmi_cl_command:
         cmd: sbmjob cmd(qsh cmd('export JAVA_HOME=/QOpenSys/QIBM/ProdData/JavaVM/jdk80/64bit; exec bash /opt/instana/instana-agent/bin/start')) jobq(QUSRNOMAX) LOG(*JOBD *JOBD *NOLIST)
   

2. Download the agent archive by following step 1 in the Installing the agent manually section, and save it in the same directory as the playbook.

3. Create an inventory.ini file, which lists all the IBM i nodes where you want to install the agent, and save it in the same directory as the playbook. For more information about the inventory.ini file, see Build your inventory.

4. Run the playbook from your Ansible server by using the following command:

   ansible-playbook -i inventory.ini playbook.yml
   

The agent is deployed on all your IBM i systems that are specified in the inventory.ini file.

After you install the agent, you can further configure the agent as you require. Configurations can be applied when the agent runs, and changes are immediately applied. For more information, see Configuring the host agent.

After you install the host agent, you can check the status of the agent in the Instana UI. For more information, see Checking the status of the host agent.

To start the host agent, run the following command:

SBMJOB CMD(QSH CMD('export JAVA_HOME=<java-home>; exec bash *instanaAgentDir*/bin/start')) JOBQ(QUSRNOMAX) LOG(*JOBD *JOBD *NOLIST)

This command starts the Instana agent jobs in the QUSRWRK subsystem and runs the jobs as the current user. The agent needs to run as a user with *ALLOBJ authority. For more information, see SBMJOB.

After the initialization is complete, three separate jobs that are named QZSHSH remain to run the agent. In these three jobs, the job that has the function PGM-sh is the parent job. The job that has the function PGM-jFromPASE is the direct child of the parent job. The job that has the function JVM-org.apache is the child of the first child job. Other jobs might briefly start or stop, especially during the startup.

To stop the host agent, run the following command:

*instanaAgentDir*/bin/stop

Issue:

The host agent fails to attach to JVM.

In the following example error message, the agent tried to attach to the JVM (PID 123) but it failed:

2025-08-22T09:45:24.832-03:00 | INFO  | instana-executor-thread-2-98     | AttachHelperImpl | com.instana.agent-jvm-handling - 1.0.22 | Agent user {Uid=128, Gid=0} and target JVM user {Uid=4294770318, Gid=201} not identical.
2025-08-22T09:45:24.833-03:00 | INFO  | instana-executor-thread-2-98     | ExternalAttach   | com.instana.agent-jvm-handling - 1.0.22 | Executing: /opt/instana/instana-agent/system/com/instana/ibmi-sudo/1.0.0/ibmi-sudo-1.0.0.exe -u qwebadmin /QOpenSys/QIBM/ProdData/JavaVM/jdk80/64bit/jre/bin/java -Xms16m -Xmx16m -Dcom.ibm.tools.attach.enable=no -Duser.dir=/ -cp /tmp/.instana/javaagent-loader-1.3.70.jar com.instana.agent.loader.AgentLoaderAttach agent=/tmp/.instana/javaagent-loader-1.3.70.jar verify=true pid=123 host=127.0.0.1 port=42699 boot=/com.instana.agent.artifact/com.instana/instrumentation-boot/1.1.31/jar shared=/com.instana.agent.artifact/com.instana/instrumentation-shared/1.0.146/jar inMemoryClassLoader=true agentSocket=true
2025-08-22T09:45:25.301-03:00 | ERROR | instana-executor-thread-2-98     | ExternalAttach   | com.instana.agent-jvm-handling - 1.0.22 | com.sun.tools.attach.AttachNotSupportedException: target 123 not found
...

Cause:

The target <pid> not found error can be caused by the following underlying issues:

• The JVM process is no longer running (or has a new PID).
• The Instana agent lacks the authority to switch to the JVM’s user profile.

Solution:

To resolve this issue, complete the following steps:

1. Verify that the JVM with the PID is still running by completing the following steps:

   1. Run the ps -e command from a PASE shell.
   2. Search for the PID listed in the error message, for example, 123.

   If the process with that PID is no longer running, then the attachment failed because the JVM stopped or is now running under a new PID. In this case, the agent attempts to attach to the new process.

2. If the JVM is not running, check the user authority. The Instana agent user profile must have the *ALLOBJ special authority to run as another user profile, which is required to attach to JVMs. For details, see qsysetuid().

   To check user authority, complete the following steps:

   1. Run the ibmi-sudo command manually with the Instana user profile as shown in the following example by using the path of the ibmi-sudo executable listed in the error message:

      /opt/instana/instana-agent/system/com/instana/ibmi-sudo/1.0.0/ibmi-sudo-1.0.0.exe -u qwebadmin /QOpenSys/pkgs/bin/whoami
      

      If the sudo command is successful, the output is the name of the user profile, for example:

      QWEBADMIN
      

      If the sudo command is not successful, the target user profile might specify OWNER(*GRPPRF). If the target user profile's first group is not in the list of supplemental groups for the Instana agent user, add the target group to the supplemental groups.

   2. Add the target user's group to the list of supplemental groups for the Instana user profile as shown in the following example:

      CHGUSRPRF USRPRF(INSTANA) SUPGRPPRF(TARGET_GROUP)
      

If this troubleshooting section does not resolve your issues, contact the IBM Instana support team.