// Module included in the following assemblies:
//
// * cicd/jenkins/images-other-jenkins.adoc

:_mod-docs-content-type: REFERENCE
[id="images-other-jenkins-env-var_{context}"]
= Jenkins environment variables

The Jenkins server can be configured with the following environment variables:

[options="header"]
|===
| Variable | Definition | Example values and settings

|`OPENSHIFT_ENABLE_OAUTH`
|Determines whether the {product-title} Login plugin manages authentication when logging in to Jenkins. To enable, set to `true`.
|Default: `false`

|`JENKINS_PASSWORD`
|The password for the `admin` user when using standard Jenkins authentication. Not applicable when `OPENSHIFT_ENABLE_OAUTH` is set to `true`.
|Default: `password`

|`JAVA_MAX_HEAP_PARAM`,
`CONTAINER_HEAP_PERCENT`,
`JENKINS_MAX_HEAP_UPPER_BOUND_MB`
|These values control the maximum heap size of the Jenkins JVM. If
`JAVA_MAX_HEAP_PARAM` is set, its value takes precedence. Otherwise, the maximum heap size is dynamically calculated as `CONTAINER_HEAP_PERCENT` of the container memory limit, optionally capped at `JENKINS_MAX_HEAP_UPPER_BOUND_MB` MiB.

By default, the maximum heap size of the Jenkins JVM is set to 50% of the container memory limit with no cap.
|`JAVA_MAX_HEAP_PARAM` example setting: `-Xmx512m`

`CONTAINER_HEAP_PERCENT` default: `0.5`, or 50%

`JENKINS_MAX_HEAP_UPPER_BOUND_MB` example setting: `512 MiB`

|`JAVA_INITIAL_HEAP_PARAM`,
`CONTAINER_INITIAL_PERCENT`
|These values control the initial heap size of the Jenkins JVM. If `JAVA_INITIAL_HEAP_PARAM` is set, its value takes precedence. Otherwise, the initial heap size is dynamically calculated as `CONTAINER_INITIAL_PERCENT` of the dynamically calculated maximum heap size.

By default, the JVM sets the initial heap size.
|`JAVA_INITIAL_HEAP_PARAM` example setting: `-Xms32m`

`CONTAINER_INITIAL_PERCENT` example setting: `0.1`, or 10%

|`CONTAINER_CORE_LIMIT`
|If set, specifies an integer number of cores used for sizing numbers of internal JVM threads.
|Example setting: `2`

|`JAVA_TOOL_OPTIONS`
|Specifies options to apply to all JVMs running in this container. It is not recommended to override this value.
|Default: `-XX:+UnlockExperimentalVMOptions -XX:+UseCGroupMemoryLimitForHeap -Dsun.zip.disableMemoryMapping=true`

|`JAVA_GC_OPTS`
|Specifies Jenkins JVM garbage collection parameters. It is not recommended to override this value.
|Default: `-XX:+UseParallelGC -XX:MinHeapFreeRatio=5 -XX:MaxHeapFreeRatio=10 -XX:GCTimeRatio=4 -XX:AdaptiveSizePolicyWeight=90`

|`JENKINS_JAVA_OVERRIDES`
|Specifies additional options for the Jenkins JVM. These options are appended to all other options, including the Java options above, and may be used to override any of them if necessary. Separate each additional option with a space; if any option contains space characters, escape them with a backslash.
|Example settings: `-Dfoo -Dbar`; `-Dfoo=first\ value -Dbar=second\ value`.

|`JENKINS_OPTS`
|Specifies arguments to Jenkins.
|

|`INSTALL_PLUGINS`
|Specifies additional Jenkins plugins to install when the container is first run or when `OVERRIDE_PV_PLUGINS_WITH_IMAGE_PLUGINS` is set to `true`. Plugins are specified as a comma-delimited list of name:version pairs.
|Example setting: `git:3.7.0,subversion:2.10.2`.

|`OPENSHIFT_PERMISSIONS_POLL_INTERVAL`
|Specifies the interval in milliseconds that the {product-title} Login plugin polls {product-title} for the permissions that are associated with each user that is defined in Jenkins.
|Default: `300000` - 5 minutes

|`OVERRIDE_PV_CONFIG_WITH_IMAGE_CONFIG`
|When running this image with 
ifndef::openshift-rosa,openshift-rosa-hcp[] 
an {product-title} 
endif::openshift-rosa,openshift-rosa-hcp[]
ifdef::openshift-rosa,openshift-rosa-hcp[]
an {product-title} 
endif::openshift-rosa,openshift-rosa-hcp[]
persistent volume (PV) for the Jenkins configuration directory, the transfer of configuration from the image to the PV is performed only the first time the image starts because the PV is assigned when the persistent volume claim (PVC) is created. If you create a custom image that extends this image and updates the configuration in the custom image after the initial startup, the configuration is not copied over unless you set this environment variable to `true`.
|Default: `false`

|`OVERRIDE_PV_PLUGINS_WITH_IMAGE_PLUGINS`
|When running this image with 
ifndef::openshift-rosa,openshift-rosa-hcp[] 
an {product-title} 
endif::openshift-rosa,openshift-rosa-hcp[]
ifdef::openshift-rosa,openshift-rosa-hcp[]
an {product-title} 
endif::openshift-rosa,openshift-rosa-hcp[]
PV for the Jenkins configuration directory, the transfer of plugins from the image to the PV is performed only the first time the image starts because the PV is assigned when the PVC is created. If you create a custom image that extends this image and updates plugins in the custom image after the initial startup, the plugins are not copied over unless you set this environment variable to `true`.
|Default: `false`

|`ENABLE_FATAL_ERROR_LOG_FILE`
|When running this image with 
ifndef::openshift-rosa,openshift-rosa-hcp[] 
an {product-title} 
endif::openshift-rosa,openshift-rosa-hcp[]
ifdef::openshift-rosa,openshift-rosa-hcp[]
an {product-title} 
endif::openshift-rosa,openshift-rosa-hcp[]
PVC for the Jenkins configuration directory, this environment variable allows the fatal error log file to persist when a fatal error occurs. The fatal error file is saved at `/var/lib/jenkins/logs`.
|Default: `false`

|`AGENT_BASE_IMAGE`
|Setting this value overrides the image used for the `jnlp` container in the sample Kubernetes plugin pod templates provided with this image. Otherwise, the image from the `jenkins-agent-base-rhel8:latest` image stream tag in the `openshift` namespace is used.
|Default:
`image-registry.openshift-image-registry.svc:5000/openshift/jenkins-agent-base-rhel8:latest`

|`JAVA_BUILDER_IMAGE`
|Setting this value overrides the image used for the `java-builder` container in the `java-builder` sample Kubernetes plugin pod templates provided with this image. Otherwise, the image from the `java:latest` image stream tag in the `openshift` namespace is used.
|Default:
`image-registry.openshift-image-registry.svc:5000/openshift/java:latest`

|`JAVA_FIPS_OPTIONS`
|Setting this value controls how the JVM operates when running on a FIPS node. For more information, see link:https://access.redhat.com/documentation/en-us/red_hat_build_of_openjdk/11/html-single/configuring_red_hat_build_of_openjdk_11_on_rhel_with_fips/index#config-fips-in-openjdk[Configure Red Hat build of OpenJDK 11 in FIPS mode].
|Default: `-Dcom.redhat.fips=false`

|===
