Installing the host agent on Linux

The Instana agent can be installed as a Linux service. Most Linux distributions use SystemV init or systemd service scripts.

We highly recommend using our one-liner solution on supported Linux distributions.

Supported operating systems

Automatic installation (one-liner)

The Agent one-liner is a powerful script that performs automated installations of the host agent on Linux-based operative systems.

Supported Distributions

The one-liner supports the following Linux distributions:

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:

Parameter Description
-a = (required) Your agent key.
-d = (optional) Instana download key. If you are utilizing an Instana distributed On-Premises deployment this will be provided for you by Instana.
-e = (required) Your host agent endpoint.
-m = (optional) Sets the Instana agent mode; apm (default), infra, or aws.
-t = (optional) The agent flavor; dynamic (default) or static.
-j = (optional) Selects Eclipse OpenJ9 11 as the bundled Java runtime.
-y = (optional) Non-interactive prompt. Specify this if the setup is being performed without an interactive shell.
-s = (optional) Start the instana-agent service and enable it to start at boot time; this option works only for systems running systemd.
-g = (optional, needed if -b is set) The specification of the remote url for the Git-based configuration management capability of the host agent.
-b = (optional, needed if -g is set) The name of the remote branch to track for the Git-based configuration management capability of the host agent.
-u = (optional, needed if -p is set) The username for basic authentication when using HTTP-based remotes for the Git-based configuration management capability of the host agent.
-p = (optional) The password for basic authentication when using HTTP-based remotes for the Git-based configuration management capability of the host agent.

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

Debian-based

With Debian-based derivatives, you might experience the following output when issuing the installation. In this case, please install the package apt-transport-https, because Apt does not (yet) know how to pull sources from https servers.

  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

SUSE and SLES

In case SUSE Enterprise Linux 12 gives you the following output, you need to update your openssl to properly receive artifacts through modern https connections:

  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

CentOS

On CentOS 6 based systems, outdated libcurl versions can cause this log output:

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

RHEL

Enabled FIPS (Federal Information Processing Standard) or SELinux can lead to the following error during one-liner installation:

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

Manual installation of instana-agent packages will also fail for this setup:

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

A possible workaround for manual installation is to skip verification with the following command:

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

Packages installation (manual)

  1. Log into Instana, click More -> Agents -> Linux.

  2. From the Technology list, select Packages (DEB, RPM).

  3. Copy and paste the URL for the agent package downloads page; https://_:${INSTANA_AGENT_KEY}@packages.instana.io/agent/download.

Debian derivate

To prepare Apt with the resources for our agent packages, create the following files:

deb [arch=amd64] https://packages.instana.io/agent generic main

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.

Preparing the agent

After refreshing the package manager's sources, configure the agent needs with the host agent endpoint and the agent key.

There are multiple options. If the following environment variables are set before running the installation, the agent is being automatically configured

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

If you are using configuration management, placing this information in a file is a good approach.

For systemd, a drop-in is the easiest approach to overwriting environment specifics for services.

For SysVinit, place the files in either /etc/sysconfig (redhat derivatives) or /etc/default (Debian derivatives). For more information on this, see the section Setting and Overriding Environment Variables.

Installing the agent

After refreshing the package manager's sources, install any of the following flavors:

Debian Derivatives

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

Redhat Derivatives

yum install instana-agent-static (or)
yum install instana-agent-dynamic

Eclipse OpenJ9 11 bundled packages

The package names for the Eclipse OpenJ9 11 bundled agents are instana-agent-static-j9 and instana-agent-dynamic-j9, respectively.

Identified problems during installation

Configuring the agent

For information on how to provide database credentials or host tags, see configuring an agent.

All the above mentioned steps can be executed in one command, using our one-liner method (systems service).

Running the agent

To run the agent, run:

Removing or updating the agent

It is considered safe to rely on the package manager of your operating system to upgrade an agent package on your machinery. In your systems patching and package rolling processes, yum update // apt-get upgrade upgrades instana-agent-static or instana-agent-dynamic packages.

To remove the agent, the first step should be your package manager.

A note on purging: Since some files are being created by the Instana agent that 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 Redhat derivatives, because Yum doesn't support purging.

Run this command:

rm -rf /opt/instana/agent

Tarball installation

The Instana agent must be installed in a system-wide accessible location, ideally run as the root user. Running the agent with any other user limits its functionality because some of the performance metrics are only supported by the root, and monitoring docker containers can only be done by the root on the docker host machine. Also, only either the root or startup user are capable of attaching and monitoring Java Virtual Machines (JVMs). Should it not be possible to run as root, please at least ensure the agent user is listed in sudoers with a valid shell.

The user that is running the agent needs to be able to write in the agent directory and all its subdirectories. The agent will download the required sensors depending on the auto detection, and create log files in its "data" subdirectory. Please ensure about 100 MB of free disk space.

Prerequisites

A Java 8 Development Kit (JDK 8) needs to be available for the agent. 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:

It is important that the JVM is executable for any user on the system. We recommend using the latest available patch release of the Java distribution of your choice. Be advised that depending on your OS distribution, the packages provided by the OS distributor might not contain strong encryption support due to export control. Using such a package will result in 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, please 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 portal for download just after logging in to Instana itself. Click on the profile picture in the top right corner to access the Management Portal. This will lead directly to the download section. Just 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.

Download the agent with wget

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

Setting and overriding environment variables

When the agent is installed as package and running via SystemV init or systemd, a place is needed to set specific Instana environment variables. Also, it might be necessary to override specific environment variables. For example for LXC container support, the agent needs to have the LXC command-line utils on its path. We'll show the various ways the environment variables can be overridden.

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 below 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.

Drop-in units

Using drop-in units, it's possible to only override specific settings without changing the original systemd unit file. Drop-ins should be placed in /etc/systemd/system/<unit>.d/ with a name <name>.conf.

For example to set the Instana and PATH environment variables, create the file /etc/systemd/system/instana-agent.service.d/10-environment.conf with the contents:

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

EnvironmentFile directives

This solution is quite similar / makes use of the drop-in units, except the Environment directives are read from a separate file. For example create a file /etc/instana/environment.conf with the following contents:

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

Then in the systemd (drop-in) unit file, refer to this configuration:

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

Global environment settings

By default, systemd will read global configuration from various paths such as /etc/systemd/system.conf or /etc/systemd/system.conf.d/10-default-env.conf. By placing DefaultEnvironment directives in these files, they become available to all systemd units. For full information, refer to the systemd config man-page.

For example the following directive would create the three Instana environment variables when placed in /etc/systemd/system.conf.d/10-default-env.conf:

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

Temporary files

The Instana host agent installs some files it needs under /tmp/.instana/ and, if those are deleted over the uptime of the host, it may cause issues during updates.

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:

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, vesion 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:

#

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.

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

  1. 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. [^2]: Suse Linux Enterprise Server (SLES) 11 is not supported due to outdated OpenSSL binaries.↩