From fe576103444b40e7122afd3a1c838e7dc1483714 Mon Sep 17 00:00:00 2001
From: DeDe Morton <dede.morton@elastic.co>
Date: Tue, 31 Oct 2017 06:53:18 -0700
Subject: [PATCH] Fix getting started (#5326)

* Move sentence to correct location

* Adds warning about deleting the index (fixes #5083)

* Clarify settings for JSON parsing (fixes #4391)

* Fix misc issues
---
 auditbeat/docs/configuring-howto.asciidoc      |  1 +
 auditbeat/docs/getting-started.asciidoc        |  3 +--
 filebeat/docs/configuring-howto.asciidoc       |  7 ++++---
 filebeat/docs/filebeat-options.asciidoc        |  3 +++
 filebeat/docs/getting-started.asciidoc         |  2 --
 filebeat/docs/load-balancing.asciidoc          |  8 ++++----
 filebeat/docs/modules-getting-started.asciidoc | 11 +++++------
 heartbeat/docs/configuring-howto.asciidoc      |  1 +
 heartbeat/docs/getting-started.asciidoc        |  3 +--
 libbeat/docs/config-file-format.asciidoc       |  1 +
 libbeat/docs/shared-template-load.asciidoc     | 12 ++++++++++--
 metricbeat/docs/configuring-howto.asciidoc     |  1 +
 metricbeat/docs/gettingstarted.asciidoc        |  3 +--
 packetbeat/docs/configuring-howto.asciidoc     |  1 +
 packetbeat/docs/gettingstarted.asciidoc        |  3 +--
 winlogbeat/docs/configuring-howto.asciidoc     |  1 +
 winlogbeat/docs/getting-started.asciidoc       |  2 --
 17 files changed, 36 insertions(+), 27 deletions(-)

diff --git a/auditbeat/docs/configuring-howto.asciidoc b/auditbeat/docs/configuring-howto.asciidoc
index e16447de3cf7..2aeeaff8b948 100644
--- a/auditbeat/docs/configuring-howto.asciidoc
+++ b/auditbeat/docs/configuring-howto.asciidoc
@@ -34,6 +34,7 @@ The following topics describe how to configure {beatname_uc}:
 * <<configuration-logging>>
 * <<using-environ-vars>>
 * <<yaml-tips>>
+* <<{beatname_lc}-reference-yml>>
 
 After changing configuration settings, you need to restart {beatname_uc} to
 pick up the changes.
diff --git a/auditbeat/docs/getting-started.asciidoc b/auditbeat/docs/getting-started.asciidoc
index 6a97c407e188..0afb75d06078 100644
--- a/auditbeat/docs/getting-started.asciidoc
+++ b/auditbeat/docs/getting-started.asciidoc
@@ -20,8 +20,7 @@ install, configure, and run {beatname_uc}:
 * <<load-kibana-dashboards>>
 * <<{beatname_lc}-starting>>
 * <<view-kibana-dashboards>>
-* <<command-line-options>>
-* <<directory-layout>>
+* <<setup-repositories>>
 
 [id="{beatname_lc}-installation"]
 === Step 1: Install {beatname_uc}
diff --git a/filebeat/docs/configuring-howto.asciidoc b/filebeat/docs/configuring-howto.asciidoc
index 4f6e53fb691b..b16c9134ce4a 100644
--- a/filebeat/docs/configuring-howto.asciidoc
+++ b/filebeat/docs/configuring-howto.asciidoc
@@ -26,6 +26,7 @@ The following topics describe how to configure Filebeat:
 * <<filebeat-configuration-reloading>>
 * <<configuring-internal-queue>>
 * <<configuring-output>>
+* <<load-balancing>>
 * <<configuration-ssl>>
 * <<filtering-and-enhancing-data>>
 * <<configuring-ingest-node>>
@@ -35,9 +36,9 @@ The following topics describe how to configure Filebeat:
 * <<configuration-template>>
 * <<configuration-logging>>
 * <<using-environ-vars>>
-* <<load-balancing>>
 * <<yaml-tips>>
 * <<regexp-support>>
+* <<{beatname_lc}-reference-yml>>
 
 --
 
@@ -58,10 +59,10 @@ include::../../libbeat/docs/queueconfig.asciidoc[]
 
 include::../../libbeat/docs/outputconfig.asciidoc[]
 
-include::../../libbeat/docs/shared-ssl-config.asciidoc[]
-
 include::./load-balancing.asciidoc[]
 
+include::../../libbeat/docs/shared-ssl-config.asciidoc[]
+
 include::./filebeat-filtering.asciidoc[]
 
 include::../../libbeat/docs/shared-config-ingest.asciidoc[]
diff --git a/filebeat/docs/filebeat-options.asciidoc b/filebeat/docs/filebeat-options.asciidoc
index daf8fef7dd43..78a3e2f62e81 100644
--- a/filebeat/docs/filebeat-options.asciidoc
+++ b/filebeat/docs/filebeat-options.asciidoc
@@ -396,6 +396,9 @@ json.add_error_key: true
 json.message_key: log
 -------------------------------------------------------------------------------------
 
+You must specify at least one of the following settings to enable JSON parsing
+mode:
+
 *`keys_under_root`*:: By default, the decoded JSON is placed under a "json" key in the output document.
 If you enable this setting, the keys are copied top level in the output document. The default is false.
 
diff --git a/filebeat/docs/getting-started.asciidoc b/filebeat/docs/getting-started.asciidoc
index 5b4cba1710e6..e6acc21c3195 100644
--- a/filebeat/docs/getting-started.asciidoc
+++ b/filebeat/docs/getting-started.asciidoc
@@ -19,8 +19,6 @@ After installing the Elastic Stack, read the following topics to learn how to in
 * <<filebeat-starting>>
 * <<view-kibana-dashboards>>
 * <<filebeat-modules-quickstart>>
-* <<command-line-options>>
-* <<directory-layout>>
 * <<setup-repositories>>
 
 [[filebeat-installation]]
diff --git a/filebeat/docs/load-balancing.asciidoc b/filebeat/docs/load-balancing.asciidoc
index 330db6d82954..2f0b8b8f0127 100644
--- a/filebeat/docs/load-balancing.asciidoc
+++ b/filebeat/docs/load-balancing.asciidoc
@@ -1,5 +1,5 @@
 [[load-balancing]]
-=== Load balance the output hosts
+== Load balance the output hosts
 
 Filebeat provides configuration options that you can use to fine
 tune load balancing when sending events to multiple hosts.
@@ -21,9 +21,9 @@ The load balancer also supports multiple workers per host. The default is
 `worker: 1`. If you increase the number of workers, additional network
 connections will be used.  The total number of workers participating
 in load balancing is `number of hosts * workers`.
-+
+
 Example:
-+
+
 [source,yaml]
 -------------------------------------------------------------------------------
 filebeat.prospectors:
@@ -35,5 +35,5 @@ output.logstash:
   loadbalance: true
   worker: 2
 -------------------------------------------------------------------------------
-+
+
 In this example, there are 4 workers participating in load balancing.
diff --git a/filebeat/docs/modules-getting-started.asciidoc b/filebeat/docs/modules-getting-started.asciidoc
index cb387a57c1d3..8e9b8b39c363 100644
--- a/filebeat/docs/modules-getting-started.asciidoc
+++ b/filebeat/docs/modules-getting-started.asciidoc
@@ -61,13 +61,12 @@ the sample dashboards for visualizing the data in Kibana. For example:
 ./filebeat setup -e
 ----------------------------------------------------------------------
 +
-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 `-e` flag is optional and sends output to standard error instead of syslog.
 
-. 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):
+. Start Filebeat and use the `--modules` flag to specify a comma-separated 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]
 ----------------------------------------------------------------------
diff --git a/heartbeat/docs/configuring-howto.asciidoc b/heartbeat/docs/configuring-howto.asciidoc
index 3774c62e983c..0a80f51486cb 100644
--- a/heartbeat/docs/configuring-howto.asciidoc
+++ b/heartbeat/docs/configuring-howto.asciidoc
@@ -36,6 +36,7 @@ The following topics describe how to configure Heartbeat:
 * <<using-environ-vars>>
 * <<yaml-tips>>
 * <<regexp-support>>
+* <<{beatname_lc}-reference-yml>>
 
 --
 
diff --git a/heartbeat/docs/getting-started.asciidoc b/heartbeat/docs/getting-started.asciidoc
index 78bdc4df0f8c..dc9c4725a39e 100644
--- a/heartbeat/docs/getting-started.asciidoc
+++ b/heartbeat/docs/getting-started.asciidoc
@@ -20,8 +20,7 @@ install, configure, and run Heartbeat:
 * <<load-kibana-dashboards>>
 * <<heartbeat-starting>>
 * <<view-kibana-dashboards>>
-* <<command-line-options>>
-* <<directory-layout>>
+* <<setup-repositories>>
 
 
 [[heartbeat-installation]]
diff --git a/libbeat/docs/config-file-format.asciidoc b/libbeat/docs/config-file-format.asciidoc
index 8f1f0dc03356..bc279cf1c146 100644
--- a/libbeat/docs/config-file-format.asciidoc
+++ b/libbeat/docs/config-file-format.asciidoc
@@ -58,6 +58,7 @@ The following topics provide more detail to help you understand and work with co
 * <<config-file-format-type>>
 * <<config-file-format-env-vars>>
 * <<config-gile-format-refs>>
+* <<config-file-permissions>>
 * <<config-file-format-cli>>
 * <<config-file-format-tips>>
 
diff --git a/libbeat/docs/shared-template-load.asciidoc b/libbeat/docs/shared-template-load.asciidoc
index adf653a73618..132b83f68637 100644
--- a/libbeat/docs/shared-template-load.asciidoc
+++ b/libbeat/docs/shared-template-load.asciidoc
@@ -105,9 +105,11 @@ PS > {beatname_lc} setup --template
 ----------------------------------------------------------------------
 
 
-NOTE: If you've already used {beatname_uc} to index data into Elasticsearch,
+[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
+you can delete the old documents from +{beatname_lc}-*+ to force Kibana to look
 at the newest documents. Use this command:
 
 ["source","sh",subs="attributes"]
@@ -115,6 +117,12 @@ at the newest documents. Use this command:
 curl -XDELETE 'http://localhost:9200/{beatname_lc}-*'
 ----------------------------------------------------------------------
 
+This command will delete all indexes that match the pattern +{beatname_lc}-*+.
+Before running this command, make sure you want to delete all indexes that
+match the pattern.
+
+=====
+
 [[passing-credentials-template-loading]]
 ==== Pass credentials
 
diff --git a/metricbeat/docs/configuring-howto.asciidoc b/metricbeat/docs/configuring-howto.asciidoc
index 2df113c9763f..d216fd0b168e 100644
--- a/metricbeat/docs/configuring-howto.asciidoc
+++ b/metricbeat/docs/configuring-howto.asciidoc
@@ -35,6 +35,7 @@ The following topics describe how to configure Metricbeat:
 * <<using-environ-vars>>
 * <<yaml-tips>>
 * <<regexp-support>>
+* <<{beatname_lc}-reference-yml>>
 
 --
 
diff --git a/metricbeat/docs/gettingstarted.asciidoc b/metricbeat/docs/gettingstarted.asciidoc
index 7fdd39fe2d7a..28237691132a 100644
--- a/metricbeat/docs/gettingstarted.asciidoc
+++ b/metricbeat/docs/gettingstarted.asciidoc
@@ -21,8 +21,7 @@ After installing the Elastic Stack, read the following topics to learn how to in
 * <<load-kibana-dashboards>>
 * <<metricbeat-starting>>
 * <<view-kibana-dashboards>>
-* <<command-line-options>>
-* <<directory-layout>>
+* <<setup-repositories>>
 
 [[metricbeat-installation]]
 === Step 1: Install Metricbeat
diff --git a/packetbeat/docs/configuring-howto.asciidoc b/packetbeat/docs/configuring-howto.asciidoc
index 018480bf84d2..8c66cff51638 100644
--- a/packetbeat/docs/configuring-howto.asciidoc
+++ b/packetbeat/docs/configuring-howto.asciidoc
@@ -37,6 +37,7 @@ The following topics describe how to configure Packetbeat:
 * <<configuration-logging>>
 * <<using-environ-vars>>
 * <<yaml-tips>>
+* <<{beatname_lc}-reference-yml>>
 
 --
 
diff --git a/packetbeat/docs/gettingstarted.asciidoc b/packetbeat/docs/gettingstarted.asciidoc
index f540213eb1bd..f709e2daefd0 100644
--- a/packetbeat/docs/gettingstarted.asciidoc
+++ b/packetbeat/docs/gettingstarted.asciidoc
@@ -20,8 +20,7 @@ After installing the Elastic Stack, read the following topics to learn how to in
 * <<load-kibana-dashboards>>
 * <<packetbeat-starting>>
 * <<view-kibana-dashboards>>
-* <<command-line-options>>
-* <<directory-layout>>
+* <<setup-repositories>>
 
 [[packetbeat-installation]]
 === Step 1: Install Packetbeat
diff --git a/winlogbeat/docs/configuring-howto.asciidoc b/winlogbeat/docs/configuring-howto.asciidoc
index dd1e94d27483..189f33c3b33c 100644
--- a/winlogbeat/docs/configuring-howto.asciidoc
+++ b/winlogbeat/docs/configuring-howto.asciidoc
@@ -31,6 +31,7 @@ The following topics describe how to configure Winlogbeat:
 * <<configuration-logging>>
 * <<using-environ-vars>>
 * <<yaml-tips>>
+* <<{beatname_lc}-reference-yml>>
 
 --
 
diff --git a/winlogbeat/docs/getting-started.asciidoc b/winlogbeat/docs/getting-started.asciidoc
index a1426efc9501..b9ead47789cf 100644
--- a/winlogbeat/docs/getting-started.asciidoc
+++ b/winlogbeat/docs/getting-started.asciidoc
@@ -20,8 +20,6 @@ After installing the Elastic Stack, read the following topics to learn how to in
 * <<load-kibana-dashboards>>
 * <<winlogbeat-starting>>
 * <<view-kibana-dashboards>>
-* <<command-line-options>>
-* <<directory-layout>>
 
 [[winlogbeat-installation]]
 === Step 1: Install Winlogbeat