oo

Blacklisting Apps

The bundle blacklist is a convenient way to uninstall or reinstall multiple apps, OSGi bundles (modules), and WAR plugins at once. It saves you the trouble of managing app, module, and plugin installations individually with the Application Manager or Gogo shell.

important

The blacklist is an OSGi configuration that DXP uses to uninstall apps. Using it will prevent any apps listed from being installed until they are removed.

You can set the list in the Control Panel or by using an OSGi configuration (.config) file (by exporting it from the Control Panel).

Blacklisting

DXP removes any installed app, module, or plugin on the blacklist. While they’re blacklisted they can’t be installed. The log reports each uninstallation.

note

Blacklisting an LPKG uninstalls all of its internal modules.

Blacklisting via the Control Panel

Follow these steps to blacklist an app, module, and plugin:

  1. In the Control Panel, navigate to ConfigurationSystem SettingsModule Container. The Bundle Blacklist screen appears.

  2. In the Bundle Blacklist screen, add the bundle symbolic names for the apps, LPKG files, module JARs, or WARs to uninstall. For each item, click the Add button (Add) and enter the item’s bundle symbolic name (see the table below). Click the Save button when you’re finished. DXP uninstalls the blacklisted items immediately.

    This blacklist uninstalls the classic-theme plugin WAR, Liferay Collaboration - Liferay Blogs - API module, and com.acme.greeter module.

Blacklisting via a Configuration File

The blacklist can also be exported from the Control Panel to an OSGi configuration (.config) file. Modifying the file and deploying it to DXP has these additional effects:

  • Persists the changes across DXP server startups
  • Propagates the changes from a local cluster node to all the other nodes.

Use these steps to blacklist using a configuration file:

  1. To export the blacklist currently in use, click its Actions button (Actions) and then click Export. The blacklist config file then downloads (com.liferay.portal.bundle.blacklist.internal.BundleBlacklistConfiguration.config). Here are file contents from exporting the example blacklist:

    blacklistBundleSymbolicNames=[ \
      "classic-theme", \
      "Liferay\ Collaboration\ -\ Liferay\ Blogs\ -\ API", \
      "com.acme.greeter", \
    ]
    
  2. Add the bundle symbolic names of any apps, modules, or plugins not already listed that you want to uninstall and prevent from installing in subsequent DXP server startups.

    warning

    Configuration values can’t contain extra spaces. Extra spaces can short-circuit lists or invalidate the configuration entry.

  3. To deploy the configuration file, copy it into the folder [Liferay Home]/osgi/configs. The Liferay Home folder is typically the app server’s parent folder.

Blacklist Bundle Symbolic Names

Type Bundle Symbolic Name
App App name displayed in the App Manager
LPKG LPKG file name without the .lpkg extension
Module/Bundle JAR Bundle-SymbolicName in bnd.bnd or MANIFEST.MF file
WAR Servlet context name in liferay-plugin-package.properties file or the WAR file name (minus .war), if there is no servlet context name property

Reinstalling Blacklisted Items

To reinstall blacklisted items, follow these steps:

  1. Open the configuration file com.liferay.portal.bundle.blacklist.internal.BundleBlacklistConfiguration.config.

  2. Remove the symbolic names of the LPKGs, module JARs, or WARs from the blacklistBundleSymbolicNames list and save the file.

To reinstall all the blacklisted items execute one of these options:

tip

To temporarily reinstall an item that’s been blacklisted, you can remove its symbolic name from the Bundle Blacklist module in System Settings and click the Update button. If you’re using a blacklist config file (in the [Liferay Home]/osgi/configs folder) and want the item to install on subsequent server startup, make sure to remove the item’s symbolic name from the file.

The log reports each item installation.

Congratulations! Now you can manage multiple app, module, and plugin installations using a simple list.

Capability: