›

Elastic Agent command reference

Elastic Agent provides commands for running Elastic Agent, managing Fleet Server, and doing common tasks. The commands listed here apply to both Fleet-managed and standalone Elastic Agent.

Restrictions

Note the following restrictions for running Elastic Agent commands:

You might need to log in as a root user (or Administrator on Windows) to run the commands described here. 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.
Running Elastic Agent commands using the Windows PowerShell ISE is not supported.

diagnostics
enroll
help
inspect
install
otel [technical preview]
privileged [technical preview]
restart
run
status
uninstall
upgrade
logs
unprivileged [technical preview]
version

elastic-agent diagnostics

edit

Gather diagnostics information from the Elastic Agent and component/unit it’s running. This command produces an archive that contains:

version.txt - version information
pre-config.yaml - pre-configuration before variable substitution
variables.yaml - current variable contexts from providers
computed-config.yaml - configuration after variable substitution
components-expected.yaml - expected computed components model from the computed-config.yaml
components-actual.yaml - actual running components model as reported by the runtime manager
state.yaml - current state information of all running components
Components Directory - diagnostic information from each running component:
- goroutine.txt - goroutine dump
- heap.txt - memory allocation of live objects
- allocs.txt - sampling past memory allocations
- threadcreate.txt - traces led to creation of new OS threads
- block.txt - stack traces that led to blocking on synchronization primitives
- mutex.txt - stack traces of holders of contended mutexes
- Unit Directory - If a given unit provides specific diagnostics, it will be placed here.

Note that credentials may not be 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 may change between releases.

Synopsis

edit

elastic-agent diagnostics [--file <string>]
                          [--cpu-profile]
                          [--exclude-events]
                          [--help]
                          [global-flags]

Options

edit

--file: Specifies the output archive name. Defaults to elastic-agent-diagnostics-<timestamp>.zip, where the timestamp is the current time in UTC.
--help: Show help for the diagnostics command.
--cpu-profile: Additionally runs a 30-second CPU profile on each running component. This will generate an additional cpu.pprof file for each component.
--p: Alias for --cpu-profile.
--exclude-events: Exclude the events log files from the diagnostics archive.

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>]
                     [--daemon-timeout <duration>]
                     [--delay-enroll]
                     [--elastic-agent-cert <string>]
                     [--elastic-agent-cert-key <string>]
                     [--elastic-agent-cert-key-passphrase <string>]
                     [--force]
                     [--header <strings>]
                     [--help]
                     [--insecure ]
                     [--proxy-disabled]
                     [--proxy-header <strings>]
                     [--proxy-url <string>]
                     [--staging <string>]
                     [--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>
                     [--fleet-server-service-token-path <string>]
                     [--ca-sha256 <string>]
                     [--certificate-authorities <string>]
                     [--daemon-timeout <duration>]
                     [--delay-enroll]
                     [--elastic-agent-cert <string>]
                     [--elastic-agent-cert-key <string>]
                     [--elastic-agent-cert-key-passphrase <string>]
                     [--fleet-server-cert <string>] 
                     [--fleet-server-cert-key <string>]
                     [--fleet-server-cert-key-passphrase <string>]
                     [--fleet-server-client-auth <string>]
                     [--fleet-server-es-ca <string>]
                     [--fleet-server-es-ca-trusted-fingerprint <string>] 
                     [--fleet-server-es-cert <string>]
                     [--fleet-server-es-cert-key <string>]
                     [--fleet-server-es-insecure]
                     [--fleet-server-host <string>]
                     [--fleet-server-policy <string>]
                     [--fleet-server-port <uint16>]
                     [--fleet-server-timeout <duration>]
                     [--force]
                     [--header <strings>]
                     [--help]
                     [--non-interactive]
                     [--proxy-disabled]
                     [--proxy-header <strings>]
                     [--proxy-url <string>]
                     [--staging <string>]
                     [--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.

--daemon-timeout <duration>

Timeout waiting for Elastic Agent daemon.

--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.

--elastic-agent-cert

Certificate to use as the client certificate for the Elastic Agent’s connections to Fleet Server.

--elastic-agent-cert-key

Private key to use as for the Elastic Agent’s connections to Fleet Server.

--elastic-agent-cert-key-passphrase

The path to the file that contains the passphrase for the mutual TLS private key that Elastic Agent will use to connect to Fleet Server. The file must only contain the characters of the passphrase, no newline or extra non-printing characters.

This option is only used if the --elastic-agent-cert-key is encrypted and requires a passphrase to use.

--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-cert-key-passphrase <string>

Path to passphrase file for decrypting Fleet Server’s private key if an encrypted private key is used.

--fleet-server-client-auth <string>

One of none, optional, or required. Defaults to none. Fleet Server’s client_authentication option for client mTLS connections. If optional, or required is specified, client certificates are verified using CAs specified in the --certificate-authorities flag.

--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-cert

The path to the client certificate that Fleet Server will use when connecting to Elasticsearch.

--fleet-server-es-cert-key

The path to the private key that Fleet Server will use when connecting to 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-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. Mutually exclusive with --fleet-server-service-token-path.

--fleet-server-service-token-path <string>

Service token file to use for communication with Elasticsearch. Mutually exclusive with --fleet-server-service-token.

--fleet-server-timeout <duration>

Timeout waiting for Fleet Server to be ready to start enrollment.

--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.

--header <strings>

Headers used in communication with elasticsearch.

--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.

--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.

--proxy-disabled

Disable proxy support including environment variables.

--proxy-header <strings>

Proxy headers used with CONNECT request.

--proxy-url <string>

Configures the proxy URL.

--staging <string>

Configures agent to download artifacts from a staging build.

--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 \
  --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 --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 \
  --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 \
  --fleet-server-port=8220

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

elastic-agent enroll --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]
elastic-agent inspect components [--show-config]
                             [--show-spec]
                             [--help]
                             [id]

Options

edit

components

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

--show-config: Use to display the configuration in all units.
--show-spec: Use to get input/output runtime spectification for a component.

--help

Show help for the inspect command.

For more flags, see Global flags.

Examples

edit

elastic-agent inspect
elastic-agent inspect components --show-config
elastic-agent inspect components log-default

elastic-agent privileged

edit

Run Elastic Agent with full superuser privileges. This is the usual, default running mode for Elastic Agent. The privileged command allows you to switch back to running an agent with full administrative privileges when you have been running it in unprivileged mode.

Refer to Run Elastic Agent without administrative privileges for more detail.

Examples

edit

elastic-agent privileged

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. Note that after an upgrade of the Elastic Agent using DEB or RPM the Elastic Agent service needs to be restarted.

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>
                      [--base-path <string>]
                      [--ca-sha256 <string>]
                      [--certificate-authorities <string>]
                      [--daemon-timeout <duration>]
                      [--delay-enroll]
                      [--elastic-agent-cert <string>]
                      [--elastic-agent-cert-key <string>]
                      [--elastic-agent-cert-key-passphrase <string>]
                      [--force]
                      [--header <strings>]
                      [--help]
                      [--insecure ]
                      [--non-interactive]
                      [--privileged]
                      [--proxy-disabled]
                      [--proxy-header <strings>]
                      [--proxy-url <string>]
                      [--staging <string>]
                      [--tag <string>]
                      [--unprivileged]
                      [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>
                      [--fleet-server-service-token-path <string>]
                      [--base-path <string>]
                      [--ca-sha256 <string>]
                      [--certificate-authorities <string>]
                      [--daemon-timeout <duration>]
                      [--delay-enroll]
                      [--elastic-agent-cert <string>]
                      [--elastic-agent-cert-key <string>]
                      [--elastic-agent-cert-key-passphrase <string>]
                      [--fleet-server-cert <string>] 
                      [--fleet-server-cert-key <string>]
                      [--fleet-server-cert-key-passphrase <string>]
                      [--fleet-server-client-auth <string>]
                      [--fleet-server-es-ca <string>]
                      [--fleet-server-es-ca-trusted-fingerprint <string>] 
                      [--fleet-server-es-cert <string>]
                      [--fleet-server-es-cert-key <string>]
                      [--fleet-server-es-insecure]
                      [--fleet-server-host <string>]
                      [--fleet-server-policy <string>]
                      [--fleet-server-port <uint16>]
                      [--fleet-server-timeout <duration>]
                      [--force]
                      [--header <strings>]
                      [--help]
                      [--non-interactive]
                      [--privileged]
                      [--proxy-disabled]
                      [--proxy-header <strings>]
                      [--proxy-url <string>]
                      [--staging <string>]
                      [--tag <string>]
                      [--unprivileged]
                      [--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 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

--base-path <string>

Install Elastic Agent in a location other than the default. Specify the custom base path for the install.

The --base-path option is not currently supported with Elastic Defend.

--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.

--daemon-timeout <duration>

Timeout waiting for Elastic Agent daemon.

--delay-enroll

--elastic-agent-cert

Certificate to use as the client certificate for the Elastic Agent’s connections to Fleet Server.

--elastic-agent-cert-key

Private key to use as for the Elastic Agent’s connections to Fleet Server.

--elastic-agent-cert-key-passphrase

This option is only used if the --elastic-agent-cert-key is encrypted and requires a passphrase to use.

--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-cert-key-passphrase <string>

Path to passphrase file for decrypting Fleet Server’s private key if an encrypted private key is used.

--fleet-server-client-auth <string>

--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>

--fleet-server-es-cert

The path to the client certificate that Fleet Server will use when connecting to Elasticsearch.

--fleet-server-es-cert-key

The path to the private key that Fleet Server will use when connecting to 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-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. Mutually exclusive with --fleet-server-service-token-path.

--fleet-server-service-token-path <string>

Service token file to use for communication with Elasticsearch. Mutually exclusive with --fleet-server-service-token.

--fleet-server-timeout <duration>

Timeout waiting for Fleet Server to be ready to start enrollment.

--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.

--header <strings>

Headers used in communication with elasticsearch.

--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.

--non-interactive

--privileged

Run Elastic Agent with full superuser privileges. This is the usual, default running mode for Elastic Agent. The --privileged option allows you to switch back to running an agent with full administrative privileges when you have been running it in unprivileged.

See the --unprivileged option and Run Elastic Agent without administrative privileges for more detail.

--proxy-disabled: Disable proxy support including environment variables.
--proxy-header <strings>: Proxy headers used with CONNECT request.
--proxy-url <string>: Configures the proxy URL.
--staging <string>: Configures agent to download artifacts from a staging build.
--tag <strings>: 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.
--unprivileged: Run Elastic Agent without full superuser privileges. This option is useful in organizations that limit root access on Linux or macOS systems, or admin access on Windows systems. For details and limitations for running Elastic Agent in this mode, refer to Run Elastic Agent without administrative privileges.

Note that changing to unprivileged mode is prevented if the agent is currently enrolled in a policy that includes an integration that requires administrative access, such as the Elastic Defend integration.

--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 \
  --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 --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 \
  --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 \
  --fleet-server-port=8220

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

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

elastic-agent otel

edit

This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features.

Run Elastic Agent as an OpenTelemetry Collector.

Synopsis

edit

elastic-agent otel [flags]
elastic-agent otel [command]

You can also run the ./otelcol command, which calls ./elastic-agent otel and passes any arguments to it.

Available commands

edit

validate: Validates the OpenTelemetry collector configuration without running the collector.

Flags

edit

--config=file:/path/to/first --config=file:path/to/second: Locations to the config file(s). Note that only a single location can be set per flag entry, for example --config=file:/path/to/first --config=file:path/to/second.
--feature-gates flag: Comma-delimited list of feature gate identifiers. Prefix with - to disable the feature. Prefixing with + or no prefix will enable the feature.
-h, --help: Get help for the otel sub-command. Use elastic-agent otel [command] --help for more information about a command.
--set string: Set an arbitrary component config property. The component has to be defined in the configuration file and the flag has a higher precedence. Array configuration properties are overridden and maps are joined. For example, --set=processors::batch::timeout=2s.

Examples

edit

Run Elastic Agent as on OTel Collector using the supplied otel.yml configuration file.

./elastic-agent otel --config otel.yml

Change the default verbosity setting in the Elastic Agent OTel configuration from detailed to normal.

./elastic-agent otel --config otel.yml --set "exporters::debug::verbosity=normal"

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. The last known status of the Fleet server is also returned. The output option controls the level of detail and formatting of the information.

Synopsis

edit

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

Options

edit

--output <string>: Output the status information in either human (the default), full, json, or yaml. human returns limited information when Elastic Agent is in the HEALTHY state. If any components or units are not in HEALTHY state, then full details are displayed for that component or unit. full, json and yaml always return the full status information. Components map to individual processes running underneath Elastic Agent, for example Filebeat or Endpoint Security. Units map to discrete configuration units within that process, for example Filebeat inputs or Metricbeat modules.

When the output is json or yaml, status codes are returned as numerical values. The status codes can be mapped using the following table:

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.

Be sure to run the uninstall command from a directory outside of where Elastic Agent is installed.

For example, on a Windows system the install location is C:\Program Files\Elastic\Agent. Run the uninstall command from C:\Program Files\Elastic or \tmp, or even your default home directory:

C:\"Program Files"\Elastic\Agent\elastic-agent.exe uninstall

You must run this command as the root user.

sudo /Library/Elastic/Agent/elastic-agent uninstall

You must run this command as the root user.

sudo /opt/Elastic/Agent/elastic-agent uninstall

Open a PowerShell prompt as an Administrator (right-click the PowerShell icon and select Run As Administrator).

From the PowerShell prompt, run:

C:\"Program Files"\Elastic\Agent\elastic-agent.exe uninstall

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 unprivileged

edit

Run Elastic Agent without full superuser privileges. This is useful in organizations that limit root access on Linux or macOS systems, or admin access on Windows systems. For details and limitations for running Elastic Agent in this mode, refer to Run Elastic Agent without administrative privileges.

Note that changing a running Elastic Agent to unprivileged mode is prevented if the agent is currently enrolled with a policy that contains the Elastic Defend integration.

Examples

edit

elastic-agent unprivileged

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.
--skip-verify: Skip the package verification process. This option is not recommended as it is insecure.
--pgp-path <string>: Use a locally stored copy of the PGP key to verify the upgrade package.
--pgp-uri <string>: Use the specified online PGP key to verify the upgrade package.
--help: Show help for the upgrade command.

For details about using the --skip-verify, --pgp-path <string>, and --pgp-uri <string> package verification options, refer to Verifying Elastic Agent package signatures.

For more flags, see Global flags.

Examples

edit

elastic-agent upgrade 7.10.1

elastic-agent logs

edit

Show the logs of the running Elastic Agent.

Synopsis

edit

elastic-agent logs [--follow] [--number <int>] [--component <string>] [--no-color] [--help] [global-flags]

Options

edit

--follow or -f: Follow log updates until the command is interrupted (for example with Ctrl-C).
--number <int> or -n <int>: How many lines of logs to print. If logs following is enabled, affects the initial output.
--component <string> or -C <string>: Filter logs based on the component name.
--no-color: Disable color based on log-level of each entry.
--help: Show help for the logs command.

For more flags, see Global flags.

Example

edit

elastic-agent logs -n 100 -f -C "system/metrics-default"

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

« URL Decode Troubleshoot »