mirror of
https://github.com/elastic/logstash.git
synced 2025-04-24 14:47:19 -04:00
161 lines
8.2 KiB
Text
161 lines
8.2 KiB
Text
[[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 }
|
|
}
|
|
-----
|