Skip to content

Commit

Permalink
[docs] Add Elastic Agent doc changes for 7.9 (#20437) (#20503)
Browse files Browse the repository at this point in the history
* [docs] Add ingest management doc changes for 7.9

* Update Beats agent docs with other 7.9 changes

* Add copy of js/css to reduce dependencies

* Temporarily override release state

* Fix bug in platform selector

* Add changes from review
  • Loading branch information
dedemorton authored Aug 8, 2020
1 parent f65abed commit 255c992
Show file tree
Hide file tree
Showing 16 changed files with 1,025 additions and 137 deletions.
Original file line number Diff line number Diff line change
@@ -1,6 +1,10 @@
[[elastic-agent-cmd-options]]
[role="xpack"]
= Command line options
= {agent} command line options

++++
<titleabbrev>Command line options</titleabbrev>
++++

beta[]

Expand Down
7 changes: 6 additions & 1 deletion x-pack/elastic-agent/docs/elastic-agent.asciidoc
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
:release-state: released

[[elastic-agent-installation-configuration]]
[role="xpack"]

Expand All @@ -8,14 +10,15 @@ 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:

* <<elastic-agent-installation>>
* <<run-elastic-agent>>
* <<stop-elastic-agent>>
* <<unenroll-elastic-agent>>
* <<elastic-agent-cmd-options>>
* <<elastic-agent-configuration>>

Expand All @@ -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]
Expand Down
75 changes: 5 additions & 70 deletions x-pack/elastic-agent/docs/install-elastic-agent.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -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-<version>-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[]

59 changes: 27 additions & 32 deletions x-pack/elastic-agent/docs/run-elastic-agent.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -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 <<ingest-management-getting-started>> for detailed steps.
. In {ingest-manager}, select **{fleet}**, then click **Add agent** to
get an enrollment token. See <<ingest-management-getting-started>> 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 <<elastic-agent-configuration>>.

//<<elastic-agent-configuration-example,`elastic-agent_configuration_example.yml`>>

// Add Javascript and CSS for tabbed panels
include::tab-widgets/code.asciidoc[]
36 changes: 3 additions & 33 deletions x-pack/elastic-agent/docs/stop-elastic-agent.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -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[]
Loading

0 comments on commit 255c992

Please sign in to comment.