Skip to content
Tutorials Center
My learning

Topics

Lesson 28 of 40 ยท Scaling and Operating Jenkins

Administration recipes: ports, restarts, upgrades, CLI, plugins and Slack

Practical Jenkins administration: change the port, restart safely, upgrade, recover a locked-out admin, reset a build number, list plugins with the CLI and send Slack notifications.

Every Jenkins administrator meets the same small jobs again and again: the port is already taken, a restart is needed but builds are running, a new version is out, somebody forgot the admin password, a job's build number must start over, or the team wants a message in Slack when a build breaks. None of them is hard, but each has a safe way and a risky way. This lesson collects the recipes in one place.

The Jenkins server and Slack cannot run on this site, so commands and configuration are read-only. The runnable examples are plain JavaScript stand-ins that model the logic: a plugin audit, a safe-restart check and a build-number reset. Paths shown are the usual ones for Linux packages (/var/lib/jenkins) and Docker (/var/jenkins_home); yours may differ.

Several recipes below change security or delete state. Take a backup first (see Backup, Monitoring and Troubleshooting), try them on a test instance, and never disable security on a server reachable from the internet.

Changing the HTTP port

Jenkins listens on 8080 by default. Change it when another service uses that port or when your policy requires another one. How you do it depends on how Jenkins was installed:

  • WAR file: pass the option when you start it: java -jar jenkins.war --httpPort=9090.
  • Docker: keep the container port and change the published one: -p 9090:8080. This is the cleanest way because nothing inside the image changes.
  • Linux package with systemd: create an override, then restart:
Terminal
sudo systemctl edit jenkins
# add these lines in the editor that opens:
#   [Service]
#   Environment="JENKINS_PORT=9090"
sudo systemctl restart jenkins

Newer packages read JENKINS_PORT this way; older ones used /etc/default/jenkins or /etc/sysconfig/jenkins. Check the file your version ships.

  • Windows service: edit the httpPort argument in jenkins.xml in the install folder and restart the service.

After the change, update the Jenkins URL under Manage Jenkins, System and any webhooks or reverse proxy that pointed at the old port, otherwise links in emails and webhook callbacks keep using it. A port below 1024 needs extra privileges; keep Jenkins on a high port and put nginx or another reverse proxy in front (see Installing Jenkins).

Restarting without losing work

There are three levels of restart, and they differ in how kind they are to running builds:

Method URL path or command What happens
Safe restart /safeRestart Stops accepting new builds, waits for running builds to finish, then restarts
Restart /restart Restarts right away; running builds are interrupted and may resume or fail
Exit /exit Shuts Jenkins down immediately
Service command sudo systemctl restart jenkins Same as an immediate restart

Use safe restart (also offered by the Restart Safely button after installing plugins) in daily life. If a restart is needed in the middle of a busy day, announce it, put Jenkins in quiet down mode (/quietDown, undo with /cancelQuietDown), and let the queue drain.

JS Is it safe to restart now?

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Upgrading Jenkins

Jenkins has two release lines: weekly releases and LTS (long-term support) releases chosen every few months for stability. Servers used by teams should follow LTS. The security advisories on the Jenkins site tell you when an upgrade is urgent.

A careful upgrade:

  1. Read the changelog and upgrade guide for your LTS line, especially the minimum Java version.
  2. Back up JENKINS_HOME.
  3. Upgrade the core:
    • Linux package: sudo apt update && sudo apt install --only-upgrade jenkins (or the dnf / yum equivalent).
    • Docker: pull the newer tag and recreate the container, keeping the volume: docker pull jenkins/jenkins:lts-jdk21, then stop, remove and run again with the same -v jenkins_home:/var/jenkins_home.
    • WAR file: replace jenkins.war and restart.
    • Windows: run the new installer, or replace the WAR in the install folder.
  4. Upgrade plugins afterwards using Manage Jenkins, Plugins, ideally on a staging copy first.
  5. Check a few important jobs run, and keep the previous version handy for a rollback.

Pin the image tag in Docker (a specific LTS number) rather than using a floating latest, so upgrades happen when you decide.

The Jenkins CLI

Jenkins ships a command-line client. Download jenkins-cli.jar from your own server (/jnlpJars/jenkins-cli.jar) and authenticate with a user name and an API token (create it under your user profile, Security), never your password:

Terminal
export JENKINS_URL=https://jenkins.example.com/
java -jar jenkins-cli.jar -auth alice:API_TOKEN who-am-i
java -jar jenkins-cli.jar -auth alice:API_TOKEN list-jobs
java -jar jenkins-cli.jar -auth alice:API_TOKEN build web/main -s -v
java -jar jenkins-cli.jar -auth alice:API_TOKEN list-plugins
java -jar jenkins-cli.jar -auth alice:API_TOKEN install-plugin slack -deploy
java -jar jenkins-cli.jar -auth alice:API_TOKEN safe-restart

list-plugins prints each plugin's short name, title and version, and flags updates with the available version in parentheses. A frequent use is checking that two servers have the same plugins, or rebuilding a server from a list. The same information is available at /pluginManager/api/json?depth=1 and from the Script Console:

GROOVY
Jenkins.instance.pluginManager.plugins
  .sort { it.shortName }
  .each { println "${it.shortName}:${it.version}" }

Keep such a list in Git; Jenkins Configuration as Code and the plugin installation manager tool can install exactly those versions (see Jenkins Configuration as Code and Plugins).

JS Compare two servers' plugin lists

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Locked out: recovering administrator access

If you lose the admin password and nobody else is an admin, you can temporarily turn security off, log in, and fix it. This leaves Jenkins open to everyone who can reach it, so do it only on a machine you control, as fast as possible, and ideally with the network blocked.

  1. Stop Jenkins.
  2. Back up config.xml in JENKINS_HOME.
  3. In config.xml, change <useSecurity>true</useSecurity> to false (or remove the <authorizationStrategy> and <securityRealm> blocks).
  4. Start Jenkins and open it without logging in.
  5. Go to Manage Jenkins, Security and set the security realm and authorization again, then create or fix an admin user (a user's password can be changed from its Configure page).
  6. Immediately confirm that security is on and sign in as a real user.

If the password you forgot is only the initial one, it is in secrets/initialAdminPassword. Docker users find it with docker exec jenkins cat /var/jenkins_home/secrets/initialAdminPassword or in the container log. See Security, Users and Authorization for the safe configuration to return to.

Resetting a job's build number

Build numbers count up forever; there is rarely a reason to reset them, and doing so risks confusion (artifacts and links that mention #12 suddenly point at a different build). If you must, for example after copying a job for a new product, there are two ways:

  • Script Console (admin only): delete old builds if wanted, then set the next number.
GROOVY
def job = Jenkins.instance.getItemByFullName("web/main")
job.builds.each { it.delete() }          // optional: removes history
job.updateNextBuildNumber(1)
  • Files: with Jenkins stopped, write the number into jobs/<job>/nextBuildNumber, delete the builds folder contents if needed, and start Jenkins.

Prefer not to reset and instead use the Discard old builds option, which keeps history bounded without renumbering.

JS Why resetting a build number needs care

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Notifications to Slack

Install the Slack Notification plugin, create a Slack app or an incoming webhook for the channel, and store its token as a Secret text credential (never in the Jenkinsfile). Configure the workspace once in Manage Jenkins, System, then call slackSend from a pipeline:

GROOVY
pipeline {
  agent any
  stages {
    stage('Build') { steps { sh './gradlew build' } }
  }
  post {
    success { slackSend channel: '#builds', color: 'good',    message: "OK ${env.JOB_NAME} #${env.BUILD_NUMBER} (<${env.BUILD_URL}|open>)" }
    failure { slackSend channel: '#builds', color: 'danger',  message: "FAILED ${env.JOB_NAME} #${env.BUILD_NUMBER} (<${env.BUILD_URL}|open>)" }
    fixed   { slackSend channel: '#builds', color: 'good',    message: "Back to normal: ${env.JOB_NAME}" }
  }
}

Notify on failure and on recovery (fixed), not on every success, or people mute the channel. Include the job name, number and a link. The post conditions are explained in Conditions and Post Actions.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. A deployment is waiting and builds are running. Which restart avoids interrupting them?

    Safe restart stops new builds from starting, lets running ones finish, and then restarts.
  2. 2. What is the safest way to move a Docker-based Jenkins to another host port?

    The container still listens on 8080; only the published host port changes.
  3. 3. You forgot the admin password. What must you do right after turning useSecurity off and logging in?

    With security off anyone who can reach the server has full control, so restore it at once.
  4. 4. Which Slack notification policy keeps a channel useful?

    Failure and fixed messages carry information; constant success messages become noise.
  5. 5. How should the CLI authenticate?

    API tokens can be revoked individually and are safer than reusing a password.

Summary

  • Change the port with --httpPort, the JENKINS_PORT setting or a Docker port mapping, then update the Jenkins URL and webhooks.
  • Prefer /safeRestart and quiet-down mode; follow LTS releases, back up, upgrade the core and then plugins, and pin versions.
  • The CLI with an API token lists jobs and plugins, builds jobs and restarts safely; keep a plugin list in Git.
  • To recover a locked-out admin, briefly turn security off in config.xml, then re-enable it at once.
  • Avoid resetting build numbers; use discard-old-builds instead. Send Slack messages from post blocks with a credential, on failure and recovery.

Next: Deployment Pipelines and Approvals.