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

717 lines
18 KiB
Text
Raw Normal View History

2018-11-18 11:08:38 +01:00
//////////////////////////////////////////////////////////////////////////
//// 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.