install-fleet-managed-elastic-agent.asciidoc

Install {fleet}-managed {agent}s

{fleet} is a web-based UI in {kib} for centrally managing {agent}s. To use {fleet}, you install {agent}, then enroll the agent in a policy defined in {kib}. The policy includes integrations that specify how to collect observability data from specific services and protect endpoints. The {agent} connects to a trusted {fleet-server} instance to retrieve the policy and report agent events.

Where to start

To get up and running quickly, read one of our end-to-end guides:

• New to Elastic? Read our solution {estc-welcome}/getting-started-guides.html[Getting started guides].

• Want to add data to an existing cluster or deployment? Read our [fleet-elastic-agent-quick-start].

Looking for upgrade info? Refer to [upgrade-elastic-agent].

Just want to learn how to install {agent}? Continue reading this page.

Prerequisites

You will always need:

• A {kib} user with All privileges on {fleet} and {integrations}. Since many Integrations assets are shared across spaces, users need the {kib} privileges in all spaces.

• {fleet-server} running in a location accessible to {agent}. {agent} must have a direct network connection to {fleet-server} and {es}. If you’re using our hosted {ess} on {ecloud}, {fleet-server} is already available as part of the {integrations-server}. For self-managed deployments, refer to [add-fleet-server-on-prem].

• Internet connection for {kib} to download integration packages from the {package-registry}. Make sure the {kib} server can connect to https://epr.elastic.co on port 443. If your environment has network traffic restrictions, there are ways to work around this requirement. See {fleet-guide}/air-gapped.html[Air-gapped environments] for more information.

If you are using a {fleet-server} that uses your organization’s certificate, you will also need:

• A Certificate Authority (CA) certificate to configure Transport Layer Security (TLS) to encrypt traffic. If your organization already uses the {stack}, you may already have a CA certificate. If you do not have a CA certificate, you can read more about generating one in [secure-connections].

If you’re running {agent} 7.9 or earlier, stop the agent and manually remove it from your host.

Installation steps

Note	You can install only a single {agent} per host.

{agent} can monitor the host where it’s deployed, and it can collect and forward data from remote services and hardware where direct deployment is not possible.

To install an {agent} and enroll it in {fleet}:

1. In {fleet}, open the Agents tab and click Add agent.

2. In the Add agent flyout, select an existing agent policy or create a new one. If you create a new policy, {fleet} generates a new {fleet-guide}/fleet-enrollment-tokens.html[{fleet} enrollment token].

   Note

   For on-premises deployments, you can dedicate a policy to all the agents in the network boundary and configure that policy to include a specific {fleet-server} (or a cluster of {fleet-server}s). Read more in {fleet-guide}/agent-policy.html#add-fleet-server-to-policy[Add a {fleet-server} to a policy].

3. Make sure Enroll in Fleet is selected.

4. Download, install, and enroll the {agent} on your host by selecting your host operating system and following the Install {agent} on your host step. Note that the commands shown are for AMD platforms, but ARM packages are also available. Refer to the {agent} downloads page for the full list of available packages.

   1. If you are enrolling the agent in a {fleet-server} that uses your organization’s certificate you must add the --certificate-authorities option to the command provided in the in-product instructions. If you do not include the certificate, you will see the following error: "x509: certificate signed by unknown authority".

      

After about a minute, the agent will enroll in {fleet}, download the configuration specified in the agent policy, and start collecting data.

Notes:

• If you encounter 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 {fleet-guide}/fleet-troubleshooting.html#agent-enrollment-certs[troubleshooting guide].

• Optionally, you can use the --tag flag to specify a comma-separated list of tags to apply to the enrolled {agent}. For more information, refer to {fleet-guide}/filter-agent-list-by-tags.html[Filter list of Agents by tags].

• Refer to {fleet-guide}/installation-layout.html[Installation layout] for the location of installed {agent} files.

• Because {agent} is installed as an auto-starting service, it will restart automatically if the system is rebooted.

To confirm that {agent} is installed and running, open the Agents tab in {fleet}.

Tip	If the status hangs at Enrolling, make sure the elastic-agent process is running.

If you run into problems:

• Check the {agent} logs. If you use the default policy, agent logs and metrics are collected automatically unless you change the default settings. For more information, refer to {fleet-guide}/monitor-elastic-agent.html[Monitor {agent} in {fleet}].

• Refer to the {fleet-guide}/fleet-troubleshooting.html[troubleshooting guide].

For information about managing {agent} in {fleet}, refer to {fleet-guide}/manage-agents-in-fleet.html[Centrally manage {agent}s in {fleet}].