diff --git a/docs/en/ingest-management/commands.asciidoc b/docs/en/ingest-management/commands.asciidoc index 341998c702..52b9f5527e 100644 --- a/docs/en/ingest-management/commands.asciidoc +++ b/docs/en/ingest-management/commands.asciidoc @@ -6,11 +6,9 @@ beta[] -{agent} provides commands for running the agent, managing {fleet-server}, and +{agent} provides commands for running {agent}, managing {fleet-server}, and doing common tasks: -//TODO: Add Fleet-related commands - * <> * <> * <> @@ -20,8 +18,10 @@ doing common tasks: * <> * <> * <> +//* <> -NOTE: You might need to log in as a root user to run these commands. +NOTE: You might need to log in as a root user (or Administrator on Windows) to +run these commands. ++++
@@ -31,31 +31,78 @@ NOTE: You might need to log in as a root user to run these commands. [[elastic-agent-enroll-command]] == elastic-agent enroll -Enroll the {elastic-agent} in {fleet}. +Enroll the {agent} in {fleet}. + +Use this command to enroll the {agent} in {fleet} without installing the +agent as a service. You will need to do this if you installed +the {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 +{agent} prior to installing it. + +If you've already installed {agent}, use this command to modify the settings that {agent} runs with. + +TIP: To enroll an {agent} _and_ install it as a service, use the +<> instead. Installing as a service is the most common scenario. -We recommend that you run this command as the root user because some +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 <>. + +IMPORTANT: This command enrolls the {agent} in {fleet}; it does not start the +agent. To start the agent, either <>, if +one exists, or use the <> to start the +agent from a terminal. + + [discrete] === Synopsis +To enroll the {agent} in {fleet}: + [source,shell] ---- -elastic-agent enroll --kibana-url= --enrollment-token= [--ca-sha256 ] - [--certificate-authorities ] [--force] [--help] - [--insecure] [global-flags] +elastic-agent enroll --url + --enrollment-token + [--ca-sha256 ] + [--certificate-authorities ] + [--force] + [--help] + [--insecure ] + [global-flags] ---- +To enroll the {agent} in {fleet} and set up {fleet-server}: + +[source,shell] +---- +elastic-agent enroll --fleet-server-es + --fleet-server-service-token + [--ca-sha256 ] + [--certificate-authorities ] + [--fleet-server-cert ] <1> + [--fleet-server-cert-key ] + [--fleet-server-es-ca ] + [--fleet-server-host ] + [--fleet-server-insecure-http] + [--fleet-server-policy ] + [--fleet-server-port ] + [--force] + [--help] + [--insecure ] + [global-flags] +---- +<1> If no `fleet-server-cert*` flags are specified, {agent} auto-generates a +self-signed certificate with the hostname of the machine. Remote {agent}s +enrolling into a {fleet-server} with self-signed certificates must specify +the `insecure` flag. + [discrete] === Options -`--kibana-url=`:: -Required. URL of the {kib} endpoint where {fleet} is running. - -`--enrollment-token=`:: -Required. Enrollment token generated by {fleet}. You can use the same -enrollment token for multiple agents. +// These descriptions are included for the enroll and install commands +// tag::enroll-install-options[] `--ca-sha256 `:: Comma-separated list of certificate authority hash pins used for certificate @@ -64,6 +111,42 @@ verification. `--certificate-authorities `:: Comma-separated list of root certificates used for server verification. +`--enrollment-token `:: +Enrollment token to use to enroll {agent} into {fleet}. You can use +the same enrollment token for multiple agents. + +`--fleet-server-cert `:: +Certificate to use for exposed {fleet-server} HTTPS endpoint. + +`--fleet-server-cert-key `:: +Private key to use for exposed {fleet-server} HTTPS endpoint. + +`--fleet-server-es `:: +Start a {fleet-server} process when {agent} is started, and connect to the +specified {es} URL. + +`--fleet-server-es-ca `:: +Path to certificate authority to use to communicate with {es}. + +`--fleet-server-host `:: +{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 `:: +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 `:: +{fleet-server} HTTP binding port (overrides the policy). + +`--fleet-server-service-token `:: +Service token to use for communication with {es}. + `--force`:: Force overwrite of current configuration without prompting for confirmation. This flag is helpful when using automation software or scripted deployments. @@ -72,17 +155,66 @@ This flag is helpful when using automation software or scripted deployments. Show help for the `enroll` command. `--insecure`:: -Allow an insecure connection to {kib}. When this flag is specified, API keys are -sent in clear text. We strongly recommend that you use a secure connection. +Allow insecure connections to {fleet-server}. 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. +-- ++ +We strongly recommend that you use a secure connection. + +`--url `:: +Fleet Server URL to use to enroll the {agent} into {fleet}. + +// end::enroll-install-options[] {global-flags-link} [discrete] -=== Example +=== Examples + +Enroll the {agent} in {fleet}: + +[source,shell] +---- +elastic-agent enroll -f \ + --url=https://cedd4e0e21e240b4s2bbbebdf1d6d52f.fleet.eu-west-1.aws.cld.elstc.co:443 \ + --enrollment-token=NEFmVllaa0JLRXhKebVKVTR5TTI6N2JaVlJpSGpScmV0ZUVnZVlRUExFQQ== +---- + +Enroll the {agent} in {fleet} and start {fleet-server}: + +[source,shell] +---- +elastic-agent enroll -f --fleet-server-es=http://elasticsearch:9200 \ + --fleet-server-service-token=AbEAAdesYXN1abMvZmxlZXQtc2VldmVyL3Rva2VuLTE2MTkxMzg3MzIzMTg7dzEta0JDTmZUcGlDTjlwRmNVTjNVQQ +---- + +Start {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 [source,shell] ---- -elastic-agent enroll http://localhost:5601 ZnmNIdzVITUJua2QIdU5FTWROVjY6dHY2N1EybWNTMUdPejg5ODbYcVpNUQ== +elastic-agent enroll -f --fleet-server-es=https://elasticsearch:9200 \ + --fleet-server-es-ca=ca.crt --fleet-server-service-token=AbEAAdesYXN1abMvZmxlZXQtc2VldmVyL3Rva2VuLTE2MTkxMzg3MzIzMTg7dzEta0JDTmZUcGlDTjlwRmNVTjNVQQ \ + --fleet-server-cert fleet-server.crt --fleet-server-cert-key fleet-server.key +---- + +Then enroll another {agent} into the {fleet-server} started in the previous +example: + +[source,shell] +---- +elastic-agent enroll -f --url https://fleet-server-host:8220 \ + --enrollment-token NEFmVllaa0JLRXhKebVKVTR5TTI6N2JaVlJpSGpScmV0ZUVnZVlRUExFQQ== + --certificate-authorities root.ca ---- ++++ @@ -140,8 +272,10 @@ If no parameters are specified, shows the full {agent} configuration. [source,shell] ---- elastic-agent inspect [--help] [global-flags] -elastic-agent inspect output [--output ] [--program ] - [--help] [global-flags] +elastic-agent inspect output [--output ] + [--program ] + [--help] + [global-flags] ---- [discrete] @@ -184,8 +318,12 @@ elastic-agent inspect output --output default --program filebeat Install {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, this command requires a system and service manager like -systemd. +complete. On Linux (tar package), this command requires a system and service +manager like systemd. + +IMPORTANT: If you installed {agent} from a DEB or RPM package, use the +<> 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 @@ -194,53 +332,98 @@ to write files to the correct locations. This command overwrites the [discrete] === Synopsis +To install the {agent} as a service, enroll it in {fleet}, and start the +`elastic-agent` service: + [source,shell] ---- -elastic-agent install [--ca-sha256 ] [--certificate-authorities ] - [--enrollment-token ] [--force] [--help] - [--insecure] [--kibana-url ] +elastic-agent install [--ca-sha256 ] + [--certificate-authorities ] + [--enrollment-token ] + [--force] + [--help] + [--insecure ] + [--url string] [global-flags] ---- +To install the {agent} as a service, enroll it in {fleet}, and start +a `fleet-server` process alongside the `elastic-agent` service: + +[source,shell] +---- +elastic-agent install [--ca-sha256 ] + [--certificate-authorities ] + [--fleet-server-cert ] + [--fleet-server-cert-key ] + [--fleet-server-es ] + [--fleet-server-es-ca ] + [--fleet-server-host ] + [--fleet-server-insecure-http] + [--fleet-server-policy ] + [--fleet-server-port ] + [--fleet-server-service-token ] + [--force] + [--help] + [--insecure ] + [global-flags] +---- + + [discrete] === Options -`--ca-sha256 `:: -Comma-separated list of certificate authority hash pins used for certificate -verification. +include::commands.asciidoc[tag=enroll-install-options] -`--certificate-authorities `:: -Comma-separated list of root certificates used for server verification. +{global-flags-link} -`--enrollment-token `:: -Enrollment token generated by {fleet}. You can use the same enrollment token for -multiple agents. +[discrete] +=== Examples -`--force`:: -Force overwrite of current configuration without prompting for confirmation. -This flag is helpful when using automation software or scripted deployments. +Install the {agent} as a service, enroll it in {fleet}, and start the +`elastic-agent` service: -`--help`:: -Show help for the `install` command. +[source,shell] +---- +elastic-agent install -f \ + --url=https://cedd4e0e21e240b4s2bbbebdf1d6d52f.fleet.eu-west-1.aws.cld.elstc.co:443 \ + --enrollment-token=NEFmVllaa0JLRXhKebVKVTR5TTI6N2JaVlJpSGpScmV0ZUVnZVlRUExFQQ== +---- + +Install the {agent} as a service, enroll it in {fleet}, and start +a `fleet-server` process alongside the `elastic-agent` service: -`--insecure`:: -Allow an insecure connection to {kib}. When this flag is specified, API keys are -sent in clear text. We strongly recommend that you use a secure connection. +[source,shell] +---- +elastic-agent install -f --fleet-server-es=http://elasticsearch:9200 \ + --fleet-server-service-token=AbEAAdesYXN1abMvZmxlZXQtc2VldmVyL3Rva2VuLTE2MTkxMzg3MzIzMTg7dzEta0JDTmZUcGlDTjlwRmNVTjNVQQ +---- -`--kibana-url `:: -URL of the {kib} endpoint where {fleet} is running. +Start {agent} with {fleet-server} (running on a custom CA). This example +assumes you've generated the certificates with the following names: -{global-flags-link} +* `ca.crt`: Root CA certificate +* `fleet-server.crt`: {fleet-server} certificate +* `fleet-server.key`: {fleet-server} private key -[discrete] -=== Examples +[source,shell] +---- +elastic-agent install -f --fleet-server-es=https://elasticsearch:9200 \ + --fleet-server-es-ca=ca.crt --fleet-server-service-token=AbEAAdesYXN1abMvZmxlZXQtc2VldmVyL3Rva2VuLTE2MTkxMzg3MzIzMTg7dzEta0JDTmZUcGlDTjlwRmNVTjNVQQ \ + --fleet-server-cert fleet-server.crt --fleet-server-cert-key fleet-server.key +---- + +Then install another {agent} and enroll it into the {fleet-server} started in +the previous example: [source,shell] ---- -elastic-agent install -f --kibana-url=https://yourhost:5601 \ - --enrollment-token=OEV0bmauVUI0a3dmdWc1T3Bad1o6VGxCa3U4UEFTQ0NycbBSUFwoazVBdx== +elastic-agent install -f --url https://fleet-server-host:8220 \ + --enrollment-token NEFmVllaa0JLRXhKebVKVTR5TTI6N2JaVlJpSGpScmV0ZUVnZVlRUExFQQ== + --certificate-authorities root.ca ---- + ++++
++++ @@ -249,7 +432,7 @@ elastic-agent install -f --kibana-url=https://yourhost:5601 \ [[elastic-agent-restart-command]] == elastic-agent restart -Restart the currently running Elastic Agent daemon. +Restart the currently running {agent} daemon. [discrete] === Synopsis @@ -382,7 +565,9 @@ elastic-agent uninstall [[elastic-agent-upgrade-command]] == elastic-agent upgrade -Upgrade the currently running {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}. +Upgrade the currently running {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}. [discrete] === Synopsis @@ -452,3 +637,40 @@ elastic-agent version ++++
++++ + +//// +//commenting out until we decide whether we want to expose this in public docs +[discrete] +[[elastic-agent-watch-command]] +== elastic-agent watch + +Watch the {agent} for failures and initiate rollback. + +[discrete] +=== Synopsis + +[source,shell] +---- +elastic-agent watch [--help] [global-flags] +---- + +[discrete] +=== Options + +`--help`:: +Show help for the `watch` command. + +{global-flags-link} + +[discrete] +=== Example + +[source,shell] +---- +elastic-agent watch +---- + +++++ +
+++++ +//// diff --git a/docs/en/ingest-management/tab-widgets/add-fleet-server/content.asciidoc b/docs/en/ingest-management/tab-widgets/add-fleet-server/content.asciidoc index 46a075becf..fa0e00d5c3 100644 --- a/docs/en/ingest-management/tab-widgets/add-fleet-server/content.asciidoc +++ b/docs/en/ingest-management/tab-widgets/add-fleet-server/content.asciidoc @@ -52,7 +52,9 @@ image::images/add-fleet-server.png[In-product instructions for adding a {fleet-s * Make sure you download an x64 architecture installation package. * After generating the service token, save it to a secure location. You might -need to use this token later to scale your deployment by adding {fleet-server}s. +want to use this token later to scale your deployment by adding {fleet-server}s. +For other ways to generate service tokens, see +{ref}/service-tokens-command.html[`elasticsearch-service-tokens`]. * The `install` command installs the {agent} as a managed service and enrolls it in a {fleet-server} policy: + @@ -62,6 +64,8 @@ sudo ./elastic-agent install -f --fleet-server-es=http://localhost:9200 \ --fleet-server-service-token=AAEAAWVsYXN0aWMvZmxlZXQtc2VydmVyL3Rva2VuLTE2MTkxMzg3MzIzMTg6dzEta0JDTmZUZGlDTjlwRmNVTjNVQQ ---- + +For more {fleet-server} commands, see <>. ++ If installation is successful, you'll see the {fleet-server} {agent} on the *Agents* tab in *{fleet}*. Notice that the Default Fleet Server Policy is assigned to the {agent}. This policy is created when you run {fleet} for the