Welcome to Knowledge Base!

KB at your finger tips

This is one stop global knowledge base where you can learn about all the products, solutions and support features.

DevOps-Jenkins

User Handbook Overview

This page provides an overview of the documentation in the Jenkins User Handbook.

If you want to get up and running with Jenkins, see Installing Jenkins for procedures on how to install Jenkins on your supported platform of choice.

If you are a typical Jenkins user (of any skill level) who wants to know more about Jenkins usage, see Using Jenkins. Also refer to the separate Pipeline and Blue Ocean chapters for more information about these core Jenkins features.

If you are a Jenkins administrator and want to know more about managing Jenkins nodes and instances, see Managing Jenkins.

If you are a system administrator and want to learn how to back-up, restore, maintain as Jenkins servers and nodes, see Jenkins System Administration.

Index

Installing Jenkins â

Was this page helpful?

Please submit your feedback about this page through this quick form.

Alternatively, if you don't wish to complete the quick form, you can simply indicate if you found this page helpful?

See existing feedback here.

Glossary

â Troubleshooting Jenkins

Index

Glossary

Table of Contents

General Terms
Build Status

General Terms

Agent: An agent is typically a machine, or container, which connects to a Jenkins controller and executes tasks when directed by the controller.
Artifact: An immutable file generated during a Build or Pipeline run which is archived onto the Jenkins Controller for later retrieval by users.
Build: Result of a single execution of a job
Cloud: A System Configuration which provides dynamic Agent provisioning and allocation, such as that provided by the Azure VM Agents or Amazon EC2 plugins.
Controller: The central, coordinating process which stores configuration, loads plugins, and renders the various user interfaces for Jenkins.
Core: The primary Jenkins application ( jenkins.war ) which provides the basic web UI, configuration, and foundation upon which Plugins can be built.
Downstream: A configured Pipeline or job which is triggered as part of the execution of a separate Pipeline or Job.
Executor: A slot for execution of work defined by a Pipeline or job on a Node. A Node may have zero or more Executors configured which corresponds to how many concurrent Jobs or Pipelines are able to execute on that Node.
Fingerprint: A hash considered globally unique to track the usage of an Artifact or other entity across multiple Pipelines or jobs.
Folder: An organizational container for Pipelines and/or jobs, similar to folders on a file system.
Item: An entity in the web UI corresponding to either a: Folder, Pipeline, or job.
Jenkins URL: The main url for the jenkins application, as visited by a user. e.g. https://ci.jenkins.io/
Job: A user-configured description of work which Jenkins should perform, such as building a piece of software, etc.
Kubernetes: Kubernetes (K8s) is an open-source system for automating deployment, scaling, and management of containerized applications. See Installing Jenkins / Kubernetes for more info.
Label: User-defined text for grouping Agents, typically by similar functionality or capability. For example linux for Linux-based agents or docker for Docker-capable agents.
LTS: A long-term support Release line of Jenkins products, becoming available for downloads every 12 weeks. See this page for more info.
Master: A deprecated term, synonymous with Controller.
Node: A machine which is part of the Jenkins environment and capable of executing Pipelines or jobs. Both the Controller and Agents are considered to be Nodes.
Project: A deprecated term, synonymous with job.
Pipeline: A user-defined model of a continuous delivery pipeline, for more read the Pipeline chapter in this handbook.
Plugin: An extension to Jenkins functionality provided separately from Jenkins Core.
Publisher: Part of a Build after the completion of all configured Steps which publishes reports, sends notifications, etc. A publisher may report Stable or Unstable result depending on the result of its processing and its configuration. For example, if a JUnit test fails, then the whole JUnit publisher may report the build result as Unstable.
Resource Root URL: A secondary url used to serve potentially untrusted content (especially build artifacts). This url is distinct from the Jenkins URL.
Release: An event, indicating availability of Jenkins distribution products or one of Jenkins plugins. Jenkins products belong either to LTS or weekly Release lines.
Stage: stage is part of Pipeline, and used for defining a conceptually distinct subset of the entire Pipeline, for example: "Build", "Test", and "Deploy", which is used by many plugins to visualize or present Jenkins Pipeline status/progress.
Step: A single task; fundamentally steps tell Jenkins what to do inside of a Pipeline or job. See Pipelines / Getting Started and Pipeline / Using a jenkinsfile for more info.
Trigger: A criteria for triggering a new Pipeline run or job.
Update Center: Hosted inventory of plugins and plugin metadata to enable plugin installation from within Jenkins.
Upstream: A configured Pipeline or job which triggers a separate Pipeline or Job as part of its execution.
View: A way of displaying the data of Jenkins in a dashboard style. This is an extensible object, so there are lots of different ways to list jobs, show trends, and analyze data.
Workspace: A disposable directory on the file system of a Node where work can be done by a Pipeline or job. Workspaces are typically left in place after a Build or Pipeline run completes unless specific Workspace cleanup policies have been put in place on the Jenkins Controller.

Build Status

Aborted: The Build was interrupted before it reaches its expected end. For example, the user has stopped it manually or there was a time-out.
Failed: The Build had a fatal error.
Stable: The Build was Successful and no Publisher reports it as Unstable.
Successful: The Build has no compilation errors.
Unstable: The Build had some errors but they were not fatal. A Build is unstable if it was built successfully and one or more publishers report it unstable. For example if the JUnit publisher is configured and a test fails then the Build will be marked unstable.

â Troubleshooting Jenkins

Index

Was this page helpful?

Please submit your feedback about this page through this quick form.

Alternatively, if you don't wish to complete the quick form, you can simply indicate if you found this page helpful?

See existing feedback here.

Read article

Jenkins Handbook

Up to all documentation

Read article

Docker

â Installing Jenkins Index

Kubernetes â

Docker

Table of Contents

Installing Docker
Prerequisites
- Downloading and running Jenkins in Docker
- On macOS and Linux
- On Windows
Accessing the Docker container
Accessing the Docker logs
Accessing the Jenkins home directory
Post-installation setup wizard
- Unlocking Jenkins
- Customizing Jenkins with plugins
- Creating the first administrator user

Docker is a platform for running applications in an isolated environment called a "container" (or Docker container). Applications like Jenkins can be downloaded as read-only "images" (or Docker images), each of which is run in Docker as a container. A Docker container is in effect a "running instance" of a Docker image. From this perspective, an image is stored permanently more or less (i.e. insofar as image updates are published), whereas containers are stored temporarily. Read more about these concepts in the Docker documentation’s Getting Started, Part 1: Orientation and setup page.

Docker’s fundamental platform and container design means that a single Docker image (for any given application like Jenkins) can be run on any supported operating system (macOS, Linux and Windows) or cloud service (AWS and Azure) which is also running Docker.

Installing Docker

To install Docker on your operating system, follow "prerequisites" section of the Guided Tour page

As an alternative solution you can visit the Dockerhub and select the Docker Community Edition suitable for your operating system or cloud service. Follow the installation instructions on their website.

If you are installing Docker on a Linux-based operating system, ensure you configure Docker so it can be managed as a non-root user. Read more about this in Docker’s Post-installation steps for Linux page of their documentation. This page also contains information about how to configure Docker to start on boot.

Prerequisites

Minimum hardware requirements:

256 MB of RAM
1 GB of drive space (although 10 GB is a recommended minimum if running Jenkins as a Docker container)

Recommended hardware configuration for a small team:

4 GB+ of RAM
50 GB+ of drive space

Comprehensive hardware recommendations:

Hardware: see the Hardware Recommendations page

Software requirements:

Java: see the Java Requirements page
Web browser: see the Web Browser Compatibility page
For Windows operating system: Windows Support Policy
For Linux operating system: Linux Support Policy
For servlet containers: Servlet Container Support Policy

Downloading and running Jenkins in Docker

There are several Docker images of Jenkins available.

The recommended Docker image to use is the Official jenkins/jenkins image (from the Docker Hub repository). This image contains the current Long-Term Support (LTS) release of Jenkins (which is production-ready). However this image doesn’t have docker CLI inside it and is not bundled with frequently used Blue Ocean plugins and features. This means that if you want to use the full power of Jenkins and Docker you may want to go through described below installation process.

A new jenkins/jenkins image is published each time a new release of Jenkins Docker is published. You can see a list of previously published versions of the jenkins/jenkins image on the tags page.

On macOS and Linux

Open up a terminal window.
Create a bridge network in Docker using the following docker network create command:
```
docker network create jenkins
```

In order to execute Docker commands inside Jenkins nodes, download and run the docker:dind Docker image using the following docker run command:

docker run \
  --name jenkins-docker \(1)
  --rm \(2)
  --detach \(3)
  --privileged \(4)
  --network jenkins \(5)
  --network-alias docker \(6)
  --env DOCKER_TLS_CERTDIR=/certs \(7)
  --volume jenkins-docker-certs:/certs/client \(8)
  --volume jenkins-data:/var/jenkins_home \(9)
  --publish 2376:2376 \(10)
  docker:dind \(11)
  --storage-driver overlay2(12)

1	( Optional ) Specifies the Docker container name to use for running the image. By default, Docker will generate a unique name for the container.
2	( Optional ) Automatically removes the Docker container (the instance of the Docker image) when it is shut down.
3	( Optional ) Runs the Docker container in the background. This instance can be stopped later by running `docker stop jenkins-docker` .
4	Running Docker in Docker currently requires privileged access to function properly. This requirement may be relaxed with newer Linux kernel versions.
5	This corresponds with the network created in the earlier step.
6	Makes the Docker in Docker container available as the hostname `docker` within the `jenkins` network.
7	Enables the use of TLS in the Docker server. Due to the use of a privileged container, this is recommended, though it requires the use of the shared volume described below. This environment variable controls the root directory where Docker TLS certificates are managed.
8	Maps the `/certs/client` directory inside the container to a Docker volume named `jenkins-docker-certs` as created above.
9	Maps the `/var/jenkins_home` directory inside the container to the Docker volume named `jenkins-data` . This will allow for other Docker containers controlled by this Docker container’s Docker daemon to mount data from Jenkins.
10	( Optional ) Exposes the Docker daemon port on the host machine. This is useful for executing `docker` commands on the host machine to control this inner Docker daemon.
11	The `docker:dind` image itself. This image can be downloaded before running by using the command: `docker image pull docker:dind` .
12	The storage driver for the Docker volume. See "Docker storage drivers" for supported options.

Note: If copying and pasting the command snippet above does not work, try copying and pasting this annotation-free version here:

docker run --name jenkins-docker --rm --detach \
  --privileged --network jenkins --network-alias docker \
  --env DOCKER_TLS_CERTDIR=/certs \
  --volume jenkins-docker-certs:/certs/client \
  --volume jenkins-data:/var/jenkins_home \
  --publish 2376:2376 \
  docker:dind --storage-driver overlay2

Customise official Jenkins Docker image, by executing below two steps:

Create Dockerfile with the following content:

FROM jenkins/jenkins:2.375.1
USER root
RUN apt-get update && apt-get install -y lsb-release
RUN curl -fsSLo /usr/share/keyrings/docker-archive-keyring.asc \
  https://download.docker.com/linux/debian/gpg
RUN echo "deb [arch=$(dpkg --print-architecture) \
  signed-by=/usr/share/keyrings/docker-archive-keyring.asc] \
  https://download.docker.com/linux/debian \
  $(lsb_release -cs) stable" > /etc/apt/sources.list.d/docker.list
RUN apt-get update && apt-get install -y docker-ce-cli
USER jenkins
RUN jenkins-plugin-cli --plugins "blueocean:1.26.0 docker-workflow:563.vd5d2e5c4007f"

Build a new docker image from this Dockerfile and assign the image a meaningful name, e.g. "myjenkins-blueocean:2.375.1-1":
```
docker build -t myjenkins-blueocean:2.375.1-1 .
```
Keep in mind that the process described above will automatically download the official Jenkins Docker image if this hasn’t been done before.

Run your own myjenkins-blueocean:2.375.1-1 image as a container in Docker using the following docker run command:

docker run \
  --name jenkins-blueocean \(1)
  --restart=on-failure \(2)
  --detach \(3)
  --network jenkins \(4)
  --env DOCKER_HOST=tcp://docker:2376 \(5)
  --env DOCKER_CERT_PATH=/certs/client \
  --env DOCKER_TLS_VERIFY=1 \
  --publish 8080:8080 \(6)
  --publish 50000:50000 \(7)
  --volume jenkins-data:/var/jenkins_home \(8)
  --volume jenkins-docker-certs:/certs/client:ro \(9)
  myjenkins-blueocean:2.375.1-1 (10)

1	( Optional ) Specifies the Docker container name for this instance of the Docker image.
2	Always restart the container if it stops. If it is manually stopped, it is restarted only when Docker daemon restarts or the container itself is manually restarted.
3	( Optional ) Runs the current container in the background (i.e. "detached" mode) and outputs the container ID. If you do not specify this option, then the running Docker log for this container is output in the terminal window.
4	Connects this container to the `jenkins` network defined in the earlier step. This makes the Docker daemon from the previous step available to this Jenkins container through the hostname `docker` .
5	Specifies the environment variables used by `docker` , `docker-compose` , and other Docker tools to connect to the Docker daemon from the previous step.
6	Maps (i.e. "publishes") port 8080 of the current container to port 8080 on the host machine. The first number represents the port on the host while the last represents the container’s port. Therefore, if you specified `-p 49000:8080` for this option, you would be accessing Jenkins on your host machine through port 49000.
7	( Optional ) Maps port 50000 of the current container to port 50000 on the host machine. This is only necessary if you have set up one or more inbound Jenkins agents on other machines, which in turn interact with your `jenkins-blueocean` container (the Jenkins "controller"). Inbound Jenkins agents communicate with the Jenkins controller through TCP port 50000 by default. You can change this port number on your Jenkins controller through the Configure Global Security page. If you were to change the TCP port for inbound Jenkins agents of your Jenkins controller to 51000 (for example), then you would need to re-run Jenkins (via this `docker run …` command) and specify this "publish" option with something like `--publish 52000:51000` , where the last value matches this changed value on the Jenkins controller and the first value is the port number on the machine hosting the Jenkins controller. Inbound Jenkins agents communicate with the Jenkins controller on that port (52000 in this example). Note that WebSocket agents do not need this configuration.
8	Maps the `/var/jenkins_home` directory in the container to the Docker volume with the name `jenkins-data` . Instead of mapping the `/var/jenkins_home` directory to a Docker volume, you could also map this directory to one on your machine’s local file system. For example, specifying the option `--volume $HOME/jenkins:/var/jenkins_home` would map the container’s `/var/jenkins_home` directory to the `jenkins` subdirectory within the `$HOME` directory on your local machine, which would typically be `/Users/<your-username>/jenkins` or `/home/<your-username>/jenkins` . Note that if you change the source volume or directory for this, the volume from the `docker:dind` container above needs to be updated to match this.
9	Maps the `/certs/client` directory to the previously created `jenkins-docker-certs` volume. This makes the client TLS certificates needed to connect to the Docker daemon available in the path specified by the `DOCKER_CERT_PATH` environment variable.
10	The name of the Docker image, which you built in the previous step.

Note: If copying and pasting the command snippet above does not work, try copying and pasting this annotation-free version here:

docker run --name jenkins-blueocean --restart=on-failure --detach \
  --network jenkins --env DOCKER_HOST=tcp://docker:2376 \
  --env DOCKER_CERT_PATH=/certs/client --env DOCKER_TLS_VERIFY=1 \
  --publish 8080:8080 --publish 50000:50000 \
  --volume jenkins-data:/var/jenkins_home \
  --volume jenkins-docker-certs:/certs/client:ro \
  myjenkins-blueocean:2.375.1-1

Proceed to the Post-installation setup wizard.

On Windows

The Jenkins project provides a Linux container image, not a Windows container image. Be sure that your Docker for Windows installation is configured to run Linux Containers rather than Windows Containers . See the Docker documentation for instructions to switch to Linux containers. Once configured to run Linux Containers , the steps are:

Open up a command prompt window and similar to the macOS and Linux instructions above do the following:
Create a bridge network in Docker
```
docker network create jenkins
```

Run a docker:dind Docker image

docker run --name jenkins-docker --rm --detach ^
  --privileged --network jenkins --network-alias docker ^
  --env DOCKER_TLS_CERTDIR=/certs ^
  --volume jenkins-docker-certs:/certs/client ^
  --volume jenkins-data:/var/jenkins_home ^
  --publish 2376:2376 ^
  docker:dind

Customise official Jenkins Docker image, by executing below two steps:

Create Dockerfile with the following content:

FROM jenkins/jenkins:2.375.1
USER root
RUN apt-get update && apt-get install -y lsb-release
RUN curl -fsSLo /usr/share/keyrings/docker-archive-keyring.asc \
  https://download.docker.com/linux/debian/gpg
RUN echo "deb [arch=$(dpkg --print-architecture) \
  signed-by=/usr/share/keyrings/docker-archive-keyring.asc] \
  https://download.docker.com/linux/debian \
  $(lsb_release -cs) stable" > /etc/apt/sources.list.d/docker.list
RUN apt-get update && apt-get install -y docker-ce-cli
USER jenkins
RUN jenkins-plugin-cli --plugins "blueocean:1.26.0 docker-workflow:563.vd5d2e5c4007f"

Build a new docker image from this Dockerfile and assign the image a meaningful name, e.g. "myjenkins-blueocean:2.375.1-1":
```
docker build -t myjenkins-blueocean:2.375.1-1 .
```
Keep in mind that the process described above will automatically download the official Jenkins Docker image if this hasn’t been done before.

Run your own myjenkins-blueocean:2.375.1-1 image as a container in Docker using the following docker run command:

docker run --name jenkins-blueocean --restart=on-failure --detach ^
  --network jenkins --env DOCKER_HOST=tcp://docker:2376 ^
  --env DOCKER_CERT_PATH=/certs/client --env DOCKER_TLS_VERIFY=1 ^
  --volume jenkins-data:/var/jenkins_home ^
  --volume jenkins-docker-certs:/certs/client:ro ^
  --publish 8080:8080 --publish 50000:50000 myjenkins-blueocean:2.375.1-1

Proceed to the Setup wizard.

Accessing the Docker container

If you have some experience with Docker and you wish or need to access your Docker container through a terminal/command prompt using the docker exec command, you can add an option like --name jenkins-tutorial to the docker exec command. That will access the Jenkins Docker container named "jenkins-tutorial".

This means you could access your docker container (through a separate terminal/command prompt window) with a docker exec command like:

docker exec -it jenkins-blueocean bash

Accessing the Docker logs

There is a possibility you may need to access the Jenkins console log, for instance, when Unlocking Jenkins as part of the Post-installation setup wizard.

The Jenkins console log is easily accessible through the terminal/command prompt window from which you executed the docker run … command. In case if needed you can also access the Jenkins console log through the Docker logs of your container using the following command:

docker logs <docker-container-name>

Your <docker-container-name> can be obtained using the docker ps command.

Accessing the Jenkins home directory

There is a possibility you may need to access the Jenkins home directory, for instance, to check the details of a Jenkins build in the workspace subdirectory.

If you mapped the Jenkins home directory ( /var/jenkins_home ) to one on your machine’s local file system (i.e. in the docker run … command above), then you can access the contents of this directory through your machine’s usual terminal/command prompt.

Otherwise, if you specified the --volume jenkins-data:/var/jenkins_home option in the docker run … command, you can access the contents of the Jenkins home directory through your container’s terminal/command prompt using the docker container exec command:

docker container exec -it <docker-container-name> bash

As mentioned above, your <docker-container-name> can be obtained using the docker container ls command. If you specified the --name jenkins-blueocean option in the docker container run … command above (see also Accessing the Jenkins/Blue Ocean Docker container ), you can simply use the docker container exec command:

docker container exec -it jenkins-blueocean bash

Post-installation setup wizard

After downloading, installing and running Jenkins using one of the procedures above (except for installation with Jenkins Operator), the post-installation setup wizard begins.

This setup wizard takes you through a few quick "one-off" steps to unlock Jenkins, customize it with plugins and create the first administrator user through which you can continue accessing Jenkins.

Unlocking Jenkins

When you first access a new Jenkins instance, you are asked to unlock it using an automatically-generated password.

Browse to http://localhost:8080 (or whichever port you configured for Jenkins when installing it) and wait until the Unlock Jenkins page appears.
From the Jenkins console log output, copy the automatically-generated alphanumeric password (between the 2 sets of asterisks).

Note:
- The command: sudo cat /var/lib/jenkins/secrets/initialAdminPassword will print the password at console.
- If you are running Jenkins in Docker using the official jenkins/jenkins image you can use sudo docker exec ${CONTAINER_ID or CONTAINER_NAME} cat /var/jenkins_home/secrets/initialAdminPassword to print the password in the console without having to exec into the container.
On the Unlock Jenkins page, paste this password into the Administrator password field and click Continue .
Notes:
- You can always access the Jenkins console log from the Docker logs (above).
- The Jenkins console log indicates the location (in the Jenkins home directory) where this password can also be obtained. This password must be entered in the setup wizard on new Jenkins installations before you can access Jenkins’s main UI. This password also serves as the default administrator account’s password (with username "admin") if you happen to skip the subsequent user-creation step in the setup wizard.

Customizing Jenkins with plugins

After unlocking Jenkins, the Customize Jenkins page appears. Here you can install any number of useful plugins as part of your initial setup.

Click one of the two options shown:

Install suggested plugins - to install the recommended set of plugins, which are based on most common use cases.
Select plugins to install - to choose which set of plugins to initially install. When you first access the plugin selection page, the suggested plugins are selected by default.

If you are not sure what plugins you need, choose Install suggested plugins . You can install (or remove) additional Jenkins plugins at a later point in time via the Manage Jenkins > Manage Plugins page in Jenkins.

The setup wizard shows the progression of Jenkins being configured and your chosen set of Jenkins plugins being installed. This process may take a few minutes.

Creating the first administrator user

Finally, after customizing Jenkins with plugins , Jenkins asks you to create your first administrator user.

When the Create First Admin User page appears, specify the details for your administrator user in the respective fields and click Save and Finish .
When the Jenkins is ready page appears, click Start using Jenkins .
Notes:
- This page may indicate Jenkins is almost ready! instead and if so, click Restart .
- If the page does not automatically refresh after a minute, use your web browser to refresh the page manually.
If required, log in to Jenkins with the credentials of the user you just created and you are ready to start using Jenkins!

â Installing Jenkins Index

Kubernetes â

Was this page helpful?

Please submit your feedback about this page through this quick form.

Alternatively, if you don't wish to complete the quick form, you can simply indicate if you found this page helpful?

See existing feedback here.

Read article

Installing Jenkins

â User Handbook Overview

Index

Docker â

Installing Jenkins

Chapter Sub-Sections

The procedures in this chapter are for new installations of Jenkins.

Jenkins is typically run as a standalone application in its own process. The Jenkins WAR file bundles Winstone, a Jetty servlet container wrapper, and can be started on any operating system or platform with a version of Java supported by Jenkins.

Theoretically, Jenkins can also be run as a servlet in a traditional servlet container like Apache Tomcat or WildFly, but in practice this is largely untested and there are many caveats. In particular, support for WebSocket agents is only implemented for the Jetty servlet container. See the Servlet Container Support Policy page for details.

â User Handbook Overview

Index

Docker â

Was this page helpful?

Please submit your feedback about this page through this quick form.

Alternatively, if you don't wish to complete the quick form, you can simply indicate if you found this page helpful?

See existing feedback here.

Read article

Initial Settings

â Offline Installations

â Installing Jenkins Index

Using Jenkins â

Initial Settings

Table of Contents

Jenkins Parameters
- Networking parameters
- Miscellaneous parameters
- Jenkins properties
Configuring HTTP
- HTTPS with an existing certificate
- Using HTTP/2
- HTTPS certificates with Windows

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:

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 options are 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. Refer to Securing Jenkins for more information.
`--paramsFromStdIn`	Reads parameters from standard input (stdin). When parameters are passed via the command line, they can be viewed using `ps(1)` in Unix or Process Explorer in Windows as long as the process keeps running. This is undesirable when passing sensitive parameters like `--httpsKeyStorePassword` . With the `--paramsFromStdIn` parameter you can replace e.g. `java -jar jenkins.war --httpPort=-1 --httpsPort=443 --httpsKeyStore=path/to/keystore --httpsKeyStorePassword=keystorePassword` with `echo '--httpPort=-1 --httpsPort=443 --httpsKeyStore=path/to/keystore --httpsKeyStorePassword=keystorePassword' \| java -jar jenkins.war --paramsFromStdIn` .
`--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 --argument s Realm 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

â Offline Installations

â Installing Jenkins Index

Using Jenkins â

Was this page helpful?

Please submit your feedback about this page through this quick form.

Alternatively, if you don't wish to complete the quick form, you can simply indicate if you found this page helpful?

See existing feedback here.

Read article