Running Logstash on Windows

edit

Before reading this section, see Installing Logstash to get started. You also need to be familiar with Running Logstash from the Command Line as command line options are used to test running Logstash on Windows.

Specifying command line options is useful when you are testing Logstash. However, in a production environment, we recommend that you use logstash.yml 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 NSSM), or run it as a scheduled task. This guide provides an example of some of the ways Logstash can run on Windows.

It is recommended to validate your configuration works by running Logstash manually before running Logstash as a service or a scheduled task.

Validating JVM Pre-Requisites on Windows

edit

After installing a supported JVM, open a PowerShell session and run the following commands to verify JAVA_HOME is set and the Java version:

Write-Host $env:JAVA_HOME

edit
  • The output should be pointed to where the JVM software is located, for example:

    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 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 SETX commands:

        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

edit
  • This command produces output similar to the following:

    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)

As of the publication of this document, please review this known issue that impacts Java 11 before proceeding.

Once you have Setting Up and Running Logstash and validated JVM pre-requisites, you may proceed.

For the examples listed below, we are running Windows Server 2016, Java 11.0.3, have extracted the Logstash ZIP package to C:\logstash-6.5.4\, and using the example syslog.conf file shown below (stored in C:\logstash-6.5.4\config\).

Running Logstash manually

edit

Logstash can be run manually using PowerShell. Open an Administrative PowerShell session, then run the following commands:

PS C:\Windows\system32> cd C:\logstash-6.5.4\
PS C:\logstash-6.5.4> .\bin\logstash.bat -f .\config\syslog.conf

In a production environment, we recommend that you use logstash.yml to control Logstash execution.

Wait for the following messages to appear, to confirm Logstash has started successfully:

[logstash.runner          ] Starting Logstash {"logstash.version"=>"6.5.4"}
[logstash.inputs.udp      ] Starting UDP listener {:address=>"0.0.0.0:514"}
[logstash.agent           ] Successfully started Logstash API endpoint {:port=>9600}

Running Logstash as a service with NSSM

edit

It is recommended to validate your configuration works by running Logstash manually before you proceed.

Download NSSM, then extract nssm.exe from nssm-<version.number>\win64\nssm.exe to C:\logstash-6.5.4\bin\. Then open an Administrative PowerShell session, then run the following commands:

PS C:\Windows\system32> cd C:\logstash-6.5.4\
PS C:\logstash-6.5.4> .\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-6.5.4\bin\logstash.bat
    • Startup Directory: Path to the bin directory: C:\logstash-6.5.4\bin
    • Arguments: For this example to start Logstash: -f C:\logstash-6.5.4\config\syslog.conf

      In a production environment, we recommend that you use logstash.yml 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 PowerShell Managing Services documentation.

Running Logstash with Task Scheduler

edit

It is recommended to validate your configuration works by running Logstash manually before you proceed.

Open the Windows 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-6.5.4\bin\logstash.bat
    • Add arguments: -f C:\logstash-6.5.4\config\syslog.conf
    • Start in: C:\logstash-6.5.4\bin\

      In a production environment, we recommend that you use logstash.yml 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.

Logstash can be stopped by selecting the service, then clicking End in the Task Scheduler window.

Example Logstash Configuration

edit

We will configure Logstash to listen for syslog messages over port 514 with this configuration (file name is syslog.conf):

# 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 }
}