Initial Settings

Most Jenkins configuration changes can be made through the Jenkins user interface or through the configuration as code plugin. There are some configuration values that can only be modified while Jenkins is starting. This section describes those settings and how you can use them.

Jenkins Parameters

Jenkins initialization can also be controlled by run time parameters passed as arguments. Command line arguments can adjust networking, security, monitoring, and other settings.

Networking parameters

Jenkins networking configuration is generally controlled by command line arguments. The networking configuration areguments are:

Table 1. Jenkins Networking Command Line Parameters
Command Line Parameter	Description
`--httpPort=$HTTP_PORT`	Runs Jenkins listener on port $HTTP_PORT using standard http protocol. The default is port 8080. To disable (because you’re using https), use port `-1`. This option does not impact the root URL being generated within Jenkins logic (UI, inbound agent files, etc.). It is defined by the Jenkins URL specified in the global configuration.
`--httpListenAddress=$HTTP_HOST`	Binds Jenkins to the IP address represented by $HTTP_HOST. The default is 0.0.0.0 — i.e. listening on all available interfaces. For example, to only listen for requests from localhost, you could use: `--httpListenAddress=127.0.0.1`
`--httpsPort=$HTTPS_PORT`	Uses HTTPS protocol on port $HTTPS_PORT. This option does not impact the root URL being generated within Jenkins logic (UI, inbound agent files, etc.). It is defined by the Jenkins URL specified in the global configuration.
`--httpsListenAddress=$HTTPS_HOST`	Binds Jenkins to listen for HTTPS requests on the IP address represented by $HTTPS_HOST.
`--http2Port=$HTTP_PORT`	Uses HTTP/2 protocol on port $HTTP_PORT. This option does not impact the root URL being generated within Jenkins logic (UI, inbound agent files, etc.). It is defined by the Jenkins URL specified in the global configuration.
`--http2ListenAddress=$HTTPS_HOST`	Binds Jenkins to listen for HTTP/2 requests on the IP address represented by $HTTPS_HOST.
`--prefix=$PREFIX`	Runs Jenkins to include the $PREFIX at the end of the URL. For example, set --prefix=/jenkins to make Jenkins accessible at http://myServer:8080/jenkins
`--sessionTimeout=$TIMEOUT`	Sets the http session timeout value to $SESSION_TIMEOUT minutes. Default to what webapp specifies, and then to 60 minutes

Miscellaneous parameters

Other Jenkins initialization configuration is also controlled by command line arguments. The miscellaneous configuration arguments are:

Table 2. Jenkins Miscellaneous Command Line Parameters
Command Line Parameter	Description
`--argumentsRealm.passwd.$USER=$PASS`	Assigns the password for user $USER. If Jenkins security is enabled, you must log in as a user who has an admin role to configure Jenkins.
`--argumentsRealm.roles.$USER=admin`	Assigns user $USER the admin role. The user can configure Jenkins even if security is enabled in Jenkins. See Securing Jenkins for more information.
`--useJmx`	Enable Jetty Java Management Extension (JMX)

Jenkins passes all command line parameters to the Winstone servlet container. More information about Jenkins Winstone command line parameters is available from the Winstone Command Line Parameter Reference.

Be Careful with Command Line Parameters
Jenkins ignores command line parameters it doesn’t understand instead of producing an error. Be careful when using command line parameters and make sure you have the correct spelling. For example, the parameter needed for defining the Jenkins administrative user is --argumentsRealm and not --argumentRealm.

Jenkins properties

Some Jenkins behaviors are configured with Java properties. Java properties are set from the command line that started Jenkins. Property assignments use the form -DsomeName=someValue to assign the value someValue to the property named someName. For example, to assign the value true to a property testName, the command line argument would be -DtestName=true.

Refer to the detailed list of Jenkins properties for more information.

Configuring HTTP

HTTPS with an existing certificate

If you’re setting up Jenkins using the built-in Winstone server and want to use an existing certificate for HTTPS:

--httpPort=-1 \
--httpsPort=443 \
--httpsKeyStore=path/to/keystore \
--httpsKeyStorePassword=keystorePassword

The keystore should be in JKS format (as created by the JDK 'keytool') and the keystore and target key must have the same password. (Placing the keystore arguments after Jenkins-specific parameters does not seem to work; either they are not forwarded to Winstone or Winstone ignores them coming after unknown parameters. So, make sure they are adjacent to the working --httpsPort argument.)

If your keystore contains multiple certificates (e.g. you are using CA signed certificate) Jenkins might end-up using a incorrect one. In this case you can convert the keystore to PEM and use following command line options:

--httpPort=-1 \
--httpsPort=443 \
--httpsCertificate=path/to/cert \
--httpsPrivateKey=path/to/privatekey

Using HTTP/2

The HTTP/2 protocol allows web servers to reduce latency over encrypted connections by pipelining requests, multiplexing requests, and allowing servers to push in some cases before receiving a client request for the data. The Jetty server used by Jenkins supports HTTP/2 with the addition of the Application-Layer Protocol Negotiation (ALPN) TLS extension. The ALPN TLS extension is connected to the specific Jetty version and has specific requirements depending on the Java version.

Note that enabling HTTP/2 implicitly enables TLS even if no HTTPS port is set, and as of Jenkins 2.339 (which uses Winstone 5.23) you have to also specify an HTTPS key store file.

Java 11, Java 8u252, and later

Java 11, Java 8 update 252 and Java 8 versions after update 252 can run the ALPN TLS extension by installing the Jetty ALPN java server jar and passing it as a java command line argument. Steps to install the extension are:

Identify the Jetty version included in your Jenkins server by searching the Jenkins startup log for the string org.eclipse.jetty.server.Server#doStart. For example:
org.eclipse.jetty.server.Server#doStart: jetty-9.4.27.v20200227
Locate the Java version on the "System Information" page of "Manage Jenkins" to confirm it is Java 11 or 8u252 (or later)
Download the jetty-alpn-java-server with the version number matching the Jetty version bundled with your Jenkins version
Place the jetty-alpn-java-server.jar file in a directory accessible to the JVM
Add --extraLibFolder=/path/to/extra/lib/folder to the Java command line arguments that start Jenkins

java --extraLibFolder=/opt/java/jetty-alpn-java-server-9.4.27.v20200227.jar \
    -jar target/jenkins.war \
    --http2Port=9090 \
    --httpsKeyStore=path/to/keystore \
    --httpsKeyStorePassword=keystorePassword

Java 8u242 and earlier

Java 8 update 242 and earlier can run the ALPN TLS extension by installing the Jetty ALPN boot library corresponding to the exact OpenJDK version you are using into the Java boot classpath. Steps to install the extension are:

Identify the Java version running your Jenkins server from the "Manage Jenkins" → "System Information" page
Find the boot library for your OpenJDK version
Download the matching alpn-boot.jar file to a directory accessible to the JVM
Add the alpn-boot.jar to the JVM boot classpath by adding -Xbootclasspath/p:/path/to/alpn-boot.jar to the Java command line arguments that start Jenkins

java -Xbootclasspath/p:/opt/java/alpn-boot-8.1.13.v20181017.jar \
    -jar target/jenkins.war \
    --http2Port=9090 \
    --httpsKeyStore=path/to/keystore \
    --httpsKeyStorePassword=keystorePassword

HTTPS certificates with Windows

These instructions use a stock Jenkins installation on Windows Server. The instructions assume a certificate signed by a Certificate Authority such as Digicert. If you are making your own certificate skip steps 3, 4, and 5.

This process utilizes Java’s keytool. Use the Java keytool included with your Java installation.

Step 1: Create a new keystore on your server. This will place a 'keystore' file in your current directory.

C:\>keytool -genkeypair -keysize 2048 -keyalg RSA -alias jenkins -keystore keystore
Enter keystore password:
Re-enter new password:
What is your first and last name?
[Unknown]: server.example.com
What is the name of your organizational unit?
[Unknown]: A Unit
What is the name of your organization?
[Unknown]: A Company
What is the name of your City or Locality?
[Unknown]: A City
What is the name of your State or Province?
[Unknown]: A State
What is the two-letter country code for this unit?
[Unknown]: US
Is CN=server.example.com, OU=A Unit, O=A Company, L=A City, ST=A State, C=US correct?
[no]: yes

Enter key password for <jenkins>
(RETURN if same as keystore password):

Step 2: Verify the keystore was created (your fingerprint will vary)

C:\>keytool -list -keystore keystore
Enter keystore password:

Keystore type: JKS
Keystore provider: SUN

Your keystore contains 1 entry

jenkins, May 6, 2015, PrivateKeyEntry,
Certificate fingerprint (SHA1): AA:AA:AA:AA:AA:AA:AA:AA:AA:AA ...

Step 3: Create the certificate request. This will create a 'certreq.csr' file in your current directory.

C:\>keytool -certreq -alias jenkins -keyalg RSA ^
-file certreq.csr ^
-ext SAN=dns:server-name,dns:server-name.your.company.com ^
-keystore keystore
Enter keystore password:

Step 4: Use the contents of the certreq.csr file to generate a certificate from your certificate provider. Request a SHA-1 certificate (SHA-2 is untested but will likely work). If using DigiCert, download the resulting certificate as Other format "a .p7b bundle of all the certs in a .p7b file".

Step 5: Add the resulting .p7b into the keystore you created above.

C:\>keytool -import ^
-alias jenkins ^
-trustcacerts ^
-file response_from_digicert.p7b ^
-keystore keystore
Enter keystore password:
Certificate reply was installed in keystore

Step 6: Copy the 'keystore' file to your Jenkins secrets directory. On a stock installation, this will be at

C:\Program Files (x86)\Jenkins\secrets

Step 7: Modify the <arguments> section of your C:\Program Files (x86)\Jenkins\jenkins.xml file to reflect the new certificate. Note: This example disables http via --httpPort=-1 and places the server on 8443 via --httpsPort=8443.

<arguments>
  -Xrs
  -Xmx256m
  -Dhudson.lifecycle=hudson.lifecycle.WindowsServiceLifecycle
  -jar "%BASE%\jenkins.war"
  --httpPort=-1
  --httpsPort=8443
  --httpsKeyStore="%BASE%\secrets\keystore"
  --httpsKeyStorePassword=your.password.here
</arguments>

Step 8: Restart the jenkins service to initialize the new configuration.

net stop jenkins
net start jenkins

Step 9: After 30-60 seconds, Jenkins will have completed the startup process and you should be able to access the website at https://server.example.com:8443. Verify the certificate looks good via your browser’s tools. If the service terminates immediately, there’s an error somewhere in your configuration. Useful error information can be found in:

C:\Program Files (x86)\Jenkins\jenkins.err.log
C:\Program Files (x86)\Jenkins\jenkins.out.log

User Handbook

Tutorials

Resources