[[running-logstash-windows]]
=== Running Logstash on Windows
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:{backslash}logstash-{logstash_version}{backslash}+, and using the example
`syslog.conf` file shown below (stored in
+C:{backslash}logstash-{logstash_version}{backslash}config{backslash}+).

[[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:{backslash}Windows{backslash}system32> cd C:{backslash}logstash-{logstash_version}{backslash}
PS C:{backslash}logstash-{logstash_version}> .{backslash}bin{backslash}logstash.bat -f .{backslash}config{backslash}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:{backslash}logstash-{logstash_version}{backslash}bin{backslash}+.
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:{backslash}logstash-{logstash_version}{backslash}
PS C:{backslash}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:{backslash}logstash-{logstash_version}{backslash}bin{backslash}logstash.bat+
*** Startup Directory: Path to the `bin` directory: +C:{backslash}logstash-{logstash_version}{backslash}bin+
*** Arguments: For this example to start Logstash: +-f C:{backslash}logstash-{logstash_version}{backslash}config{backslash}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:{backslash}logstash-{logstash_version}{backslash}bin{backslash}logstash.bat+
*** Add arguments: +-f C:\logstash-{logstash_version}{backslash}config{backslash}syslog.conf+
*** Start in: +C:{backslash}logstash-{logstash_version}{backslash}bin{backslash}+
+
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 `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 }
}
-----
