Administering the host agent on Linux

Starting the agent

When you install the host agent, it is enabled to start automatically at system boot. You can turn off this behavior by setting the environment variable INSTANA_AGENT_AUTOSTART=false when you install the agent.

• To start the host agent, run the following command:

  /opt/instana/agent/bin/start
  

• If your operating system uses systemd as the init system, run the following command:

  systemctl start instana-agent.service
  

• If your operating system uses SysVinit as the init system, run the following command:

  service instana-agent start
  

Stopping the agent

To stop the agent, run the following command:

 /opt/instana/agent/bin/stop

• If your operating system uses systemd as the init system, run the following command:

  systemctl stop instana-agent.service
  

• If your operating system uses SysVinit as the init system, run the following command:

  service instana-agent stop
  

Updating the agent

You can use the package manager of your operating system to upgrade an agent package on your machine. To update and manage the packages and patches of your system, run the following command:

yum update // apt-get upgrade

The instana-agent-static or instana-agent-dynamic packages are upgraded.

SystemV Init

If your operating system uses SysVinit as the init system, the host 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 the /etc/default/instana-agent file or the /etc/sysconfig/instana-agent file.

For example, in Debian, you can update the Instana variables and PATH 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}

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.

Systemd

If your operating system uses Systemd as the init system, you can set and override environment variables by using the following available options. The drop-in units method is the recommended approach because you need not modify the service unit file whereas the other methods need you to make changes to the file. These changes might also be removed during the updates. The drop-in units method ensures that the changes and environment variables set are retained even after updates.

• Drop-in units
• EnvironmentFile directives
• Global environment settings

After you change environment variables, make sure to run the sudo systemctl daemon-reload command, and then run the sudo systemctl restart instana-agent.service command 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 daemon 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 181, DEB and RPM agent packages automatically install the following configuration script in /usr/lib/tmpfiles.d that adjusts the behavior to not delete the required files and impact the functions of 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.

Red Hat Enterprise Linux and CentOS, in versions 6 and 7, include default tmpdfiles.d policies that delete the entire /tmp directory every 10 days regardless of which policies a package 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.

Many Debian derivatives, including Ubuntu, include 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.

You might see the following warning on systems with policies that override the required behavior that is specified by the Instana agent packages:

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.

You can address this issue by editing the default tmpfiles.d policies. 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 Deleting 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