Upgrading to VMware Identity Manager (Linux) MAY 2018 VMware Identity Manager 3.2

Transcription

1 Upgrading to VMware Identity Manager (Linux) MAY 2018 VMware Identity Manager 3.2

2 You can find the most up-to-date technical documentation on the VMware website at: If you have comments about this documentation, submit your feedback to VMware, Inc Hillview Ave. Palo Alto, CA Copyright 2018 VMware, Inc. All rights reserved. Copyright and trademark information. VMware, Inc. 2

3 Contents Upgrading to VMware Identity Manager (Linux) 4 1 About Upgrading to VMware Identity Manager (Linux) 5 Upgrading a Cluster 6 2 Check for Elasticsearch Mapping Conflicts 8 3 Upgrading VMware Identity Manager Online 10 Prerequisites for Online Upgrade 10 Configure Proxy Server Settings for the VMware Identity Manager Appliance 11 Check for the Availability of a VMware Identity Manager Upgrade Online 12 Perform an Online Upgrade to the Latest Version 12 Performing an Online Upgrade to a Specific Version 13 4 Upgrading VMware Identity Manager Offline 15 Prerequisites for Offline Upgrade 15 Using a Local Web Server for Offline Upgrade 16 Using the updateoffline.hzn Script for Offline Upgrade 18 5 Post-Upgrade Configuration 20 6 Troubleshooting Upgrade Errors 28 Checking the Upgrade Error Logs 28 Rolling Back to Snapshots of VMware Identity Manager 28 Collecting a Log File Bundle 29 VMware, Inc. 3

4 Upgrading to VMware Identity Manager (Linux) Upgrading to VMware Identity Manager (Linux) describes how to upgrade the Linux-based VMware Identity Manager virtual appliance to version from earlier versions. If you would prefer to do a fresh installation, see VMware Identity Manager Installation and Configuration (Linux) and Deploying VMware Identity Manager in the DMZ. Remember that a new installation does not preserve your existing configurations. For information about upgrading VMware Identity Manager on Windows, see Upgrading to VMware Identity Manager for Windows Intended Audience This information is intended for anyone who installs, upgrades, and configures VMware Identity Manager. The information is written for experienced system administrators who are familiar with virtual machine technology. VMware Technical Publications Glossary VMware Technical Publications provides a glossary of terms that might be unfamiliar to you. For definitions of terms as they are used in VMware technical documentation, go to VMware, Inc. 4

5 About Upgrading to VMware Identity Manager (Linux) 1 The following upgrade paths and scenarios are supported. Supported Upgrade Paths The following upgrade paths are supported: From version 3.1 or 3.2 to version To upgrade from a version prior to 3.1, you must first upgrade to version 3.1 or 3.2, and then upgrade from 3.1 or 3.2 to When you perform an online upgrade, the latest version to which upgrade is permitted appears. Upgrade to the allowed version and then upgrade to Compatibility with AirWatch If you upgrade to AirWatch 9.2.x or later, you must also upgrade VMware Identity Manager to version 3.x. AirWatch 9.2.x and later are not compatible with earlier versions of VMware Identity Manager. You can use VMware Identity Manager 3.x with earlier versions of AirWatch. Using the latest available version of the products is recommended. Elasticsearch Migration 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 During the upgrade to VMware Identity Manager 3.2.x, Elasticsearch records are migrated. Before you upgrade to version 3.2.x, see: Chapter 2 Check for Elasticsearch Mapping Conflicts Chapter 5 Post-Upgrade Configuration Internet Connectivity You can upgrade VMware Identity Manager online or offline. VMware, Inc. 5

6 By default, the VMware Identity Manager appliance uses the VMware web site for the upgrade procedure, which requires the appliance to have Internet connectivity. You must also configure proxy server settings for the appliance, if applicable. If your virtual appliance does not have Internet connectivity, you can perform the upgrade offline. For an offline upgrade, you download the upgrade package from My VMware. You can either use the updateoffline.hzn script to perform the upgrade or set up a local Web server to host the upgrade file. Upgrade Scenarios If you have deployed a single VMware Identity Manager appliance, upgrade it online or offline as described in Chapter 3 Upgrading VMware Identity Manager Online or Chapter 4 Upgrading VMware Identity Manager Offline. Note Expect some downtime because all services are stopped during the upgrade. Plan the timing of your upgrade accordingly. If you have deployed multiple VMware Identity Manager virtual appliances in a cluster for failover or high availability, see Upgrading a Cluster. To upgrade VMware Identity Manager with no downtime in a multi-data center deployment scenario, see "Upgrading VMware Identity Manager with No Downtime" in Installing and Configuring VMware Identity Manager. Upgrading a Cluster If you have deployed multiple VMware Identity Manager virtual appliances in a cluster for failover or high availability, you can upgrade the nodes one at a time. Expect some downtime during upgrade and plan the timing of your upgrade accordingly. Procedure 1 Take snapshots of the database and the VMware Identity Manager nodes. 2 Remove all nodes except one from the load balancer. 3 Upgrade the node that is still connected to the load balancer. Follow the process for an online or offline upgrade, as described in Chapter 3 Upgrading VMware Identity Manager Online or Chapter 4 Upgrading VMware Identity Manager Offline. Important Expect some downtime during the upgrade process. 4 After the node is upgraded, leave it connected to the load balancer. This ensures that the VMware Identity Manager service is available while you upgrade the other nodes. 5 Upgrade the other nodes one at a time. VMware, Inc. 6

7 6 Verify that RabbitMQ is not running in cluster mode in the upgraded nodes. In and later releases, RabbitMQ clustering has been disabled. Follow these commands for each upgraded node. a b Log in to the upgraded node. Run the following command: rabbitmqctl cluster_status The command should return status similar to the following: sva-1:~ # rabbitmqctl cluster_status Cluster status of node 'rabbitmq@sva-1'... [{nodes,[{disc,['rabbitmq@sva-1']}]}, {running_nodes,['rabbitmq@sva-1']}, {cluster_name,<<"rabbitmq@sva-1.hs.trcint.com">>}, {partitions,[]}, {alarms,[{'rabbitmq@sva-1',[]}]}] c If the status includes references to any node other than the one on which you ran the rabbitmqctl cluster_status command, run the following commands: 1 Stop RabbitMQ. rabbitmqctl stop_app 2 Reset RabbitMQ rabbitmqctl force_reset 3 Start RabbitMQ. rabbitmqctl start_app 7 After all the nodes are upgraded, add them back to the load balancer. VMware, Inc. 7

8 Check for Elasticsearch 2 Mapping Conflicts 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 During the upgrade to VMware Identity Manager 3.2.x, Elasticsearch records are migrated. Before you upgrade to VMware Identity Manager 3.2.x, check for indices that have mapping conflicts and delete them to avoid problems after upgrade. Elasticsearch does not start if it finds any mapping conflicts. If you choose not to delete the indices that have mapping conflicts prior to upgrade as described in this procedure, after upgrade you must delete the indices manually from all VMware Identity Manager nodes. See Chapter 5 Post-Upgrade Configuration for information. Note This information applies to upgrade to version 3.2.x from previous versions. It does not apply to upgrade from 3.2 to Procedure 1 Install the migration plugin on one of the VMware Identity Manager nodes: export JAVA_HOME=/usr/java/jre-vmware /opt/vmware/elasticsearch/bin/plugin -i migration -u service elasticsearch restart 2 View the Elasticsearch log file: tail -f /opt/vmware/elasticsearch/logs/horizon.log Look for the message that verifies that the migration sites plugin was loaded, such as the following: [ :28:03,593][INFO ][plugins ] [Crusader] loaded [discovery-idm], sites [migration] VMware, Inc. 8

9 3 Wait until Elasticsearch is up. Messages similar to the following appear: [ :28:13,282][INFO ][node ] [Crusader] started [ :29:16,468][INFO ][gateway ] [Crusader] recovered [91] indices into cluster_state 4 Temporarily allow port 9200 to be accessible from the outside to allow access to the plugin via a browser. a Edit the /usr/local/horizon/conf/iptables/elasticsearch file and add "9200" to the ELASTICSEARCH_tcp_all entry. After you make the changes, the file should be similar to the following: ELASTICSEARCH_tcp_all="9200" ELASTICSEARCH_tcp_vapp="9300" ELASTICSEARCH_udp_all="" ELASTICSEARCH_udp_vapp="" b Apply the new iptables rule by running the following script: /usr/local/horizon/scripts/updateiptables.hzn 5 Run the migration report. a b In a browser, go to where <ES_NODE_FQDN> is the fully-qualified domain name of the VMware Identity Manager node on which you installed the migration plugin. Click the Run checks now button. 6 View the migration report and look for red indices. Indices that are red because they are closed are expected items on the report and can be ignored. Any indices that are red for any reason other than that they are closed, for example, due to mapping conflicts, need to be deleted. Use the following command to delete the indices: curl -XDELETE 7 Block port 9200 again. a b Edit the /usr/local/horizon/conf/iptables/elasticsearch file and set ELASTICSEARCH_tcp_all to "". Run the following script: /usr/local/horizon/scripts/updateiptables.hzn VMware, Inc. 9

10 Upgrading VMware Identity Manager Online 3 You can upgrade the VMware Identity Manager virtual appliance online. The virtual appliance must be able to connect to the Internet for an online upgrade. This chapter includes the following topics: Prerequisites for Online Upgrade Configure Proxy Server Settings for the VMware Identity Manager Appliance Check for the Availability of a VMware Identity Manager Upgrade Online Perform an Online Upgrade to the Latest Version Performing an Online Upgrade to a Specific Version Prerequisites for Online Upgrade Before you upgrade the VMware Identity Manager virtual appliance online, perform these prerequisite tasks. Verify that at least 4 GB of disk space is available on the primary root partition of the virtual appliance. Take a snapshot of your virtual appliance to back it up. For information about how to take snapshots, see the vsphere documentation. If you revoked the db_owner role on the Microsoft SQL database, as described in A94A-8B7AA3F5BC75.html, you must add it back before performing the upgrade, otherwise upgrade will fail. Add the db_owner role to the same user that was used during installation: a b c Log in to the Microsoft SQL Server Management Studio as a user with sysadmin privileges. Connect to the database instance for VMware Identity Manager. Enter the following commands. If you are using Windows Authentication mode, use the following commands: USE <saasdb>; ALTER ROLE db_owner ADD MEMBER <domain\username>; GO VMware, Inc. 10

11 Make sure that you replace <saasdb> with your database name and <domain\username> with the relevant domain and username. If you are using SQL Server Authentication mode, use the following commands: USE <saasdb>; ALTER ROLE db_owner ADD MEMBER <loginusername>; GO Make sure that you replace <saasdb> with your database name and <loginusername> with the relevant username. Take a snapshot or backup of the external database. Verify that VMware Identity Manager is properly configured. Verify that the virtual appliance can resolve and reach vapp-updates.vmware.com on ports 80 and 443 over HTTP. If an HTTP proxy server is required for outbound HTTP access, configure the proxy server settings for the virtual appliance. See Configure Proxy Server Settings for the VMware Identity Manager Appliance. Confirm that a VMware Identity Manager upgrade exists. Run the appropriate command to check for upgrades. See Check for the Availability of a VMware Identity Manager Upgrade Online. Before you upgrade, check for Elasticsearch mapping conflicts. See Chapter 2 Check for Elasticsearch Mapping Conflicts. Configure Proxy Server Settings for the VMware Identity Manager Appliance The VMware Identity Manager virtual appliance accesses the VMware update servers through the Internet. If your network configuration provides Internet access using an HTTP proxy, you must adjust the proxy settings for the appliance. Enable your proxy to handle only Internet traffic. To ensure that the proxy is set up correctly, set the parameter for internal traffic to no-proxy within the domain. Prerequisites Verify that you have the root password for the virtual appliance. Verify that you have the proxy server information. Procedure 1 Log in to the VMware Identity Manager virtual appliance as the root user. 2 Enter YaST on the command line to run the YaST utility. 3 Select Network Services in the left pane, then select Proxy. 4 Enter the proxy server URLs in the HTTP Proxy URL and HTTPS Proxy URL fields. VMware, Inc. 11

12 5 Select Finish and exit the YaST utility. 6 Restart the Tomcat server on the VMware Identity Manager virtual appliance to use the new proxy settings. service horizon-workspace restart The VMware update servers are now available to the VMware Identity Manager virtual appliance. Check for the Availability of a VMware Identity Manager Upgrade Online If your VMware Identity Manager virtual appliance can connect to the Internet, you can check for the availability of upgrades online from the appliance. Procedure 1 Log in to the virtual appliance as the root user. 2 Run the following command to check for an online upgrade. /usr/local/horizon/update/updatemgr.hzn check Perform an Online Upgrade to the Latest Version If your VMware Identity Manager virtual appliance has Internet connectivity, you can upgrade the appliance online. Use these commands to upgrade to the latest available version. To upgrade to a specific version instead of the latest available version, see Performing an Online Upgrade to a Specific Version. Prerequisites Ensure that you meet the prerequisites listed in Prerequisites for Online Upgrade. Verify that the virtual appliance is powered on and functioning. Procedure 1 Log in to the VMware Identity Manager virtual appliance as the root user. 2 Run the following updatemgr.hzn command. /usr/local/horizon/update/updatemgr.hzn updateinstaller 3 Run the following command to check that on online upgrade exists. /usr/local/horizon/update/updatemgr.hzn check VMware, Inc. 12

13 4 Run the following command to update the appliance. /usr/local/horizon/update/updatemgr.hzn update Messages that occur during the upgrade are saved to the update.log file at /opt/vmware/var/log/update.log. 5 Run the updatemgr.hzn check command again to verify that a newer update does not exist. /usr/local/horizon/update/updatemgr.hzn check 6 Check the version of the upgraded appliance. vamicli version --appliance The new version is displayed. 7 Restart the virtual appliance. reboot The upgrade is complete. Performing an Online Upgrade to a Specific Version You can perform an online upgrade of the VMware Identity Manager service to a specific version instead of the latest available version, if required. Note To upgrade to the latest available version, see Perform an Online Upgrade to the Latest Version. Prerequisites Ensure that you meet the prerequisites listed in Prerequisites for Online Upgrade. Verify that the virtual appliance is powered on and functioning. Procedure 1 Log in to the VMware Identity Manager virtual appliance as the root user. 2 Run the following updatemgr.hzn command. /usr/local/horizon/update/updatemgr.hzn updateinstaller 3 Run the following command to update the appliance to a specific version. /usr/local/horizon/update/configureupdate.hzn provider --url VMware, Inc. 13

14 where newversion is the version to which you want to upgrade. To upgrade to version , use: /usr/local/horizon/update/configureupdate.hzn provider --url To upgrade to version 3.1, use: /usr/local/horizon/update/configureupdate.hzn provider --url To upgrade to version 3.2, use: /usr/local/horizon/update/configureupdate.hzn provider --url To upgrade to version , use: /usr/local/horizon/update/configureupdate.hzn provider --url Messages that occur during the upgrade are saved to the update.log file at /opt/vmware/var/log/update.log. 4 Check the version of the upgraded appliance. vamicli version --appliance The new version is displayed. 5 Restart the virtual appliance. reboot The upgrade is complete. VMware, Inc. 14

15 Upgrading VMware Identity 4 Manager Offline If your VMware Identity Manager virtual appliance cannot connect to the Internet for upgrade, you can perform an offline upgrade. Two options are available for offline upgrade. You can set up an upgrade repository on a local Web server and configure the appliance to use the local Web server for upgrade. Or you can download the upgrade package to the VMware Identity Manager server and use the updateoffline.hzn script to upgrade. This chapter includes the following topics: Prerequisites for Offline Upgrade Using a Local Web Server for Offline Upgrade Using the updateoffline.hzn Script for Offline Upgrade Prerequisites for Offline Upgrade Before you upgrade the VMware Identity Manager virtual appliance offline, perform these prerequisite tasks. Verify that at least 4 GB of disk space is available on the primary root partition of the virtual appliance. Take a snapshot of your virtual appliance to back it up. For information about how to take snapshots, see the vsphere documentation. If you revoked the db_owner role on the Microsoft SQL database, as described in A94A-8B7AA3F5BC75.html, you must add it back before performing the upgrade, otherwise upgrade will fail. Add the db_owner role to the same user that was used during installation: a b c Log in to the Microsoft SQL Server Management Studio as a user with sysadmin privileges. Connect to the database instance for VMware Identity Manager. Enter the following commands. VMware, Inc. 15

16 If you are using Windows Authentication mode, use the following commands: USE <saasdb>; ALTER ROLE db_owner ADD MEMBER <domain\username>; GO Make sure that you replace <saasdb> with your database name and <domain\username> with the relevant domain and username. If you are using SQL Server Authentication mode, use the following commands: USE <saasdb>; ALTER ROLE db_owner ADD MEMBER <loginusername>; GO Make sure that you replace <saasdb> with your database name and <loginusername> with the relevant username. Take a snapshot or backup of the external database. Verify that VMware Identity Manager is properly configured. Confirm that a VMware Identity Manager upgrade exists. Check the My VMware site at my.vmware.com for upgrades. Before you upgrade, check for Elasticsearch mapping conflicts. See Chapter 2 Check for Elasticsearch Mapping Conflicts. Using a Local Web Server for Offline Upgrade If you want to perform the offline upgrade using a local Web server, prepare the Web server to host the upgrade file, configure the VMware Identity Manager appliance to point to the Web server, and perform the upgrade. Prepare a Local Web Server for Offline Upgrade Before you start the offline upgrade, set up the local Web server by creating a directory structure that includes a subdirectory for the VMware Identity Manager virtual appliance. Prerequisites Download the identity-manager buildnumber-updaterepo.zip file from the VMware Identity Manager product download page on my.vmware.com. If you use an IIS Web server, configure the Web server to allow special characters in file names. You configure this in the Request Filtering section by selecting the Allow double escaping option. Procedure 1 Create a directory on the Web server at and copy the downloaded zip file to it. VMware, Inc. 16

17 2 Verify that your Web server includes mime types for.sig (text/plain) and.sha256 (text/plain). Without these mime types your Web server fails to check for updates. 3 Unzip the file. The contents of the extracted ZIP file are served by The extracted contents of the file contain the following subdirectories: /manifest and /packagepool. 4 Run the following updatelocal.hzn command to check that the URL has valid update contents. /usr/local/horizon/update/updatelocal.hzn checkurl Configure the Appliance and Perform Offline Upgrade Configure the VMware Identity Manager appliance to point to the local Web server to perform an offline upgrade. Then upgrade the appliance. Prerequisites Prepare a Local Web Server for Offline Upgrade. Procedure 1 Log in to the VMware Identity Manager appliance as the root user. 2 Run the following command to configure an upgrade repository that uses a local Web server. /usr/local/horizon/update/updatelocal.hzn seturl Note To undo the configuration and restore the ability to perform an online upgrade, you can run the following command. /usr/local/horizon/update/updatelocal.hzn setdefault 3 Perform the upgrade. a Run the following updatemgr.hzn command. /usr/local/horizon/update/updatemgr.hzn updateinstaller b Run the following command. /usr/local/horizon/update/updatemgr.hzn update Messages that occur during the upgrade are saved to the update.log file at /opt/vmware/var/log/update.log. VMware, Inc. 17

18 c Run the updatemgr.hzn check command again to verify that a newer update does not exist. /usr/local/horizon/update/updatemgr.hzn check d Check the version of the upgraded appliance. vamicli version --appliance The command should display the new version. e Restart the virtual appliance. For example, from the command line run the following command. reboot The upgrade is complete. Using the updateoffline.hzn Script for Offline Upgrade You can use the updateoffline.hzn script to perform an offline upgrade of the VMware Identity Manager virtual appliance. Download the offline upgrade package from the VMware Identity Manager product download page to use with the script. The script verifies that the upgrade package matches the product. For example, if you are upgrading the VMware Identity Manager service virtual appliance and you use the connector upgrade package instead of the service upgrade package, the script results in an error. Procedure 1 Locate the updateoffline.hzn script. In versions 3.1 and 3.2, the script is available from the following path: /usr/local/horizon/update/updateoffline.hzn Note To use the script with a version earlier than 3.1, you can download the updateoffline.hzn script from KB article on 2 Download the identity-manager buildnumber-updaterepo.zip file from the VMware Identity Manager product download page on my.vmware.com. The recommended location for saving the file is /var/tmp. 3 Run the updateoffline.hzn script as the root user. /usr/local/horizon/update/updateoffline.hzn [-r] -f upgradefilepath VMware, Inc. 18

19 -f upgradefilepath Upgrade the appliance using upgradefilepath. upgradefilepath must be an absolute path. Required -r Reboot after upgrade. Optional -h Displays the script usage. Optional For example: /usr/local/horizon/update/updateoffline.hzn -f /var/tmp/identitymanager updaterepo.zip 4 If you did not use the -r option with the script, restart the virtual appliance after upgrade is complete. reboot VMware, Inc. 19

20 Post-Upgrade Configuration 5 After you upgrade to VMware Identity Manager , 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 After you upgrade to VMware Identity Manager 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. 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 VMware, Inc. 20

21 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 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 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: a Determine the master node by running the following command: curl b 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 " ": { "cluster_name" : "horizon", "master_node" : "Gq-ITVBKRJKz1816XqrRKw", "nodes" : { "mzwhvmzutxyfso61nlphna" : { "name" : Node1, "transport_address" : :9300", VMware, Inc. 21

22 } "attributes" : { } }, "Gq-ITVBKRJKz1816XqrRKw" : { "name" : Node2, "transport_address" : :9300", "attributes" : { } }, "pkrex2d9r1a-lqf69pqmkq" : { "name" : Node3, "transport_address" : :9300", "attributes" : { } } c ssh to the master node and restart Elasticsearch: service elasticsearch restart d After Elasticsearch has restarted, check the cluster health again: curl The command may show "yellow" status initially. Run the command again until it shows green status. Elasticsearch Mapping Conflicts Elasticsearch 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 Chapter 2 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: [ :13:41,722][ERROR][bootstrap ] Guice Exception: java.lang.illegalstateexception: unable to upgrade the mappings for the index [v3_ ], 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 VMware, Inc. 22

23 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: a b c d Navigate to Options > Privacy & Security. Under History, click the remove individual cookies link. In the Cookies dialog box, search for HZN. 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" -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 VMware, Inc. 23

24 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. VMware, Inc. 24

25 Citrix Integration For Citrix integration in VMware Identity Manager 3.2, all external connectors must be version (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 (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 (the connector version in the 3.0 release) are not compatible with older versions of the Integration Broker. Table 5 1. Supported Versions VMware Identity Manager or Connector Version Integration Broker Version Supported VMware Identity Manager VMware Identity Manager Connector (Connector version in the VMware Identity Manager 3.0 release) VMware Identity Manager or earlier VMware Identity Manager Connector or earlier or earlier 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. VMware, Inc. 25

26 Changes in Releases Prior to 3.0 Bulk sync changes in VMware Identity Manager 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. a b In the administration console, click the arrow on the Catalog tab and select Settings. 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. VMware, Inc. 26

27 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 VMware, Inc. 27

28 Troubleshooting Upgrade Errors 6 You can troubleshoot upgrade problems by reviewing the error logs. If VMware Identity Manager does not start, you can revert to a previous instance by rolling back to a snapshot. This chapter includes the following topics: Checking the Upgrade Error Logs Rolling Back to Snapshots of VMware Identity Manager Collecting a Log File Bundle Checking the Upgrade Error Logs Resolve errors that occur during upgrade by reviewing the error logs. Upgrade log files are in the /opt/vmware/var/log directory. Problem After the upgrade finishes, VMware Identity Manager does not start and errors appear in the error logs. Cause Errors occurred during upgrade. Solution 1 Log in to the VMware Identity Manager virtual appliance. 2 Go to the directory located at /opt/vmware/var/log. 3 Open the update.log file and review the error messages. 4 Resolve the errors and rerun the upgrade command. The upgrade command resumes from the point where it stopped. Note Alternatively, you can revert to a snapshot and run the upgrade again. Rolling Back to Snapshots of VMware Identity Manager If VMware Identity Manager does not start properly after an upgrade, you can roll back to a previous instance. VMware, Inc. 28

29 Problem After you upgrade VMware Identity Manager, it does not start correctly. You reviewed the upgrade error logs and ran the upgrade command again but it did not resolve the issue. Cause Errors occurred during the upgrade process. Solution u Revert to one of the snapshots you took as a backup of your original VMware Identity Manager instance and external database, if applicable. For information, see the vsphere documentation. Collecting a Log File Bundle You can collect a bundle of log files. You obtain the bundle from the VMware Identity Manager appliance configuration page. The following log files are collected in the bundle. Table 6 1. Log Files Component Location of Log File Description Apache Tomcat Logs (catalina.log) Configurator Logs (configurator.log) Connector Logs (connector.log) Service Logs (horizon.log) Unified Catalog Logs (greenbox_web.log) /opt/vmware/horizon/workspace/logs/catal ina.log /opt/vmware/horizon/workspace/logs/confi gurator.log /opt/vmware/horizon/workspace/logs/conne ctor.log /opt/vmware/horizon/workspace/logs/horiz on.log /opt/vmware/horizon/workspace/logs/green box_web.log Apache Tomcat records messages that are not recorded in other log files. Requests that the Configurator receives from the REST client and the Web interface. A record of each request received from the Web interface. Each log entry also includes the request URL, timestamp, and exceptions. No sync actions are recorded. The service log records activity that takes place on the VMware Identity Manager appliance, such as activity related to entitlements, users, and groups. Records activity related to the unified catalog. Procedure 1 Log in to the VMware Identity Manager appliance configuration page at /cfg/logs. 2 Click Prepare log bundle. 3 Download the bundle. VMware, Inc. 29