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

Elastic Agent command reference

edit

Elastic Agent command reference

edit

Elastic Agent provides commands for running Elastic Agent, managing Fleet Server, and doing common tasks.

You might need to log in as a root user (or Administrator on Windows) to run these commands. After the Elastic Agent service is installed and running, make sure you run these commands without prepending them with ./ to avoid invoking the wrong binary.

elastic-agent diagnostics

edit

Gather diagnostics information from the Elastic Agent and applications it’s running.

If no options are specified, this command displays version numbers and application metadata.

If collect is specified, it produces an archive containing application metadata, configuration information, the policy, local logs, and metrics data (if the buffer is enabled).

Note that credentials are not redacted in the archive; they may appear in plain text in the configuration or policy files inside the archive.

This command is intended for debugging purposes only. The output format and structure of the archive produced by collect may change between releases.

If pprof is specified, it gathers specific pprof data from the Elastic Agent or one of the specified underlying Beats, and displays to stdout. By default it gathers a 30 second profile of the Elastic Agent.

Synopsis

edit
elastic-agent diagnostics [--help] [--output <string>] [global-flags]
elastic-agent diagnostics collect [--output <string>]
                                  [--file <string>]
                                  [--pprof]
                                  [--pprof-duration <string>]
                                  [--timeout <string>]
                                  [--help]
                                  [global-flags]
elastic-agent diagnostics pprof [--file <string>]
                                [--pprof-type <string]
                                [--pprof-duration <string>]
                                [--timeout <string>]
                                [--pprof-application <string>]
                                [--pprof-route-key <string>]
                                [--help]
                                [global-flags]

Options

edit
--output <string>
Output format. If using collect, specify json or yaml (the default). Otherwise specify json, yaml, or human (the default).
--file

When running collect, specifies the output archive name. Defaults to elastic-agent-diagnostics-<timestamp>.zip, where the timestamp is the current time in UTC.

When running pprof, specifies the output file name. Defaults to stdout.

--pprof
Gather pprof data when running collect (default false).
--pprof-duration <string>
The length for the trace and profile data that’s collected when gathering pprof data. Must be a string that can be parsed as a time.Duration value (default: 30s).
--timeout <string>
The timeout value for the diagnostics collect or diagnostics pprof command. Should be longer then pprof-duration as the command needs to gather and process the data. Must be a string that can be parsed as a time.Duration value (default: 30s + pprof-duration).
--pprof-type <string>
The pprof data to gather, one of: allocs, block, cmdline, goroutine, heap, mutex, profile, threadcreate, or trace (default: profile).
--pprof-application <string>
The application name to gather pprof data from (default elastic-agent).
--pprof-route-key <string>
The route key (output destination) associated with the application to gather pprof data from (default default). Note that this setting is ignored in the case where pprof-application=elastic-agent.
--help
Show help for the diagnostics command.

For more flags, see Global flags.

Example

edit
elastic-agent diagnostics

elastic-agent enroll

edit

Enroll the Elastic Agent in Fleet.

Use this command to enroll the Elastic Agent in Fleet without installing the agent as a service. You will need to do this if you installed the Elastic Agent from a DEB or RPM package and plan to use systemd commands to start and manage the service. This command is also useful for testing Elastic Agent prior to installing it.

If you’ve already installed Elastic Agent, use this command to modify the settings that Elastic Agent runs with.

To enroll an Elastic Agent and install it as a service, use the install command instead. Installing as a service is the most common scenario.

We recommend that you run the enroll (or install) command as the root user because some integrations require root privileges to collect sensitive data. This command overwrites the elastic-agent.yml file in the agent directory.

This command includes optional flags to set up Fleet Server.

This command enrolls the Elastic Agent in Fleet; it does not start the agent. To start the agent, either start the service, if one exists, or use the run command to start the agent from a terminal.

Synopsis

edit

To enroll the Elastic Agent in Fleet:

elastic-agent enroll --url <string>
                     --enrollment-token <string>
                     [--ca-sha256 <string>]
                     [--certificate-authorities <string>]
                     [--delay-enroll]
                     [--force]
                     [--non-interactive]
                     [--help]
                     [--insecure ]
                     [--tag <string>]
                     [global-flags]

To enroll the Elastic Agent in Fleet and set up Fleet Server:

elastic-agent enroll --fleet-server-es <string>
                     --fleet-server-service-token <string>
                     [--ca-sha256 <string>]
                     [--certificate-authorities <string>]
                     [--delay-enroll]
                     [--fleet-server-cert <string>] 
                     [--fleet-server-cert-key <string>]
                     [--fleet-server-es-ca <string>]
                     [--fleet-server-es-ca-trusted-fingerprint <string>] 
                     [--fleet-server-es-insecure]
                     [--fleet-server-host <string>]
                     [--fleet-server-insecure-http]
                     [--fleet-server-policy <string>]
                     [--fleet-server-port <uint16>]
                     [--force]
                     [--non-interactive]
                     [--help]
                     [--tag <string>]
                     [--url <string>] 
                     [global-flags]

If no fleet-server-cert* flags are specified, Elastic Agent auto-generates a self-signed certificate with the hostname of the machine. Remote Elastic Agents enrolling into a Fleet Server with self-signed certificates must specify the --insecure flag.

Required when using self-signed certificates with Elasticsearch.

Required when enrolling in a Fleet Server with custom certificates. The URL must match the DNS name used to generate the certificate specified by --fleet-server-cert.

For more information about custom certificates, refer to Configure SSL/TLS for self-managed Fleet Servers.

Options

edit
--ca-sha256 <string>
Comma-separated list of certificate authority hash pins used for certificate verification.
--certificate-authorities <string>
Comma-separated list of root certificates used for server verification.
--delay-enroll
Delays enrollment to occur on first start of the Elastic Agent service. This setting is useful when you don’t want the Elastic Agent to enroll until the next reboot or manual start of the service, for example, when you’re preparing an image that includes Elastic Agent.
--enrollment-token <string>
Enrollment token to use to enroll Elastic Agent into Fleet. You can use the same enrollment token for multiple agents.
--fleet-server-cert <string>
Certificate to use for exposed Fleet Server HTTPS endpoint.
--fleet-server-cert-key <string>
Private key to use for exposed Fleet Server HTTPS endpoint.
--fleet-server-es <string>
Start a Fleet Server process when Elastic Agent is started, and connect to the specified Elasticsearch URL.
--fleet-server-es-ca <string>
Path to certificate authority to use to communicate with Elasticsearch.
--fleet-server-es-ca-trusted-fingerprint <string>
The SHA-256 fingerprint (hash) of the certificate authority used to self-sign Elasticsearch certificates. This fingerprint will be used to verify self-signed certificates presented by Fleet Server and any inputs started by Elastic Agent for communication. This flag is required when using self-signed certificates with Elasticsearch.
--fleet-server-es-insecure

Allows fleet server to connect to Elasticsearch in the following situations:

  • When connecting to an HTTP server.
  • When connecting to an HTTPs server and the certificate chain cannot be verified. The content is encrypted, but the certificate is not verified.

When this flag is used the certificate verification is disabled.

--fleet-server-host <string>
Fleet Server HTTP binding host (overrides the policy).
--fleet-server-insecure-http
Expose Fleet Server over HTTP. This option is not recommended because it’s insecure. It’s useful during development and testing, but should not be used in production. When using this option, you should bind Fleet Server to the local host (this is the default).
--fleet-server-policy <string>
Used when starting a self-managed Fleet Server to allow a specific policy to be used.
--fleet-server-port <uint16>
Fleet Server HTTP binding port (overrides the policy).
--fleet-server-service-token <string>
Service token to use for communication with Elasticsearch.
--force

Force overwrite of current configuration without prompting for confirmation. This flag is helpful when using automation software or scripted deployments.

If the Elastic Agent is already installed on the host, using --force may result in unpredictable behavior with duplicate Elastic Agents appearing in Fleet.

--non-interactive
Install Elastic Agent in a non-interactive mode. This flag is helpful when using automation software or scripted deployments. If Elastic Agent is already installed on the host, the installation will terminate.
--help
Show help for the enroll command.
--insecure

Allow the Elastic Agent to connect to Fleet Server over insecure connections. This setting is required in the following situations:

  • When connecting to an HTTP server. The API keys are sent in clear text.
  • When connecting to an HTTPs server and the certificate chain cannot be verified. The content is encrypted, but the certificate is not verified.
  • When using self-signed certificates generated by Elastic Agent.

We strongly recommend that you use a secure connection.

--tag <string>

A comma-separated list of tags to apply to Fleet-managed Elastic Agents. You can use these tags to filter the list of agents in Fleet.

Currently, there is no way to remove or edit existing tags. To change the tags, you must unenroll the Elastic Agent, then re-enroll it using new tags.

--url <string>
Fleet Server URL to use to enroll the Elastic Agent into Fleet.

For more flags, see Global flags.

Examples

edit

Enroll the Elastic Agent in Fleet:

elastic-agent enroll -f \
  --url=https://cedd4e0e21e240b4s2bbbebdf1d6d52f.fleet.eu-west-1.aws.cld.elstc.co:443 \
  --enrollment-token=NEFmVllaa0JLRXhKebVKVTR5TTI6N2JaVlJpSGpScmV0ZUVnZVlRUExFQQ==

Enroll the Elastic Agent in Fleet and set up Fleet Server:

elastic-agent enroll -f --fleet-server-es=http://elasticsearch:9200 \
  --fleet-server-service-token=AbEAAdesYXN1abMvZmxlZXQtc2VldmVyL3Rva2VuLTE2MTkxMzg3MzIzMTg7dzEta0JDTmZUcGlDTjlwRmNVTjNVQQ \
  --fleet-server-policy=a35fd520-26f5-11ec-8bd9-3374690g57b6

Start Elastic Agent with Fleet Server (running on a custom CA). This example assumes you’ve generated the certificates with the following names:

  • ca.crt: Root CA certificate
  • fleet-server.crt: Fleet Server certificate
  • fleet-server.key: Fleet Server private key
  • elasticsearch-ca.crt: CA certificate to use to connect to Elasticsearch 
elastic-agent enroll -f \
  --url=https://fleet-server:8220 \
  --fleet-server-es=https://elasticsearch:9200 \
  --fleet-server-service-token=AAEBAWVsYXm0aWMvZmxlZXQtc2XydmVyL3Rva2VuLTE2MjM4OTAztDU1OTQ6dllfVW1mYnFTVjJwTC2ZQ0EtVnVZQQ \
  --fleet-server-policy=a35fd520-26f5-11ec-8bd9-3374690g57b6 \
  --certificate-authorities=/path/to/ca.crt \
  --fleet-server-es-ca=/path/to/elasticsearch-ca.crt \
  --fleet-server-cert=/path/to/fleet-server.crt \
  --fleet-server-cert-key=/path/to/fleet-server.key

Then enroll another Elastic Agent into the Fleet Server started in the previous example:

elastic-agent enroll -f --url=https://fleet-server:8220 \
  --enrollment-token=NEFmVllaa0JLRXhKebVKVTR5TTI6N2JaVlJpSGpScmV0ZUVnZVlRUExFQQ== \
  --certificate-authorities=/path/to/ca.crt

elastic-agent help

edit

Show help for a specific command.

Synopsis

edit
elastic-agent help <command> [--help] [global-flags]

Options

edit
command
The name of the command.
--help
Show help for the help command.

For more flags, see Global flags.

Example

edit
elastic-agent help enroll

elastic-agent inspect

edit

Show the current Elastic Agent configuration.

If no parameters are specified, shows the full Elastic Agent configuration.

Synopsis

edit
elastic-agent inspect [--help] [global-flags]
elastic-agent inspect output [--output <string>]
                             [--program <string>]
                             [--help]
                             [global-flags]

Options

edit
output

Display the current configuration for the output. This command accepts additional flags:

--output <string>
The name of the output to inspect.
--program <string>
The type of program to inspect. For example, filebeat. This option must be combined with --output.
--help
Show help for the inspect command.

For more flags, see Global flags.

Examples

edit
elastic-agent inspect
elastic-agent inspect output --output default
elastic-agent inspect output --output default --program filebeat

elastic-agent install

edit

Install Elastic Agent permanently on the system and manage it by using the system’s service manager. The agent will start automatically after installation is complete. On Linux (tar package), this command requires a system and service manager like systemd.

If you installed Elastic Agent from a DEB or RPM package, the install command will skip the installation itself and function as an alias of the enroll command instead.

You must run this command as the root user (or Administrator on Windows) to write files to the correct locations. This command overwrites the elastic-agent.yml file in the agent directory.

The syntax for running this command varies by platform. For platform-specific examples, refer to Install Elastic Agents.

Synopsis

edit

To install the Elastic Agent as a service, enroll it in Fleet, and start the elastic-agent service:

elastic-agent install --url <string>
                      --enrollment-token <string>
                      [--ca-sha256 <string>]
                      [--certificate-authorities <string>]
                      [--delay-enroll]
                      [--force]
                      [--non-interactive]
                      [--help]
                      [--insecure ]
                      [--tag <string>]
                      [global-flags]

To install the Elastic Agent as a service, enroll it in Fleet, and start a fleet-server process alongside the elastic-agent service:

elastic-agent install --fleet-server-es <string>
                      --fleet-server-service-token <string>
                      [--ca-sha256 <string>]
                      [--certificate-authorities <string>]
                      [--delay-enroll]
                      [--fleet-server-cert <string>] 
                      [--fleet-server-cert-key <string>]
                      [--fleet-server-es-ca <string>]
                      [--fleet-server-es-ca-trusted-fingerprint <string>] 
                      [--fleet-server-host <string>]
                      [--fleet-server-insecure-http]
                      [--fleet-server-policy <string>]
                      [--fleet-server-port <uint16>]
                      [--force]
                      [--non-interactive]
                      [--help]
                      [--tag <string>]
                      [--url <string>] 
                      [--fleet-server-es-insecure]
                      [global-flags]

If no fleet-server-cert* flags are specified, Elastic Agent auto-generates a self-signed certificate with the hostname of the machine. Remote Elastic Agents enrolling into a Fleet Server with self-signed certificates must specify the --insecure flag.

Required when using self-signed certificate on Elasticsearch side.

Required when enrolling in a Fleet Server with custom certificates. The URL must match the DNS name used to generate the certificate specified by --fleet-server-cert.

For more information about custom certificates, refer to Configure SSL/TLS for self-managed Fleet Servers.

Options

edit
--ca-sha256 <string>
Comma-separated list of certificate authority hash pins used for certificate verification.
--certificate-authorities <string>
Comma-separated list of root certificates used for server verification.
--delay-enroll
Delays enrollment to occur on first start of the Elastic Agent service. This setting is useful when you don’t want the Elastic Agent to enroll until the next reboot or manual start of the service, for example, when you’re preparing an image that includes Elastic Agent.
--enrollment-token <string>
Enrollment token to use to enroll Elastic Agent into Fleet. You can use the same enrollment token for multiple agents.
--fleet-server-cert <string>
Certificate to use for exposed Fleet Server HTTPS endpoint.
--fleet-server-cert-key <string>
Private key to use for exposed Fleet Server HTTPS endpoint.
--fleet-server-es <string>
Start a Fleet Server process when Elastic Agent is started, and connect to the specified Elasticsearch URL.
--fleet-server-es-ca <string>
Path to certificate authority to use to communicate with Elasticsearch.
--fleet-server-es-ca-trusted-fingerprint <string>
The SHA-256 fingerprint (hash) of the certificate authority used to self-sign Elasticsearch certificates. This fingerprint will be used to verify self-signed certificates presented by Fleet Server and any inputs started by Elastic Agent for communication. This flag is required when using self-signed certificates with Elasticsearch.
--fleet-server-es-insecure

Allows fleet server to connect to Elasticsearch in the following situations:

  • When connecting to an HTTP server.
  • When connecting to an HTTPs server and the certificate chain cannot be verified. The content is encrypted, but the certificate is not verified.

When this flag is used the certificate verification is disabled.

--fleet-server-host <string>
Fleet Server HTTP binding host (overrides the policy).
--fleet-server-insecure-http
Expose Fleet Server over HTTP. This option is not recommended because it’s insecure. It’s useful during development and testing, but should not be used in production. When using this option, you should bind Fleet Server to the local host (this is the default).
--fleet-server-policy <string>
Used when starting a self-managed Fleet Server to allow a specific policy to be used.
--fleet-server-port <uint16>
Fleet Server HTTP binding port (overrides the policy).
--fleet-server-service-token <string>
Service token to use for communication with Elasticsearch.
--force

Force overwrite of current configuration without prompting for confirmation. This flag is helpful when using automation software or scripted deployments.

If the Elastic Agent is already installed on the host, using --force may result in unpredictable behavior with duplicate Elastic Agents appearing in Fleet.

--non-interactive
Install Elastic Agent in a non-interactive mode. This flag is helpful when using automation software or scripted deployments. If Elastic Agent is already installed on the host, the installation will terminate.
--help
Show help for the enroll command.
--insecure

Allow the Elastic Agent to connect to Fleet Server over insecure connections. This setting is required in the following situations:

  • When connecting to an HTTP server. The API keys are sent in clear text.
  • When connecting to an HTTPs server and the certificate chain cannot be verified. The content is encrypted, but the certificate is not verified.
  • When using self-signed certificates generated by Elastic Agent.

We strongly recommend that you use a secure connection.

--tag <string>

A comma-separated list of tags to apply to Fleet-managed Elastic Agents. You can use these tags to filter the list of agents in Fleet.

Currently, there is no way to remove or edit existing tags. To change the tags, you must unenroll the Elastic Agent, then re-enroll it using new tags.

--url <string>
Fleet Server URL to use to enroll the Elastic Agent into Fleet.

For more flags, see Global flags.

Examples

edit

Install the Elastic Agent as a service, enroll it in Fleet, and start the elastic-agent service:

elastic-agent install -f \
  --url=https://cedd4e0e21e240b4s2bbbebdf1d6d52f.fleet.eu-west-1.aws.cld.elstc.co:443 \
  --enrollment-token=NEFmVllaa0JLRXhKebVKVTR5TTI6N2JaVlJpSGpScmV0ZUVnZVlRUExFQQ==

Install the Elastic Agent as a service, enroll it in Fleet, and start a fleet-server process alongside the elastic-agent service:

elastic-agent install -f --fleet-server-es=http://elasticsearch:9200 \
  --fleet-server-service-token=AbEAAdesYXN1abMvZmxlZXQtc2VldmVyL3Rva2VuLTE2MTkxMzg3MzIzMTg7dzEta0JDTmZUcGlDTjlwRmNVTjNVQQ \
  --fleet-server-policy=a35fd620-26f6-11ec-8bd9-3374690f57b6

Start Elastic Agent with Fleet Server (running on a custom CA). This example assumes you’ve generated the certificates with the following names:

  • ca.crt: Root CA certificate
  • fleet-server.crt: Fleet Server certificate
  • fleet-server.key: Fleet Server private key
  • elasticsearch-ca.crt: CA certificate to use to connect to Elasticsearch 
elastic-agent install -f \
  --url=https://fleet-server:8220 \
  --fleet-server-es=https://elasticsearch:9200 \
  --fleet-server-service-token=AAEBAWVsYXm0aWMvZmxlZXQtc2XydmVyL3Rva2VuLTE2MjM4OTAztDU1OTQ6dllfVW1mYnFTVjJwTC2ZQ0EtVnVZQQ \
  --fleet-server-policy=a35fd520-26f5-11ec-8bd9-3374690g57b6 \
  --certificate-authorities=/path/to/ca.crt \
  --fleet-server-es-ca=/path/to/elasticsearch-ca.crt \
  --fleet-server-cert=/path/to/fleet-server.crt \
  --fleet-server-cert-key=/path/to/fleet-server.key

Then install another Elastic Agent and enroll it into the Fleet Server started in the previous example:

elastic-agent install -f --url=https://fleet-server:8220 \
  --enrollment-token=NEFmVllaa0JLRXhKebVKVTR5TTI6N2JaVlJpSGpScmV0ZUVnZVlRUExFQQ== \
  --certificate-authorities=/path/to/ca.crt

elastic-agent restart

edit

Restart the currently running Elastic Agent daemon.

Synopsis

edit
elastic-agent restart [--help] [global-flags]

Options

edit
--help
Show help for the restart command.

For more flags, see Global flags.

Examples

edit
elastic-agent restart

elastic-agent run

edit

Start the elastic-agent process.

Synopsis

edit
elastic-agent run [global-flags]

Global flags

edit

These flags are valid whenever you run elastic-agent on the command line.

-c <string>
The configuration file to use. If not specified, Elastic Agent uses {path.config}/elastic-agent.yml.
--e
Log to stderr and disable syslog/file output.
--environment <environmentVar>
The environment in which the agent will run.
--path.config <string>
The directory where Elastic Agent looks for its configuration file. The default varies by platform.
--path.home <string>

The root directory of Elastic Agent. path.home determines the location of the configuration files and data directory.

If not specified, Elastic Agent uses the current working directory.

--path.logs <string>
Path to the log output for Elastic Agent. The default varies by platform.
--v
Set log level to INFO.

Example

edit
elastic-agent run -c myagentconfig.yml

elastic-agent status

edit

Returns the current status of the running Elastic Agent daemon and of each process in the Elastic Agent.

Synopsis

edit
elastic-agent status [--output <string>]
                     [--help]
                     [global-flags]

Options

edit
--output <string>

Output the status information in either human (the default), json, or yaml. When the output is json or yaml, the command returns status codes:

Code Status

0

STARTING

1

CONFIGURING

2

HEALTHY

3

DEGRADED

4

FAILED

5

STOPPING

6

UPGRADING

7

ROLLBACK
--help
Show help for the status command.

For more flags, see Global flags.

Examples

edit
elastic-agent status

elastic-agent uninstall

edit

Permanently uninstall Elastic Agent from the system.

You must run this command as the root user (or Administrator on Windows) to remove files.

Synopsis

edit
elastic-agent uninstall [--force] [--help] [global-flags]

Options

edit
--force
Uninstall Elastic Agent and do not prompt for confirmation. This flag is helpful when using automation software or scripted deployments.
--help
Show help for the uninstall command.

For more flags, see Global flags.

Examples

edit
elastic-agent uninstall

elastic-agent upgrade

edit

Upgrade the currently running Elastic Agent to the specified version. This should only be used with agents running in standalone mode. Agents enrolled in Fleet should be upgraded through Fleet.

Synopsis

edit
elastic-agent upgrade <version> [--source-uri <string>] [--help] [flags]

Options

edit
version
The version of Elastic Agent to upgrade to.
--source-uri <string>
The source URI to download the new version from. By default, Elastic Agent uses the Elastic Artifacts URL.
--help
Show help for the upgrade command.

For more flags, see Global flags.

Examples

edit
elastic-agent upgrade 7.10.1

elastic-agent version

edit

Show the version of Elastic Agent.

Synopsis

edit
elastic-agent version [--help] [global-flags]

Options

edit
--help
Show help for the version command.

For more flags, see Global flags.

Example

edit
elastic-agent version
« Reference YAML Troubleshoot »