Initial Settings
This site is the new docs site currently being tested. For the actual docs in use please go to https://www.jenkins.io/doc. |
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 arguments are:
Command Line Parameter | Description |
---|---|
|
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 |
|
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:
|
|
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. |
|
Binds Jenkins to listen for HTTPS requests on the IP address represented by $HTTPS_HOST. |
|
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. |
|
Binds Jenkins to listen for HTTP/2 requests on the IP address represented by $HTTPS_HOST. |
|
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 |
|
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 options are also controlled by command line arguments. The miscellaneous configuration arguments are:
Command Line Parameter | Description |
---|---|
|
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. |
|
Assigns user $USER the admin role. The user can configure Jenkins even if security is enabled in Jenkins. Refer to Securing Jenkins for more information. |
|
Reads parameters from standard input (stdin).
When parameters are passed via the command line, they can be viewed using |
|
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
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.
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. |
--httpPort=-1 \
--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