How to set up UCMDB server and CMS UI environment with F5 BIG-IP load balancer and WebSEAL reserve proxy

This end-to-end use case describes how to set up a high-availability UCMDB and CMS UI environment with F5 BIG-IP load balancer and WebSEAL reverse proxy.

The diagram below illustrates the overall architecture of the environment we will set up.

This case contains the following key tasks:

 

1. UCMDB Server configuration

   1. Prerequisites

      1. You have installed the UCMDB Server and CMS UI.

      2. (Optional) You have set up high availability mode by following the instructions in the Deployment Guide: "Set Up High Availability Mode".

   2. Export the out-of-the-box UCMDB server keystore to a cert file

      If using the out-of-the-box (OOTB) UCMDB cert, export it for later use.

      To export the UCMDB server keystore (server.keystore) to a cert file (server.cert), do the following:

      1. Open the command prompt and run the following command:

         C:\UCMDB\UCMDBServer\bin\jre\bin\keytool.exe -export -alias <certificate alias> -keystore <Keystore file path> -file C:\UCMDB\UCMDBServer\conf\security\server.cert

         where:

         • certificate alias is the name given to the certificate.

         • Keystore file path is the full path of the location of the keystore file.

         For example, for the out-of-the-box server.keystore use the following command:

         C:\UCMDB\UCMDBServer\bin\jre\bin\keytool.exe -export -alias hpcert -keystore C:\ucmdb\ucmdbserver\conf\security\server.keystore -file C:\UCMDB\UCMDBServer\conf\security\server.cert

         Note If self-signed certificate is not used, but a company generated certificate, use the following command to get the alias for this certificate:

         C:\UCMDB\UCMDBServer\bin\jre\bin\keytool.exe -list -keystore c:\ucmdb\ucmdbserver\conf\security\server.keystore

         Keystore type: JKS

         Keystore provider: SUN

         Your keystore contains 1 entry.

         <alias>, 14 Sept. 2012, PrivateKeyEntry.

         Certificate fingerprint (SHA1): 2A:52:DF:17:D9:A5:37:2D:1F:1D:BA:4B:41:46:33:A8:18:42:5B:D7

         The alias will look like: {45789-15478-1236-7895}

         Use this alias to export the certificate.

      2. Enter the keystore password.

      3. Verify that the certificate was created in the following directory: C:\UCMDB\UCMDBServer\conf\security\server.cert

      4. Convert the generated JKS file into PKCS12 format using UCMDB key tool keytool.exe (located in the <UCMDBServer>\bin\jre\bin directory). (WebSEAL requires PKCS12 format cert.)

         Run the following command:

         C:\UCMDB\UCMDBServer\bin\jre\bin\keytool.exe -importkeystore -srckeystore server.keystore -destkeystore server.p12 -srcalias <source serverkey> -destalias <target serverkey> -srcstoretype jks -deststoretype pkcs12 -srcstorepass <keystore password> -deststorepass <keystore password> -noprompt
         

         The server.p12 file is the resulting PKCS12 format cert.

   3. (Single Sign-On only) Set IDM User Name

      1. Go to UCMDB server JMX console.
      2. Locate the setUserName JMX operation under the UCMDB-UI:name=LW-SSO Configuration category.

      3. Provide the following parameter values for the setUserName JMX method:

         • Is inbound handler enabled: True
         • LW-SSO IDM User Name: <The real value for the IDM user name>. For example, iv-user (if you are using LDAP with user iv-user).
      4. Click Invoke.

   4. Set CMS UI URL

      1. In UCMDB UI, go to Administration > Infrastructure Settings Manager.
      2. Locate the UCMDB Browser URL infrastructure setting, and set the value to your WebSEAL URL.
2. F5 load balancer configuration

   1. Make sure you have a working F5 BIG-IP load balancer environment.
   2. Log in to the F5 BIG-IP load balancer environment.

   3. Make sure you have created the following in the F5 BIG-IP load balancer environment (Local Traffic > Virtual Servers > Nodes|Pools):

      • A node for each of the virtual machines on which UCMDB server and/or CMS UI are running.
      • A pool that contains all the above nodes.

   4. Import the UCMDB CA cert/key into F5.

      1. In the navigation pane, go to Main > System > Certificate Management.
      2. Click Import .

      3. In the SSL Certificate/Key Source page, select Import Type:

         • When selecting Certificate, do the following:

           • Certificate Name: Keep Create New selected and provide the certificate name.
           • Certificate Source: Keep Upload File selected, click Browse... to select the UCMDB server.cert file you exported earlier.

         • When selecting Key, do the following:

           • Key Name: Keep Create New selected and provide the key name.
           • Certificate Source: Keep Upload File selected, click Browse... to select the UCMDB key file.
      4. Click Import .

   5. Add UCMDB CA cert/key to Certificate Key Chain.

      1. In F5, go to Local Traffic > Virtual Servers > Profiles > SSL.

      2. Select and click an existing UCMDB cert profile.

         Note Create a SSL profile for HTTPS by clicking Create if you do not have one.

      3. Go to the Certificate Key Chain configuration setting, click Add .

      4. In the Add SSL Certificate to Key Chain dialog, select or provide values for the following settings as appropriate and click Add :

         Certificate: Select the UCMDB certificate file.

         Key. Select the UCMDB key.

         Chain. Select the UCMDB chain.

         Passphrase. Provide a pass phrase.

   6. Create a cookie-based persistence profile.

      1. In F5, go to Local Traffic > Virtual Servers > Persistence, and click Create .
      2. Select Cookie for Persistence Type and provide a name for the persistence profile.
      3. Click Finished.

   7. Create a virtual server.

      1. In F5, go to Local Traffic > Virtual Servers, and click Create .

      2. Specify values the following settings:

         • Configuration > HTTP Profile: http
         • Configuration > SSL Profile (Client): Select the UCMDB cert you imported in step 2.e from the Available column and add it into the Selected column.
         • Configuration > Source Address Translation: Auto Map (If you select SNAT, make sure you configure SNAT related settings properly)
         • Resources > Default Persistence Profile: Select the persistence profile you created in step 2.f.
      3. Provide values for other settings as appropriate.
      4. Click Finished.
3. WebSEAL reverse proxy configuration

   1. Configure WebSEAL reverse proxy by following IBM official documentation: IBM Security Access Manager (ISAM) Reverse Proxy Scenario.

      Important During the configuration, in the Identity tab of the Edit a Standard Junction window, make sure you set the following settings as described below:

      • Junction Cookie: Leave the checkbox unselected
      • Include session cookie: Select the checkbox

      • HTTP Basic Authentication Header: For CMS UI and RESTful API authentication to work properly, select Ignore from the dropdown list.

      • (Optional) HTTP Header Identity Information: Select IV-USER if you are using LDAP with user iv-user.

   2. Import UCMDB cert (OOTB or self-signed).

      1. In IBM Security Access Manager, go to Manage > Secure Settings > SSL Certificate.
      2. Go to Manage > Edit SSL certificate database menu option, and select pdsrv.
      3. Go to the Personal Certificates tab, check if the OOTB UCMDB cert (for example, ucmdbcert) is already listed in this tab.

      4. If no, select Manage > Import from the menu.

         Provide the self signed certificate from the CMS UI/UCMDB Server or the OOTB UCMDB cert.

         Make sure the cert type is PKCS12. If not PKCS12, you may need to convert it to PKCS12 from JKS.

         Note The OOTB UCMDB cert can be converted to PKCS12 using UCMDB key tool keytool.exe (located in the <UCMDBServer>\bin\jre\bin directory). For the conversion command, see step 1.b.iv in UCMDB Server configuration.

4. CMS UI configuration

   1. Configure the ucmdb_browser_config.xml file.

      1. Open the ucmdb_browser_config.xml file (located in the <CMS_UI_install_dir>\conf folder) using a text editor.
      2. Set the <hostname> parameter value to the VIP that you set in F5.
      3. Set the <host_port> parameter to the Port that you set in F5.

      4. (Single Sign-on only) If you are using LDAP with user iv-user, locate the <webui> tags, then the <validation> tags, copy and paste the following into the file:

         <in-ui-identity-management>
             <identity-management> 
                 <userNameHeaderName>iv-user</userNameHeaderName> 
             </identity-management>
         </in-ui-identity-management>
         

      5. Save the file.

   2. Create and configure a credentials file.

      1. Create a credentials.txt file and put it in the same directory as the ucmdb_browser_config.xml file.

      2. In the file credentials.txt, enter the following content:

         • user=UISysadmin
         • password=<your-password>
      3. Save the file.
5. Verify the configured environment works

   To do so, log in to any of the following:

   Environment	Login URL	Remarks
   WebSEAL	https://<WebSEAL URL>:<port><WebSEAL Junction>	Including CMS UI, UCMDB server, and API
   F5	https://<VIP>:<port>	Including CMS UI and UCMDB server
   CMS UI	https://<CMS UI IP address>:<port>
   UCMDB Server	https://<UCMDB Server IP address>:<port>

Troubleshooting F5 load balancer

Problem: In a very rare case, you might find UCMDB server is displayed as down or not available in F5 monitor.

Workaround: This might be caused by the difference between the F5 interval setting and the duration that garbage collector requires to run on UCMDB server. For example, the default value for the Interval setting is 5 seconds in F5 (Local Traffic > Monitors > Browser > Properties); on UCMDB server, in a very extreme case, the garbage collector needs more than 5 seconds to complete a run (normally it takes only 2 seconds or so to complete a run), which makes the UCMDB writer server in the high availability environment busy with garbage collection and F5 monitor fails to detect the UCMDB writer server status.

In case you encounter such extreme case, to resolve the issue, increase the Interval setting in F5 environment (Local Traffic > Monitors > Browser > Properties) to a desired value. Normally the default Interval value of 5 seconds should be sufficient.

To determine the total duration needed for running garbage collector on the UCMDB server, you can check for the longest duration that the garbage collector takes in the <UCMDBServer>\runtime\log\wrapper.log file.