icingabeat/vendor/github.com/elastic/beats/libbeat/docs/command-reference.asciidoc

//////////////////////////////////////////////////////////////////////////
//// 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>>.

:export-command-short-desc: Exports the configuration or index template to stdout
:help-command-short-desc: Shows help for any command
:modules-command-short-desc: Manages configured modules
:run-command-short-desc: Runs {beatname_uc}. This command is used by default if you start {beatname_uc} without specifying a command
:setup-command-short-desc: Sets up the initial environment, including the index template, Kibana dashboards (when available), and machine learning jobs (when available)
:test-command-short-desc: Tests the configuration
:version-command-short-desc: Shows information about the current version


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

{beatname_uc} provides a command-line interface for running the Beat and
performing common tasks, like testing configuration files and loading
dashboards. The command-line also supports <<global-flags,global flags>>
for controlling global behaviors.

ifeval::["{beatname_lc}"!="winlogbeat"]

[NOTE]
=========================
You may need to use `sudo` to run the following commands if you've:

* changed ownership of the config file to `root`
* enabled the Beat to capture data that requires `root` access

=========================

endif::[]

[horizontal]
<<export-command,`export`>>::
{export-command-short-desc}.

<<help-command,`help`>>::
{help-command-short-desc}.

ifeval::[("{beatname_lc}"=="filebeat") or ("{beatname_lc}"=="metricbeat")]

<<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}.

<<version-command,`version`>>::
{version-command-short-desc}.

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

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

{export-command-short-desc}. You can use this
command to quickly view your configuration or the contents of the index
template.

*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.

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

*FLAGS*

*`--es.version VERSION`*::
When specified along 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 specified along 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}+.

{global-flags}

*EXAMPLES*

["source","sh",subs="attributes"]
-----
{beatname_lc} export config
{beatname_lc} export template --es.version {stack-version} --index myindexname
-----


[[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
-----

ifeval::[("{beatname_lc}"=="filebeat") or ("{beatname_lc}"=="metricbeat")]

[[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 the publishing of events to the defined output. This option is useful
only for testing {beatname_uc}.

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 prospectors, and runs each prospector 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`*::
Loads the sample Kibana dashboards. If you want to load the dashboards 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 Kibana dashboards make it easier for you to visualize {beatname_uc} data
in Kibana.
* The machine learning jobs contain the configuration information and metadata
necessary to analyze data for anomalies.

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*

*`--dashboards`*::
Sets up the Kibana dashboards only.

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

*`--machine-learning`*::
Sets up machine learning job configurations only.

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.

endif::[]

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

{global-flags}

*EXAMPLE*

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


[[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::[]

[[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
{libbeat}/config-file-permissions.html[Config file ownership and permissions] in
the _Beats Platform Reference_ for more information.

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