Issue Summary

Article ID:360044970711
4 minute readKnowledge base

On June 22nd, 2020, the certificate used to sign all existing CloudBees licenses for Jenkins-based products expires. This certificate is used to verify the authenticity of the customer’s CloudBees license.

Customers must install a new license (generated with the new certificate) before June 22, 2020. Existing licenses will become invalid as of June 22, 2020. This article describes how to resolve this error for CloudBees Core on traditional platforms, CloudBees Jenkins Platform, and CloudBees Jenkins Distribution. See the article on Fixing license errors in CloudBees Core on modern platforms after June 22, 2020 if you are using that platform.

If you did not update your licenses prior to June 23rd, 2020, the following licensing screen will appear:

image::common-kb::licenses/license-screen.png[]

Figure 1. CloudBees Jenkins-based Product Licensing Screen

Prerequisites

Before you begin applying the update, it is important to determine the currently installed version of the cloudbees-license plugin for each Jenkins instance. You will need to know the version numbers so that you can download/apply the correct update for each instance. If the versions of your Jenkins instances are not heterogeneous across your environment, care must be taken to ensure that the correct plugin version is installed on each instance.

Throughout this article, PLUGIN_ROOT is used to refer to the base directory where Jenkins plugins are installed, which is "$JENKINS_HOME/plugins". The update must be performed by a user who has shell access to the environment where the Jenkins instance is installed, and they must have permission to modify files in PLUGIN_ROOT.

Regardless of the deployment platform, the following steps must be performed on all CloudBees Jenkins instances. This includes Operation Center, connected controllers, and standalone controllers.

Update the cloudbees-license plugin

Choose one of the methods below to update the cloudbees-license plugin:

Method

Details

Using an init.d groovy script

The simplest way to update CloudBees Jenkins instances deployed on traditional platforms is by copying this groovy script, available at https://github.com/cloudbees/jenkins-scripts/blob/master/license-upgrade/initd-unbreak.groovy, to $JENKINS_HOME/init.groovy.d/ and restarting the instance. The script automates the process of determining which version of the plugin needs to be installed, backing up the current plugin, and installing the update.
This approach is also recommended for deployments on Windows platforms, or for customers who are not able to run the bash script.

Using a bash script

This script automates the process of determining which version of the plugin needs to be installed, backing up the current plugin, and installing the update.

Manually

The manual steps are primarily provided as a reference for those who want to understand what the scripted approach is doing.

To update each instance using an init.d groovy script

  1. Download this groovy script initd-unbreak.groovy from https://raw.githubusercontent.com/cloudbees/jenkins-scripts/master/license-upgrade/initd-unbreak.groovy.

  2. Copy the script to $JENKINS_HOME/init.groovy.d/ for each CloudBees Jenkins instance that needs to be updated. Note: if the directory $JENKINS_HOME/init.groovy.d/ does not exist you will need to create it first.

  3. Restart Jenkins. The script will run as part of the Jenkins initialization process, and the instance will restart one more time to complete the update.

  4. Once your instance is online and working well, you can remove the groovy script $JENKINS_HOME/init.groovy.d/initd-unbreak.groovy

Once all of your instances have been updated you can contact support by going to https://support.cloudbees.com/ and opening a ticket or contact CloudBees Customer Success (csm-help@cloudbees.com) for an updated license.

To update each instance using a bash script:

  1. Open a terminal session on the instance you are planning to update.

  2. Download the update script from https://raw.githubusercontent.com/cloudbees/jenkins-scripts/master/license-upgrade/core-traditional-unbreak.sh to this instance.

  3. Ensure that the environment variable PLUGIN_ROOT is set, and contains the full path to the home directory of the CloudBees Jenkins instance being upgraded.

     $ export PLUGIN_ROOT=/var/lib/jenkins/plugins
    ▼

  4. Execute the script.

     $ ./core-traditional-unbreak.sh
 Using PLUGIN_ROOT defined as /Users/mcirioli/export/jenkins-wars/cloudbees-core-oc.2.164.3.2/plugins
 Checking to see if required tools are present
 Verifying command [awk] is installed...
 Confirmed command [awk] present.
 Verifying command [grep] is installed...
 Confirmed command [grep] present.
 Verifying command [tr] is installed...
 Confirmed command [tr] present.
 Checking for wget or curl....
 Verifying command [wget] is installed...
 Confirmed command [wget] present.
 CURRENT_PLUGIN_VERSION = 9.32
 Backing up the currently installed license plugin
 Downloading updated plugin from https://jenkins-updates.cloudbees.com/download/plugins/cloudbees-license/9.32.1/cloudbees-license.hpi
 2020-06-01 16:06:58 URL:https://jenkins-updates.cloudbees.com/download/plugins/cloudbees-license/9.32.1/cloudbees-license.hpi [4364246] -> "/Users/mcirioli/export/jenkins-wars/cloudbees-core-oc.2.164.3.2/plugins/cloudbees-license.jpi" [1]
 Plugin updated successfully, please restart your Jenkins instance to complete the installation
    ▼

    If the script completed successfully, you will see the following message:

     Plugin updated successfully, please restart your Jenkins instance to complete the installation

  5. Restart the CloudBees Jenkins instance to complete the update.

Once all of your instances have been updated you can contact support by going to https://support.cloudbees.com/ and opening a ticket or contact CloudBees Customer Success (csm-help@cloudbees.com) for an updated license.

To manually update each instance:

It is possible to manually perform the steps needed to update the cloudbees-license plugin by following the steps below. You will need to perform these steps on each CloudBees Jenkins instance that needs to be updated.

To determine your currently installed plugin version:

For traditional platforms, the plugin is installed in:

<PLUGIN_ROOT>/cloudbees-license/

To determine the currently installed version of the plugin, execute the following command and examine the output:

cat $PLUGIN_ROOT/cloudbees-license/META-INF/MANIFEST.MF \| grep "Plugin-Version"
▼

For example:

$ cat /export/jenkins-wars/cloudbees-core-oc/plugins/cloudbees-license/META-INF/MANIFEST.MF | grep Plugin-Version
Plugin-Version: 9.33
▼

In this example, we can see that the currently installed plugin version is 9.33. Based on this, you will then look up the version of the plugin you need to upgrade to in this KB article: Upgrading for the new CloudBees License Certificate. For the example above, you would need to update to version 9.33.1

To manually upgrade the cloudbees-license plugin:

  1. Back up the currently installed version of the cloudbees-license plugin

     mv $PLUGIN_ROOT/cloudbees-license.jpi $PLUGIN_ROOT/cloudbees-license.bak.
    ▼

  2. Download (or copy) the new version of the cloudbees-license plugin to the plugins folder. For example:

     wget https://jenkins-updates.cloudbees.com/download/plugins/cloudbees-license/9.33.1/cloudbees-license.hpi -o $PLUGIN_ROOT/cloudbees-license.hpi
    ▼

  3. Change the plugins file extension from .hpi to .jpi

     mv $PLUGIN_ROOT/cloudbees-license.hpi $PLUGIN_ROOT/cloudbees-license.jpi
    ▼

  4. Restart your Jenkins instance.

Once all of your instances have been updated you can contact support by going to https://support.cloudbees.com/ and opening a ticket or contact CloudBees Customer Success (csm-help@cloudbees.com) for an updated license.