diff --git a/x-pack/elastic-agent/docs/elastic-agent-command-line.asciidoc b/x-pack/elastic-agent/docs/elastic-agent-command-line.asciidoc index aa47b8505e7e..ccb85b7f4355 100644 --- a/x-pack/elastic-agent/docs/elastic-agent-command-line.asciidoc +++ b/x-pack/elastic-agent/docs/elastic-agent-command-line.asciidoc @@ -1,6 +1,10 @@ [[elastic-agent-cmd-options]] [role="xpack"] -= Command line options += {agent} command line options + +++++ +Command line options +++++ beta[] diff --git a/x-pack/elastic-agent/docs/elastic-agent.asciidoc b/x-pack/elastic-agent/docs/elastic-agent.asciidoc index f68138f9d538..274cf9b0b636 100644 --- a/x-pack/elastic-agent/docs/elastic-agent.asciidoc +++ b/x-pack/elastic-agent/docs/elastic-agent.asciidoc @@ -1,3 +1,5 @@ +:release-state: released + [[elastic-agent-installation-configuration]] [role="xpack"] @@ -8,7 +10,7 @@ beta[] // tag::agent-install-intro[] {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, {agent} runs the -{beats} shippers or Endpoint required for your configuration. +{beats} shippers or Elastic Endpoint required for your configuration. // end::agent-install-intro[] To learn how to install, configure, and run your {agent}s, see: @@ -16,6 +18,7 @@ To learn how to install, configure, and run your {agent}s, see: * <> * <> * <> +* <> * <> * <> @@ -25,6 +28,8 @@ include::run-elastic-agent.asciidoc[leveloffset=+1] include::stop-elastic-agent.asciidoc[leveloffset=+1] +include::unenroll-elastic-agent.asciidoc[leveloffset=+1] + include::elastic-agent-command-line.asciidoc[leveloffset=+1] include::elastic-agent-configuration.asciidoc[leveloffset=+1] diff --git a/x-pack/elastic-agent/docs/install-elastic-agent.asciidoc b/x-pack/elastic-agent/docs/install-elastic-agent.asciidoc index dc661e6308ca..4186c9718c49 100644 --- a/x-pack/elastic-agent/docs/install-elastic-agent.asciidoc +++ b/x-pack/elastic-agent/docs/install-elastic-agent.asciidoc @@ -4,82 +4,17 @@ beta[] -Download and install the Agent on each system you want to monitor. - -//TODO: Replace with tabbed panel when the code is stable. +Download and install {agent} on each system you want to monitor. // tag::install-elastic-agent[] To download and install {elastic-agent}, use the commands that work with your system: -*mac:* - -ifeval::["{release-state}"=="unreleased"] - -Version {version} of {agent} has not yet been released. - -endif::[] - -ifeval::["{release-state}"!="unreleased"] - -["source","sh",subs="attributes"] ----- -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:* - -ifeval::["{release-state}"=="unreleased"] - -Version {version} of {agent} has not yet been released. - -endif::[] - -ifeval::["{release-state}"!="unreleased"] - -["source","sh",subs="attributes"] ----- -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:* - -ifeval::["{release-state}"=="unreleased"] - -Version {version} of {agent} has not yet been released. - -endif::[] - -ifeval::["{release-state}"!="unreleased"] - -. Download the {agent} Windows zip file from the -https://www.elastic.co/downloads/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::[] +include::{beats-repo-dir}/x-pack/elastic-agent/docs/tab-widgets/install-widget.asciidoc[] // end::install-elastic-agent[] +// Add Javascript and CSS for tabbed panels +include::tab-widgets/code.asciidoc[] + diff --git a/x-pack/elastic-agent/docs/run-elastic-agent.asciidoc b/x-pack/elastic-agent/docs/run-elastic-agent.asciidoc index 9c7ce91e2ec2..34613ae9696d 100644 --- a/x-pack/elastic-agent/docs/run-elastic-agent.asciidoc +++ b/x-pack/elastic-agent/docs/run-elastic-agent.asciidoc @@ -5,67 +5,62 @@ beta[] {agent} runs in two modes: standalone or fleet. The two modes differ in how you -configure and manage the Agent. +configure and manage the agent. [discrete] [[fleet-mode]] == Run in {fleet} mode -With _fleet mode_, you manage {agent} remotely. The Agent uses a trusted {kib} -instance to retrieve configurations and report Agent events. This trusted {kib} +With _fleet mode_, you manage {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 {agent} and {kib}, enroll the -Agent to {fleet}. +agent to {fleet}. To enroll an {agent} to {fleet}: -. Stop the Agent, if it's already running. +. Stop {agent}, if it's already running. -. Go the **{fleet}** tab in {ingest-manager}, and click **Enroll new agent** to -generate a token. See <> for detailed steps. +. In {ingest-manager}, select **{fleet}**, then click **Add agent** to +get an enrollment token. See <> for +detailed steps. -. Enroll the Agent: +. Change to the directory where {agent} is installed, and enroll the agent to +{fleet}: + -[source,shell] ----- -./elastic-agent enroll http://localhost:5601 $token ----- -+ -Where `$token` is an enrollment token acquired from {fleet}. - -//TODO: Add tabbed panels for platform-specific tabs (waiting for final design) +-- +include::{beats-repo-dir}/x-pack/elastic-agent/docs/tab-widgets/enroll-widget.asciidoc[] +-- -To start {agent}, run: - -// tag::run-agent[] -[source,shell] ----- -./elastic-agent run <1> ----- -<1> On Windows, you must run {agent} under the SYSTEM account if you plan -to use the {elastic-endpoint} integration. -// end::run-agent[] +. Run the agent: ++ +-- +include::{beats-repo-dir}/x-pack/elastic-agent/docs/tab-widgets/run-widget.asciidoc[] +-- [discrete] [[standalone-mode]] == Run in standalone mode (default) -With _standalone mode_, you manually configure and manage the Agent locally. -Each Agent is configured to be in standalone mode by default after installation. +With _standalone mode_, you manually configure and manage {agent} locally on the +system where the agent is installed. {agent} is configured to run in standalone +mode by default unless you enroll it in {fleet}. If {agent} is installed as an auto-starting service, it will run automatically when you restart your system. To start {agent} manually, run: -include::run-elastic-agent.asciidoc[tag=run-agent] +include::{beats-repo-dir}/x-pack/elastic-agent/docs/tab-widgets/run-standalone-widget.asciidoc[] -If no configuration file is specified, {agent} uses the default configuration, -`elastic-agent.yml`, which is located in the same directory as {agent}. Specify -the `-c` flag to use a different configuration file. +Use the `-c` flag to specify the configuration file. If no configuration file is +specified, {agent} uses the default configuration, `elastic-agent.yml`, which is +located in the same directory as {agent}. For configuration options, see <>. //<> +// Add Javascript and CSS for tabbed panels +include::tab-widgets/code.asciidoc[] diff --git a/x-pack/elastic-agent/docs/stop-elastic-agent.asciidoc b/x-pack/elastic-agent/docs/stop-elastic-agent.asciidoc index 1c90d4c3f608..82078c5eb783 100644 --- a/x-pack/elastic-agent/docs/stop-elastic-agent.asciidoc +++ b/x-pack/elastic-agent/docs/stop-elastic-agent.asciidoc @@ -5,37 +5,7 @@ To stop {agent} and its related executables, stop the {agent} process. Use the commands that work for your system. -*Windows:* +include::{beats-repo-dir}/x-pack/elastic-agent/docs/tab-widgets/stop-widget.asciidoc[] -If you installed the Agent as a service, stop the service. If -necessary, use Task Manager on Windows to stop {agent}. This will kill the -{agent} process and any sub-processes it created (such as {beats}). - -*Linux or macOS:* - -Run the following command to get the ID of the `elastic-agent` process: - -[source,shell] ----- -ps | grep elastic-agent ----- - -Then kill the process: - -[source,shell] ----- -kill -9 PID ----- - -Where `PID` is the ID of the `elastic-agent` process. - -*Systemd:* - -The DEB and RPM packages include a service unit for Linux systems with systemd. -On these systems, you can manage {agent} by using systemd commands. Use -`systemctl` to stop the Agent: - -[source,shell] ----- -systemctl stop elastic-agent ----- +// Add Javascript and CSS for tabbed panels +include::tab-widgets/code.asciidoc[] diff --git a/x-pack/elastic-agent/docs/tab-widgets/code.asciidoc b/x-pack/elastic-agent/docs/tab-widgets/code.asciidoc new file mode 100644 index 000000000000..61b18b0015d5 --- /dev/null +++ b/x-pack/elastic-agent/docs/tab-widgets/code.asciidoc @@ -0,0 +1,166 @@ +// Defining styles and script here for simplicity. +++++ + + + +++++ diff --git a/x-pack/elastic-agent/docs/tab-widgets/enroll-widget.asciidoc b/x-pack/elastic-agent/docs/tab-widgets/enroll-widget.asciidoc new file mode 100644 index 000000000000..202c38913dbf --- /dev/null +++ b/x-pack/elastic-agent/docs/tab-widgets/enroll-widget.asciidoc @@ -0,0 +1,92 @@ +++++ +
+
+ + + + + +
+
+++++ + +include::enroll.asciidoc[tag=deb] + +++++ +
+ + + + +
+++++ \ No newline at end of file diff --git a/x-pack/elastic-agent/docs/tab-widgets/enroll.asciidoc b/x-pack/elastic-agent/docs/tab-widgets/enroll.asciidoc new file mode 100644 index 000000000000..479e8cfba7c6 --- /dev/null +++ b/x-pack/elastic-agent/docs/tab-widgets/enroll.asciidoc @@ -0,0 +1,70 @@ +// tag::deb[] + +// tag::enroll-tip[] +TIP: We recommend that you run this command as the root user because some +integrations require root privileges to collect sensitive data. + +// end::enroll-tip[] +[source,shell] +---- +elastic-agent enroll KIBANA_URL ENROLLMENT_KEY +---- + +include::enroll.asciidoc[tag=where-description] +// end::deb[] + +// tag::rpm[] + +include::enroll.asciidoc[tag=enroll-tip] + +[source,shell] +---- +elastic-agent enroll KIBANA_URL ENROLLMENT_KEY +---- + +include::enroll.asciidoc[tag=where-description] +// end::rpm[] + +// tag::mac[] + +include::enroll.asciidoc[tag=enroll-tip] + +[source,shell] +---- +./elastic-agent enroll KIBANA_URL ENROLLMENT_KEY +---- + +include::enroll.asciidoc[tag=where-description] +// end::mac[] + +// tag::linux[] + +include::enroll.asciidoc[tag=enroll-tip] + +[source,shell] +---- +./elastic-agent enroll KIBANA_URL ENROLLMENT_KEY +---- + +include::enroll.asciidoc[tag=where-description] +// end::linux[] + +// tag::win[] +Open a PowerShell prompt as an Administrator (right-click the PowerShell icon +and select **Run As Administrator**). + +From the PowerShell prompt, change to the directory where you installed {agent}, +and run: + +[source,shell] +---- +.\elastic-agent.exe enroll KIBANA_URL ENROLLMENT_KEY +---- + +include::enroll.asciidoc[tag=where-description] +// end::win[] + +// tag::where-description[] +Where `KIBANA_URL` is the {kib} URL where {fleet} is running, and +`ENROLLMENT_KEY` is the enrollment token acquired from {fleet}. +// end::where-description[] \ No newline at end of file diff --git a/x-pack/elastic-agent/docs/tab-widgets/install-widget.asciidoc b/x-pack/elastic-agent/docs/tab-widgets/install-widget.asciidoc new file mode 100644 index 000000000000..c25fc7fadbef --- /dev/null +++ b/x-pack/elastic-agent/docs/tab-widgets/install-widget.asciidoc @@ -0,0 +1,92 @@ +++++ +
+
+ + + + + +
+
+++++ + +include::install.asciidoc[tag=deb] + +++++ +
+ + + + +
+++++ \ No newline at end of file diff --git a/x-pack/elastic-agent/docs/tab-widgets/install.asciidoc b/x-pack/elastic-agent/docs/tab-widgets/install.asciidoc new file mode 100644 index 000000000000..824825f86dfd --- /dev/null +++ b/x-pack/elastic-agent/docs/tab-widgets/install.asciidoc @@ -0,0 +1,93 @@ +// tag::deb[] +ifeval::["{release-state}"=="unreleased"] + +Version {version} of {agent} has not yet been released. + +endif::[] + +ifeval::["{release-state}"!="unreleased"] + +["source","sh",subs="attributes"] +---- +curl -L -O https://artifacts.elastic.co/downloads/beats/elastic-agent/elastic-agent-{version}-amd64.deb +sudo dpkg -i elastic-agent-{version}-amd64.deb +---- + +endif::[] +// end::deb[] + +// tag::rpm[] +ifeval::["{release-state}"=="unreleased"] + +Version {version} of {agent} has not yet been released. + +endif::[] + +ifeval::["{release-state}"!="unreleased"] + +["source","sh",subs="attributes"] +---- +curl -L -O https://artifacts.elastic.co/downloads/beats/elastic-agent/elastic-agent-{version}-x86_64.rpm +sudo rpm -vi elastic-agent-{version}-x86_64.rpm +---- +endif::[] +// end::rpm[] + +// tag::mac[] +ifeval::["{release-state}"=="unreleased"] + +Version {version} of {agent} has not yet been released. + +endif::[] + +ifeval::["{release-state}"!="unreleased"] + +["source","sh",subs="attributes"] +---- +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::[] +// end::mac[] + +// tag::linux[] +ifeval::["{release-state}"=="unreleased"] + +Version {version} of {agent} has not yet been released. + +endif::[] + +ifeval::["{release-state}"!="unreleased"] + +["source","sh",subs="attributes"] +---- +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 +---- + +NOTE: We recommend that you use the DEB or RPM distribution, instead of the +tarball, to ensure that {agent} restarts automatically if the system is +rebooted. + +endif::[] +// end::linux[] + +// tag::win[] +ifeval::["{release-state}"=="unreleased"] + +Version {version} of {agent} has not yet been released. + +endif::[] + +ifeval::["{release-state}"!="unreleased"] + +. Download the {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`. + +endif::[] +// end::win[] diff --git a/x-pack/elastic-agent/docs/tab-widgets/run-standalone-widget.asciidoc b/x-pack/elastic-agent/docs/tab-widgets/run-standalone-widget.asciidoc new file mode 100644 index 000000000000..63993c2106ca --- /dev/null +++ b/x-pack/elastic-agent/docs/tab-widgets/run-standalone-widget.asciidoc @@ -0,0 +1,92 @@ +++++ +
+
+ + + + + +
+
+++++ + +include::run.asciidoc[tag=deb] + +++++ +
+ + + + +
+++++ \ No newline at end of file diff --git a/x-pack/elastic-agent/docs/tab-widgets/run-widget.asciidoc b/x-pack/elastic-agent/docs/tab-widgets/run-widget.asciidoc new file mode 100644 index 000000000000..34382f822e93 --- /dev/null +++ b/x-pack/elastic-agent/docs/tab-widgets/run-widget.asciidoc @@ -0,0 +1,92 @@ +++++ +
+
+ + + + + +
+
+++++ + +include::run.asciidoc[tag=deb] + +++++ +
+ + + + +
+++++ \ No newline at end of file diff --git a/x-pack/elastic-agent/docs/tab-widgets/run.asciidoc b/x-pack/elastic-agent/docs/tab-widgets/run.asciidoc new file mode 100644 index 000000000000..1252886f02fa --- /dev/null +++ b/x-pack/elastic-agent/docs/tab-widgets/run.asciidoc @@ -0,0 +1,97 @@ +// tag::deb[] + +The DEB package includes a service unit for Linux systems with systemd. On these +systems, you can manage {agent} by using the usual systemd commands: + +[source,shell] +---- +systemctl enable elastic-agent +systemctl start elastic-agent +---- + +Otherwise, use: + +[source,shell] +---- +sudo service elastic-agent start +---- + +NOTE: {agent} will restart automatically if the system is rebooted. + +// end::deb[] + +// tag::rpm[] +The RPM package includes a service unit for Linux systems with systemd. On these +systems, you can manage {agent} by using the usual systemd commands: + +[source,shell] +---- +systemctl enable elastic-agent +systemctl start elastic-agent +---- + +Otherwise, use: + +[source,shell] +---- +sudo service elastic-agent start +---- + +NOTE: {agent} will restart automatically if the system is rebooted. + +// end::rpm[] + +// tag::mac[] +[source,shell] +---- +./elastic-agent run +---- + +NOTE: You must restart {agent} manually if the agent terminates or the system is +rebooted. + +// end::mac[] + +// tag::linux[] +[source,shell] +---- +./elastic-agent run +---- + +NOTE: You must restart {agent} manually if the agent terminates or the system is +rebooted. + +// end::linux[] + +// tag::win[] +The first time you run {agent}, you need to install it as auto-starting Windows +service. To do this, run the PowerShell script provided in the archive you +downloaded: + +. 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 {agent} as +an service and start the service: ++ +[source,shell] +---- +cd 'C:\Program Files\Elastic-Agent' +.\install-service-elastic-agent.ps1 <1> <2> +---- +<1> You must run {agent} under the SYSTEM account if you plan +to use the {elastic-endpoint} integration. +<2> If script execution is disabled on your system, 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`. ++ +If the service stops and you need to restart it manually, run: ++ +[source,shell] +---- +Start-Service elastic-agent +---- + +NOTE: {agent} will restart automatically if the system is rebooted. + +// end::win[] diff --git a/x-pack/elastic-agent/docs/tab-widgets/stop-widget.asciidoc b/x-pack/elastic-agent/docs/tab-widgets/stop-widget.asciidoc new file mode 100644 index 000000000000..f4527cbcd49b --- /dev/null +++ b/x-pack/elastic-agent/docs/tab-widgets/stop-widget.asciidoc @@ -0,0 +1,92 @@ +++++ +
+
+ + + + + +
+
+++++ + +include::stop.asciidoc[tag=deb] + +++++ +
+ + + + +
+++++ \ No newline at end of file diff --git a/x-pack/elastic-agent/docs/tab-widgets/stop.asciidoc b/x-pack/elastic-agent/docs/tab-widgets/stop.asciidoc new file mode 100644 index 000000000000..7d1f8f97a3f0 --- /dev/null +++ b/x-pack/elastic-agent/docs/tab-widgets/stop.asciidoc @@ -0,0 +1,74 @@ +// tag::deb[] + +The DEB package includes a service unit for Linux systems with systemd. On these +systems, you can manage {agent} by using the usual systemd commands. + +// tag::stop-command[] +Use `systemctl` to stop the agent: + +[source,shell] +---- +systemctl stop elastic-agent +---- + +Otherwise, use: + +[source,shell] +---- +sudo service elastic-agent stop +---- + +NOTE: {agent} will restart automatically if the system is rebooted. + +// end::stop-command[] + +// end::deb[] + +// tag::rpm[] +The RPM package includes a service unit for Linux systems with systemd. On these +systems, you can manage {agent} by using the usual systemd commands. + +include::stop.asciidoc[tag=stop-command] + +// end::rpm[] + +// tag::mac[] +// tag::kill-process[] +Get the process ID (PID) of the `elastic-agent` process: + +[source,shell] +---- +ps | grep elastic-agent +---- + +Then kill the process, replacing the PID in this example with the PID from +the grep command: + +[source,shell] +---- +kill -9 90682 +---- + +NOTE: {agent} will NOT restart automatically if the system is rebooted. + +// end::kill-process[] +// end::mac[] + +// tag::linux[] +include::stop.asciidoc[tag=kill-process] +// end::linux[] + +// tag::win[] + +If you installed {agent} as a service, stop the service. +[source,shell] +---- +Stop-Service elastic-agent +---- + +If necessary, use Task Manager on Windows to stop {agent}. This will kill the +`elastic-agent` process and any sub-processes it created (such as {beats}). + +NOTE: {agent} will restart automatically if the system is rebooted. + +// end::win[] diff --git a/x-pack/elastic-agent/docs/unenroll-elastic-agent.asciidoc b/x-pack/elastic-agent/docs/unenroll-elastic-agent.asciidoc new file mode 100644 index 000000000000..cd77fc3dde37 --- /dev/null +++ b/x-pack/elastic-agent/docs/unenroll-elastic-agent.asciidoc @@ -0,0 +1,19 @@ +[[unenroll-elastic-agent]] +[role="xpack"] += Unenroll {agent} + +You can unenroll an agent to invalidate the API key used to connect to {es}. + +. In {ingest-manager}, select **{fleet}**. + +. Under Agents, choose **Unenroll** from the **Actions** menu next to the agent +you want to unenroll. + +. Click **Unenroll**. ++ +The agent will continue to run, but will not be able to send data. It will show +this error instead: `invalid api key to authenticate with fleet`. + +TIP: If unenrollment hangs, select **Force unenroll** to invalidate all API +keys related to the agent and change the status to `inactive` so that the agent +no longer appears in {fleet}.