IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.
« Elastic Agents Uninstall Elastic Agent »
Elastic Docs ›Fleet and Elastic Agent Guide [7.15] ›Elastic Agents

Install Elastic Agents

edit

Install Elastic Agents

edit

To collect and ship data to the Elastic Stack, install an Elastic Agent on each host you want to monitor. These steps assume that you’re running a fresh installation. If Elastic Agent is already running on your system and you want to upgrade to a new version, see Upgrade Elastic Agent.

You have a few options for installing and managing an Elastic Agent:

  • Install a Fleet-managed Elastic Agent (recommended)

    With Fleet, you enroll each agent in a policy defined in Kibana and stored in Elasticsearch. The policy specifies how to collect observability data from the services you want to monitor. The Elastic Agent connects to a trusted Fleet Server instance to retrieve the policy and report agent events.

    We recommend using Fleet management because it makes the management and upgrade of your agents considerably easier.

    See Install a Fleet-managed Elastic Agent.

  • Run an Elastic Agent standalone (advanced users)

    With standalone mode, you manually configure and manage Elastic Agents locally on the systems where they are installed. This approach is recommended for advanced users only.

    See Run Elastic Agent standalone (advanced users).

Running Elastic Agent in standalone mode is an advanced use case. The documentation is incomplete and not yet mature. When possible, we recommend using Fleet-managed agents instead of standalone mode.

Install a Fleet-managed Elastic Agent

edit

This section shows the commands to install an Elastic Agent and enroll it in Fleet. If you’re a new user, read the Quick Start and follow the in-product steps in Kibana, if possible, instead of following the steps described here.

Prerequisites:

  • Fleet is currently only available to users with the superuser role.
  • A Fleet Server must be running in a location accessible to the Elastic Agent. See Fleet Server.
  • In order to use Fleet, the Elastic Agents must have a direct network connection to Fleet Server and Elasticsearch.
  • An internet connection is required for Kibana to download integration packages from the Elastic Package Registry. Make sure the Kibana server can connect to https://epr.elastic.co on port 443.
  • You must have an enrollment token generated by Fleet. Don’t have a Fleet enrollment key? Read Fleet enrollment tokens to learn how to get one from Fleet.
  • You must have the host and IP where Fleet Server is running. Not sure where it’s running? Look at the Fleet settings in Kibana.
  • If you’re running Elastic Agent 7.9 or earlier, stop the agent and manually remove it from your host.

To install an Elastic Agent and enroll it in Fleet:

  1. On your host, download and extract the installation package.

    curl -L -O https://artifacts.elastic.co/downloads/beats/elastic-agent/elastic-agent-7.15.2-darwin-x86_64.tar.gz
tar xzvf elastic-agent-7.15.2-darwin-x86_64.tar.gz

  2. From the agent directory, run the following commands to install Elastic Agent, enroll it in Fleet, and start it as a service.

    On macOS, Linux (tar package), and Windows, run the install command to install Elastic Agent as a managed service, enroll it in Fleet, and start the service. The DEB and RPM packages include a service unit for Linux systems with systemd, so use the enroll command instead of install.

    You must run this command as the root user because some integrations require root privileges to collect sensitive data.

    cd elastic-agent-7.15.2-darwin-x86_64
sudo ./elastic-agent install -f --url=<fleet_server_url> --enrollment-token=<enrollment_token>

    fleet_server_url is the host and IP where Fleet Server is running, and enrollment_token is the enrollment token acquired from Fleet.

    Omit -f to run an interactive installation.

    If you see an "x509: certificate signed by unknown authority" error, you might be trying to enroll in a Fleet Server that uses self-signed certs. To fix this problem in a non-production environment, pass the --insecure flag. For more information, refer to the troubleshooting guide.

    Refer to Installation layout for the location of installed Elastic Agent files.

Because Elastic Agent is installed as an auto-starting service, it will restart automatically if the system is rebooted.

To confirm that Elastic Agent is installed and running, go to the Agents tab in Fleet.

If you run into problems:

Installation layout

edit

When you run the install command, Elastic Agent installs files in the following locations. You cannot override these installation paths because they are required for upgrades.

/Library/Elastic/Agent/*
Elastic Agent program files
/Library/Elastic/Agent/elastic-agent.yml
Main Elastic Agent configuration
/Library/Elastic/Agent/fleet.yml
Main Elastic Agent Fleet configuration
/Library/Elastic/Agent/data/elastic-agent-*/logs/elastic-agent-json.log
Log files for Elastic Agent[1]
/Library/Elastic/Agent/data/elastic-agent-*/logs/default/*-json.log
Log files for Beats shippers
/usr/bin/elastic-agent
Shell wrapper installed into PATH
[1] Logs are numbered log.1, log.2, and so on as they are rotated off the main log.
« Elastic Agents Uninstall Elastic Agent »