Installing the agent on Linux

One-liner script parameters

The one-liner script accepts the following parameters:

1. Downloading the agent package

If you are on a self-hosted backend, the backend version must be 275 to download an agent package.

To download an Instana agent package, complete the following steps:

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

   If you are starting a new trial instance of Instana, the agent catalog is displayed with a prompt to select a host agent to install.

2. On the agent deployment catalog page, click the tile Linux - Packages (DEB, RPM).

3. Select the agent configurations.

   • In the Packaging section, select the agent type (Dynamic or Static) that you want to deploy. To understand the differences of static agents and dynamic agents, see Host agent types.

   • In the Runtime section, select Azul Zulu 11 or Eclipse OpenJ9 11 runtime.

   • In the Mode section, select the package mode (RPM or DEM) that you want to use.

4. In the Platform architecture section, select the architecture of the Linux machine where you want to install the host agent.

5. Click the download icon to download the host agent package (DEB or RPM) from your web browser.

In an offline (air-gapped) environment that is not connected to the internet, you can download the agent package for DEB or RPM directly from the Artifactory. Make sure that you download the latest package.

Now the agent package is downloaded. Go to the next section to install the agent package.

2. Installing the agent package

Instruct your package manager to install the agent package or install the agent package manually.

To install the agent package by using a package manager, use one of the following ways based on your Linux distribution:

• Debian derivatives (apt package manager)

  1. Prepare the apt package manager with resources for the Instana agent package by creating the following files:

     # /etc/apt/sources.list.d/instana-agent.list
     deb [arch=amd64] https://packages.instana.io/agent generic main
     

     # /etc/apt/auth.conf.d/instana-packages.conf
     machine packages.instana.io
     login _
     password <your_agent_key>
     

     Alternatively, you might hardcode the authentication in the URL in /etc/apt/sources.list.d/instana-agent.list. However, this method causes a mild security risk and apt issues warnings that are shown whenever you install or update Instana packages.

  2. Add the Instana GPG key to the apt package manager by running the following command:

     wget -qO - https://packages.instana.io/Instana.gpg | sudo apt-key add -
     

• RPM-based distributions (yum package manager)

  1. Copy the following code snippet into your yum sources (/etc/yum.repos.d/Instana-Agent.repo):

     [instana-agent]
     name=Instana
     baseurl=https://_:<your_agent_key>@packages.instana.io/agent/generic/x86_64
     enabled=1
     gpgcheck=1
     repo_gpgcheck=1
     gpgkey=https://packages.instana.io/Instana.gpg
     priority=5
     sslverify=1
     

     Replace <your_agent_key> with your agent key.

  2. If you want to enable GPG package verification, for some distributions, you need to import the key into the package manager's key ring beforehand.

     To import the key, run the following command:

     rpm --import https://packages.instana.io/Instana.gpg
     

• openSUSE/SLES (zypp package manager)

  For openSUSE and SUSE Linux Enterprise Server, the path is /etc/zypp/yum.repos.d/Instana-Agent.repo, but the contents can remain the same as the RPM-based distribution.

Now the agent package is installed. After you refresh the package manager's sources, go to the next section to continue.

3. Preparing the agent

1. Configure the host agent endpoint and the agent key.

   To find the endpoint, port, and agent key values, go to the home page of the Instana UI and click Agent deployment. On the agent deployment catalog page, click the tile Linux - Automatic Installation (One-liner). Then, you can see endpoint, port, and agent key values in the deployment script.

   See the following script example:

   curl -o setup_agent.sh https://setup.instana.io/agent && chmod 700 ./setup_agent.sh && sudo ./setup_agent.sh -a aGeNTKEY0vaLuO0Eu1ABc -d n3asffgkg -t dynamic -e ingress-green-saas.instana.io:443  
   

2. Set environment variables before you install the host agent.

   export INSTANA_AGENT_KEY=$agentkey
   export INSTANA_AGENT_HOST=$endpoint
   export INSTANA_AGENT_PORT=$endpoint_port
   

   Summary of options for setting environment variables:

   • Git-based configuration management: Placing environment variables in a file is a good approach. For more information, see Git-based configuration management.

   • Systemd: A drop-in is the easiest way to overwrite environment specifics for services.

   • SysVinit: Place the files in either /etc/sysconfig (Red Hat derivatives) or /etc/default (Debian derivatives).

   For more information about the options for environment variables, see Setting and overriding environment variables.

Now the preparation work for the agent installation is completed. Go to the 4. Installing the agent section to continue.

4. Installing the agent

Refresh the package manager's sources, and then run one of the following commands to install the agent on your chosen architecture:

• Debian derivatives

  • To install a static agent, run the following command:

    apt-get install instana-agent-static
    

  • To install a dynamic agent, run the following command:

    apt-get install instana-agent-dynamic
    

• Red Hat derivatives

  • To install a static agent, run the following command:

    yum install instana-agent-static
    

  • To install a dynamic agent, run the following command:

    yum install instana-agent-dynamic
    

• Eclipse OpenJ9 11 bundled packages

  Install the host agent with one of the following package names: instana-agent-static-j9 or instana-agent-dynamic-j9.

Now the host agent is installed. For what you can do after the installation, go to the What to do next section.

1. Checking the prerequisites

Before you install the host agent, make sure that the following prerequisites are met:

• A Java development kit (JDK) must be available for the agent by using either of the following options:

  • Place or link the JDK into <instana-agent-install-dir>/jvm (so that <instana-agent-install-dir>/jvm/bin/java exists).

  • The customizable way is to export an environment variable JAVA_HOME to point to that JDK (this environment variable can also be set to instana-agent-install-dir>/bin/setenv).

  The following JDKs are supported for running the agent:

  • IBM OpenJ9 JDK 11 (Preferred)
  • Azul Zulu JDK 11
  • OpenJDK JDK 11
  • Oracle Hotspot JDK 11
  • Amazon Corretto JDK 11
  • IBM J9 11

  The JVM must be executable for all users on the system. You are recommended to use the latest available patch release of the Java distribution of your choice. The agent requires a JDK that supports TLSv1.3 (available in all current JDK 11 builds). Depending on your OS distribution, the packages that are provided by the OS distributor might not contain strong encryption support due to export control. If you use such a package, you might meet the errors like "java.lang.RuntimeException: Could not generate DH key pair."

• To reduce the resources used by the agent when the file system is changed, you must install the inotify-tools package on your Linux distribution.

• Ensure that the user that is used to run the agent can write in the agent directory and all its subdirectories. The agent downloads the required sensors in accordance with auto-detection and creates log files in its data subdirectory.

• Make sure that you have about 100 MB of available disk space.

• The agent downloads updates and sensors from the following host. Make sure that the following host and ports can be accessed:

  • DNS Name: artifact-public.instana.io
  • Destination Port: tcp/80 and tcp/443

• Currently, the Instana Service is provided in two different regions. Your individual instance is located geographically closest to most of your agents and users. Agents are pre-configured upon download, but some installation methods require Instana backend configuration. Consult the Agent Management section inside the product or your technical contact at IBM to learn about the region where your instance is located.

• If you are using the self-hosted (on-premises) Instana, use the endpoints that are defined during the Instana backend installation. You can also see the endpoint to which the agent reports in the Instana UI. Go to Deploy agent and check the deployment code or YAML configuration.

• If you are using Instana SaaS, use the endpoints that are described at host agent endpoints.

2. Downloading the agent

You can download the host agent by using either of the following ways:

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

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

     If you are starting a new trial instance of Instana, the agent catalog is displayed with a prompt to select a host agent to install.

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

  3. In the Packaging section, select the agent type (Dynamic or Static) that you want to deploy. To understand the differences of static agents and dynamic agents, see Host agent types.

  4. In the dropdown list, select the platform architecture (operating system).

     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, and then extract the file.

• Download the agent with wget by running the following commands:

  wget --save-cookies {{agent_folder_name}}/instana-cookies.txt --post-data 'email={{instana_username}}&password={{instana_password}}' https://{{instana_tenant_unit}}-{{instana_tenant}}.instana.io/auth/signIn
  

  wget --content-disposition --load-cookies {{agent_folder_name}}/instana-cookies.txt --post-data 'type=linux64' https://instana.io/ump/{{instana_tenant}}/{{instana_tenant_unit}}/agent/download -O {{opt_folder}}/{{name_of_agent_archive.tar.gz}}
  

Now the host agent is downloaded. Go to the next section to start the agent.

3. Starting the agent

Put the extracted agent package file to a system-wide accessible location, and run the agent as the root user.

If you run the host agent with any other user, the functions of the host agent are limited. The reason is that some performance metrics are supported only by the root. The monitoring of Docker containers can be done only by the root on the Docker host machine. In addition, only either the root or startup users can attach and monitor Java virtual machines (JVMs). If you can't run the host agent as root, make sure that the agent user is listed in sudoers with a valid shell.

To start the agent, run the following command:

INSTANA_AGENT_FOLDER/bin/start

Now the host agent is installed and started. For what you can do after the installation, see What to do next.

Supported features

The Instana agent that is run as a non-root user supports the following features: