Elastic Agent command reference
editElastic Agent command reference
editElastic 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
editGather 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, and any local logs.
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.
Synopsis
editelastic-agent diagnostics [--help] [--output <string>] [global-flags] elastic-agent diagnostics collect [--output <string>] [--file <string>] [--help] [global-flags]
Options
edit-
--output <string>
-
Output format. If using
collect
, specifyjson
oryaml
(the default). Otherwise specifyjson
,yaml
, orhuman
(the default). -
--file
-
Output archive name for the
collect
option. Defaults toelastic-agent-diagnostics-<timestamp>.zip
where the timestamp is the current time in UTC. -
--help
-
Show help for the
diagnostics
command.
For more flags, see Global flags.
Example
editelastic-agent diagnostics
elastic-agent enroll
editEnroll 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
editTo enroll the Elastic Agent in Fleet:
elastic-agent enroll --url <string> --enrollment-token <string> [--ca-sha256 <string>] [--certificate-authorities <string>] [--delay-enroll] [--force] [--help] [--insecure ] [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-host <string>] [--fleet-server-insecure-http] [--fleet-server-policy <string>] [--fleet-server-port <uint16>] [--force] [--help] [--url <string>] [--fleet-server-es-insecure ] [global-flags]
If no |
|
Required when enrolling in a Fleet Server with custom certificates. The
URL must match the DNS name used to generate the certificate specified by
|
|
Required when using self-signed certificate on Elasticsearch side. |
For more information about custom certificates, refer to Encrypt traffic in clusters with a self-managed Fleet Server.
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-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 using self-signed certificates.
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, instead of the Default Fleet Server policy.
-
--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.
-
--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.
-
--url <string>
- Fleet Server URL to use to enroll the Elastic Agent into Fleet.
For more flags, see Global flags.
Examples
editEnroll 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
editShow help for a specific command.
Synopsis
editelastic-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
editelastic-agent help enroll
elastic-agent inspect
editShow the current Elastic Agent configuration.
If no parameters are specified, shows the full Elastic Agent configuration.
Synopsis
editelastic-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
editelastic-agent inspect elastic-agent inspect output --output default elastic-agent inspect output --output default --program filebeat
elastic-agent install
editInstall 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, use the
enroll
command instead of install
. The DEB
and RPM packages include a service unit for Linux systems with systemd.
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
editTo 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] [--help] [--insecure ] [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-host <string>] [--fleet-server-insecure-http] [--fleet-server-policy <string>] [--fleet-server-port <uint16>] [--force] [--help] [--url <string>] [--fleet-server-es-insecure ] [global-flags]
If no |
|
Required when enrolling in a Fleet Server with custom certificates. The
URL must match the DNS name used to generate the certificate specified by
|
|
Required when using self-signed certificate on Elasticsearch side. |
For more information about custom certificates, refer to Encrypt traffic in clusters with a self-managed Fleet Server.
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-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 using self-signed certificates.
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, instead of the Default Fleet Server policy.
-
--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.
-
--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.
-
--url <string>
- Fleet Server URL to use to enroll the Elastic Agent into Fleet.
For more flags, see Global flags.
Examples
editInstall 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
editRestart the currently running Elastic Agent daemon.
Synopsis
editelastic-agent restart [--help] [global-flags]
Options
edit-
--help
-
Show help for the
restart
command.
For more flags, see Global flags.
Examples
editelastic-agent restart
elastic-agent run
editStart the elastic-agent
process.
Synopsis
editelastic-agent run [global-flags]
Global flags
editThese 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
editelastic-agent run -c myagentconfig.yml
elastic-agent status
editReturns the current status of the running Elastic Agent daemon and of each process in the Elastic Agent.
Synopsis
editelastic-agent status [--output <string>] [--help] [global-flags]
Options
edit-
--output <string>
-
Output the status information in either
human
(the default),json
, oryaml
. When the output isjson
oryaml
, 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
editelastic-agent status
elastic-agent uninstall
editPermanently uninstall Elastic Agent from the system.
You must run this command as the root user (or Administrator on Windows) to remove files.
Synopsis
editelastic-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
editelastic-agent uninstall
elastic-agent upgrade
editUpgrade 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
editelastic-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
editelastic-agent upgrade 7.10.1
elastic-agent version
editShow the version of Elastic Agent.
Synopsis
editelastic-agent version [--help] [global-flags]
Options
edit-
--help
-
Show help for the
version
command.
For more flags, see Global flags.
Example
editelastic-agent version