[float]
[[ls-jvm]]
=== Java (JVM) version

{ls} requires one of these versions:

* Java 11
* Java 17 (see <<jdk17-upgrade>> for settings info)

Use the
http://www.oracle.com/technetwork/java/javase/downloads/index.html[official
Oracle distribution] or an open-source distribution, such as
http://openjdk.java.net/[OpenJDK].
See the https://www.elastic.co/support/matrix#matrix_jvm[Elastic Support Matrix]
for the official word on supported versions across releases.

[[bundled-jdk]]
.Bundled JDK
[NOTE]
===== 
{ls} offers architecture-specific
https://www.elastic.co/downloads/logstash[downloads] that include
Adoptium Eclipse Temurin 11, the latest long term support (LTS) release of the JDK.

Use the LS_JAVA_HOME environment variable if you want to use a JDK other than the
version that is bundled. 
If you have the LS_JAVA_HOME environment variable set to use a custom JDK, Logstash
will continue to use the JDK version you have specified, even after you upgrade.
=====

[float]
[[check-jvm]]
==== Check your Java version
Run the following command:

[source,shell]
java -version

On systems with Java installed, this command produces output similar to the following:

[source,shell]
-----
java version "11.0.1" 2018-10-16 LTS
Java(TM) SE Runtime Environment 18.9 (build 11.0.1+13-LTS)
Java HotSpot(TM) 64-Bit Server VM 18.9 (build 11.0.1+13-LTS, mixed mode)
-----

[float]
[[java-home]]
==== `LS_JAVA_HOME`

{ls} includes a bundled JDK which has been verified to work with each specific version 
of {ls}, and generally provides the best performance and reliability. 
If you need to use a JDK other than the bundled version, then set the `LS_JAVA_HOME` 
environment variable to the version you want to use.


On some Linux systems, you may need to have the `LS_JAVA_HOME` environment
exported before installing {ls}, particularly if you installed Java from
a tarball. 
{ls} uses Java during installation to automatically detect your environment and
install the correct startup method (SysV init scripts, Upstart, or systemd). If
{ls} is unable to find the `LS_JAVA_HOME` environment variable during package
installation, you may get an error message, and {ls} will not start properly.

[float]
[[jdk17-upgrade]]
==== Using JDK 17

{ls} supports JDK 17, but you need to update settings in `jvm.options` and
`log4j2.properties` if you are upgrading from  {ls} 7.11.x (or earlier) to 7.12 or later.


[float]
===== Updates to `jvm.options`
In the `config/jvm.options` file, remove all CMS related flags:

[source,shell]
-----
## GC configuration
-XX:+UseConcMarkSweepGC
-XX:CMSInitiatingOccupancyFraction=75
-XX:+UseCMSInitiatingOccupancyOnly
-----

For more information about how to use `jvm.options`, please refer to <<jvm-settings>>.

[float]
===== Updates to `log4j2.properties`
In the `config/log4j2.properties`:

* Replace properties that start with `appender.rolling.avoid_pipelined_filter.*` with: 
+
[source,shell]
-----
appender.rolling.avoid_pipelined_filter.type = PipelineRoutingFilter
-----

* Replace properties that start with `appender.json_rolling.avoid_pipelined_filter.*` with:
[source,shell]
+
-----
appender.json_rolling.avoid_pipelined_filter.type = PipelineRoutingFilter
-----

* Replace properties that start with `appender.routing.*` with:
[source,shell]
+
-----
appender.routing.type = PipelineRouting
appender.routing.name = pipeline_routing_appender
appender.routing.pipeline.type = RollingFile
appender.routing.pipeline.name = appender-${ctx:pipeline.id}
appender.routing.pipeline.fileName = ${sys:ls.logs}/pipeline_${ctx:pipeline.id}.log
appender.routing.pipeline.filePattern = ${sys:ls.logs}/pipeline_${ctx:pipeline.id}.%i.log.gz
appender.routing.pipeline.layout.type = PatternLayout
appender.routing.pipeline.layout.pattern = [%d{ISO8601}][%-5p][%-25c] %m%n
appender.routing.pipeline.policy.type = SizeBasedTriggeringPolicy
appender.routing.pipeline.policy.size = 100MB
appender.routing.pipeline.strategy.type = DefaultRolloverStrategy
appender.routing.pipeline.strategy.max = 30
-----