//////////////////////////////////////////////////////////////////////////
//// This content is shared by all Elastic Beats. Make sure you keep the
//// descriptions here generic enough to work for all Beats that include
//// this file. When using cross references, make sure that the cross
//// references resolve correctly for any files that include this one.
//// Use the appropriate variables defined in the index.asciidoc file to
//// resolve Beat names: beatname_uc and beatname_lc
//// Use the following include to pull this content into a doc file:
//// include::../../libbeat/docs/command-reference.asciidoc[]
//////////////////////////////////////////////////////////////////////////


// These attributes are used to resolve short descriptions

:global-flags: Also see <<global-flags,Global flags>>.

:deploy-command-short-desc: Deploys the specified function to your serverless environment
:export-command-short-desc: Exports the configuration, index template, or a dashboard to stdout
:help-command-short-desc: Shows help for any command
:keystore-command-short-desc: Manages the <<keystore,secrets keystore>>
:modules-command-short-desc: Manages configured modules
:package-command-short-desc: Packages the configuration and executable into a zip file
:remove-command-short-desc: Removes the specified function from your serverless environment
:run-command-short-desc: Runs {beatname_uc}. This command is used by default if you start {beatname_uc} without specifying a command

ifndef::deprecate_dashboard_loading[]

ifdef::has_ml_jobs[]
:setup-command-short-desc: Sets up the initial environment, including the index template, {kib} dashboards (when available), and machine learning jobs (when available)
endif::[]

ifndef::has_ml_jobs[]
:setup-command-short-desc: Sets up the initial environment, including the index template and {kib} dashboards (when available)
endif::[]

endif::[]

ifdef::deprecate_dashboard_loading[]

:setup-command-short-desc: Sets up the initial environment, including the ES index template and {kib} dashboards (deprecated).

endif::[]

:update-command-short-desc: Updates the specified function
:test-command-short-desc: Tests the configuration
:version-command-short-desc: Shows information about the current version


[[command-line-options]]
=== {beatname_uc} command reference

++++
<titleabbrev>Command reference</titleabbrev>
++++

ifndef::deprecate_dashboard_loading[]
{beatname_uc} provides a command-line interface for starting {beatname_uc} and
performing common tasks, like testing configuration files and loading dashboards.
endif::[]

ifdef::deprecate_dashboard_loading[]
{beatname_uc} provides a command-line interface for starting {beatname_uc} and
performing common tasks, like testing configuration files and loading dashboards (deprecated).
endif::[]

The command-line also supports <<global-flags,global flags>>
for controlling global behaviors.

ifeval::["{beatname_lc}"!="winlogbeat"]
[TIP]
=========================
Use `sudo` to run the following commands if:

* the config file is owned by `root`, or
* {beatname_uc} is configured to capture data that requires `root` access

=========================
endif::[]

[options="header"]
|=======================
|Commands |
ifeval::["{beatname_lc}"=="functionbeat"]
|<<deploy-command,`deploy`>> | {deploy-command-short-desc}.
endif::[]
|<<export-command,`export`>> |{export-command-short-desc}.
|<<help-command,`help`>> |{help-command-short-desc}.
|<<keystore-command,`keystore`>> |{keystore-command-short-desc}.
ifeval::["{beatname_lc}"=="functionbeat"]
|<<package-command,`package`>> |{package-command-short-desc}.
|<<remove-command,`remove`>> |{remove-command-short-desc}.
endif::[]
ifdef::has_modules_command[]
|<<modules-command,`modules`>> |{modules-command-short-desc}.
endif::[]
|<<run-command,`run`>> |{run-command-short-desc}.
|<<setup-command,`setup`>> |{setup-command-short-desc}.
|<<test-command,`test`>> |{test-command-short-desc}.
ifeval::["{beatname_lc}"=="functionbeat"]
|<<update-command,`update`>> |{update-command-short-desc}.
endif::[]
|<<version-command,`version`>> |{version-command-short-desc}.
|=======================

Also see <<global-flags,Global flags>>.

ifeval::["{beatname_lc}"=="functionbeat"]
[[deploy-command]]
==== `deploy` command

{deploy-command-short-desc}. Before deploying functions, make sure the user has
the credentials required by your cloud service provider.

*SYNOPSIS*

["source","sh",subs="attributes"]
----
{beatname_lc} deploy FUNCTION_NAME [FLAGS]
----

*`FUNCTION_NAME`*::
Specifies the name of the function to deploy.  

*FLAGS*

*`-h, --help`*::
Shows help for the `deploy` command.

{global-flags}

*EXAMPLES*

["source","sh",subs="attributes"]
-----
{beatname_lc} deploy cloudwatch
{beatname_lc} deploy sqs
-----
endif::[]

[[export-command]]
==== `export` command

{export-command-short-desc}. You can use this
command to quickly view your configuration, see the contents of the index
template, or export a dashboard from {kib}.

*SYNOPSIS*

["source","sh",subs="attributes"]
----
{beatname_lc} export SUBCOMMAND [FLAGS]
----

*SUBCOMMANDS*

*`config`*::
Exports the current configuration to stdout. If you use the `-c` flag, this
command exports the configuration that's defined in the specified file.

[[dashboard-subcommand]]*`dashboard`*::
Exports a dashboard. You can use this option to store a dashboard on disk in a
module and load it automatically. For example, to export the dashboard to a JSON
file, run:
+
["source","shell",subs="attributes"]
----
{beatname_lc} export dashboard --id="DASHBOARD_ID" > dashboard.json
----
+
To find the `DASHBOARD_ID`, look at the URL for the dashboard in {kib}. By
default, `export dashboard` writes the dashboard to stdout. The example shows
how to write the dashboard to a JSON file so that you can import it later. The
JSON file will contain the dashboard with all visualizations and searches. You
must load the index pattern separately for {beatname_uc}.
+
To load the dashboard, copy the generated `dashboard.json` file into the
`kibana/6/dashboard` directory of {beatname_uc}, and run
+{beatname_lc} setup --dashboards+ to import the dashboard.
+
If {kib} is not running on `localhost:5061`, you must also adjust the
{beatname_uc} configuration under `setup.kibana`.

[[template-subcommand]]*`template`*::
Exports the index template to stdout. You can specify the `--es.version` and
`--index` flags to further define what gets exported.

[[ilm-policy-subcommand]]
*`ilm-policy`*::
Exports ILM policy to stdout.

*FLAGS*

*`--es.version VERSION`*::
When used with <<template-subcommand,`template`>>, exports an index
template that is compatible with the specified version.

*`-h, --help`*::
Shows help for the `export` command.

*`--index BASE_NAME`*::
When used with <<template-subcommand,`template`>>, sets the base name to use for
the index template. If this flag is not specified, the default base name is
+{beatname_lc}+.

*`--id DASHBOARD_ID`*::
When used with <<dashboard-subcommand,`dashboard`>>, specifies the dashboard ID.

{global-flags}

*EXAMPLES*

["source","sh",subs="attributes"]
-----
{beatname_lc} export config
{beatname_lc} export template --es.version {stack-version} --index myindexname
{beatname_lc} export dashboard --id="a7b35890-8baa-11e8-9676-ef67484126fb" > dashboard.json
-----


[[help-command]]
==== `help` command

{help-command-short-desc}. If no command is specified, shows help for the
`run` command.

*SYNOPSIS*

["source","sh",subs="attributes"]
----
{beatname_lc} help COMMAND_NAME [FLAGS]
----


*`COMMAND_NAME`*::
Specifies the name of the command to show help for.

*FLAGS*

*`-h, --help`*:: Shows help for the `help` command.

{global-flags}

*EXAMPLE*

["source","sh",subs="attributes"]
-----
{beatname_lc} help export
-----

[[keystore-command]]
==== `keystore` command

{keystore-command-short-desc}.

*SYNOPSIS*

["source","sh",subs="attributes"]
----
{beatname_lc} keystore SUBCOMMAND [FLAGS]
----

*SUBCOMMANDS*

*`add KEY`*::
Adds the specified key to the keystore. Use the `--force` flag to overwrite an
existing key. Use the `--stdin` flag to pass the value through `stdin`.

*`create`*::
Creates a keystore to hold secrets. Use the `--force` flag to overwrite the
existing keystore.

*`list`*::
Lists the keys in the keystore.

*`remove KEY`*::
Removes the specified key from the keystore.

*FLAGS*

*`--force`*::
Valid with the `add` and `create` subcommands. When used with `add`, overwrites
the specified key. When used with `create`, overwrites the keystore.

*`--stdin`*::
When used with `add`, uses the stdin as the source of the key's value.

*`-h, --help`*::
Shows help for the `keystore` command.


{global-flags}

*EXAMPLES*

["source","sh",subs="attributes"]
-----
{beatname_lc} keystore create
{beatname_lc} keystore add ES_PWD
{beatname_lc} keystore remove ES_PWD
{beatname_lc} keystore list
-----

See <<keystore>> for more examples.

ifeval::["{beatname_lc}"=="functionbeat"]
[[package-command]]
==== `package` command

{package-command-short-desc}. 

*SYNOPSIS*

["source","sh",subs="attributes"]
----
{beatname_lc} package [FLAGS]
----

*FLAGS*

*`-h, --help`*::
Shows help for the `package` command.

*`-o, --output`*::
Specifies the full path to the zip file that will contain the package.

{global-flags}

*EXAMPLES*

["source","sh",subs="attributes"]
-----
{beatname_lc} package /path/to/file.zip
-----

[[remove-command]]
==== `remove` command

{remove-command-short-desc}. Before removing functions, make sure the user has
the credentials required by your cloud service provider.

*SYNOPSIS*

["source","sh",subs="attributes"]
----
{beatname_lc} remove FUNCTION_NAME [FLAGS]
----

*`FUNCTION_NAME`*::
Specifies the name of the function to remove.  

*FLAGS*

*`-h, --help`*::
Shows help for the `remove` command.

{global-flags}

*EXAMPLES*

["source","sh",subs="attributes"]
-----
{beatname_lc} remove cloudwatch
{beatname_lc} remove sqs
-----
endif::[]

ifdef::has_modules_command[]
[[modules-command]]
==== `modules` command

{modules-command-short-desc}. You can use this command to enable and disable
specific module configurations defined in the `modules.d` directory. The
changes you make with this command are persisted and used for subsequent
runs of {beatname_uc}.

To see which modules are enabled and disabled, run the `list` subcommand.

*SYNOPSIS*

["source","sh",subs="attributes"]
----
{beatname_lc} modules SUBCOMMAND [FLAGS]
----


*SUBCOMMANDS*

*`disable MODULE_LIST`*::
Disables the modules specified in the space-separated list.

*`enable MODULE_LIST`*::
Enables the modules specified in the space-separated list.

*`list`*::
Lists the modules that are currently enabled and disabled.


*FLAGS*

*`-h, --help`*::
Shows help for the `export` command.


{global-flags}

*EXAMPLES*

ifeval::["{beatname_lc}"=="filebeat"]
["source","sh",subs="attributes"]
-----
{beatname_lc} modules list
{beatname_lc} modules enable apache2 auditd mysql
-----
endif::[]

ifeval::["{beatname_lc}"=="metricbeat"]
["source","sh",subs="attributes"]
-----
{beatname_lc} modules list
{beatname_lc} modules enable apache nginx system
-----
endif::[]
endif::[]


[[run-command]]
==== `run` command

{run-command-short-desc}.

*SYNOPSIS*

["source","sh",subs="attributes"]
-----
{beatname_lc} run [FLAGS]
-----

Or:

["source","sh",subs="attributes"]
-----
{beatname_lc} [FLAGS]
-----

*FLAGS*

ifeval::["{beatname_lc}"=="packetbeat"]
*`-I, --I FILE`*::
Reads packet data from the specified file instead of reading packets from the
network. This option is useful only for testing {beatname_uc}.
+
["source","sh",subs="attributes"]
-----
{beatname_lc} run -I ~/pcaps/network_traffic.pcap
-----
endif::[]

*`-N, --N`*:: Disables publishing for testing purposes.
ifndef::only-elasticsearch[]
This option disables all outputs except the <<file-output,File output>>.
endif::only-elasticsearch[]

ifeval::["{beatname_lc}"=="packetbeat"]
*`-O, --O`*::
Read packets one by one by pressing _Enter_ after each. This option is useful
only for testing {beatname_uc}.
endif::[]

*`--cpuprofile FILE`*::
Writes CPU profile data to the specified file. This option is useful for
troubleshooting {beatname_uc}.

ifeval::["{beatname_lc}"=="packetbeat"]
*`-devices`*::
Prints the list of devices that are available for sniffing and then exits.
endif::[]

ifeval::["{beatname_lc}"=="packetbeat"]
*`-dump FILE`*::
Writes all captured packets to the specified file. This option is useful for
troubleshooting {beatname_uc}.
endif::[]

*`-h, --help`*::
Shows help for the `run` command.

*`--httpprof [HOST]:PORT`*::
Starts an http server for profiling. This option is useful for troubleshooting
and profiling {beatname_uc}.

ifeval::["{beatname_lc}"=="packetbeat"]
*`-l N`*::
Reads the pcap file `N` number of times. The default is 1. Use this option in
combination with the `-I` option. For an infinite loop, use _0_. The `-l`
option is useful only for testing {beatname_uc}.
endif::[]

*`--memprofile FILE`*::
Writes memory profile data to the specified output file. This option is useful
for troubleshooting {beatname_uc}.

ifeval::["{beatname_lc}"=="filebeat"]
*`--modules MODULE_LIST`*::
Specifies a comma-separated list of modules to run. For example:
+
["source","sh",subs="attributes"]
-----
{beatname_lc} run --modules nginx,mysql,system
-----
+
Rather than specifying the list of modules every time you run {beatname_uc},
you can use the <<modules-command,`modules`>> command to enable and disable
specific modules. Then when you run {beatname_uc}, it will run any modules
that are enabled.
endif::[]

ifeval::["{beatname_lc}"=="filebeat"]
*`--once`*::
When the `--once` flag is used, {beatname_uc} starts all configured harvesters
and inputs, and runs each input until the harvesters are closed. If you set the
`--once` flag, you should also set `close_eof` so the harvester is closed when
the end of the file is reached. By default harvesters are closed after
`close_inactive` is reached.
endif::[]

*`--setup`*::
ifdef::deprecate_dashboard_loading[]
deprecated[{deprecate_dashboard_loading}]
endif::[]
+
ifdef::has_ml_jobs[]
Loads the initial setup, including Elasticsearch template, {kib} index pattern,
{kib} dashboards (when available), and Machine learning jobs.
endif::[]
ifndef::has_ml_jobs[]
Loads the initial setup, including Elasticsearch template, {kib} index pattern, and {kib} dashboards (when available).
endif::[]
If you want to use the command without running {beatname_uc}, use the <<setup-command,`setup`>> command instead.


ifeval::["{beatname_lc}"=="metricbeat"]
*`--system.hostfs MOUNT_POINT`*::

Specifies the mount point of the host's filesystem for use in monitoring a host
from within a container.
endif::[]

ifeval::["{beatname_lc}"=="packetbeat"]
*`-t`*::
Reads packets from the pcap file as fast as possible without sleeping. Use this
option in combination with the `-I` option. The `-t` option is useful only for
testing Packetbeat.
endif::[]

{global-flags}

*EXAMPLE*

["source","sh",subs="attributes"]
-----
{beatname_lc} run -e --setup
-----

Or:

["source","sh",subs="attributes"]
-----
{beatname_lc} -e --setup
-----

[[setup-command]]
==== `setup` command

{setup-command-short-desc}

* The index template ensures that fields are mapped correctly in Elasticsearch.

* The {kib} dashboards make it easier for you to visualize {beatname_uc} data
in {kib}.

ifdef::has_ml_jobs[]
* The machine learning jobs contain the configuration information and metadata
necessary to analyze data for anomalies.
endif::[]

Use this command instead of `run --setup` when you want to set up the
environment without actually running {beatname_uc} and ingesting data.

*SYNOPSIS*

["source","sh",subs="attributes"]
----
{beatname_lc} setup [FLAGS]
----


*FLAGS*

ifndef::deprecate_dashboard_loading[]
*`--dashboards`*::
Sets up the {kib} dashboards (when available). This option loads the dashboards
from the {beatname_uc} package. For more options, such as loading customized
dashboards, see {beatsdevguide}/import-dashboards.html[Importing Existing Beat
Dashboards] in the _Beats Developer Guide_.
endif::[]

ifdef::deprecate_dashboard_loading[]
*`--dashboards`*::

deprecated[{deprecate_dashboard_loading}]
+
Sets up the {kib} dashboards only.
endif::[]

*`-h, --help`*::
Shows help for the `setup` command.

ifdef::has_ml_jobs[]
*`--machine-learning`*::
Sets up machine learning job configurations only.
endif::[]

ifeval::["{beatname_lc}"=="filebeat"]
*`--modules MODULE_LIST`*::
Specifies a comma-separated list of modules. Use this flag to avoid errors when
there are no modules defined in the +{beatname_lc}.yml+ file.

*`--pipelines`*::
Sets up ingest pipelines for configured filesets. {beatname_uc} looks for
enabled modules in the +{beatname_lc}.yml+ file. If you used the
<<modules-command,`modules`>> command to enable modules in the `modules.d`
directory, also specify the `--modules` flag.
endif::[]

*`--template`*::
Sets up the index template only.

{global-flags}

*EXAMPLES*

ifeval::["{beatname_lc}"=="filebeat"]
["source","sh",subs="attributes"]
-----
{beatname_lc} setup --dashboards
{beatname_lc} setup --machine-learning
{beatname_lc} setup --pipelines
{beatname_lc} setup --pipelines --modules system,nginx,mysql <1>
{beatname_lc} setup --template
-----
<1> If you used the <<modules-command,`modules`>> command to enable modules in
the `modules.d` directory, also specify the `--modules` flag to indicate which
modules to load pipelines for.
endif::[]

ifeval::["{beatname_lc}"!="filebeat"]
["source","sh",subs="attributes"]
-----
{beatname_lc} setup --dashboards
{beatname_lc} setup --machine-learning
{beatname_lc} setup --template
-----
endif::[]

[[test-command]]
==== `test` command

{test-command-short-desc}.

*SYNOPSIS*

["source","sh",subs="attributes"]
----
{beatname_lc} test SUBCOMMAND [FLAGS]
----

*SUBCOMMANDS*

*`config`*::
Tests the configuration settings.

ifeval::["{beatname_lc}"=="metricbeat"]
*`modules [MODULE_NAME] [METRICSET_NAME]`*::
Tests module settings for all configured modules. When you run this command,
{beatname_uc} does a test run that applies the current settings, retrieves the
metrics, and shows them as output. To test the settings for a specific module,
specify `MODULE_NAME`. To test the settings for a specific metricset in the
module, also specify `METRICSET_NAME`.
endif::[]

*`output`*::
Tests that {beatname_uc} can connect to the output by using the
current settings.

*FLAGS*

*`-h, --help`*:: Shows help for the `test` command.

{global-flags}

ifeval::["{beatname_lc}"!="metricbeat"]
*EXAMPLE*

["source","sh",subs="attributes"]
-----
{beatname_lc} test config
-----
endif::[]

ifeval::["{beatname_lc}"=="metricbeat"]
*EXAMPLES*

["source","sh",subs="attributes"]
-----
{beatname_lc} test config
{beatname_lc} test modules system cpu
-----
endif::[]

ifeval::["{beatname_lc}"=="functionbeat"]
[[update-command]]
==== `update` command

{update-command-short-desc}. Before updating functions, make sure the user has
the credentials required by your cloud service provider.

*SYNOPSIS*

["source","sh",subs="attributes"]
----
{beatname_lc} update FUNCTION_NAME [FLAGS]
----

*`FUNCTION_NAME`*::
Specifies the name of the function to update.  

*FLAGS*

*`-h, --help`*::
Shows help for the `update` command.

{global-flags}

*EXAMPLES*

["source","sh",subs="attributes"]
-----
{beatname_lc} update cloudwatch
{beatname_lc} update sqs
-----
endif::[]

[[version-command]]
==== `version` command

{version-command-short-desc}.

*SYNOPSIS*

["source","sh",subs="attributes"]
----
{beatname_lc} version [FLAGS]
----


*FLAGS*

*`-h, --help`*:: Shows help for the `version` command.

{global-flags}

*EXAMPLE*

["source","sh",subs="attributes"]
-----
{beatname_lc} version
-----


[float]
[[global-flags]]
=== Global flags

These global flags are available whenever you run {beatname_uc}.

*`-E, --E "SETTING_NAME=VALUE"`*::
Overrides a specific configuration setting. You can specify multiple overrides.
For example:
+
["source","sh",subs="attributes"]
----------------------------------------------------------------------
{beatname_lc} -E "name=mybeat" -E "output.elasticsearch.hosts=['http://myhost:9200']"
----------------------------------------------------------------------
+
This setting is applied to the currently running {beatname_uc} process.
The {beatname_uc} configuration file is not changed.

ifeval::["{beatname_lc}"=="filebeat"]
*`-M, --M "VAR_NAME=VALUE"`*:: Overrides the default configuration for a
{beatname_uc} module. You can specify multiple variable overrides. For example:
+
["source","sh",subs="attributes"]
----------------------------------------------------------------------
{beatname_lc} -modules=nginx -M "nginx.access.var.paths=['/var/log/nginx/access.log*']" -M "nginx.access.var.pipeline=no_plugins"
----------------------------------------------------------------------
endif::[]

*`-c, --c FILE`*::
Specifies the configuration file to use for {beatname_uc}. The file you specify
here is relative to `path.config`. If the `-c` flag is not specified, the
default config file, +{beatname_lc}.yml+, is used.

*`-d, --d SELECTORS`*::
Enables debugging for the specified selectors. For the selectors, you can
specify a comma-separated
list of components, or you can use `-d "*"` to enable debugging for all
components. For example, `-d "publish"` displays all the "publish" related
messages.

*`-e, --e`*::
Logs to stderr and disables syslog/file output.

*`--path.config`*::
Sets the path for configuration files. See the <<directory-layout>> section for
details.

*`--path.data`*::
Sets the path for data files. See the <<directory-layout>> section for details.

*`--path.home`*::
Sets the path for miscellaneous files. See the <<directory-layout>> section for
details.

*`--path.logs`*::
Sets the path for log files. See the <<directory-layout>> section for details.

*`--strict.perms`*::
Sets strict permission checking on configuration files. The default is
`-strict.perms=true`. See
{beats-ref}/config-file-permissions.html[Config file ownership and permissions] in
the _Beats Platform Reference_ for more information.

*`-v, --v`*::
Logs INFO-level messages.
