////////////////////////////////////////////////////////////////////////// //// 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 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 <> 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-short-desc}. <>:: {help-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 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 <>, 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 ----- 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 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 <> 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 <> 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.