After you upgrade to VMware Identity Manager 3.2.0.1, you may need to configure certain settings.

Customer Experience Improvement Program

This product participates in VMware's Customer Experience Improvement Program ("CEIP"). Details regarding the data collected through CEIP and the purposes for which it is used by VMware are set forth at the Trust & Assurance Center at http://www.vmware.com/trustvmware/ceip.html.

After you upgrade to VMware Identity Manager 3.2.0.1 and log in to the administration console, the Join the VMware Customer Experience Program option appears on the banner. If you prefer not to participate in VMware's CEIP, uncheck the check box and click OK.



CEIP option on banner


The banner persists until you click OK or close the banner. You can join or leave the CEIP at any time from the Appliance Settings > Telemetry page.

Elasticsearch Migration

Note:

This information applies to upgrade to version 3.2.x from previous versions. It does not apply to upgrade from 3.2 to 3.2.0.1.

Elasticsearch, a search and analytics engine, is embedded in VMware Identity Manager and is used for auditing, reports, and search. VMware Identity Manager 3.2.x includes Elasticsearch 2.3.5, while previous versions included Elasticsearch 1.75. During the upgrade to VMware Identity Manager 3.2.x, Elasticsearch records are migrated.

Once the VMware Identity Manager upgrade is complete, a background job will start to migrate existing audit and search records, which are handled by Elasticsearch, to the new format. The start of this process could be delayed up to one hour after the upgrade is complete. Once started, it typically completes quickly, but could take as much 1-2 hours, depending on the number of records.

You can view the analytics-service.log file, which is in the /opt/vmware/horizon/workspace/logs directory, for messages related to the progress of the migration.

  • When the migration starts, the message The latest Audit schema version is 4. will be logged.

  • As each day’s data is migrated, messages starting with Re-indexing documents from will be logged.

  • When the migration finishes, the message Audit schema check completed. will be logged.

Until the migration is complete, none or only some of the old records will be available, so the dashboard and audit report will not show older records and search and autocomplete will not work. However, new audit records will be generated and processed, independent of the migration, so the dashboard and audit report should show new logins, etc. If new audit records do not appear in the audit report, check the health of the Elasticsearch cluster.

To check the health of the Elasticsearch cluster:

  1. ssh into any of the nodes and run the following command:

    curl http://localhost:9200/_cluster/health?pretty

    If the "status" field is "yellow" or "green", check the analytics-service log for errors. If the "status" field is "red", you must restart the master node.

  2. To restart the master node:

    1. Determine the master node by running the following command:

      curl http://localhost:9200/_cluster/state/master_node,nodes?pretty

    2. Look for the "master_node" field value and then find the matching value in the list of nodes to determine its IP address. For example, in this sample output the master node is "Gq-ITVBKRJKz1816XqrRKw", which has the IP address "1.1.1.2":

      {
         "cluster_name" : "horizon",
         "master_node" : "Gq-ITVBKRJKz1816XqrRKw",
         "nodes" : {
            "mzWHVMZuTXyFsO61NLpHnA" : {
               "name" : “Node1”,
               "transport_address" : “1.1.1.1:9300",
               "attributes" : { }
         },
         "Gq-ITVBKRJKz1816XqrRKw" : {
               "name" : “Node2”,
               "transport_address" : “1.1.1.2:9300",
               "attributes" : { }
         },
         "pkREX2D9R1a-lqf69PQMKQ" : {
               "name" : “Node3”,
               "transport_address" : “1.1.1.3:9300",
               "attributes" : { }
         }
      }
    3. ssh to the master node and restart Elasticsearch:

      service elasticsearch restart

    4. After Elasticsearch has restarted, check the cluster health again:

      curl http://localhost:9200/_cluster/health?pretty

      The command may show "yellow" status initially. Run the command again until it shows “green” status.

Elasticsearch Mapping Conflicts

Elasticsearch 2.3.5 in VMware Identity Manager 3.2.x does not start if there are mapping conflicts in any indices. If you did not delete indices that have mapping conflicts prior to upgrade, by following the procedure in Check for Elasticsearch Mapping Conflicts, Elasticsearch does not start.

The Elasticsearch log file, /opt/vmware/elasticsearch/logs/horizon.log, includes a message such as the following for the affected indices:

[2018-04-24 13:13:41,722][ERROR][bootstrap                ] Guice Exception: java.lang.IllegalStateException: unable to upgrade the mappings for the index [v3_2018-03-16], reason: [Mapper for [tenantId] conflicts with existing mapping in other types:

To resolve this issue, delete the indices manually from all VMware Identity Manager nodes.

  1. On all nodes, ensure that Elasticsearch is stopped:

    service elasticsearch stop

  2. On all nodes, remove the index files from the disk:

    rm -rf /db/elasticsearch/horizon/nodes/0/indices/<INDEX_NAME>

  3. On all nodes, restart Elasticsearch:

    service elasticsearch start

Search Does Not Work After Upgrade

After the upgrade, if audit reports and dashboards work but search does not work, the search index may not be correct.

During the upgrade, all the users, groups and applications are re-indexed into the new search index. If there were any issues with Elasticsearch such as the mapping conflicts issue, re-indexing may not happen correctly.

To resolve the issue, manually force a re-index either with the zero-down time option using the HZN cookie value or the down-time option by modifying the value directly in the database.

To manually force a re-index using the zero down-time option:

  1. Log in to the VMware Identity Manager service as the admin user, that is, the default administrator that is created in the System domain when you first install VMware Identity Manager.

  2. Obtain the value of the HZN cookie from your browser's cookie cache.

    For example, on Firefox:

    1. Navigate to Options > Privacy & Security.

    2. Under History, click the remove individual cookies link.

    3. In the Cookies dialog box, search for HZN.

    4. Select the HZN cookie in the search results, then copy its value from the Content field.

  3. ssh into any of the VMware Identity Manager nodes and make the following REST call, replacing <cookie_value> with the HZN cookie value obtained from the browser.

    /usr/local/horizon/bin/curl -k -XPUT -H "Authorization:HZN <cookie_value>" -H "Content-Type: application/vnd.vmware.horizon.manager.systemconfigparameter+json" https://localhost/SAAS/jersey/manager/api/system/config/SearchCalculatorMode -d '{ "name": "SearchCalculatorMode", "values": { "values": ["REINDEX"] } }'

To manually force a re-index using the down-time option:

  1. Stop the VMware Identity service on all nodes:

    service horizon-workspace stop

  2. Run the following command on any of the nodes:

    hznAdminTool reindexSearchData

  3. Restart the VMware Identity Manager service on all nodes:

    service horizon-workspace start

To verify that re-indexing has started, look in the /opt/vmware/horizon/workspace/logs/horizon.log file for a message such as the following:

com.vmware.horizon.search.SearchCalculatorLogic - Keep existing index. Search calculator mode is: REINDEX

Re-indexing should complete in a few minutes.

Log4j Configuration Files

If any log4j configuration files in a VMware Identity Manager instance were edited, new versions of the files are not automatically installed during the upgrade. However, after the upgrade, the logs controlled by those files will not work.

To resolve this issue:

  1. Log in to the virtual appliance.

  2. Search for log4j files with the .rpmnew suffix.

    find / -name "**log4j.properties.rpmnew"

  3. For each file found, copy the new file to the corresponding old log4j file without the .rpmnew suffix.

Cache Service Setting in Secondary Data Center Appliances

If you set up a secondary data center, VMware Identity Manger instances in the secondary data center are configured for read-only access with the "read.only.service = true" entry in the /usr/local/horizon/conf/runtime-config.properties file. After you upgrade such an appliance, the service fails to start.

To resolve this issue:

  1. Log in to the virtual appliance.

  2. Add the following line to the /usr/local/horizon/conf/runtime-config.properties file:

    cache.service.type = ehcache

  3. Restart the service.

    service horizon-workspace restart

Role Based Access Control

Role-based access control was introduced in VMware Identity Manager 3.2. For known issues, see the VMware Identity Manager 3.2 Release Notes.

Citrix Integration

For Citrix integration in VMware Identity Manager 3.2, all external connectors must be version 2018.1.1.0 (the connector version in the 3.2 release) or later.

You must also upgrade to Integration Broker 3.2 or later.

Changes in Past Releases

Changes in Version 3.1

  • Beginning with version 3.1, a new feature was introduced that changed the way user groups are synced. After you upgrade to VMware Identity Manager 3.1 or later, for all user groups already added prior to upgrade, ensure that entitlements are assigned. New user groups added after the upgrade are not synced to the VMware Identity Manager service until the group is entitled to a resource, added to an access policy rule, or, beginning with version 3.2, synced manually from the group's Group > Users page.

    If your entitlements are set to ALL USERS, users from new groups created after the upgrade will not be included if the users have not been synced yet. Add entitlements for the new groups.

    See How Group Sync Works after Upgrading to VMware Identity Manager 3.1 for more information.

  • If you integrate Citrix published resources with VMware Identity Manager 3.1, upgrade to Integration Broker 3.1. VMware Identity Manager 3.1 and VMware Identity Manager Connector 2017.12.1.0 (the connector version in the 3.1 release) require Integration Broker 3.1.

Changes in Version 3.0

  • If you integrate Citrix published resources with VMware Identity Manager, upgrade to Integration Broker 3.0. VMware Identity Manager 3.0 and VMware Identity Manager Connector 2017.8.1.0 (the connector version in the 3.0 release) are not compatible with older versions of the Integration Broker.

    Table 1. Supported Versions

    VMware Identity Manager or Connector Version

    Integration Broker Version Supported

    VMware Identity Manager 3.0

    3.0

    VMware Identity Manager Connector 2017.8.1.0 (Connector version in the VMware Identity Manager 3.0 release)

    3.0

    VMware Identity Manager 2.9.1 or earlier

    2.9.1 or earlier

    VMware Identity Manager Connector 2.9.1 or earlier

    2.9.1 or earlier

  • If you integrate Horizon desktops and applications in VMware Identity Manager and you have deployed a VMware Identity Manager cluster, you must configure Horizon integration again.

    • In the primary connector, where you saved and synced Horizon resources, remove all the Horizon pods, add them again, and click Save and Sync.

    • In the other connectors, where you saved the Horizon resources configuration, remove all the Horizon pods, add them again, and click Save.

Changes in Releases Prior to 3.0

  • Bulk sync changes in VMware Identity Manager 2.9.1 and later

    In earlier versions, bulk sync was processed with 4 threads per CPU through a global configuration parameter in the database named bulkSyncThreadLimitPerCPU=4.

    Beginning with version 2.9.1, the number of threads for bulk sync processing is not based on CPU. It is an absolute number, which is the same as the number of CPUs on a node by default.

    If you sync large numbers of users and groups and you notice that sync is slow after upgrade, you can specify the number of threads by setting the global configuration parameter called bulkSyncSharedThreadCount.

    Set the thread value in the database using the following REST API, then restart the nodes for the change to take effect.

    HTTP Request:

    Operation: PUT
    URI: bulkSyncSharedThreadCount

    HTTP Headers:

    Content-Type: application/vnd.vmware.horizon.manager.systemconfigparameter+json
    Accept: application/vnd.vmware.horizon.manager.systemconfigparameter+json
    Authorization: HZN <operator token>

    Request Body (with 8 threads as an example):

    {
        "name": "bulkSyncSharedThreadCount",
        "values": {
            "values": [
                "8"
            ]
        }
    }

  • Enable the new portal user interface.

    1. In the administration console, click the arrow on the Catalog tab and select Settings.

    2. Select New End User Portal UI in the left pane and click Enable New Portal UI.

  • If you have set up a VMware Identity Manager cluster for failover with two nodes, updating it to three nodes is recommended. This is because of a limitation of Elasticsearch, a search and analytics engine embedded in the VMware Identity Manager appliance. You may continue to use two nodes but you should be aware of a few limitations related to Elasticsearch. See "Configuring Failure and Redundancy" in Installing and Configuring VMware Identity Manager for more information.

  • Transport Layer Security (TLS) protocol 1.0 is disabled by default in VMware Identity Manager. TLS 1.1 and 1.2 are supported.

    External product issues are known to occur when TLS 1.0 is disabled. Updating your other product configurations to use TLS 1.1 or 1.2 is recommended. However, if these products have a dependence on TLS 1.0, you can enable TLS 1.0 in VMware Identity Manager by following the instructions in Knowledge Base article 2144805.