Document running Logstash on Windows (#10805)

* Create running-logstash-windows.asciidoc
Initial commit for #4005

* Update running-logstash-windows
1. Added section to validate JVM pre-requisites and shell sections for nssm, task scheduler, and PowerShell
2. Updated options to run Logstash on Windows, update section headers
3. Clarified JVM pre-requisites and included example to add environmental variables using SETX
4. Added example Logstash configuration, added steps for running Logstash manually with PowerShell
5. Removed `WIP` from the PowerShell section; updated the example to include output to Elasticsearch; Added notes for running Logstash as a service with NSSM
6. Removed `WIP` from the NSSM section; Added notes for running Logstash as a Scheduled Task; Added notes to stopping Logstash for each section; Removed `WIP` from the Scheduled Task section; Removed `WIP` from the page header
7. Updated initial section; moved the running manually section as the first configuration; added notes to the NSSM and Schedule Task sections.
8. Push headings down one level
9. Clarify this document contains examples for running Logstash on Windows.  Updated which NSSM file should be extracted for use.
10. Updated formatting for the example Logstash configuration
11. Update formatting for the command examples
12. Update the instructions in the Task Scheduler section
13. Update the instructions in the run Logstash manually section, the NSSM section, and update formatting
14. Update formatting
15. Add note regarding support for running multiple pipelines
16. Clarify use of command line options.  Re-state what is mentioned in the `Running Logstash from the Command Line` doc that: "Specifying command line options is useful when you are testing Logstash. However, in a production environment, we recommend that you use [logstash-settings-file] to control Logstash execution."
17. Clarify steps to accessing the Windows Environmental Variables window (i.e., link to Microsoft docs).
18. Remove unnecessary plus signs
19. Updated source types for examples, updated documents for specific Logstash versions with `{logstash_version}`

* Update running-logstash-command-line
1. Add note for running Logstash on Windows with `bin\logstash.bat`
2. Update formatting for running Logstash from the Windows command line

Fixes #10946

docs/static/running-logstash-command-line.asciidoc

@@ -8,6 +8,13 @@ To run Logstash from the command line, use the following command:
 bin/logstash [options]
 ----
 
+To run Logstash from the Windows command line, use the following command:
+
+[source,shell]
+----
+bin/logstash.bat [options]
+----
+
 Where `options` are <<command-line-flags,command-line>> flags that you can
 specify to control Logstash execution. The location of the `bin` directory
 varies by platform. See <<dir-layout>> to find the location of `bin\logstash` on

docs/static/running-logstash-windows.asciidoc

@@ -1,3 +1,153 @@
 [[running-logstash-windows]]
 === Running Logstash on Windows
-Coming soon!
+Before reading this section, see <<installing-logstash>> to get started.  You also need to be familiar with <<running-logstash-command-line>> as command line options are used to test running Logstash on Windows.
+
+IMPORTANT: Specifying command line options is useful when you are testing Logstash. However, in a production environment, we recommend that you use <<logstash-settings-file>> to control Logstash execution. Using the settings file makes it easier for you to specify multiple options, and it provides you with a single, versionable file that you can use to start up Logstash consistently for each run.
+
+Logstash is not started automatically after installation. How to start and stop Logstash on Windows depends on whether you want to run it manually, as a service (with https://nssm.cc/[NSSM]), or run it as a scheduled task. This guide provides an example of some of the ways Logstash can run on Windows.
+
+NOTE: It is recommended to validate your configuration works by running Logstash manually before running Logstash as a service or a scheduled task.
+
+[[running-logstash-windows-validation]]
+==== Validating JVM Pre-Requisites on Windows
+After installing a https://www.elastic.co/support/matrix#matrix_jvm[supported JVM], open a https://docs.microsoft.com/en-us/powershell/[PowerShell] session and run the following commands to verify `JAVA_HOME` is set and the Java version:
+
+===== `Write-Host $env:JAVA_HOME`
+** The output should be pointed to where the JVM software is located, for example:
++
+[source,sh]
+-----
+PS C:\> Write-Host $env:JAVA_HOME
+C:\Program Files\Java\jdk-11.0.3
+-----
+
+** If `JAVA_HOME` is not set, perform one of the following:
+*** Set using the GUI:
+**** Navigate to the Windows https://docs.microsoft.com/en-us/windows/win32/procthread/environment-variables[Environmental Variables] window
+**** In the Environmental Variables window, edit JAVA_HOME to point to where the JDK software is located, for example: `C:\Program Files\Java\jdk-11.0.3`
+*** Set using PowerShell:
+**** In an Administrative PowerShell session, execute the following `https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/setx[SETX]` commands:
++
+[source,sh]
+-----
+PS C:\Windows\system32> SETX /m JAVA_HOME "C:\Program Files\Java\jdk-11.0.3"
+PS C:\Windows\system32> SETX /m PATH "$env:PATH;C:\Program Files\Java\jdk-11.0.3\bin;"
+-----
+**** Exit PowerShell, then open a new PowerShell session and run `Write-Host $env:JAVA_HOME` to verify
+
+===== `Java -version`
+** This command produces output similar to the following:
++
+[source,sh]
+-----
+PS C:\> Java -version
+java version "11.0.3" 2019-04-16 LTS
+Java(TM) SE Runtime Environment 18.9 (build 11.0.3+12-LTS)
+Java HotSpot(TM) 64-Bit Server VM 18.9 (build 11.0.3+12-LTS, mixed mode)
+-----
+
+NOTE: As of the publication of this document, please review this https://github.com/elastic/logstash/issues/10496[known issue that impacts Java 11] before proceeding.
+
+Once you have <<setup-logstash>> and validated JVM pre-requisites, you may proceed.  
+
+NOTE: For the examples listed below, we are running Windows Server 2016, Java 11.0.3, have extracted the https://www.elastic.co/downloads/logstash[Logstash ZIP package] to `C:\logstash-{logstash_version}\`, and using the example `syslog.conf` file shown below (stored in `C:\logstash-{logstash_version}\config\`).
+
+[[running-logstash-windows-manual]]
+==== Running Logstash manually
+Logstash can be run manually using https://docs.microsoft.com/en-us/powershell/[PowerShell].  Open an Administrative https://docs.microsoft.com/en-us/powershell/[PowerShell] session, then run the following commands:
+
+["source","sh",subs="attributes"]
+-----
+PS C:\Windows\system32> cd C:\logstash-{logstash_version}\
+PS C:\logstash-{logstash_version}> .\bin\logstash.bat -f .\config\syslog.conf
+-----
+
+NOTE: In a production environment, we recommend that you use <<logstash-settings-file>> to control Logstash execution.
+
+Wait for the following messages to appear, to confirm Logstash has started successfully:
+
+["source","sh",subs="attributes"]
+-----
+[logstash.runner          ] Starting Logstash {"logstash.version"=>"{logstash_version}"}
+[logstash.inputs.udp      ] Starting UDP listener {:address=>"0.0.0.0:514"}
+[logstash.agent           ] Successfully started Logstash API endpoint {:port=>9600}
+-----
+
+[[running-logstash-windows-nssm]]
+==== Running Logstash as a service with NSSM
+NOTE: It is recommended to validate your configuration works by running Logstash manually before you proceed.
+
+Download https://nssm.cc/[NSSM], then extract `nssm.exe` from `nssm-<version.number>\win64\nssm.exe` to `C:\logstash-{logstash_version}\bin\`.  Then open an Administrative https://docs.microsoft.com/en-us/powershell/[PowerShell] session, then run the following commands:
+
+["source","sh",subs="attributes"]
+-----
+PS C:\Windows\system32> cd C:\logstash-{logstash_version}\
+PS C:\logstash-{logstash_version}> .\bin\nssm.exe install logstash
+-----
+
+Once the `NSSM service installer` window appears, specify the following parameters in the `Application` tab:
+
+** In the `Application` tab:
+*** Path: Path to `logstash.bat`: `C:\logstash-{logstash_version}\bin\logstash.bat`
+*** Startup Directory: Path to the `bin` directory: `C:\logstash-{logstash_version}\bin`
+*** Arguments: For this example to start Logstash: `-f C:\logstash-{logstash_version}\config\syslog.conf`
++
+NOTE: In a production environment, we recommend that you use <<logstash-settings-file>> to control Logstash execution.
+
+** Review and make any changes necessary in the `Details` tab:
+*** Ensure `Startup Type` is set appropriately
+*** Set the `Display name` and `Description` fields to something relevant
+
+** Review any other required settings (for the example we aren't making any other changes)
+*** Be sure to determine if you need to set the `Log on` user
+** Validate the `Service name` is set appropriately
+*** For this example, we will set ours to `logstash-syslog`
+
+** Click `Install Service`
+*** Click 'OK' when the `Service "logstash-syslog" installed successfully!` window appears
+
+Once the service has been installed with NSSM, validate and start the service following the https://docs.microsoft.com/en-us/powershell/scripting/samples/managing-services[PowerShell Managing Services] documentation.
+
+[[running-logstash-windows-scheduledtask]]
+==== Running Logstash with Task Scheduler
+NOTE: It is recommended to validate your configuration works by running Logstash manually before you proceed.
+
+Open the Windows https://docs.microsoft.com/en-us/windows/desktop/taskschd/task-scheduler-start-page[Task Scheduler], then click `Create Task` in the Actions window.  Specify the following parameters in the `Actions` tab:
+
+** In the `Actions` tab:
+*** Click `New`, then specify the following:
+*** Action: `Start a program`
+*** Program/script: `C:\logstash-{logstash_version}\bin\logstash.bat`
+*** Add arguments: `-f C:\logstash-{logstash_version}\config\syslog.conf`
++
+NOTE: In a production environment, we recommend that you use <<logstash-settings-file>> to control Logstash execution.
+*** Start in: C:\logstash-{logstash_version}\bin\
+
+** Review and make any changes necessary in the `General`, `Triggers`, `Conditions`, and `Settings` tabs.
+
+** Click `OK` to finish creating the scheduled task.
+
+** Once the new task has been created, either wait for it to run on the schedule or select the service then click `Run` to start the task.
+
+NOTE: Logstash can be stopped by selecting the service, then clicking `End` in the Task Scheduler window.
+
+[[running-logstash-windows-example]]
+==== Example Logstash Configuration
+We will configure Logstash to listen for syslog messages over port 514 with this configuration (file name is `syslog.conf`):
+[source,yaml]
+-----
+# Sample Logstash configuration for receiving
+# UDP syslog messages over port 514
+
+input {
+  udp {
+    port => 514
+    type => "syslog"
+  }
+}
+
+output {
+  elasticsearch { hosts => ["localhost:9200"] }
+  stdout { codec => rubydebug }
+}
+-----