How To Rename a WS-Proxy or Multi-Protocol Gateway Object on a DataPower Appliance

datapower, Uncategorized

Anyone who has worked with DataPower for a while has gotten into a situation where they need to rename a service object (XML Firewall, WS-Proxy, Multi-Protocol Gateway, etc).  There isn’t a rename button that I have ever found.  This tutorial will describe two ways of renaming such objects.

I’ll put a warning label on this post right now that this may have undesirable side effects.  So, backup the application domain where you are attempting this and as the warning label on our front page states, try anything presented on Thinkmiddleware.com in a non-production environment prior to doing it in production.

With that out of the way, I have found two ways of renaming service objects.  Both of them are a verge on the not-straightforward side. 

Option #1: Export/Import & Rename with a Deployment Policy

This procedure assumes that you are familiar with the export/import functionality of DataPower.

Suppose you have a WS-Proxy object that doesn’t match your organization’s naming conventions.  It needs to be changed.   Do the following:

  1. Log into the console.
  2. Change to the Application Domain where you will be working.
  3. Backup the application domain where you will be working.  Note, that private keys & certificates in the cert:// directory are not included in normal backups.  Nor, are keys stored in the HSM module.
  4. Export the object using the link on the service configuration screen (click the “export” link).
  5. Save the resulting ZIP file somewhere that it can be easily retrieved on your local file system later.
  6. Go to the Deployment Policy screen.  Search for it using the 4.0.x menu search feature if necessary.  Click Add.
  7. Add a name for the new Deployment Policy.
  8. Go to the Modified Configuration screen.
  9. Click Add.
  10. For the Configuraiton Match field click the Build button.
  11. Leave the Device Address field blank.
  12. For Application Domain, chose (none).
  13. For Resource Type, choose Web Service Proxy (under Service Configuration) from the drop down or whatever type of service is to be renamed.
  14. In the Name Match(PCRE) field, build a regular expression using the name of the service object.  So, if the service object name is RCBJ0001-WS-Proxy, then this field should contain “^RCBJ0001-WS-Proxy$”. 
  15. Leave the Configuration Property field blank.  This means the value being changed is the name of the service object.
  16. Leave the Configuration Value Match(PCRE) value blank.
  17. Click Save.
  18. Back on the Edit Modified Configuration screen, Choose “Change Configuration” from the drop down.
  19. In the Configuration Value field, add the new name for the service object.
  20. Click Apply.
  21. Click Apply on the Deployment Policy screen.
  22. Click the save link.
  23. Go to the Control Panel.
  24. Click the Import Configuration icon.
  25. Choose the ZIP file that was exported at the beginning of this process.
  26. Chose the Deployment Policy that was just created.
  27. Click Next.
  28. Continue to work through the import wizard.
  29. Select any objects that are listed in the “The following configuration is new:” box.
  30. Select any objects that are listed in the “The following files already exist:”
  31. Select any files that are listed in the “The following files are new:” box.
  32. Select any files that are listed in the “The following files differ from existing files:” box.
  33. Click the Import button.
  34. Review the results for any errors.
  35. Click save.
  36. Go to the Control Panel.
  37. Click on the Web Service Proxy screen (or the appropriate icon for the desired type of service).
  38. The new name for the service object should be listed.

Service objects (especially WS-Proxy objects) have numerous dependent objects whose names will likely have been auto-generated at service creation time.  The names for this objects will still reflect the old service object name.  Fixing all of these could take a while.

Option #2: Find & Replace in the Application Domain Configuration File & Restart the App Domain

Warning:  I believe IBM recommends not modifying the configuration file that is mentioned below.  That being stated, let us continueSmile.

The Application domain configuration file (where all of the objects are defined) is kept in the config:// directory in each application domain. The file is named after the application domain.  So, for example, if the Application Domain is named RCBJ, the configuration file for the domain would be config://rcbj.cfg.  This can be accessed by anyone with permission to access the application domain from the web console.  Do the following:

  1. Log into the DataPower Web Console.
  2. Change to the desired Application Domain.
  3. Go to the Control Panel.
  4. Click on the File Manager icon.
  5. Expand the config:// directory tree node.
  6. Right-click on the domain configuration file.
  7. Save the file to your local file system.
  8. Open up the configuration file in your favorite text editor (do not use Notepad, this file does not use Windows rn end-of-line delimiters.
  9. Do a Find & Replace operation to change all occurrences of the old service name to the new service name.
  10. Save the file.
  11. Upload it to the appliance using the File Manager (be sure to chose the “Overwrite exiting files” option.
  12. Restart the application domain by going to Control Panel->System Control.
  13. Verify that there are no unsaved changes according to the messages at the top of the DataPower console screen.  If there are, they will be lost after doing the restart.
  14. Click the Restart Domain button.
  15. Follow the wizard.
  16. Wait for the domain to come back up.
  17. Check the service object to make sure the new name is present and it is in an up state.