youtubebeat/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, 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
: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, Kibana 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 Kibana dashboards (when available)
endif::[]

endif::[]

ifdef::deprecate_dashboard_loading[]

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

endif::[]

: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 |
|<<export-command,`export`>> |{export-command-short-desc}.
|<<help-command,`help`>> |{help-command-short-desc}.
|<<keystore-command,`keystore`>> |{keystore-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, see the contents of the index
template or export a dashboard from Kibana.

*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`*::
Exporting a dashboard allows to store a dashboard on disk in a
module and load it automatically. The following command can be used:
+
["source","shell",subs="attributes"]
----
{beatname_lc} export dashboard --id="dashboard-id" > dashboard.json
----
+
The `dashboard-id` can be found in the Kibana URL. By default `export dashboard`
will write the dashboard to stdout. Above it's written into `dashboard.json` so
it can later imported again. The file contains the dashboard with all
visualizations and searches. The index pattern is removed as it is
expected to be loaded separately for {beatname_uc}.
+
The generated `dashboard.json` file can be copied into the `kibana/6/dashboard`
directory of {beatname_lc} and next time +{beatname_lc} setup dashboards+ is
run the dashboard will be imported.
+
In case Kibana is not running on `localhost:5061` the {beatname_uc}
configuration under `setup.kibana` must be adjusted.

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

[[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}"=="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 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, Kibana index pattern,
Kibana dashboards and Machine learning jobs.
endif::[]
ifndef::has_ml_jobs[]
Loads the initial setup, including Elasticsearch template, Kibana index pattern and Kibana dashboards.
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 Kibana dashboards make it easier for you to visualize {beatname_uc} data
in Kibana.

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 Kibana dashboards only. 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 Kibana 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.

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.