Update getting started to include info about credentials and new comm…

…and syntax (elastic#4841)

* Update getting started to include info about credentials and new command syntax

* Add fixes from review

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

filebeat/docs/getting-started.asciidoc

@@ -202,6 +202,8 @@ configure the Logstash output in <<config-filebeat-logstash>>.
 
 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
 

filebeat/docs/modules-getting-started.asciidoc

@@ -47,62 +47,57 @@ 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.
 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,15 +114,24 @@ logs:
 See the <<modules-tutorial>> 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,
 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]

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 <<command-line-options>>). 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
 

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[]

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.

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.

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

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:

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[]
+

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 <<command-line-options,command line>> (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 <<setup-kibana-endpoint>> and
+<<elasticsearch-output,Configure the Elasticsearch output>>.

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 <<setup-kibana-endpoint>> if you are
-connecting to a secured instance of Kibana.
-
 --

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 <<directory-layout>>),
 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"]