Upgrading to VMware Identity Manager 19.03.0.0 (Linux ... · VMware Identity Manager 19.03.0.0...

Upgrading to VMware Identity Manager 19.03.0.0 (Linux)

MAY 2019VMware Workspace ONE Access 19.03VMware Identity Manager 19.03

You can find the most up-to-date technical documentation on the VMware website at:

https://docs.vmware.com/

If you have comments about this documentation, submit your feedback to

[email protected]

VMware, Inc.3401 Hillview Ave.Palo Alto, CA 94304www.vmware.com

Copyright © 2019-2020 VMware, Inc. All rights reserved. Copyright and trademark information.


VMware, Inc. 2

https://docs.vmware.com/

mailto:[email protected]

http://pubs.vmware.com/copyright-trademark.html

Contents

About Upgrading to VMware Identity Manager 19.03.0.0 (Linux) 4

1 Overview of Upgrading to VMware Identity Manager 19.03.0.0 (Linux) 5Upgrading a Cluster 7

2 Upgrading VMware Identity Manager Online 8Prerequisites for Online Upgrade 9

Configure Proxy Server Settings for the VMware Identity Manager Appliance 12

Check for the Availability of a VMware Identity Manager Upgrade Online 13

Verifying F5 Load Balancer Configuration Before Upgrade 13

Perform an Online Upgrade to VMware Identity Manager 19.03.0.0 14

Performing an Online Upgrade to a Specific Version 16

3 Upgrading VMware Identity Manager Offline 18Prerequisites for Offline Upgrade 19

Using a Local Web Server for Offline Upgrade 22

Prepare a Local Web Server for Offline Upgrade 22

Configure the Appliance and Perform Offline Upgrade 23

Using the updateoffline.hzn Script for Offline Upgrade 25

4 Post-Upgrade Configuration 28Saving External Linux-Based Connector-Configuration Information 31

Perform Migration-Related Steps When Configuring the External Windows-Based Connector 32

5 Troubleshooting Upgrade Errors 37Checking the Upgrade Error Logs 37

Rolling Back to Snapshots of VMware Identity Manager 38

Collecting a Log File Bundle 38

Networking Error after Upgrade 39

"Certificate auth configuration update required" Error 39

Chain Upgrade Fails During the Preupdate Process 40

Upgrade with an External Connector Results in a Harmless NullPointerException Error 41

VMware, Inc. 3

About Upgrading to VMware Identity Manager 19.03.0.0 (Linux)

Upgrading to VMware Identity Manager 19.03.0.0 (Linux) describes how to upgrade Linux-based VMware Identity Manager™ to version 19.03.0.0 from earlier versions.

If you would prefer to do a fresh installation, see installing and Configuring VMware Identity Manager for 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 19.03.0.0.

Intended AudienceThis 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, Inc. 4

Overview of Upgrading to VMware Identity Manager 19.03.0.0 (Linux) 1The following upgrade paths and scenarios are supported.

Important Starting with VMware Identity Manager 19.03.0.0, the VMware Identity Manager service no longer includes an embedded connector and the external Linux-based connector is deprecated. New versions of the external Linux-based connector are no longer available.

If you are upgrading from a deployment that uses the embedded connector, you must switch to the external Windows-based connector. If you are using the external Linux-based connector, the best practice is to switch to the external Windows-based connector during this upgrade. Otherwise, you cannot use the newest functionality available in the updated connector. If you are using the external Windows-based connector, you can continue to use existing instances, but as a best practice upgrade the external Windows-based connector instances to enable the use of the newest functionality.

VMware Identity Manager 19.03.0.0 Windows connector does not support VMware ThinApp® packages. If your deployment provides access to ThinApp packages that you want to maintain, do not upgrade to VMware Identity Manager 19.03.0.0 Windows connector.

A migration package is available to you for migrating embedded-connector or external Linux-based-connector information to the external Windows-based connector.

When you run the migration package on the embedded-connector or external Linux-based-connector, all authentication methods, except for the Password authentication method, are disabled. The disablement allows configuration settings, such as the IP address of the connector, to be updated. After you install the corresponding Windows-based connector instances, you must re-enable the disabled authentication methods with the correct configuration settings.

VMware Identity Manager Version NumbersVMware Identity Manager is moving from a major.minor version-number model to a date-driven model represented by a year and month (yy.mm). This release is version 19.03.0.0. The previous version was 3.3.

VMware, Inc. 5

Supported Upgrade PathsThe following upgrade paths are supported:

n From version 3.2.0.1 or 3.3 directly to version 19.03.0.0.

Note To upgrade from a version prior to 3.2.0.1, you must first upgrade to version 3.2.0.1, and then upgrade from 3.2.0.1 to 19.03.0.0. When you perform an online upgrade, the latest version to which upgrade is permitted appears. If necessary, upgrade to the allowed version and then upgrade to 3.2.0.1.

Compatibility with Workspace ONE UEMVMware Product Interoperability Matrix provides details about the compatibility of current and previous versions of VMware products and components, such as VMware Workspace ONE UEM Console.

Internet ConnectivityYou can upgrade VMware Identity Manager online or offline.

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 Scenariosn If you have deployed a single VMware Identity Manager appliance, upgrade it online or offline as

described in Chapter 2 Upgrading VMware Identity Manager Online or Chapter 3 Upgrading VMware Identity Manager Offline.

Note Expect some downtime because all services are stopped during the upgrade. Plan the timing of your upgrade accordingly.

n If you have deployed multiple VMware Identity Manager virtual appliances in a cluster for failover or high availability, see Upgrading a Cluster.

n To upgrade VMware Identity Manager with minimal downtime in a multi-data center deployment scenario, see "Upgrading VMware Identity Manager with Minimal Downtime" in Installing and Configuring VMware Identity Manager.

This chapter includes the following topics:

n Upgrading a Cluster


VMware, Inc. 6

https://partnerweb.vmware.com/comp_guide2/sim/interop_matrix.php

Upgrading a ClusterIf 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 2 Upgrading VMware Identity Manager Online or Chapter 3 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.

6 After all the nodes are upgraded, add them back to the load balancer.


VMware, Inc. 7

Upgrading VMware Identity Manager Online 2You can upgrade the VMware Identity Manager virtual appliance online. The virtual appliance must be able to connect to the Internet for an online upgrade.


n Prerequisites for Online Upgrade

n Configure Proxy Server Settings for the VMware Identity Manager Appliance

n Check for the Availability of a VMware Identity Manager Upgrade Online

n Verifying F5 Load Balancer Configuration Before Upgrade

n Perform an Online Upgrade to VMware Identity Manager 19.03.0.0

n Performing an Online Upgrade to a Specific Version

VMware, Inc. 8

Prerequisites for Online UpgradeBefore you upgrade the VMware Identity Manager virtual appliance online, perform these prerequisite tasks.






Perform the following prerequisite tasks.

n Verify that at least 4 GB of disk space is available on the primary root partition of the virtual appliance.

n Back up the virtual appliance by taking a snapshot. For information about how to take snapshots, see the vSphere documentation.

n If you revoked the db_owner role on the Microsoft SQL database, as described in https://docs.vmware.com/en/VMware-Identity-Manager/3.3/vidm-install/GUID-5B533EE2-8F6C-4716-A94A-8B7AA3F5BC75.html, you must add it back before performing the upgrade, otherwise the upgrade fails.

Add the db_owner role to the same user that was used during installation:

a Log in to the Microsoft SQL Server Management Studio as a user with sysadmin privileges.

b Connect to the database instance for VMware Identity Manager.

c Enter the following commands.


VMware, Inc. 9

https://docs.vmware.com/en/VMware-Identity-Manager/3.3/vidm-install/GUID-5B533EE2-8F6C-4716-A94A-8B7AA3F5BC75.html



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 user name.

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.

n Take a snapshot or backup of the external database.

n Verify that VMware Identity Manager is properly configured.

n Verify that the virtual appliance can resolve and reach vapp-updates.vmware.com on ports 80 and 443 over HTTP.

n 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.

n 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.

n If the VMware Identity Manager deployment you are upgrading uses both the embedded connector and certificate-based authentication, take note of the settings for the CertificateAuthAdapter component configured in the embedded connector.

Note Because the embedded connector is no longer available, the CertificateAuthAdapter component configured in the embedded connector is also no longer available. The certificate (Cloud Deployment) authentication method replaces the CertificateAuthAdapter component. The migration process handles the conversion from the CertificateAuthAdapter component to the certificate (Cloud Deployment) authentication method.

Now, before the migration, take note of the settings in the CertificateAuthAdapter component, so after the migration you can verify that the pre-migration settings match the post-migration settings.

a Log in to the VMware Identity Manager admin console and select Identity & Access Management > Setup.

b On the Connectors page, select the Worker link for the embedded-connector instance being replaced.

c Click Auth Adapters and then click CertificateAuthAdapter.


VMware, Inc. 10

d Take note of the settings on the Certificate Service Auth Adapter page.

n Prepare the connector migration file.

To upgrade from a VMware Identity Manager version earlier than 19.03.0.0 to version 19.03.0.0 or later, download the migration package (cluster-support.tgz) from My VMware or My Workspace ONE to your existing VMware Identity Manager appliance under the /root directory.

The migration package must be present under the /root directory whether your current deployment uses the embedded connector or not. During the upgrade, a script in the migration package creates a cluster-hostname-conn-timestamp.enc file to which the script saves the embedded-connector configuration information.

If your current deployment uses the embedded connector, you can use the cluster...enc file when deploying the new external Windows-based connector by selecting the Are you migrating your Connector check box. The collected embedded-connector information, including directory and authentication methods, is migrated to the newly deployed external Windows-based connector. See the corresponding version of the Installing and Configuring VMware Identity Manager Connector (Windows) guide.

If your current deployment uses one or more instances of the external Linux-based connector, which is now deprecated, the best practice is to update your deployment to use the external Windows-based connector. New versions of the external Linux-based connector are not available and existing versions do not have updated functionality that the new external Windows-based connector has. To switch external Linux-based connector instances to the external Windows-based connector, download the migration package to each of the corresponding Linux hosts, and run the generateClusterFile.sh migration script. The script saves the configuration information from a specific external Linux-based connector instance to the cluster...enc configuration package file. See Saving External Linux-Based Connector-Configuration Information. To migrate collected external Linux-based connector-information to the external Windows-based connector, copy each cluster...enc file to a separate Windows host, and install a new Windows-based connector instance using the cluster...enc configuration package file. See the corresponding version of the Installing and Configuring VMware Identity Manager Connector (Windows) guide.

If your current deployment uses one or more instances of the external Windows-based connector, you can use the existing external Windows-based connector instances, but earlier external Windows-based connector instances are not up-to-date. To ensure full functionality of the external Windows-based connector, upgrade the connector instances. Upgrading external Windows-based connector instances does not require the use of the migration package. See the upgrade section of the corresponding Installing and Configuring VMware Identity Manager Connector (Windows) guide.

n If VMware Identity Manager is deployed in a load-balancing environment, verify that the environment is properly configured.

If you use an F5 load balancing server, when you upgrade to VMware Identity Manager 19.03.0.0, reconfigure the load balancer, if required. The requirement to reconfigure your F5 load balancing server depends on the version of VMware Identity Manager that you are upgrading from. To upgrade your F5 load balancing server, see Verifying F5 Load Balancer Configuration Before Upgrade.


VMware, Inc. 11

VMware Identity Manager Version Required Action

Earlier than 3.3 Reconfigure the F5 load balancing server according to the referenced instructions.

3.3 and later None. If you have an F5 load balancing server functioning with VMware Identity Manager 3.3 or later, the load balancing server is already appropriately configured.

Configure Proxy Server Settings for the VMware Identity Manager ApplianceThe 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.

To use a proxy server with VMware Identity Manager, when you install VMware Identity Manager, you configure VMware Identity Manager using the YaST utility. To upgrade VMware Identity Manager, you must now edit the proxy server settings by running specific vami commands in the VMware Identity Manager virtual appliance.

Note 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

n Verify that you have the root password for the virtual appliance. See Installing and Configuring VMware Identity Manager for information about creating passwords for administrator accounts.

n Verify that you have the proxy server information.

Procedure

1 Log in to the VMware Identity Manager virtual appliance as the root user.

2 Run the following command to set the proxy.

/opt/vmware/share/vami/vami_set_proxy proxyServer proxyPort

For example:

/opt/vmware/share/vami/vami_set_proxy proxy.mycompany.com 3128

3 Run the following command to verify the proxy settings.

/opt/vmware/share/vami/vami_proxy

4 If your proxy sever requires authentication, edit the /etc/environment configuration file and add the user name and password. For example:

http_proxy=http://username:[email protected]:3128


VMware, Inc. 12

5 Restart the Tomcat server on the VMware Identity Manager virtual appliance to use the new proxy settings.

service horizon-workspace restart

Results

The VMware update servers are now available to the VMware Identity Manager virtual appliance.

Check for the Availability of a VMware Identity Manager Upgrade OnlineIf your VMware Identity Manager appliance has Internet connectivity, 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

Verifying F5 Load Balancer Configuration Before UpgradeBefore you upgrade to the latest VMware Identity Manger service from version 3.2, verify that the F5 load balancing server is configured correctly.

Beginning with VMware Identity Manager 3.3, the host header cannot be null for health checks. Make sure that the F5 health check monitor created for VMware Identity Manager load balancing integration is configured to send the following string.

GET /SAAS/API/1.0/REST/system/health/heartbeat HTTP/1.1\r\nHost: your_workspace_url\r

\nConnection: Close\r\n\r\n

Beginning with VMware Identity Manager version 3.3, the VMware Identity Manager server and connector are configured to use only the following cipher suites. Make sure that your F5 server is configured with at least one of these cipher suites.

n TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384

n TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256

n TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384

n TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256

n TLS_DHE_RSA_WITH_AES_256_GCM_SHA384

n TLS_DHE_RSA_WITH_AES_128_GCM_SHA256

n TLS_DHE_RSA_WITH_AES_256_CBC_SHA256


VMware, Inc. 13

n TLS_DHE_RSA_WITH_AES_128_CBC_SHA256

n TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA

n TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA

Perform an Online Upgrade to VMware Identity Manager 19.03.0.0If your VMware Identity Manager virtual appliance has Internet connectivity, you can upgrade the appliance online.

Prerequisites

n You have met the prerequisites listed in Prerequisites for Online Upgrade.

n Verify that the virtual appliance is powered on and functioning.

Procedure


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.


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.

A message appears about migrating the embedded connector configuration.

5 Press the Enter key.

The system searches for the migration package (cluster-support.tgz) under the /root directory.

Downloading the package is a prerequisite step required to migrate the embedded connector configuration. This step is required if your current deployment uses the embedded connector or not. Starting with VMware Identity Manager 19.03.0.0, the connector is no longer embedded with the VMware Identity Manager, but available for external-Windows systems only.

A message appears about the cluster-support.tgz migration package.

n If the system cannot find the cluster-support.tgz package, the message states this fact. In this case, save the package under the /root location and run the update command again.


VMware, Inc. 14

n If the system finds the cluster-support.tgz package, it uncompresses the package, lists the files in the package, runs the generateClusterFile.sh file, and prompts you to create a configuration-package file password.

6 Create a configuration-package file password and respond to the additional prompts to save the embedded-connector configuration to the file.

Keep in mind that the embedded connector is on a Linux system. If you re migrating the embedded-connector configuration information, you must migrate the information to an external connector on a Windows system. The following settings might not apply to Linux and Windows systems equally, depending on the specifics of your deployment. Therefore, decide if you want to include the following configuration information or not.

Prompt Description

Would you like to include syslog settings?

If you want to copy the syslog-sever settings for the embedded Linux-based connector to the external Windows system, accept the default Y, for yes.

Otherwise, enter N, for no.

Would you like to include proxy settings?

If you want to copy the Proxy settings for the embedded Linux-based connector to the external Windows system, accept the default Y, for yes.


The system starts the upgrade of the VMware Identity Manager service and creates the .enc configuration-package file under the /root directory that starts with the name cluster, such as cluster-host-domain-conn-timestamp.enc. See the command output for the exact filename. This cluster...enc file contains the embedded-connector migration information. If you are migrating the embedded connector to an external connector, you must copy this file to the external Windows system. If you are not migrating the embedded connector, the best practice is to keep the cluster...enc file as a backup of the embedded-connector configuration in case the information is needed in the future.

After the upgrade finishes, the upgraded version of the VMware Identity Manager service no longer includes a functional embedded connector.

7 Run the updatemgr.hzn check command again to verify that a newer update does not exist.


8 Check the version of the upgraded appliance.

vamicli version --appliance

The new version is displayed.

9 Restart the virtual appliance.

reboot

Results

The upgrade is complete.


VMware, Inc. 15

See Chapter 4 Post-Upgrade Configuration.

Performing an Online Upgrade to a Specific VersionYou 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 VMware Identity Manager 19.03.0.0.

Prerequisites

n Ensure that you meet the prerequisites listed in Prerequisites for Online Upgrade.

n Verify that the virtual appliance is powered on and functioning.

Procedure


2 Run the following updatemgr.hzn command.


3 Run the following command to update the appliance to a specific version.

/usr/local/horizon/update/configureupdate.hzn provider --url https://vapp-updates.vmware.com/vai-

catalog/valm/vmw/5C08B358-F782-11E1-8F08-78776188709B/newVersion

where newVersion is the version to which you want to upgrade.n To upgrade to version 2.9.2.1, use:

/usr/local/horizon/update/configureupdate.hzn provider --url https://vapp-updates.vmware.com/

vai-catalog/valm/vmw/5C08B358-F782-11E1-8F08-78776188709B/2.9.2.1

n To upgrade to version 3.1, use:






n To upgrade to version 3.2.0.1, use:




VMware, Inc. 16





4 Check the version of the upgraded appliance.


The new version is displayed.

5 Restart the virtual appliance.

reboot

Results



VMware, Inc. 17

Upgrading VMware Identity Manager Offline 3If 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.


n Prerequisites for Offline Upgrade

n Using a Local Web Server for Offline Upgrade

n Using the updateoffline.hzn Script for Offline Upgrade

VMware, Inc. 18

Prerequisites for Offline UpgradeBefore you upgrade the VMware Identity Manager virtual appliance offline, perform these prerequisite tasks.






n Verify that at least 4 GB of disk space is available on the primary root partition of the virtual appliance.

n Take a snapshot of your virtual appliance to back it up. For information about how to take snapshots, see the vSphere documentation.

n If you revoked the db_owner role on the Microsoft SQL database, as described in https://docs.vmware.com/en/VMware-Identity-Manager/3.3/vidm-install/GUID-5B533EE2-8F6C-4716-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 Log in to the Microsoft SQL Server Management Studio as a user with sysadmin privileges.

b Connect to the database instance for VMware Identity Manager.

c 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. 19




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.

n Take a snapshot or backup of the external database.

n Verify that VMware Identity Manager is properly configured.

n Confirm that a VMware Identity Manager upgrade exists. Check the My VMware site at my.vmware.com for upgrades.

n If you are upgrading using the updateoffline.hzn script and your deployment includes a proxy server, disable the proxy server.

Disable the proxy server from the command line.

a Run the following command.

yast2

The YaST2 Control Center dialog box opens.

b Select Network services.

c Select Proxy.

The Proxy Configuration dialog box opens.

d If selected, deselect Enable proxy.

e Quit the YaST2 utility.

After a successful upgrade, enable the proxy server again.

n If the VMware Identity Manager deployment you are upgrading uses both the embedded connector and certificate-based authentication, take note of the settings for the CertificateAuthAdapter component configured in the embedded connector.

Note Because the embedded connector is no longer available, the CertificateAuthAdapter component configured in the embedded connector is also no longer available. The certificate (Cloud Deployment) authentication method replaces the CertificateAuthAdapter component. The migration process handles the conversion from the CertificateAuthAdapter component to the certificate (Cloud Deployment) authentication method.


VMware, Inc. 20

http://my.vmware.com

Now, before the migration, take note of the settings in the CertificateAuthAdapter component, so after the migration you can verify that the pre-migration settings match the post-migration settings.

a Log in to the VMware Identity Manager admin console and select Identity & Access Management > Setup.

b On the Connectors page, select the Worker link for the embedded-connector instance being replaced.

c Click Auth Adapters and then click CertificateAuthAdapter.

d Take note of the settings on the Certificate Service Auth Adapter page.

n Prepare the connector migration file.

To upgrade from a VMware Identity Manager version earlier than 19.03.0.0 to version 19.03.0.0 or later, download the migration package (cluster-support.tgz) from My VMware or My Workspace ONE to your existing VMware Identity Manager appliance under the /root directory.

The migration package must be present under the /root directory whether your current deployment uses the embedded connector or not. During the upgrade, a script in the migration package creates a cluster-hostname-conn-timestamp.enc file to which the script saves the embedded-connector configuration information.

If your current deployment uses the embedded connector, you can use the cluster...enc file when deploying the new external Windows-based connector by selecting the Are you migrating your Connector check box. The collected embedded-connector information, including directory and authentication methods, is migrated to the newly deployed external Windows-based connector. See the corresponding version of the Installing and Configuring VMware Identity Manager Connector (Windows) guide.

If your current deployment uses one or more instances of the external Linux-based connector, which is now deprecated, the best practice is to update your deployment to use the external Windows-based connector. New versions of the external Linux-based connector are not available and existing versions do not have updated functionality that the new external Windows-based connector has. To switch external Linux-based connector instances to the external Windows-based connector, download the migration package to each of the corresponding Linux hosts, and run the generateClusterFile.sh migration script. The script saves the configuration information from a specific external Linux-based connector instance to the cluster...enc configuration package file. See Saving External Linux-Based Connector-Configuration Information. To migrate collected external Linux-based connector-information to the external Windows-based connector, copy each cluster...enc file to a separate Windows host, and install a new Windows-based connector instance using the cluster...enc configuration package file. See the corresponding version of the Installing and Configuring VMware Identity Manager Connector (Windows) guide.


VMware, Inc. 21

If your current deployment uses one or more instances of the external Windows-based connector, you can use the existing external Windows-based connector instances, but earlier external Windows-based connector instances are not up-to-date. To ensure full functionality of the external Windows-based connector, upgrade the connector instances. Upgrading external Windows-based connector instances does not require the use of the migration package. See the upgrade section of the corresponding Installing and Configuring VMware Identity Manager Connector (Windows) guide.

n If VMware Identity Manager is deployed in a load-balancing environment, verify that the environment is properly configured.

If you use an F5 load balancing server, when you upgrade to VMware Identity Manager 19.03.0.0, reconfigure the load balancer, if required. The requirement to reconfigure your F5 load balancing server depends on the version of VMware Identity Manager that you are upgrading from. To upgrade your F5 load balancing server, see Verifying F5 Load Balancer Configuration Before Upgrade.

VMware Identity Manager Version Required Action

Earlier than 3.3 Reconfigure the F5 load balancing server according to the referenced instructions.

3.3 and later None. If you have an F5 load balancing server functioning with VMware Identity Manager 3.3 or later, the load balancing server is already appropriately configured.

Using a Local Web Server for Offline UpgradeIf 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 UpgradeBefore 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

n Obtain the identity-manager-19.03.0.0-buildNumber-updaterepo.zip file that is required to prepare a local Web server. Go to my.vmware.com and navigate to the VMware Identity Manager product download page to download the file.

n 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 http://YourWebServer/VM/ and copy the downloaded zip file to it.

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.


VMware, Inc. 22


3 Unzip the file.

The contents of the extracted ZIP file are served by http://YourWebServer/VM/.

The extracted contents of the file contain the following subdirectories: /manifest and /package-pool.

4 Run the following updatelocal.hzn command to check that the URL has valid update contents.

/usr/local/horizon/update/updatelocal.hzn checkurl http://YourWebServer/VM

Configure the Appliance and Perform Offline UpgradeConfigure 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 http://YourWebServer/VM/

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.


b Run the following command.

/usr/local/horizon/update/updatemgr.hzn update


A message appears about migrating the embedded connector configuration.


VMware, Inc. 23

c Press the Enter key.

The system searches for the migration package (cluster-support.tgz) under the /root directory.


A message appears about the cluster-support.tgz migration package.


n If the system finds the cluster-support.tgz package, it uncompresses the package, lists the files in the package, runs the generateClusterFile.sh file, and prompts you to create a password.

d Create a password and respond to the additional prompts to save the embedded-connector configuration to a file.

Keep in mind that the embedded connector is on a Linux system. If you re migrating the embedded-connector-configuration information, you must migrate the information to an external connector on a Windows system. The following settings might not apply to Linux and Windows systems equally, depending on the specifics of your deployment. Therefore, decide if you want to include the following configuration information or not.

Prompt Description







The system starts the upgrade of the VMware Identity Manager service and creates a .enc migration file under the /root directory that starts with the name cluster, such as cluster-host-domain-conn-timestamp.enc. See the command output for the exact filename. This file contains the embedded-connector-migration information. If you are migrating the embedded connector to an external connector, you must copy this file to the external Windows system. If you are not migrating the embedded connector, the best practice is to keep the cluster...enc file as a backup of the embedded-connector configuration in case the information is needed in the future.



VMware, Inc. 24

e Run the updatemgr.hzn check command again to verify that a newer update does not exist.


f Check the version of the upgraded appliance.


The command should display the new version.

g Restart the virtual appliance.

For example, from the command line run the following command.

reboot

Results


See Chapter 4 Post-Upgrade Configuration.

Using the updateoffline.hzn Script for Offline UpgradeYou 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.

Prerequisites

Perform the prerequisites. See Prerequisites for Offline Upgrade.

Procedure

1 Locate the updateoffline.hzn script.

The script is available at the following path:

/usr/local/horizon/update/updateoffline.hzn

2 Download the VMware Identity Manager offline upgrade package, identity-manager-19.03.0.0-buildNumber-updaterepo.zip, 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. 25


-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/identity-manager-19.03.0.0-buildNumber-updaterepo.zip

4 If the "The product RID matches so continue" prompt appears, press Enter to continue.

5 If you did not use the -r option with the script, restart the virtual appliance after upgrade is complete.

reboot

6 Respond appropriately to the migration-related prompts as the script performs the following actions.

n Searches for the migration package (cluster-support.tgz) under the /root directory and prompts you accordingly.



n If the system finds the cluster-support.tgz package, it uncompresses the package, lists the files in the package, runs the generateClusterFile.sh file, and prompts you to create a configuration-package file password. Provide a configuration-package file password.

n Prompts you for syslog and proxy settings.

Keep in mind that the embedded connector is on a Linux system. If you re migrating the embedded-connector configuration information, you must migrate the information to an external connector on a Windows system. The following settings might not apply to Linux and Windows systems equally, depending on the specifics of your deployment. Therefore, decide if you want to include the following configuration information or not.

Prompt Description








VMware, Inc. 26

The system starts the upgrade of the VMware Identity Manager service and creates a .enc migration file under the /root directory that starts with the name cluster, such as cluster-host-domain-conn-timestamp.enc. See the command output for the exact filename. This file contains the embedded-connector-migration information. If you are migrating the embedded connector to an external connector, you must copy this file to the external Windows system. If you are not migrating the embedded connector, the best practice is to keep the cluster...enc file as a backup of the embedded-connector configuration in case the information is needed in the future.



VMware, Inc. 27

Post-Upgrade Configuration 4After you upgrade to VMware Identity Manager 19.03.0.0, you might need to configure certain settings.

Log4j Configuration FilesIf any log4j configuration files in a VMware Identity Manager 19.03 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.

Save the Workspace ONE UEM ConfigurationSaving the Workspace ONE UEM configuration populates the Device Services URL for the catalog. Perform this task to allow new end users to enroll and manage their devices.

1 Log in to the administration console.

2 Select Identity & Access Management > Setup > VMware Workspace ONE UEM.

3 In the Workspace ONE UEM Configuration section, click Save.

Cluster ID in Secondary Data CenterBeginning with VMware Identity Manager 3.3, cluster IDs are used to identify the nodes in a cluster.

If your VMware Identity Manager 19.03 deployment includes a secondary data center, you might need to change the cluster ID of the secondary data center after upgrade.

VMware Identity Manager detects and assigns a cluster ID automatically when a new service appliance is powered up. For a multiple data center deployment, each cluster must be identified with a unique ID.

All appliances that belong to a cluster have the same cluster ID and a cluster typically consists of three appliances.

VMware, Inc. 28

When you set up the secondary data center, verify that the cluster ID is unique to the data center. If a cluster ID is not unique to the data center, verify that each node has the Elasticsearch discovery-idm plugin installed and edit the cluster ID manually as described in the instructions that follow. You only need to perform these actions once and only on the secondary data center.

1 Verify that each node has the Elasticsearch discovery-idm plugin.

a Log in to the virtual appliance.

b Use the following command to check if the plugin is installed.

/opt/vmware/elasticsearch/bin/plugin list

c If the plugin does not exist, use the following command to add it.

/opt/vmware/elasticsearch/bin/plugin install file:///opt/vmware/

elasticsearch/jars/discovery-idm-1.0.jar

2 Log in to the administration console.

3 Select the Dashboard > System Diagnostics Dashboard tab.

4 In the top panel, locate the cluster information for the secondary data center cluster.

5 Update the cluster ID of all the nodes in the secondary data center to a different number than the one used in the first data center.

For example, set all the nodes in the secondary data center to 2, if the first data center is not using 2.

6 Verify that the clusters in both the primary and secondary data centers are formed correctly.

Follow these steps for each node in the primary and secondary data centers.

a Log in to the virtual appliance.

b Run the following command:

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

If the cluster is configured correctly, the command returns a result similar to the following example:

{

"cluster_name" : "horizon",

"status" : "green",

"timed_out" : false,

"number_of_nodes" : 3,

"number_of_data_nodes" : 3,

"active_primary_shards" : 20,

"active_shards" : 40,

"relocating_shards" : 0,


VMware, Inc. 29

"initializing_shards" : 0,

"unassigned_shards" : 0,

"delayed_unassigned_shards" : 0,

"number_of_pending_tasks" : 0,

"number_of_in_flight_fetch" : 0

}

Cache Service Setting in Secondary Data Center AppliancesIf you set up a secondary data center, VMware Identity Manager 19.03 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, perform the steps that follow. The steps include an example scenario of a secondary data center containing the following three nodes.

sva1.example.com

sva2.example.com

sva3.example.com

1 Log in to a virtual appliance in the secondary data center as the root user.

For this example, log in to sva1.example.com.

2 Edit the /usr/local/horizon/conf/runtime-config.properties file as indicated in the substeps that follow.

You might be able to edit an existing entry, or you can add a new entry. If applicable, uncomment entries that are commented out.

a Set the value of the cache.service.type entry to ehcache.

cache.service.type=ehcache

b Set the value of the ehcache.replication.rmi.servers entry to the fully qualified domain names (FQDN) of the other nodes in the secondary data center. Use a colon : as the separator.

For this example, configure the entry as follows.

ehcache.replication.rmi.servers=sva2.example.com:sva3.example.com

3 Restart the service.

service horizon-workspace restart

4 Repeat the preceding steps on the remaining nodes in the secondary data center.

For this example, the remaining nodes to configure are sva2.example.com and sva3.example.com.


VMware, Inc. 30

Citrix IntegrationFor Citrix integration in VMware Identity Manager 3.3, all external connectors must be version 2018.8.1.0 for Linux (the connector version in the 3.3 release) or later.

You must also use Integration Broker 3.3. Upgrade is not available for Integration Broker. Uninstall the old version, then install the new version.

Changes in Past ReleasesFor changes in past releases, see Upgrading to VMware Identity Manager 3.3 (Linux).


n Saving External Linux-Based Connector-Configuration Information

n Perform Migration-Related Steps When Configuring the External Windows-Based Connector

Saving External Linux-Based Connector-Configuration InformationTo facilitate the move to external Windows-based connectors, you can migrate the configuration information from external Linux-based connectors to external Windows-based connectors.

If you used one or more external Linux-based connector instances for a version of VMware Identity Manager earlier than 19.03.0.0 and upgraded to version 19.03.0.0 or later, you must now use external Windows-based connector instances.

If you want to migrate the configuration information from external Linux-based connector instances, you must collect the configuration information from each external Linux-based connector instance separately.

Prerequisites

Download the cluster-support.tgz cluster-migration package from My VMware or My Workspace ONE to an instance of the connector virtual appliance whose configuration information you plan to collect for migration purposes. Save the file under the /root directory.

Procedure

1 As a root user, log in to an instance of the connector virtual appliance whose configuration information you plan to collect for migration purposes.

2 Run a command at the location to which you saved the cluster-support.tgz file that uncompresses the file, such as the following command.

tar xvfz cluster-support.tgz

The command extracts two files, one of which is the generateClusterFile.sh file.


VMware, Inc. 31

https://docs.vmware.com/en/VMware-Workspace-ONE-Access/3.3/identitymanager-upgrade.doc/GUID-58C1E237-86CF-4DD8-ACC6-0D761218E15B.html

3 Run the generateClusterFile.sh script with a command that creates a password, such as the following command.

./generateClusterFile.sh password

Replace password with a password of at least eight characters of your own creation. You need the password later to migrate the external Linux-based connector-configuration information when you configure the corresponding external Windows-based connector.

The command creates cluster...enc, an encrypted file that contains the external Linux-based connector configuration information.

What to do next

To transfer the external Linux-based connector-configuration information in cluster...enc file instances to instances of the external Windows-based connector, download each cluster...enc file to a respective Windows host before you install VMware Identity Manager connector on the Windows system. Use information in Perform Migration-Related Steps When Configuring the External Windows-Based Connector to supplement the instructions in the corresponding version of the Installing and Configuring VMware Identity Manager Connector (Windows) guide.

Perform Migration-Related Steps When Configuring the External Windows-Based ConnectorTake the following actions when migrating embedded-connector or external Linux-based connector configuration information during external Windows-based connector installation and configuration. See the corresponding version of the Installing and Configuring VMware Identity Manager Connector (Windows) guide.

The Installing and Configuring VMware Identity Manager Connector (Windows) guide describes how to install and configure the external Windows-based connector. Use the information that follows to supplement that guide. Taking these specific actions ensures the following.

n The transfer of the connector-configuration information from the embedded-connector or from the external Linux-based connector to the external Windows-based connector.

n The configuration of settings disconnected during the upgrade of VMware Identity Manager or not handled by the migration.

Prerequisites

n Collect a cluster...enc file for each embedded-connector and external Linux-based connector instance that you plan to use to migrate connector-configuration information during the installation and configuration of the replacement external Windows-based connector instances.

n Save each cluster...enc file to a corresponding Windows system that will host a replacement external Windows-based connector instance.


VMware, Inc. 32

Procedure

u When running the VMware Identity Manager Connector Installation Wizard, respond appropriately to the migration-related dialog boxes.

a When prompted for the configuration package file, select Are you migrating your Connector? and click Next.

b Respond as necessary for the system to locate the cluster...enc file that you saved to the host and click Next.

Dialog Box Item Action

Config Package (.enc) Enter or browse to the location of the cluster...enc file that you saved to the host.

Password Enter the password you created for the cluster...enc file when you upgraded VMware Identity Manager.


VMware, Inc. 33

c When prompted to launch the VMware Identity Manager connector setup wizard or not, click No to exit the installation.

In this situation, clicking No is appropriate because the migrated configuration information from the cluster...enc file completes the configuration for you. Clicking Yes is necessary when you must access the admin console to finish the connector setup configuration.

d Use the Windows Services manager to restart the VMware Identity Manager Connector service.

Services is an administrative tool included with the Windows operating system.

1 Open the Windows Services manager.

2 Wait until the status of the VMware IDM Connector service appears as Running.

3 Restart the VMware IDM Connector service.

u Log in to the VMware Identity Manager admin console, select the Identity & Access Management > Setup, and verify and reconfigure the connector settings.

a Verify that the new external Windows-based connector instance is listed on the Connectors page.

The existence of the new external Windows-based connector instance on the Connectors page confirms that it is paired with VMware Identity Manager.

b Delete the connector instance that the new external Windows-based connector instance is replacing, by clicking the Delete icon next to the connector instance you want to delete and clicking Confirm.

The connector instance is removed from the VMware Identity Manager admin console.

Caution Delete all VMware Identity Manager connector instances that you are replacing. The existence of connector instances that are no longer in use can interfere with VMware Identity Manager processes, especially directory-related processes, such as sync and save.


VMware, Inc. 34

u If the VMware Identity Manager deployment that you upgraded from used both the embedded connector and certificate-based authentication, verify that the settings from the CertificateAuthAdapter component were properly migrated to the newly created certificate (Cloud Deployment) authentication method.

If this scenario applies to you, a prerequisite step to upgrading VMware Identity Manager was to take note of the settings for the CertificateAuthAdapter component. Use that information to verify that the pre-migration settings in the CertificateAuthAdapter component match the post-migration settings in the certificate (Cloud Deployment) authentication method.

a On the Identity & Access Management tab, select Manage > Authentication Methods.

b In the Certificate (Cloud Deployment) Configure column, click the pencil icon.

c Review and, if necessary, edit the settings on the Certificate Service Auth Adapter page.

u To verify and reconfigure applicable directories as necessary, on the Identity & Access Management tab, click Manage and perform the appropriate directory-related steps.

Caution Before configuring directories, confirm that all connector instances that were migrated and are now unused are deleted. The existence of connector instances that are no longer in use can interfere with directory-related processes.

a Click Sync Now next to each directory that applies.

b Perform any necessary edits based on updates made to applicable directories and click Sync Directory.

u On the Manage page, click Identity Providers, click the name of an affected identity provider instance, and update the IdP Hostname value.

Because of unpredictable factors in determining the host used, for example because a load balancer is deployed, the migration process does not attempt to update the IdP Hostname value.

Consider the following situations.

n If you used a load balancer for your connector instances before the migration and continue to use that load balancer, the IdP Hostname value does not change. In such a case, do not update the IdP Hostname value. Instead you must adjust the load balancer to use the new Windows-based connector instances as the load-balancer members.

n If you used the URL of a connector instance before the migration, therefore you did not use a load balancer, update the IdP Hostname value accordingly.

For more information on configuring identity provider instances, see the VMware Identity Manager Administration guide.

a Click the name of an identity provider instance for which the IdP Hostname value must be updated.

b On the Identity Provider page, change the host name in the IdP Hostname text box and click Save.


VMware, Inc. 35

u Enable applicable authentication methods.

When you ran the migration package on the embedded-connector or the external Linux-based-connector, all authentication methods, except for the Password authentication method were disabled. Now you must re-enable the disabled authentication methods on the external Windows-based connector.

See Installing and Configuring VMware Identity Manager Connector (Windows) guide for information about enabling authentication adapters for the connector.

u If applicable, enable outbound mode for the new external Windows-based connector.

Before the migration, if outbound mode was not enabled for the connector, for example outbound mode is not an embedded-connector option, you probably want to enable outbound mode for the new external Windows-based connector.

The procedure involves adding the new external Windows-based connector to the Built-in identity provider and configuring policies for each authentication method enabled. See Installing and Configuring VMware Identity Manager Connector (Windows) guide for information about enabling outbound mode for the connector.


VMware, Inc. 36

Troubleshooting Upgrade Errors 5You 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.


n Checking the Upgrade Error Logs

n Rolling Back to Snapshots of VMware Identity Manager

n Collecting a Log File Bundle

n Networking Error after Upgrade

n "Certificate auth configuration update required" Error

n Chain Upgrade Fails During the Preupdate Process

n Upgrade with an External Connector Results in a Harmless NullPointerException Error

Checking the Upgrade Error LogsResolve 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.

VMware, Inc. 37

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 ManagerIf VMware Identity Manager does not start properly after an upgrade, you can roll back to a previous instance.

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 BundleYou 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 5-1. Log Files

Component Location of Log File Description

Apache Tomcat Logs (catalina.log)

/opt/vmware/horizon/workspace/logs/

catalina.log

Apache Tomcat records messages that are not recorded in other log files.

Configurator Logs (configurator.log)


configurator.log

Requests that the Configurator receives from the REST client and the Web interface.

Connector Logs /opt/vmware/horizon/workspace/logs/

connector.log

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.


connector-dir-sync.log

Messages related to directory sync.


VMware, Inc. 38

Table 5-1. Log Files (continued)

Component Location of Log File Description

Service Logs (horizon.log) /opt/vmware/horizon/workspace/logs/

horizon.log

The service log records activity that takes place on the VMware Identity Manager appliance, such as activity related to entitlements, users, and groups.

Unified Catalog Logs (greenbox_web.log)


greenbox_web.log

Records activity related to the unified catalog.

Procedure

1 Log in to the VMware Identity Manager appliance configuration page at https://identitymanagerURL:8443/cfg/logs.

2 Click Prepare log bundle.

3 Download the bundle.

Networking Error after UpgradeAfter you upgrade the virtual appliance and reboot, a networking error occurs.

Problem

After you upgrade the appliance, the following error message appears:

NO NETWORKING DETECTED. PLEASE LOGIN AND RUN THE COMMAND

/opt/vmware/share/vami/vami_config_net TO CONFIGURE THE NETWORK

Solution

1 Roll back to the snapshot you created before upgrading the virtual appliance.

2 Either log in to the virtual appliance as the root user or log in as the sshuser and run the su command to switch to super user.

3 Navigate to the following directory:

/etc/sysconfig/networking/devices

4 Back up the ifcfg-eth0 file to another directory.

5 Upgrade the virtual appliance but do not restart it.

6 Restore the ifcfg-eth0 file to the /etc/sysconfig/networking/devices directory.

7 Restart the virtual appliance:

reboot

"Certificate auth configuration update required" ErrorUpgrade fails with a "Certificate auth configuration update required" error.


VMware, Inc. 39

Problem

When you try to upgrade to VMware Identity Manager 19.03.0.0, the following error message appears and upgrade is aborted.

Certificate auth configuration update required for tenant <tenantName> prior to upgrade.

Pre-update check failed, aborting upgrade.

Cause

This problem occurs if certificates for the CertificateAuthAdapter were last added or updated prior to version 3.0.

Solution

1 Log in to the VMware Identity Manager console.

2 Navigate to Identity & Access Management > Setup.

3 In the Connectors page, click the link in the Worker column.

4 Click the Auth Adapters tab, then click CertificateAuthAdapter.

5 In the Uploaded CA Certificates section, click the red X to remove the certificate.

6 Click Save.

7 In the Root and intermediate CA certificates section, click Select File to add the certificate back.

8 Click Save.

9 Return to the virtual appliance console and run the upgrade commands again.

Chain Upgrade Fails During the Preupdate ProcessA chain upgrade creates multiple instances of the bc-fips-1.0.x.BC-FIPS-Certified.jar file, which causes an upgrade to fail during the preupdate process.

Problem

When you try to upgrade to VMware Identity Manager, the following error message appears and the upgrade aborts.

Please validate database permissions and try upgrade again

The pre-update process failed, upgrade aborted.

Cause

Performing a series of VMware Identity Manager upgrades might result in the creation of a bc-fips-1.0.0.BC-FIPS-Certified.jar file and a bc-fips-1.0.1.BC-FIPS-Certified.jar. The existence of both files at the same time causes the upgrade to fail.


VMware, Inc. 40

Solution

1 Go to the /usr/local/horizon/jre-endorsed/ directory.

2 If both the bc-fips-1.0.0.BC-FIPS-Certified.jar file and the bc-fips-1.0.1.BC-FIPS-Certified.jar exist, delete the older version, bc-fips-1.0.0.BC-FIPS-Certified.jar, and perform the upgrade again.

Upgrade with an External Connector Results in a Harmless NullPointerException ErrorAn upgrade of a VMware Identity Manager deployment on Linux that includes an external VMware Identity Manager connector might result in a NullPointerException error message.

Problem

When you issue the /usr/local/horizon/update/updatemgr.hzn update command, the command output might include a java.lang.NullPointerException error.

Solution

1 Ignore the NullPointerException error message.

The upgrade succeeds as indicated at the end of the command output.

2 Proceed to reboot the virtual appliance as instructed.


VMware, Inc. 41

Upgrading to VMware Identity Manager 19.03.0.0 (Linux ... · VMware Identity Manager 19.03.0.0...

Documents

Transcript of Upgrading to VMware Identity Manager 19.03.0.0 (Linux ... · VMware Identity Manager 19.03.0.0...