diff --git a/auditbeat/docs/getting-started.asciidoc b/auditbeat/docs/getting-started.asciidoc index 5abc893f51e2..6a97c407e188 100644 --- a/auditbeat/docs/getting-started.asciidoc +++ b/auditbeat/docs/getting-started.asciidoc @@ -178,6 +178,8 @@ If you are sending output to Logstash, make sure you include::../../libbeat/docs/step-configure-kibana-endpoint.asciidoc[] +include::../../libbeat/docs/step-configure-credentials.asciidoc[] + include::../../libbeat/docs/step-test-config.asciidoc[] include::../../libbeat/docs/step-look-at-config.asciidoc[] @@ -242,6 +244,12 @@ PS C:{backslash}Program Files{backslash}{beatname_uc}> Start-Service {beatname_l By default the log files are stored in +C:{backslash}ProgramData{backslash}{beatname_lc}{backslash}Logs+. +[id="{beatname_lc}-passing-credentials"] +==== Pass credentials + +:start-type: start +include::../../libbeat/docs/shared-passing-credentials-setup.asciidoc[] + ==== Test the {beatname_uc} installation To verify that your server's statistics are present in Elasticsearch, issue diff --git a/filebeat/docs/getting-started.asciidoc b/filebeat/docs/getting-started.asciidoc index 5a18fe63fa70..e09a06a545fc 100644 --- a/filebeat/docs/getting-started.asciidoc +++ b/filebeat/docs/getting-started.asciidoc @@ -202,6 +202,8 @@ configure the Logstash output in <>. include::../../libbeat/docs/step-configure-kibana-endpoint.asciidoc[] +include::../../libbeat/docs/step-configure-credentials.asciidoc[] + include::../../libbeat/docs/step-test-config.asciidoc[] include::../../libbeat/docs/step-look-at-config.asciidoc[] @@ -279,6 +281,12 @@ By default, Windows log files are stored in `C:\ProgramData\filebeat\Logs`. Filebeat is now ready to send log files to your defined output. +[id="{beatname_lc}-passing-credentials"] +==== Pass credentials + +:start-type: start +include::../../libbeat/docs/shared-passing-credentials-setup.asciidoc[] + [[view-kibana-dashboards]] === Step 7: View the sample Kibana dashboards diff --git a/filebeat/docs/images/kibana-system.png b/filebeat/docs/images/kibana-system.png index fccfbd81f4a1..eded1a605403 100644 Binary files a/filebeat/docs/images/kibana-system.png and b/filebeat/docs/images/kibana-system.png differ diff --git a/filebeat/docs/modules-getting-started.asciidoc b/filebeat/docs/modules-getting-started.asciidoc index 4256205e213c..6191105c6df7 100644 --- a/filebeat/docs/modules-getting-started.asciidoc +++ b/filebeat/docs/modules-getting-started.asciidoc @@ -47,31 +47,41 @@ ready to receive data from Filebeat. [[running-modules-quickstart]] ==== Running Filebeat with modules enabled -To set up and run one or more Filebeat modules, you issue the following command: +To set up and run Filebeat modules: +. Run the `setup` command to set up the initial environment. This command +loads the recommended index template for writing to Elasticsearch and deploys +the sample dashboards for visualizing the data in Kibana. For example: ++ [source,shell] ---------------------------------------------------------------------- -./filebeat -e -modules=MODULES -setup +./filebeat setup -e ---------------------------------------------------------------------- - -Where `MODULES` is the name of the module (or a comma-separated list of -modules) that you want to enable. The `-e` flag is optional and sends output ++ +The value that you pass with the `-modules` flag is a comma-separated list of +modules that you want to set up. The `-e` flag is optional and sends output to standard error instead of syslog. -The `-setup` flag is a one-time setup step. For subsequent runs of Filebeat, -do not specify this flag. - -The following example starts Filebeat with the `system` module enabled and -loads the sample Kibana dashboards: - +. Start Filebeat and use the `-modules` flag to specify the list of modules +you want to run. The following example starts Filebeat with the `system` module +enabled (it's assumed that you've already loaded the sample dashboards): ++ +[source,shell] +---------------------------------------------------------------------- +./filebeat -e -modules=system +---------------------------------------------------------------------- ++ +This command takes care of configuring Filebeat and loading the ingest node +pipelines and other configuration settings required to parse the log files. ++ +To run more than one module, specify a comma-separated list of modules. For +example: ++ [source,shell] ---------------------------------------------------------------------- -./filebeat -e -modules=system -setup +./filebeat -e -modules=system,nginx,mysql ---------------------------------------------------------------------- -This command takes care of configuring Filebeat, loading the recommended index -template for writing to Elasticsearch, and deploying the sample dashboards -for visualizing the data in Kibana. NOTE: Depending on how you've installed Filebeat, you might see errors related to file ownership or permissions when you try to run Filebeat modules. @@ -79,30 +89,15 @@ See {libbeat}/config-file-permissions.html[Config File Ownership and Permissions in the _Beats Platform Reference_ if you encounter errors related to file ownership or permissions. -include::system-module-note.asciidoc[] +//include::system-module-note.asciidoc[] -To start Filebeat with the `system`, `nginx`, and `mysql` modules enabled -and load the sample dashboards, run: - -[source,shell] ----------------------------------------------------------------------- -./filebeat -e -modules=system,nginx,mysql -setup ----------------------------------------------------------------------- - -To start Filebeat with the `system` module enabled (it's assumed that -you've already loaded the sample dashboards), run: - -[source,shell] ----------------------------------------------------------------------- -./filebeat -e -modules=system ----------------------------------------------------------------------- TIP: In a production environment, you'll probably want to use a configuration file, rather than command-line flags, to specify which modules to run. See the detailed documentation for more about configuring and running modules. [[setting-variables]] -==== Setting the path variable +==== Set the path variable The examples here assume that the logs you're harvesting are in the location expected for your OS and that the default behavior of Filebeat is appropriate @@ -119,8 +114,14 @@ logs: See the <> for more information about setting variables and advanced options. +[[passing-credentials-modules]] +==== Pass credentials + +:start-type: modules +include::../../libbeat/docs/shared-passing-credentials-setup.asciidoc[] + [[visualizing-data]] -==== Visualizing the data in Kibana +==== Visualize the data in Kibana After you've confirmed that Filebeat is sending events to Elasticsearch, launch the Kibana web interface by pointing your browser to port 5601. For example, @@ -128,6 +129,9 @@ http://127.0.0.1:5601[http://127.0.0.1:5601]. Open the dashboard and explore the visualizations for your parsed logs. +TIP: If you don't see data in Kibana, try changing the date range to a larger +range. By default, Kibana shows the last 15 minutes. + Here's an example of the syslog dashboard: image:./images/kibana-system.png[Syslog dashboard] diff --git a/heartbeat/docs/getting-started.asciidoc b/heartbeat/docs/getting-started.asciidoc index d47a6dcdb4e1..78bdc4df0f8c 100644 --- a/heartbeat/docs/getting-started.asciidoc +++ b/heartbeat/docs/getting-started.asciidoc @@ -220,6 +220,8 @@ If you are sending output to Logstash, make sure you include::../../libbeat/docs/step-configure-kibana-endpoint.asciidoc[] +include::../../libbeat/docs/step-configure-credentials.asciidoc[] + include::../../libbeat/docs/step-test-config.asciidoc[] include::../../libbeat/docs/step-look-at-config.asciidoc[] @@ -245,8 +247,6 @@ NOTE: If you use an init.d script to start Heartbeat on deb or rpm, you can't specify command line flags (see <>). To specify flags, start Heartbeat in the foreground. -//REVIEWERS: Should the deb and rpm examples say start or run? - *deb:* ["source","sh",subs="attributes"] @@ -285,6 +285,12 @@ By default, Windows log files are stored in +C:\ProgramData\heartbeat\Logs+. Heartbeat is now ready to check the status of your services and send events to your defined output. +[id="{beatname_lc}-passing-credentials"] +==== Pass credentials + +:start-type: start +include::../../libbeat/docs/shared-passing-credentials-setup.asciidoc[] + [[view-kibana-dashboards]] === Step 6: View the sample Kibana dashboards diff --git a/libbeat/docs/dashboards.asciidoc b/libbeat/docs/dashboards.asciidoc index f169129c9c6a..5d96b3728c15 100644 --- a/libbeat/docs/dashboards.asciidoc +++ b/libbeat/docs/dashboards.asciidoc @@ -72,3 +72,9 @@ and run: ---------------------------------------------------------------------- PS > {beatname_lc} setup --dashboards ---------------------------------------------------------------------- + +[[passing-credentials-dashboard-loading]] +==== Pass credentials + +:start-type: setup-dashboards +include::./shared-passing-credentials-setup.asciidoc[] diff --git a/libbeat/docs/reference-yml.asciidoc b/libbeat/docs/reference-yml.asciidoc index 7f9b1854d9b2..0b04a14a0130 100644 --- a/libbeat/docs/reference-yml.asciidoc +++ b/libbeat/docs/reference-yml.asciidoc @@ -1,8 +1,6 @@ [id="{beatname_lc}-reference-yml"] == {beatname_lc}.reference.yml -//REVIEWERS: Right now, I'm referencing the path to the file in the beats repo, but to make sure we don't expose new config options prematurely (for example, for 6.0.1) I'll need to make a copy of the file and put in the docs directory. - The following reference file is available with your {beatname_uc} installation. It shows all non-deprecated {beatname_uc} options. You can copy from this file and paste configurations into the +{beatname_lc}.yml+ file to customize it. diff --git a/libbeat/docs/shared-passing-credentials-setup.asciidoc b/libbeat/docs/shared-passing-credentials-setup.asciidoc new file mode 100644 index 000000000000..a6d4cf9c724b --- /dev/null +++ b/libbeat/docs/shared-passing-credentials-setup.asciidoc @@ -0,0 +1,45 @@ +If you've secured Elasticsearch and Kibana, you need to pass credentials when +you run {beatname_uc} commands. You can specify credentials from the command +line, or in the config file. For example, from the command line, specify: + +ifeval::["{start-type}"=="setup-index"] + +["source","sh",subs="attributes"] +---- +{beatname_lc} setup --template -e -E output.elasticsearch.username=elastic -E output.elasticsearch.password=elastic +---- + +endif::[] + +ifeval::["{start-type}"=="setup-dashboards"] + +["source","sh",subs="attributes"] +---- +{beatname_lc} setup --dashboards -e -E output.elasticsearch.username=elastic -E output.elasticsearch.password=elastic -E setup.kibana.username=elastic -E setup.kibana.password=elastic +---- + +endif::[] + +ifeval::["{start-type}"=="start"] + +["source","sh",subs="attributes"] +---- +{beatname_lc} -e -c {beatname_lc}.yml -d "publish" -E output.elasticsearch.username=elastic -E output.elasticsearch.password=elastic +---- + +If you start {beatname_uc} as a service instead of running it in the +foreground, you must specify credentials in the config file. + +endif::[] + +ifeval::["{start-type}"=="modules"] + +["source","sh",subs="attributes"] +---- +{beatname_lc} setup -e -E output.elasticsearch.username=elastic -E output.elasticsearch.password=elastic -E setup.kibana.username=elastic -E setup.kibana.password=elastic +---- + +endif::[] + +See <<{beatname_lc}-configuration>> for more information about specifying +credentials in the config file. diff --git a/libbeat/docs/shared-path-config.asciidoc b/libbeat/docs/shared-path-config.asciidoc index 1b1c6e6230d4..f08d2810c681 100644 --- a/libbeat/docs/shared-path-config.asciidoc +++ b/libbeat/docs/shared-path-config.asciidoc @@ -13,8 +13,6 @@ [[configuration-path]] == Set up project paths -//REVIEWERS: I'm not sure if "project paths" is the right way to describe these settings, but I want to differentiate the path users set here from other paths (like the prospector setting). - The `path` section of the +{beatname_lc}.yml+ config file contains configuration options that define where the Beat looks for its files. For example, all Beats look for the Elasticsearch template file in the configuration path, Filebeat and diff --git a/libbeat/docs/shared-ssl-config.asciidoc b/libbeat/docs/shared-ssl-config.asciidoc index 61fe8c7f4164..6b0b1f6795f2 100644 --- a/libbeat/docs/shared-ssl-config.asciidoc +++ b/libbeat/docs/shared-ssl-config.asciidoc @@ -74,8 +74,6 @@ The passphrase used to decrypt an encrypted key stored in the configured `key` f [float] ==== `supported_protocols` -//REVIEWERS: This description is kind of garbled. Can we fix the language, but maybe without going into details about how the client and server negotiate which version to use? - List of allowed SSL/TLS versions. If SSL/TLS server decides for protocol versions not configured, the connection will be dropped during or after the handshake. The setting is a list of allowed protocol versions: diff --git a/libbeat/docs/shared-template-load.asciidoc b/libbeat/docs/shared-template-load.asciidoc index ab6a8a3583a9..adf653a73618 100644 --- a/libbeat/docs/shared-template-load.asciidoc +++ b/libbeat/docs/shared-template-load.asciidoc @@ -61,6 +61,10 @@ Logstash output. If you disable automatic template loading, you can run the `setup` command to load the template manually. +ifdef::allplatforms[] + +*deb, rpm, and mac:* + ["source","sh",subs="attributes"] ---- ./{beatname_lc} setup --template @@ -73,6 +77,34 @@ command with `sudo`. endif::[] +ifeval::["{beatname_lc}"!="auditbeat"] + +*docker:* + +["source","sh",subs="attributes"] +---------------------------------------------------------------------- +docker run {dockerimage} setup --template +---------------------------------------------------------------------- + +endif::[] + +*win:* + +endif::allplatforms[] + +Open a PowerShell prompt as an Administrator (right-click the PowerShell icon +and select *Run As Administrator*). If you are running Windows XP, you may need +to download and install PowerShell. + +From the PowerShell prompt, change to the directory where you installed {beatname_uc}, +and run: + +["source","sh",subs="attributes,callouts"] +---------------------------------------------------------------------- +PS > {beatname_lc} setup --template +---------------------------------------------------------------------- + + NOTE: If you've already used {beatname_uc} to index data into Elasticsearch, the index may contain old documents. After you load the index template, you can delete the old documents from {beatname_lc}-* to force Kibana to look @@ -82,3 +114,10 @@ at the newest documents. Use this command: ---------------------------------------------------------------------- curl -XDELETE 'http://localhost:9200/{beatname_lc}-*' ---------------------------------------------------------------------- + +[[passing-credentials-template-loading]] +==== Pass credentials + +:start-type: setup-index +include::./shared-passing-credentials-setup.asciidoc[] + diff --git a/libbeat/docs/step-configure-credentials.asciidoc b/libbeat/docs/step-configure-credentials.asciidoc new file mode 100644 index 000000000000..b49aebe97dcc --- /dev/null +++ b/libbeat/docs/step-configure-credentials.asciidoc @@ -0,0 +1,30 @@ +ifeval::["{beatname_lc}"!="winlogbeat"] +. If you've secured Elasticsearch and Kibana, you need to pass credentials when +you run the commands that set up and start {beatname_uc}. You can either pass +credentials at the <> (as shown later in the +getting started guide), or specify credentials in the config file. If you plan +to run {beatname_uc} as a service, you must specify credentials in the config +file. +endif::[] +ifeval::["{beatname_lc}"=="winlogbeat"] +. If you've secured Elasticsearch and Kibana, you need to specify credentials +in the config file before you run the commands that set up and start +{beatname_uc}. +endif::[] ++ +For example: ++ +[source,yaml] +---- +output.elasticsearch: + hosts: ["myEShost:9200"] + username: elastic + password: elastic +setup.kibana: + host: "mykibanahost:5601" + username: elastic + password: elastic +---- ++ +Also see the security-related options described in <> and +<>. diff --git a/libbeat/docs/step-configure-kibana-endpoint.asciidoc b/libbeat/docs/step-configure-kibana-endpoint.asciidoc index 00fe1397703c..97cc82d16097 100644 --- a/libbeat/docs/step-configure-kibana-endpoint.asciidoc +++ b/libbeat/docs/step-configure-kibana-endpoint.asciidoc @@ -14,7 +14,4 @@ for example, `localhost:5601`. NOTE: If you specify a path after the port number, you need to include the scheme and port: `http://localhost:5601/path`. -Also see the security-related options in <> if you are -connecting to a secured instance of Kibana. - -- diff --git a/libbeat/docs/step-test-config.asciidoc b/libbeat/docs/step-test-config.asciidoc index 9cb576833869..d83a45f0eda2 100644 --- a/libbeat/docs/step-test-config.asciidoc +++ b/libbeat/docs/step-test-config.asciidoc @@ -6,8 +6,6 @@ the following options specified: +./{beatname_lc} test config -e+. Make sure you config files are in the path expected by {beatname_uc} (see <>), or use the `-c` flag to specify the path to the config file. -//REVIEWERS: I'm assuming that the test command works the same on all platforms - endif::[] ifeval::["{requires-sudo}"=="yes"] diff --git a/metricbeat/docs/gettingstarted.asciidoc b/metricbeat/docs/gettingstarted.asciidoc index b7ce54c8b023..7fdd39fe2d7a 100644 --- a/metricbeat/docs/gettingstarted.asciidoc +++ b/metricbeat/docs/gettingstarted.asciidoc @@ -229,6 +229,8 @@ If you are sending output to Logstash, make sure you include::../../libbeat/docs/step-configure-kibana-endpoint.asciidoc[] +include::../../libbeat/docs/step-configure-credentials.asciidoc[] + include::../../libbeat/docs/step-test-config.asciidoc[] include::../../libbeat/docs/step-look-at-config.asciidoc[] @@ -301,6 +303,12 @@ By default the log files are stored in `C:\ProgramData\metricbeat\Logs`. NOTE: On Windows, statistics about system load and swap usage are currently not captured. +[id="{beatname_lc}-passing-credentials"] +==== Pass credentials + +:start-type: start +include::../../libbeat/docs/shared-passing-credentials-setup.asciidoc[] + ==== Test the Metricbeat installation To verify that your server's statistics are present in Elasticsearch, issue diff --git a/packetbeat/docs/gettingstarted.asciidoc b/packetbeat/docs/gettingstarted.asciidoc index 86c55b99e610..f540213eb1bd 100644 --- a/packetbeat/docs/gettingstarted.asciidoc +++ b/packetbeat/docs/gettingstarted.asciidoc @@ -243,6 +243,8 @@ If you are sending output to Logstash, make sure you include::../../libbeat/docs/step-configure-kibana-endpoint.asciidoc[] +include::../../libbeat/docs/step-configure-credentials.asciidoc[] + :requires-sudo: yes include::../../libbeat/docs/step-test-config.asciidoc[] @@ -313,8 +315,13 @@ PS C:\Program Files\Packetbeat> Start-Service packetbeat By default the log files are stored in `C:\ProgramData\packetbeat\Logs`. -[float] -=== Test the Packetbeat installation +[id="{beatname_lc}-passing-credentials"] +==== Pass credentials + +:start-type: start +include::../../libbeat/docs/shared-passing-credentials-setup.asciidoc[] + +==== Test the Packetbeat installation Packetbeat is now ready to capture data from your network traffic. You can test that it works by creating a simple HTTP request. For example: diff --git a/winlogbeat/docs/getting-started.asciidoc b/winlogbeat/docs/getting-started.asciidoc index 927c985333a1..a1426efc9501 100644 --- a/winlogbeat/docs/getting-started.asciidoc +++ b/winlogbeat/docs/getting-started.asciidoc @@ -121,6 +121,8 @@ If you are sending output to Logstash, make sure you include::../../libbeat/docs/step-configure-kibana-endpoint.asciidoc[] +include::../../libbeat/docs/step-configure-credentials.asciidoc[] + . After you save your configuration file, test it with the following command. + [source,shell] @@ -167,6 +169,13 @@ this command: PS C:\Program Files\Winlogbeat> services.msc ---------------------------------------------------------------------- +[id="{beatname_lc}-passing-credentials"] +==== Pass credentials + +:start-type: start +include::../../libbeat/docs/shared-passing-credentials-setup.asciidoc[] + + ==== Stop Winlogbeat Stop the Winlogbeat service with the following command: