Installing the 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.

Both the “one-liner” method and the manual installation are detailed below.

Background

As of now, for manual installations, we provide packaged agents for Linux-based system under the AMD 64-architecture.

For non-container environments, the Instana Agent is configured for two package managers for easy installation: Apt and Yum. We provide systems packages and test setup methods for pretty much any Linux distribution using the APT or RPM package managers, including, but not limited to, the following distributions and versions:

Distribution Version
Ubuntu Linux 14.04 (trusty)
Ubuntu Linux 16.04 (xenial)
Ubuntu Linux 18.04 (beaver)
CentOS 6
CentOS 7
Debian 9 (stretch)
SUSE Linux Enterprise Server (SLES) 12
Redhat Enterprise Linux (RHEL) 6
Redhat Enterprise Linux (RHEL) 7
Redhat Enterprise Linux (RHEL) 8
Amazon Linux 1
Amazon Linux 2

Notice: SUSE Linux Enterprise Server (SLES) 11 is not supported due to outdated OpenSSL binaries.

Requirements

Please make sure the host machine has a hostname set that is resolving to one of the machine addresses. This can either be the machine’s Cluster-IP-, local-, or public-address.

The other requirement can be acquired from our sales team. It consists of an identifying key and an address:

  • The Agent key: This serves as a tenancy identifier across the platform;
  • The monitoring endpoint address: This serves as a tenancy identifier across the platform;
  • The monitoring endpoint port: This is the port where the agent will send its packets to.

If you’re running an On-Premises version of our setup, please make sure that the machine on which the agent is being installed reaches the backend endpoint. In case you’re running in our SaaS space, please review the network access requirements to enable communication between the agent and the SaaS space.

What’s In It

Our agent comes in two flavors, depending on your setup and needs.

The static packages comes fully packed for operation including all of our latest sensor versions. This is the optimal solution if you’re running restrictive networks or our On-Premises offering, as this “thicker” package does not need internet connectivity.

The dynamic flavor comes as a blank agent that downloads the latest set of sensors from our repositories on startup. Also it is updating them on a daily basis by default (this is configurable).

Note: If you still run older versions of our agent which came in the full or minimal flavor, please switch to the new ones, static and dynamic, mentioned above.

One-Liner Installation

Please make sure you have your Instana agent key at hand. If you do not know your key, please contact our sales team to help you get the installation going. They will also give you the endpoint country code for your SaaS environment.

The following command will extract and run the latest Instana agent package on your machine:

curl2bash instana-agent

curl -o setup_agent.sh https://setup.instana.io/agent && chmod 700 ./setup_agent.sh && ./setup_agent.sh -a $yourAgentKey -l $location

As you can tell from the snippet above, the script we offer takes a set of parameters:

  • -a = (required) Specifies the agent key. Like mentioned above, this is a tenancy identifier. It can be looked up in the Management Portal in your Instana environment.
  • -d = (optional) Specifies the download key. If you are utilizing an Instana distributed On-Premises deployment this will be provided for you by Instana.
  • -e = (either -l or -e are required) The SaaS endpoint. An option for our On-Premises customers: please use the backend machine’s cluster name/ip along with the acceptor’s port (1444) on it: {instana-backend-hostname}:1444
  • -m = (optional) Sets the Instana agent mode Valid options are apm (default), infra, or aws
  • -l = (either -l or -e are required) The location identifier. This tells the agent to which of our SaaS machines it should connect. Valid options are eu (all SaaS customers in Europe), or us (all Customers in the US and the rest of the World).
  • -t = (optional) The agent flavor. This parameter can either be static or dynamic (default).
  • -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. Note: This option only works for systems running systemd.

The parameters are case sensitive.

What It Will Do

The downloaded script is simply adding our authenticated public systems package repository to your system. It will create a repository file that adds our authenticated repositories to the machine’s installation sources. The different derivatives available are:

  • Debian derivatives: /etc/apt/sources.list.d/;
  • Redhat derivatives: /etc/yum/repos.d/;
  • SUSE derivatives: /etc/zypp/repos.d/.

After creating a repository file, it will install the agent package to your system in the specified flavor.

Running the Agent

Since the Instana agent is being installed as a basic systems service, simply run:

  • systemctl start instana-agent.service if you’re running systemd.
  • service instana-agent start if you’re running SysVinit.

Removing the Agent

Please use the package manager of your OS.

A Deprecation Note

Earlier agents were delivered in two different flavors: full and minimal. They are deprecated and being replaced by static and dynamic respectively. Please update accordingly.

Identified Problems during Installation

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

Manual Installation Process

Please make sure you have your Instana agent key at hand. If you do not know your key, you can contact our sales team to help you get the installation going. They will also give you the endpoint country code for the corresponding SaaS endpoint.

You will most certainly need our GPG key with which the repository is signed. If you are using an RPM based distribution, you can also enable the package-based GPG verification. You can find the key publicly available at https://packages.instana.io/Instana.gpg.

Debian Derivate

In case you are running a Debian derivative, the following code example will prepare Apt with the resources for our agent packages:

/etc/apt/sources.list.d/instana-agent.list

deb [arch=amd64] https://_:${INSTANA_AGENT_KEY}@packages.instana.io/agent generic main

RPM-based Distribution

If on the other hand, you are running an RPM-based distribution, you can copy this 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

If you want to enable GPG package verification, some distributions require you to import the key into the package manager’s keyring beforehand. You can easily do so by issuing the following:

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

Please replace the snippet ${INSTANA_AGENT_KEY} with your agent key.

openSUSE/SLES

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

Preparing the Agent

After refreshing the package manager’s sources, the agent needs to be configured with the Instana backend monitoring endpoint address 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:

Preparing the installation

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

Yet if you are using configuration management, placing this information in a file might be easier. For systemd, a drop-in is the easiest approach to overwriting environment specifics for services. For SysVinit, we are used to placing 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, you can now install any of the above mentioned 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

Configuring the Agent

Further informations on how to provide database credentials, or host tags, can be found under the Agent Configuration section.

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

Running the Agent

Since the Instana agent is being installed as a simple systems service, simply run:

  • systemctl start instana-agent.service if you’re running systemd, or:
  • service instana-agent start if you’re running SysVinit.

Removing and 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, a simple yum update // apt-get upgrade should suffice for upgrading instana-agent-static or instana-agent-dynamic packages.

As for removal, the first step should (again) 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 a manual step at last, which is removing the installation directory. This is especially needed for SUSE or Redhat derivatives, since Yum does not support purging at all.

rm -rf /opt/instana/agent

Identified Problems During Installation

  • Debian-based Derivatives might present an error message to you that looks like a connection issue, but is rather more a bug in GnuTLS-depending programs like Curl, git, or apt:

GnuTLS recv error (-9): A TLS packet with unexpected length was received

  • 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 doesn’t (yet) know how to pull sources from https servers.

E: The method driver /usr/lib/apt/methods/https could not be found. APT repository metadata update failed

  • In case SUSE Enterprise Linux 12 gives you the following output, you need to update your GnuTLS, OpenSSL, and NSS libraries and its dependent Programs (e.g. Curl) to properly receive artifacts through modern https connections:

    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
  • On CentOS 6 based systems, outdated libcurl versions can cause this log output:

    Updating YUM metadata ...
    YUM repository metadata update failed

Manual Download 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

Java 8 must be available.

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.

  • Europe:

    • DNS Name: saas-eu-west-1.instana.io
    • Destination Port: tcp/443
  • United States and Rest of the World:

    • DNS Name: saas-us-west-2.instana.io
    • Destination Port: tcp/443

Note: Even though the IP addresses are static, please use the DNS names wherever possible.

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