////////////////////////////////////////////////////////////////////////// //// 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 <>. :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 <> :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 ++++ Command reference ++++ 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 <> 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-short-desc}. |<> |{help-command-short-desc}. |<> |{keystore-command-short-desc}. ifeval::[("{beatname_lc}"=="filebeat") or ("{beatname_lc}"=="metricbeat")] |<> |{modules-command-short-desc}. endif::[] |<> |{run-command-short-desc}. |<> |{setup-command-short-desc}. |<> |{test-command-short-desc}. |<> |{version-command-short-desc}. |======================= Also see <>. [[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 <>, 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 <>, 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 <> 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 <> 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 <> 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 <> section for details. *`--path.data`*:: Sets the path for data files. See the <> section for details. *`--path.home`*:: Sets the path for miscellaneous files. See the <> section for details. *`--path.logs`*:: Sets the path for log files. See the <> 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.