diff --git a/docs/static/running-logstash-command-line.asciidoc b/docs/static/running-logstash-command-line.asciidoc index b5cd5219a..a177ddab1 100644 --- a/docs/static/running-logstash-command-line.asciidoc +++ b/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 <> flags that you can specify to control Logstash execution. The location of the `bin` directory varies by platform. See <> to find the location of `bin\logstash` on diff --git a/docs/static/running-logstash-windows.asciidoc b/docs/static/running-logstash-windows.asciidoc index 443d22c0a..79ecc4222 100644 --- a/docs/static/running-logstash-windows.asciidoc +++ b/docs/static/running-logstash-windows.asciidoc @@ -1,3 +1,153 @@ [[running-logstash-windows]] === Running Logstash on Windows -Coming soon! +Before reading this section, see <> to get started. You also need to be familiar with <> 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 <> 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 <> 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 <> 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-\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 <> 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 <> 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 } +} +-----