About removing plugins from CloudBees Core

When a plugin is no longer used in a CloudBees Core environment, it should be removed either from Operations Center or from the appropriate master. Removing unused plugins provides a number of benefits, such as reducing memory overhead at boot or runtime, reducing configuration options in the web UI, and removing the potential for future conflicts with new plugin updates. You have two choices when removing plugins; uninstall or disable.

Uninstalling a plugin removes the plugin binary (.jpi or .hpi) from the disk. The plugin continues to function normally until you restart Jenkins, but once you restart, Jenkins will function as if you didn’t have the plugin to begin with. Uninstalled plugins will not appear anywhere in the UI, and all the extensions they contributed will disappear.

Disabling a plugin is useful for temporarily “turning off” a plugin, and allowing it to be enabled again in a few hours/days. Jenkins will continue to recognize that the plugin is installed, but it will not start the plugin, and no extensions contributed from the plugin will be visible.

The fragments contributed from a disabled plugin to configuration files would follow the same fate as in the case of uninstalled plugins.

Uninstalling plugins

To uninstall a plugin using the web UI:
  1. From the Operations Center or the appropriate Master, select the Manage Jenkins area.

  2. Select Manage Plugins.

  3. Select the Installed tab.

  4. Find the plugin you want to uninstall.

    They are listed in alphabetical order.
  5. Select the Uninstall button to the left of the plugin you want to uninstall.

    If the plugin is safe to uninstall and is not a dependency for other plugins, a selectable Uninstall button displays to the left of the plugin.

A plugin may also be uninstalled by removing the corresponding .hpi file from the JENKINS_HOME/plugins directory on the master. The plugin will continue to function until the master has been restarted.

If a plugin .hpi file is removed but required by other plugins, the master may fail to boot correctly.

Uninstalling a plugin does not remove the configuration(s) that the plugin may have created. If there are existing job/node/view/build/etc. configurations that reference data created by the uninstalled plugin, during startup Jenkins will warn that some configurations could not be fully loaded and ignore the unrecognized data.

Configuration(s) will be preserved until they are overwritten, so if the plugin is reinstalled, the configuration values will reappear.

To purge uninstalled plugin configurations:
  1. From the Operations Center or the appropriate Master, select the Manage Jenkins area.

  2. Select Manage Old Data to review and remove old data.

Uninstalling a plugin via a cluster operation

You can uninstall plugins using a cluster operation that will affect multiple client masters and update centers. For more information about cluster operations, see Cluster operations.

To uninstall plugins using a cluster operation:
  1. Find the plugin id on the master using the following script in the Script Console:

    Jenkins.instance.pluginManager.plugins.each{
      plugin ->
        println (" Display Name: ${plugin.getDisplayName()}, Plugin Id: ${plugin.getShortName()}")
    }
  2. Once you have the plugin id, you can uninstall the plugin using the following script in a Cluster Operation:

    String pluginId = "mock-security-realm"
    def plugin = Jenkins.getInstance().getPluginManager().getPlugin(pluginId)
    plugin.doDoUninstall()
    In the above example, the plugin mock-security-realm will be uninstalled.

The plugin will be removed completely after the master is restarted.

Disabling plugins

CloudBees Core provides two methods for disabling plugins:

  • The Plugin Manager in the web UI.

  • The Jenkins CLI disable-plugin command.

To disable a plugin using the web UI:
  1. From the Operations Center or the appropriate Master, select the Manage Jenkins area.

  2. Select Manage Plugins.

  3. Select the Installed tab.

  4. Find the plugin you want to disable.

    They are listed in alphabetical order.
  5. Select the checkbox in the Enabled column to the right of the plugin you want to disable.

    If the plugin is safe to disable and is not a dependency for other plugins, the checkbox in the Enabled column will be selectable.

A systems administrator can also disable a plugin by creating a file on the Jenkins master, such as: JENKINS_HOME/plugins/PLUGIN_NAME.hpi.disabled.

The configurations created by the disabled plugin function as if the plugin was uninstalled, insofar as they result in warnings on boot but are otherwise ignored.

To disable a plugin using Jenkins CLI:
  1. Enter the following command:

java -jar jenkins-cli.jar disable-plugin plugin1 plugin2 plugin3 …​ [-quiet (-q)] [-restart (-r)] [-strategy (-s) strategy]

The disable-plugin command disables one or more installed plugins, using short names. You can specify the verbosity level, how dependencies should be handled, and whether Jenkins should restart after the operation completes.

java -jar jenkins-cli.jar disable-plugin plugin1 plugin2 plugin3 ... [-quiet (-q)] [-restart (-r)] [-strategy (-s) strategy]

Arguments

Argument

Description

plugin1 plugin2 plugin3

The list of plugins to be disabled, specified as the plugin short name.

-quiet (-q)

Be quiet, and print only error messages to the console.

-restart (-r)

Restart Jenkins after disabling plugins.

-strategy (-s) strategy

Specify handling for plugin dependencies:

* none (default) If a mandatory dependent plugin exists and is enabled, do not disable the parent plugin.

* mandatory Disable all mandatory dependent plugins, but do not disable optional dependent plugins.

* all Disable all dependent plugins regardless of whether the dependency is mandatory or optional.

The disable-plugin command was added to Jenkins in v2.151.

Disabling a plugin when Jenkins is down

Occasionally a plugin might prevent Jenkins from restarting, for instance if a dependency has been removed, etc. You can disable a plugin when Jenkins is down so that you can restart Jenkins.

To disable a plugin via File System, create a file, <PLUGIN_ID>.jpi.disabled, inside the $JENKINS_HOME/plugins folder.

For example, the following command will disable the Green Balls plugin:

touch $JENKINS_HOME/plugins/greenballs.jpi.disabled

Copyright © 2010-2020 CloudBees, Inc.Online version published by CloudBees, Inc. under the Creative Commons Attribution-ShareAlike 4.0 license.CloudBees and CloudBees DevOptics are registered trademarks and CloudBees Core, CloudBees Flow, CloudBees Flow Deploy, CloudBees Flow DevOps Insight, CloudBees Flow DevOps Foresight, CloudBees Flow Release, CloudBees Accelerator, CloudBees Accelerator ElectricInsight, CloudBees Accelerator Electric Make, CloudBees CodeShip, CloudBees Jenkins Enterprise, CloudBees Jenkins Platform, CloudBees Jenkins Operations Center, and DEV@cloud are trademarks of CloudBees, Inc. Most CloudBees products are commonly referred to by their short names — Accelerator, Automation Platform, Flow, Deploy, Foresight, Release, Insight, and eMake — throughout various types of CloudBees product-specific documentation. Oracle and Java are registered trademarks of Oracle and/or its affiliates. Jenkins is a registered trademark of the non-profit Software in the Public Interest organization. Used with permission. See here for more info about the Jenkins project. The registered trademark Jenkins® is used pursuant to a sublicense from the Jenkins project and Software in the Public Interest, Inc. Read more at www.cloudbees.com/jenkins/about. Apache, Apache Ant, Apache Maven, Ant and Maven are trademarks of The Apache Software Foundation. Used with permission. No endorsement by The Apache Software Foundation is implied by the use of these marks.Other names may be trademarks of their respective owners. Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in this content, and CloudBees was aware of a trademark claim, the designations have been printed in caps or initial caps. While every precaution has been taken in the preparation of this content, the publisher and authors assume no responsibility for errors or omissions, or for damages resulting from the use of the information contained herein.