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

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

1. Sign in to Instana, 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.

   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 agent, run:

   • systemctl start instana-agent.service, if your Operating System uses systemd as init system
   • service instana-agent start, if your Operating System uses SysVinit as init system

Additional parameters

The one-liner command accepts the following parameters:

The downloaded script adds our authenticated public systems package repository to your system by creating a repository file that adds our 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 the resources for our 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 could hard-code the authentication in the URL in /etc/apt/sources.list.d/instana-agent.list, but it causes a mild security risk and apt will issue warnings shown whenever you install or update Instana packages.

To add the Instana GPG key to APT, run:

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 keyring beforehand. To do so, run:

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

openSUSE/SLES

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

Debian Derivatives

apt-get install instana-agent-static (or)
apt-get install instana-agent-dynamic

Red Hat Derivatives

yum install instana-agent-static (or)
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: Because some files that are created by the Instana agent are not part of the package on rollout, purging the Instana agent installation needs an additional manual step to remove the installation directory. This is required for SUSE and Red Hat derivatives, because Yum doesn't support purging.

Run this command:

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. There are two options:

1. The easiest is to place or link that JDK into <instana-agent-install-dir>/jvm (so that <instana-agent-install-dir>/jvm/bin/java exists).

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

At the moment, 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

It is important that the JVM is executable for any 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). Note that depending on your OS distribution, the packages 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."

It is recommended to install the inotify-tools package on your Linux distribution, because it reduces the resources used by the agent when listening on filesystem changes.

Agent communication

The agent will download updates and sensors from the following host:

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

We currently provide the Instana Service from two different regions. Your individual instance will be located geographically closest to the majority of your agents and users. Agents are preconfigured when downloaded, but there are additional installation methods that require configuring the Instana Backend. Please consult the Agent Management section inside the product or your technical contact at Instana to learn about the region where your instance is located.

Unless you're using our self-hosted product offering, refer to our list of host agent endpoints.

Agent download

To install, simply download and extract the agent archive matching your system architecture.

You can access the Instana user interface (UI) for download just after logging in to Instana itself. Click More > Agents on the Instana user interface. Select the appropriate operating system in the dropdown menu and download the agent. It is automatically preconfigured with your account settings so that you just have 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

INSTANA_AGENT_FOLDER/bin/start

Stopping the agent

INSTANA_AGENT_FOLDER/bin/stop

Status of the agent

INSTANA_AGENT_FOLDER/bin/status

SystemV Init

Our agent sources the corresponding shell scripts under /etc/default/ (Debian and derivatives) and /etc/sysconfig/ (Red Hat and derivatives). Assuming the service name hasn't been changed, the SysVinit script will source /etc/default/instana-agent and /etc/sysconfig/instana-agent.

For example under Debian the Instana variables and PATH can be updated via /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 there are various available options; drop-in units, EnvironmentFile directives and global environment settings. Drop-in units are the most recommended approach.

In all as follows cases, afterwards make sure to execute 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 may delete files needed by the host agent in the /tmp/.instana folder, causing update failures that are very 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/*

The configuration above allows tmpdfiles.d to delete the files needed by the Instana agent only after a host restart, when they are no longer needed, as the newly-running Instana host agent will recreate them on startup.

IMPORTANT: RHEL and CentOS, version 6 and 7, ship default tmpdfiles.d policies that will delete the entire /tmp directory every 10 days regardless of which policies a package like Instana's may specify:

#  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, there is no known workaround. 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 will delete the entire /tmp directory regardless of which policies a package like Instana's may specify. Upon installation, the DEB and RPM packages run a test for tmpfiles.d behavior running systemd-tmpfiles --remove. On systems with policies that override the desired behavior specified by the Instana agent packages, you will 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, there is no known workaround. The offending tmpfiles.d policy is located in /usr/lib/tmpfiles.d/tmp.conf.

Tmpwatch

RHEL 6 and CentOS 6 ship tmpwatch, which is known to delete necessary files in the /tmp/.instana and occasionally cause update issues in the host agent. See the Temporary files section for more information.

# 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