Quickstart guide for upgrading Broker Server 10


The following technical note describes various upgrade scenarios for Broker and lists high-level steps that can be used. This technical note should be used along with webMethods Upgrade guide. It covers the scenario of upgrading from version 9 to version 10, but the same steps should be applicable to upgrade between any two versions in 9.x/10.x/11.x.

The best scenario for an upgrade is to:

  • reuse storage
  • use the same old hostname:port

If storage cannot be reused, then export/import is required.

If hostname: port cannot be reused, then the following changes will be needed:

  1. Territory/cluster/gateway needs to be rebuilt, or use broker_update to surgically (and carefully) update the persisted hostname.
  2. IS messaging setting & JMS connection factories etc client settings needs to be fixed to point to new hostname:port.

Case 1: Upgrading on same box, then the simplest option is to reuse storage and use the same hostname:port. High-level steps will be:

  1. Install 10.x without creating server.
  2. Shutdown 9.x server
  3. Remove 9.x server (server_config remove)
  4. Add data directory as 10.x server (server_config add)
  5. Start 10.x server.

Case 2: Upgrading on different box with same Operating System (maybe of higher version), then reuse storage.

In this case one can reuse hostname:port too as long both boxes are not running in the same network at the same time.

  1. Keep 10.x box off the network and install 10.x without creating server.
  2. Shutdown 9.x
  3. Remove 9.x server (server_config remove)
  4. Copy over the storage to new box while keeping same data directory path.
  5. If the same directory path is not possible in step 3, then one needs to use “server_config relocate” on 10.x server.
  6. Add to 10.x server (server_config add)
  7. Shut down the old box and take it off the network.
  8. Start new box in network and start 10.x server.

Note: server_config relocate is useful, if you wants to change data directory for some reason, say storage mount point has changed from /opt/wm82 to /opt/sag96. “server_config relocate” is not supported in 9.0 and earlier version.

Case 3: If storage reuse is not possible, then export/import is required.

Export/import can be done in 3 ways:

  • broker_save/broker_load command line utility
  • UI based export/import
  • Deployer based export/import

All 3 are functionally equivalent, each subsequent option is increasingly complex due to the number of products required and number of steps to execute. The guide is based on Deployer-based export/import.

The usual upgrade steps will be:

  1. Install 10.x server. Also create a new server
  2. Export from 9.x and import to 10.x
  3. Stop 9.x server and start 10.x server

If hostname:port remains the same, you need to take care of the network visibility of the new server.

If hostname:port is changing, then you must either rebuild territory/cluster/gateway, or change the hostname before importing the terrtory/gateway definitions.

Case 4A: If hostname:port reuse is not possible in a territory/gateway setup, and one opts for rebuilding territory/gateways, then one should do the following:

  1. Remove 9.x broker from gateway/territories
  2. Upgrade/migrate to 10.x
  3. Setup 10.x territory/gateways
  4. Start 10.x server
  5. Fix client settings: IS messaging for native, connection factories etc
  6. Start clients.

Case 4B: If hostname:port reuse is not possible in a territory/gateway setup, and one opts for using broker_update, then one should do the following

  1. Upgrade/migrate to 10.x
  2. Start 10.x servers in a separate network to avoid then connecting to 9.x servers.
  3. Use the broker_update tool to update the hostname directly in the storage.
  4. Fix client settings: IS messaging for native, connection factories, etc
  5. Start clients.


The upgrade guide is organized as a single large flow. If you search by “Broker” keyword, it will fall in more or less above flow. The upgrade guide gets a bit complicated as it needs to cater to a single flow which must address all use cases (storage reuse vs export/import, upgrade from 9.x SP2 vs SP3, upgrade from 9.x vs 9.0, storage incompatibility on zLinux etc).

The usual caveats apply: first upgrade in dev/test environment; take periodic backup at important stages; apply latest fixes as soon as possible.


Installing and Upgrading webMethods Broker - official guide containing lots of stuff and lots of fluff.


Nice summary @Sandeep_Kumar