diff --git a/x-pack/elastic-agent/docs/elastic-agent.asciidoc b/x-pack/elastic-agent/docs/elastic-agent.asciidoc index 67aa02651e6..f2a092c7d47 100644 --- a/x-pack/elastic-agent/docs/elastic-agent.asciidoc +++ b/x-pack/elastic-agent/docs/elastic-agent.asciidoc @@ -1,78 +1,242 @@ -Agent's notes - - -[[requirements]] -Requirements - -The remote Kibana version of the Agent must be equal or higher than the Agent version, if this is not met -Kibana will refuse the connection. - - -[[Supported Actions by the Agent]] - -The Elastic Agent supports the following actions received by Fleet. - -Implemented: - -[[Configuration change]] - -The Elastic Agent receives a configuration encoded as a JSON object. - -[source,json] ------------------------------------------------------------------------------- - { - "type": "CONFIG_CHANGE", - "id": "id1", - "data": { - "config": { - "id": "policy-id", - "outputs": { - "default": { - "hosts": "https://localhost:9200" - } - }, - "datasources": [{ - "id": "string", - "enabled": true, - "use_output": "default", - "inputs": [{ - "type": "logs", - "streams": [{ - "paths": ["/var/log/hello.log"] - }] - }] - }] - } - } - } ------------------------------------------------------------------------------- - -[[Planned but not implemented]] - -[source,json] ------------------------------------------------------------------------------- -{ - "type": "UPGRADE", - "id": "id1", - "target_version": "7.2.1" -} ------------------------------------------------------------------------------- - -[source,json] ------------------------------------------------------------------------------- -{ - "type": "DOWNGRADE", - "id": "id1", - "target_version": "7.2.1" -} ------------------------------------------------------------------------------- - -[source,json] ------------------------------------------------------------------------------- -{ - "type": "RELAY", - "id": "id1", - "destination": {"name":"endpoint"} - "data": {} -} ------------------------------------------------------------------------------- +[[elastic-agent-installation-configuration]] +== Get started with {beatname_uc} + +++++ +Get started +++++ + +Elastic Agent is a single, unified agent that you can deploy to hosts or containers to collect data and send it to the {stack}. Behind the scenes, Elastic Agent runs the {beats} shippers or Endpoint required for your configuration. + +* <> +* <> +* <> +* <> + +[[elastic-agent-installation]] +== Install Elastic Agent + +=== Step 1: Unpack archive + + +[[mac]] +*mac:* + +ifeval::["{release-state}"=="unreleased"] + +Version {version} of {beatname_uc} has not yet been released. + +endif::[] + +ifeval::["{release-state}"!="unreleased"] + +["source","sh",subs="attributes,callouts"] +------------------------------------------------ +curl -L -O https://artifacts.elastic.co/downloads/beats/elastic-agent/elastic-agent-{version}-darwin-x86_64.tar.gz +tar xzvf elastic-agent-{version}-darwin-x86_64.tar.gz +------------------------------------------------ + +endif::[] + +[[linux]] +*linux:* + +ifeval::["{release-state}"=="unreleased"] + +Version {version} of {beatname_uc} has not yet been released. + +endif::[] + +ifeval::["{release-state}"!="unreleased"] + +["source","sh",subs="attributes,callouts"] +------------------------------------------------ +curl -L -O https://artifacts.elastic.co/downloads/beats/elastic-agent/elastic-agent-{version}-linux-x86_64.tar.gz +tar xzvf elastic-agent-{version}-linux-x86_64.tar.gz +------------------------------------------------ + +endif::[] + +[[win]] +*win:* + +ifeval::["{release-state}"=="unreleased"] + +Version {version} of {beatname_uc} has not yet been released. + +endif::[] + +ifeval::["{release-state}"!="unreleased"] + +. Download the Elastic Agent Windows zip file from the +https://www.elastic.co/downloads/beats/elastic-agent[downloads page]. + +. Extract the contents of the zip file into `C:\Program Files`. + +. Rename the `elastic-agent--windows` directory to `Elastic-Agent`. + +. Open a PowerShell prompt as an Administrator (right-click the PowerShell icon and select *Run As Administrator*). + +. From the PowerShell prompt, run the following commands to install Filebeat as a +Windows service: ++ +[source,shell] +---------------------------------------------------------------------- +PS > cd 'C:\Program Files\Elastic-Agent' +PS C:\Program Files\Elastic-Agent> .\install-service-elastic-agent.ps1 +---------------------------------------------------------------------- + +NOTE: If script execution is disabled on your system, you need to set the execution policy for the current session to allow the script to run. For example: `PowerShell.exe -ExecutionPolicy UnRestricted -File .\install-service-elastic-agent.ps1`. + +endif::[] + +=== Step 2: Run Elastic Agent + +If Elastic Agent is not installed as an auto-starting service, start it manually: + + +[source,shell] +---------------------------------------------------------------------- +$ ./elastic-agent run +---------------------------------------------------------------------- + +[[elastic-agent-execution-modes]] +== Execution modes + +Elastic Agent runs in two modes: standalone or fleet. The two modes differ in how you configure and manage the agent. +[float] +=== Standalone mode + +With _standalone mode_, you manually configure and manage the agent locally. Each agent is configured to be in standalone mode by default after installation. +At startup, Elastic Agent reads the configuration file specified by the `-c` argument or uses the default configuration, `elastic-agent.yml`, which is located in the same directory as the agent. + +For configuration options see `elastic-agent_configuration_example.yml` + +=== Fleet mode + +With _fleet mode_, you manage Elastic Agent remotely. The agent uses a trusted {kib} instance to retrieve configurations and report agent events. This trusted {kib} instance must have Ingest Manager and Fleet enabled. + +To create a trusted communication channel between Elastic Agent and {kib}, you enroll the agent to Fleet. + +To enroll an Elastic Agent to Fleet: + + +. Stop the agent. + +. Enroll the agent: ++ +[source,shell] +---------------------------------------------------------------------- +$ ./elastic-agent http://localhost:5601 $token +---------------------------------------------------------------------- ++ +`$token` is an enrollment token acquired from Fleet. + +[[elastic-agent-cmd-options]] +== Command line options + +The `elastic-agent run` command provides flags that alter the behavior of an agent. + +==== `-path.home` + +The home directory of the Elastic Agent. `path.home` determines the location of the configuration files and data directory. + +==== `-c` + +The configuration file to load. +If not specified, Elastic Agent uses `{path.home}/elastic-agent.yml`. + + +==== `-path.data` + +The data directory used by Elastic Agent to store downloaded artifacts. Also stores logs for any Beats started and managed by Elastic Agent. + +If not specified, Elastic Agent uses `{path.home}/data`. + +[[elastic-agent-configuration]] +== Configure Elastic Agent + +By default Elastic Agent runs in standalone mode to ingest system data and send it to a local {es} instance running on port 9200. It uses the demo credentials of the `elastic` user. It's also configured to monitor all Beats managed by the agent and send the Beats logs and metrics to the same {es) instance. + +To alter this behavior, configure the output. + +=== Configure the output + +Elastic Agent enables definition of multiple outputs where each data source can be paired with different output. + +At the moment Elastic Agent works only with Elasticsearch output. +Sample configuration can look like the example below: + +[source,yaml] +------------------------------------------------------------------------------------- +outputs: + default: + type: elasticsearch + hosts: [127.0.0.1:9200] + username: elastic + password: changeme + + monitoring: + type: elasticsearch + api_key: VuaCfGcBCdbkQm-e5aOx:ui2lp2axTNmsyakw9tvNnw + hosts: ["localhost:9200"] + ca_sha256: "7lHLiyp4J8m9kw38SJ7SURJP4bXRZv/BNxyyXkCcE/M=" +------------------------------------------------------------------------------------- + +This example configures two outputs: `default` and `monitoring`. +Notice that they use different authentication methods. The first one uses a username and password pair, and the second one contains an api key. + +[NOTE] +============== +A default output configuration is required. +============== + +=== Configure Beats monitoring + +Elastic Agent is monitoring _Beats_ by default. To disable or change monitoring settings, set options under `settings.monitoring`: + +[source,yaml] +------------------------------------------------------------------------------------- +settings.monitoring: + # enabled turns on monitoring of running processes + enabled: true + # enables log monitoring + logs: true + # enables metrics monitoring + metrics: true + # specifies output to be used + use_output: monitoring +------------------------------------------------------------------------------------- + + +To disable monitoring, set `settings.monitoring.enabled` to `false`. When set to `false`, Beats monitoring is turned off, and all other options in this section are ignored. +To enable monitoring, set `settings.monitoring.enabled` to `true`. Also set the `logs` and `metrics` settings to control whether logs, metrics, or both are collected. If neither setting is specified, monitoring is disabled. + + +Set `use_output` to specify the output to which monitoring events are sent. + +=== Specify data sources + +By default Elastic Agent collects system metrics, such as cpu, memory, network, and filesystem metrics, and sends them to the default output. For example: + + +[source,yaml] +------------------------------------------------------------------------------------- +datasources: + - namespace: default + use_output: default + inputs: + - type: system/metrics + streams: + - metricset: cpu + dataset: system.cpu + - metricset: memory + dataset: system.memory + - metricset: network + dataset: system.network + - metricset: filesystem + dataset: system.filesystem +------------------------------------------------------------------------------------- + +If `use_output` is not specified, the `default` output is used. + +For more examples, see `elastic-agent_configuration_example.yml`