Installing the host agent on Linux

Supported Distributions

The one-liner supports the following Linux distributions:

• Debian derivatives (apt package manager)
• Red Hat derivatives (yum package manager)
• SUSE derivatives (zypp package manager)

Using the one-liner

Note: You need root user privileges to install the Instana host agent.

To use the one-liner, complete the following steps:

1. Sign in to Instana, and click More > Agents > Instana agent installation > Linux.

2. From the Technology list, select Automatic Installation (One-liner).

   Your agent key and location are pre-populated in the one-liner command.

3. Copy and run one of the following commands for host agent installation:

   Dynamic agent with Zulu JVM (interactive installation):

   curl -o setup_agent.sh https://setup.instana.io/agent && chmod 700 ./setup_agent.sh && sudo ./setup_agent.sh -a $yourAgentKey -t dynamic -e $location:443
   

   Dynamic agent with Zulu JVM (silent installation):

   curl -o setup_agent.sh https://setup.instana.io/agent && chmod 700 ./setup_agent.sh && sudo ./setup_agent.sh -a $yourAgentKey -t dynamic -e $location:443 -y
   

   Static agent with Zulu JVM (interactive installation):

   curl -o setup_agent.sh https://setup.instana.io/agent && chmod 700 ./setup_agent.sh && sudo ./setup_agent.sh -a $yourAgentKey -t static -e $location:443
   

   Static agent with Zulu JVM (silent installation):

   curl -o setup_agent.sh https://setup.instana.io/agent && chmod 700 ./setup_agent.sh && sudo ./setup_agent.sh -a $yourAgentKey -t static -e $location:443 -y
   

4. To run the Instana host agent, run one of the following commands:

   • If your operating System uses systemd as init system, run the systemctl start instana-agent.service command.
   • If your operating System uses SysVinit as init system, run the service instana-agent start command.

Additional parameters

The one-liner command accepts the following parameters:

When you download and run one-liner.sh script, it adds the public systems package repository of Instana to your system by creating a repository file. This file adds Instana authenticated repositories to the machine's installation sources.

Potential problems during installation

  Setting up Instana APT repository
  Importing Instana GPG key
  Updating apt metadata ...
  E: The method driver /usr/lib/apt/methods/https could not be found.
  APT repository metadata update failed

  Setting up Instana agent for GNU/Linux
  Setting up Instana zypper repository
  Updating zypper metadata ...
  Installing Instana agent ...
  Error building the cache:
  [instana-agent|https://_@packages.instana.io/agent/generic/x86_64] Valid metadata not found at specified URL
  Some of the repositories have not been refreshed because of an error.
  No provider of 'instana-agent-static' found.
  Instana agent package install failed

Setting up Instana agent for GNU/Linux
Setting up Instana YUM repository
Updating YUM metadata ...
YUM repository metadata update failed

Error unpacking rpm package instana-agent-dynamic-20210630-0948.x86_64
Error: Transaction failed

sudo rpm -ivh instana-agent-dynamic-20210713-1352.x86_64.rpm
...
error: unpacking of archive failed on file /etc/init.d/instana-agent;60eda3b3: cpio: Digest mismatch
error: instana-agent-dynamic-20210713-1352.x86_64: install failed

sudo rpm -ivh --nodigest --nofiledigest instana-agent-dynamic-20210713-1352.x86_64.rpm

Debian derivate

To prepare Apt with resources for the Instana agent packages, create 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 ${INSTANA_AGENT_KEY}

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

To add the Instana GPG key to APT, run the following command:

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

RPM-based distribution

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

[instana-agent]
name=Instana
baseurl=https://_:${INSTANA_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

Note: Replace ${INSTANA_AGENT_KEY} with your agent key.

If you want to enable GPG package verification, some distributions require that you 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

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 RPM-based distribution.

Debian Derivatives

To install the static agent, run the following command:

apt-get install instana-agent-static

To install the dynamic agent, run the following command:

apt-get install instana-agent-dynamic

Red Hat Derivatives

To install the static agent, run the following command:

yum install instana-agent-static

To install the dynamic agent, run the following command:

yum install instana-agent-dynamic

Uninstall on Debian Derivatives

Get the name of the package that is installed on your system by running the following command:

apt list --installed | grep instana-agent

The output holds the exact package name to use for the uninstall command. In the following example, the package name is instana-agent-static-j9/generic:

instana-agent-static-j9/generic,now 20221024-1455 amd64 [installed]

Uninstall the agent by running the following command:

sudo apt-get purge <package_name>

Where <package_name> is the package name that you get.

Uninstall on Red Hat Derivatives

Get the name of the package that is installed on your system by running the following command:

yum list installed | grep instana-agent

The output holds the exact package name to use for the uninstall command. In the following example, the package name is instana-agent-static-j9.x86_64:

instana-agent-static-j9.x86_64       20221024-1455                 @instana-agent

Uninstall the agent by running the following command:

sudo yum remove <package_name>

Where <package_name> is the package name that you get.

Note: Some files that are created by the Instana agent are not part of the package on rollout. The process of clean-up the installation of the Instana agent requires an extra manual step to remove the installation directory. The clean-up is required for SUSE and Red Hat derivatives because Yum doesn't support clean-up.

Run the following command to remove the installation directory:

rm -rf /opt/instana/agent

Prerequisites

A Java Development Kit (JDK) needs to be available for the agent. You can see the list of supported JDKs as follows. You have two 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 that is called JAVA_HOME to point to that JDK (this environment variable can be also set via instana-agent-install-dir>/bin/setenv).

The following JVMs are supported for running the agent:

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

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 8 and 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 detect file system changes, you need to install the inotify-tools package on your Linux distribution.

Agent communication

The agent downloads updates and sensors from the following host:

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 preconfigured upon download, but some installation methods that require Instana Backend configuration. Consult the Agent Management section inside the product or your technical contact at Instana 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 described at Self-hosted Instana backend on Docker (on-premises).

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

Downloading the agent

To download the agent, follow the steps:

1. Sign in to Instana, and click More > Agents.

2. Click Installing Instana Agents.

3. In the dropdown menu, select the appropriate operating system.

4. Click the Download button, and extract the agent archive that is corresponding to your system architecture.

It is automatically preconfigured with your account settings so that you only need to extract and start the agent.

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}}

Starting the agent

To start the agent, run the following command:

INSTANA_AGENT_FOLDER/bin/start

Stopping the agent

To stop the agent, run the following command:

INSTANA_AGENT_FOLDER/bin/stop

Status of the agent

To see the status of the agent, run the following command:

INSTANA_AGENT_FOLDER/bin/status

SystemV Init

The agent sources the corresponding shell scripts in the /etc/default/ directory (Debian and derivatives) or /etc/sysconfig/ directory (Red Hat and derivatives). If the service name is not changed, the SysVinit script sources /etc/default/instana-agent file or /etc/sysconfig/instana-agent file.

For example, in Debian the Instana variables and PATH can be updated by using /etc/default/instana-agent (when this file is found readable):

INSTANA_AGENT_KEY=$agentkey
INSTANA_AGENT_HOST=$endpoint
INSTANA_AGENT_PORT=$endpoint_port
PATH=/usr/local/bin:${PATH}

Systemd

For systemd, you can find various available options, the drop-in units, EnvironmentFile directives, and global environment settings. Drop-in units are the most recommended approach.

In the following options, make sure to run sudo systemctl daemon-reload followed by sudo systemctl restart instana-agent.service to reload the agent with the variable changes.

[Service]
Environment=INSTANA_AGENT_KEY=$agentkey
Environment=INSTANA_AGENT_HOST=$endpoint
Environment=INSTANA_AGENT_PORT=$endpoint_port
Environment=PATH=/usr/local/bin:${PATH}

INSTANA_AGENT_KEY=$agentkey
INSTANA_AGENT_HOST=$endpoint
INSTANA_AGENT_PORT=$endpoint_port
PATH=/usr/local/bin:${PATH}

[Service]
EnvironmentFile=/etc/instana/environment.conf

[Manager]
DefaultEnvironment="INSTANA_AGENT_KEY=<key>" "INSTANA_AGENT_HOST=<host>" "INSTANA_AGENT_PORT=<port>"

Tmpfiles.d

On system.d-based systems, the systemd-tmpfiles deamon can delete files that are needed by the host agent in the /tmp/.instana directory, which causes update failures that are hard to troubleshoot. Since version v181, DEB and RPM agent packages automatically install the following configuration script in /usr/lib/tmpfiles.d that adjusts the behavior to play nice with the Instana host agent:

# Instana files in /tmp cannot be deleted when the agent is running,
# or it may lead to issues on agent update
R! /tmp/.java_pid*
R! /tmp/.instana/*

This configuration allows tmpdfiles.d to delete the files that are needed by the Instana agent only after a host restart. The newly running Instana host agent re-creates the files on startup.

IMPORTANT: Red Hat Enterprise Linux and CentOS, in versions 6 and 7, ship default tmpdfiles.d policies that delete the entire /tmp directory every 10 days regardless of which policies a package like Instana's can specify. It means that a package like instana can define custom policies to control the behavior of the system or the package itself.

#  This file is part of systemd.
#
#  systemd is free software; you can redistribute it and/or modify it
#  under the terms of the GNU Lesser General Public License as published by
#  the Free Software Foundation; either version 2.1 of the License, or
#  (at your option) any later version.

# See tmpfiles.d(5) for details
# Clear tmp directories separately, to make them easier to override
v /tmp 1777 root root 10d
v /var/tmp 1777 root root 30d

...

Short of editing the default tmpfiles.d policies, no known workaround is available. The offending tmpfiles.d policy is located in /usr/lib/tmpfiles.d/tmp.conf.

IMPORTANT: Many Debian derivatives, including Ubuntu, ship default tmpdfiles.d policies that delete the entire /tmp directory regardless of which policies a package like Instana's can specify. Upon installation, the DEB, and RPM packages run a test to verify the behavior of the temporary files tmpfiles.d, running the command systemd-tmpfiles --remove. On systems with policies that are override the wanted behavior that is specified by the Instana agent packages, you might see the following warning:

WARNING: The tmpfiles.d policies of this system may cause the Instana agent to malfunction by deleting the /tmp/.instana directory; refer https://www.instana.com/docs/setup_and_manage/host_agent/on/linux#tmpfiles.d for more information.

Short of editing the default tmpfiles.d policies, no known workaround is available. The offending tmpfiles.d policy is located in /usr/lib/tmpfiles.d/tmp.conf.

Tmpwatch

Red Hat Enterprise Linux 6 and CentOS 6 include the tool tmpwatch, which is known to delete unnecessary files in the /tmp/.instana. However, the use of tmpwatch in these distributions can occasionally cause update problems with the host agent. For more information, see Temporary files.

# Deal with tmpwatch, found in RHEL 6 and CentOS 6.
# It is a cronjob, installed in /etc/cron.d/daily, with pretty much hardcoded
# configurations to wipe data the Instana agent needs.
readonly TMPWATCH_CRONJOB='/etc/cron.d/daily/tmpwatch'
if [ -f "${TMPWATCH_CRONJOB}" ]; then
  # Let's check if we already touched the file and, if not, add our excludes
  if ! grep "${TMPWATCH_CRONJOB}" Instana 2&>1 > /dev/null; then
    echo "tmpwatch discovered in '${TMPWATCH_CRONJOB}': adding the exclude flags for Instana"
    # Edit in place with `sed`
    sed -i '/^flags=/a flags="${flags} -x /tmp/instana -x /tmp/.javapid* # Added by Instana"' "${TMPWATCH_CRONJOB}"
  fi
fi