Upgrading Virtual Appliance

This article guides you through the process of preparing and executing Virtual Appliance upgrade:
cislp143
This article guides you through the process of preparing and executing Virtual Appliance upgrade:
 
 
Supported Upgrade Paths
Upgrade to CA Identity Suite Virtual Appliance 14.3.0 is supported from the following releases:
  • CA Identity Suite Virtual Appliance 14.0.0 (any CP level)
  • CA Identity Suite Virtual Appliance 14.0.1 (any CP level)
  • CA Identity Suite Virtual Appliance 14.1.0 (any CP level)
  • CA Identity Suite Virtual Appliance 14.2.0 (any CP level)
Upgrade to 14.3.0 is only supported for systems that are already part of a deployed solution.
Upgrading an undeployed 14.0, 14.1 or 14.2 Virtual Appliance node is not supported. Instead, you should terminate it and should install a fresh Virtual Appliance 
14.3.0
 node.
Upgrade Overview
When you are upgrading to 14.3.0, the upgrade installer upgrades the following products in the given order on the Virtual Appliance node:
  • Virtual Appliance platform, O/S security updates, and web-UI
  • CA Directory
  • CA Identity Manager
  • CA Provisioning Server
  • CA Connector Server
  • CA Identity Portal
  • CA Identity Governance
 
Note: 
The installer upgrades a single node at a time. For systems with multiple nodes, you must run the installer on each node.
As part of the upgrade process, the services are stopped on all the Virtual Appliance nodes. You must
 schedule a maintenance window
 for the upgrade during which no user traffic is directed to the solution.
Upgrade Prerequisites
Before you upgrade Virtual Appliance, review the prerequisites that are detailed in this section:
Backups
Before you upgrade, perform the following actions:
  1. Take a full backup of the databases/schemas used by CA Identity Manager, CA Identity Governance, and CA Identity Portal.
    A database backup is mandatory for rollback!
  2. Back up CA Identity Manager environment (IME). To take a backup, navigate to 
    CA Identity Manager management console
    Environments
    identityEnv
    Export
    .
  3. Back up any custom files on the file-system. The custom files can be found at /opt/CA/VirtualAppliance/custom/<product name>.
  4. Take a snapshot of the Virtual Machine.
Disk Space Requirements
The upgrade requires at least 
15GB
 of free disk space on the "/" volume on each node.
Run the following command to check free space on the "/" volume:
df -h /
For example:
 Filesystem            Size Used Avail Use% Mounted on
                               47G   26G    
19G
   58 percent          /
In case a node does not have 15GB of disk space, either 
delete the log files
 or 
resize the Virtual Disk
 to free disk space:
  • Delete log files
     
    1. Navigate to 
      /opt/CA/VirtualAppliance/logs/.
       
    2. Delete unnecessary log files to reclaim disk space.
  • Resize the Virtual Disk
     
    In case deletion of log files is undesirable or insufficient to reclaim enough free disk space, you may resize the Virtual Disk:
    1. Turn off the server.
    2. Ask the ESX administrator to extend the primary Virtual Disk that is assigned to the Virtual Machine.
      Note:
       You may ask the ESX administrator to add an extra (non-primary) disk to the Virtual Machine, or to extend the size of a non-primary disk that is already added to the Virtual Machine.
    3. Power on the server.
    4. Run the 
      resizeDisk
       command.
      Note:
       If the ESX administrator added an extra (non-primary) disk to the Virtual Machine, you must run the 
      addDisk
       command instead.
OOTB Environment Objects Upgrade
Due to a limitation of Identity Manager, an upgrade from 14.x to 14.3 overwrites OOTB objects that were changed in the new version (Roles and Tasks, Screens, BLTH, LAH) and resets these objects to a default OOTB state. To avoid the potential impact of such overwrite, you must always copy the OOTB objects and customize the copy.
During an upgrade, the following objects in the Identity Manager configuration will be overwritten with default values. 
Roles and tasks
AdminRole
 
System Manager
BusinessLogicTaskHandler
 
BlthDisplayUserID
ImsRole
 
Use Cases - Self, Runtime Manager, Email Manager, Offline Endpoint Manager, Inbound Filter Manager, Use Case Service Admin, Onboard Manager, Endpoint Group Manager
ImsTask
 
CreateWorkflowTemplate, DeleteWorkflowTemplate, ModifyWorkflowTemplate, ViewWorkflowTemplate, ConfigureGlobalPolicyBasedWorkflow, ForgottenLoginID, OfflineEndpointTasks, CleanupCompletedTasks, CreateEmail, ModifyEmail, DeleteEmail, ViewEmail, ConfigureTaskResubmissionPolicy, TaskPersistenceMonitor, ResubmitTasks, GenerateSyntheticTransactions, OfflineOnlineEndpoint, EndpointOfflineStatusReminder, ApproveModifyUseCase, ModifyUseCase, TransferDocumentOwnership, ViewUseCase, CreateAdminTask, ModifyAdminTask, ViewAdminTask, OnboardAccount, CreateExploreAndCorrelate, ModifyExploreAndCorrelate, ViewExploreAndCorrelate, DeleteExploreAndCorrelate, ExecuteEAC, CreateEndpointGroup, ViewEndpointGroup, ModifyEndpointGroup, DeleteEndpointGroup, DoSynchUserRoles, ModifyUserEndpointAccounts, HandleOrphanAccounts, HandleSystemAccounts, ProvisioningDeleteUser
Screen
 
OfflineEndpointSearchScreen, DefaultUserSearch, EnableDisableUserSearch, DefaultUserList, DefaultAccessRoleSearch, CreateUserProfile, DefaultUserProfile, MyUserProfile, ApproveDeleteUserProfile, DefaultProvisioningRoleSearch, RequestUserProfile, ReportServerConnectionProfile, ResetUserPasswordProfile, ChangeMyPasswordProfile, SelfRegistrationProfile, ForgottenPasswordSearch, ForgottenPasswordIdentify, ForgottenPasswordVerify, ForgottenUserIDSearch, ForgottenLoginIDSearch, SearchEmails, ManageUsersSearch, TransferOwnershipUserProfile, ServiceAccessRequestMembershipSearch, DefaultAdminTaskSearch, DefaultWorkflowTemplateSearch, SearchUseCase, ModifyUseCaseProfileTab, ViewUseCaseProfileTab, EmailUseCaseHandlerSearch, PolicyUseCaseHandlerSearch, AdminTaskUseCaseSearchHandler, AdminRoleUseCaseSearchHandler, BulkTaskUseCaseSearchHandler, DefaultExploreAndCorrelateDefinitionSearch, OnboardAccountSearch
Environment Settings
LogicalAttributeHandler
 
Alternate Login ID Handler, Date Display Handler, ForgottenPasswordHandler, Generic LAH Handler, Temporary Password Handler, Unique ID Handler, User Full Name Handler, User ID Build Handler
In case you have customized these objects, you will need to re-apply your customizations after the upgrade. The list of objects that will be overwritten by the upgrade process are listed in the following file(s):
  • Roles and Tasks: /home/config/compare-roles-and-tasks.XXXX
  • Environment Settings: /home/config/compare-roles-and-tasks.XXXX
After the upgrade process completes, you can perform the OOTB tasks and screens restore by creating a .xml file, copying the desired xml content from the backup file, and importing the .xml file to 
CA Identity Manager
 Management Console.
Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Requirement - for customers upgrading from Virtual Appliance 14.0.x
CA Identity Suite requires Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy.
If you are upgrading from 14.0.x, you must download the JCE package (
jce_policy-8.zip
) from the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files 8 Download page.
Using an SCP utility, upload the contained 
local_policy.jar
 and 
US_export_policy.jar
 to 
/opt/CA/VirtualAppliance/custom/jce/ 
on 
each Virtual Appliance node.
 
Note:
 You can also upload to /opt/CA/jdk1.8.0_71/jre/lib/security/.
Enable XA Transactions
For customers using CA Identity Governance on Microsoft SQL database, you must enable XA transactions on the database. For more information, see Install XA.
For Customers using CA Single Sign-On (formerly CA SiteMinder)
Configure three host records in the hosts file on all CA Single Sign-On Policy Servers
.
The hostname records are named
 ca-prov-srv, 
 
ca-prov-srv-01, and
 
ca-prov-srv-primary
 and must point to any Virtual Appliance based Provisioning Server in the deployment.
For example
10.0.0.20 ca-prov-srv ca-prov-srv-01 ca-prov-srv-primary
Perform an Upgrade
 
Review the following notes before performing an upgrade.
  • The installer upgrades a single node at a time. For systems with multiple nodes, you must run the installer on each node.
  • Upgrade the Virtual Appliance nodes one after the other. Only when a Virtual Appliance node is upgraded, proceed with the next node upgrade.
  • For systems with a custom Provisioning Server domain, see Deployments with Custom Provisioning Server Domain (Migrated Environments).
  • During an upgrade, solution health checks performed by the dashboard may return various errors. This is expected behavior since during the upgrade, services are being stopped and started - all dashboard errors and warnings during the upgrade are safe to ignore.
  • For Virtual Appliance 14.1 users:
    • We recommend executing upgrade from within a "screen" session. This is accomplished by running "screen" followed by <RETURN> before running the "patch_vapp" command
      Screen sessions are terminal sessions allowing to resume a disconnected session (Example, a terminal session is used in a case where an upgrade operation may disconnect due to a network issue).
    • To resume a disconnected screen session, perform the steps below:
      • Open a new SSH or CLI session to the node on which the terminal session disconnected.
      • Run the following command:
        screen -x
         
 
Follow these steps to perform an Upgrade:
 
  1. Download patch 
    IS_GA-140300.tgz.gpg
     from the given links:
  2. For your reference the file size and checksum are listed below:
    1. Size:
       3,853,205,583 bytes
    2. Checksum: 
      A5D735F4B67ABAD61A10E103CEC5053E
  3. Using SCP software, copy the patch files to all the Virtual Appliance nodes.
  4. Review the upgrade prerequisites.
  5. We recommend that all nodes in the Virtual Appliance solution are powered-on before starting the upgrade and that all services are started (you may inspect the monitoring dashboard to ensure it does not report any errors).
    You may inspect the monitoring dashboard from web-UI or from the command line by running the "
    s
    " command.
  6. Perform the upgrade as detailed on "
    Run the below commands to start the patch upgrade process
    " on all nodes.
     
  7. Start by upgrading a node that has the
     CA Identity Manager
     
     
    service deployed
  8. Run the below commands to start the patch upgrade process:
    1. Customers running Virtual Appliance 14.0 with no Cumulative Patches installed:
      upgrade_vapp GA-140300.tgz.gpg
       
    2. All other customers:
      patch_vapp GA-140300.tgz.gpg
       
    The installation may take up to 90 minutes on each node, depending on hardware performance and the number of services deployed on the node.
    The following message signifies that the node was successfully upgraded:
    [OK] patch "<path>/
    GA-140300.tgz.gpg
    " successfully installed!
  9. Continue by upgrading all remaining nodes that have CA Identity Manager service deployed (if applicable) one after the other until all CA Identity Manager nodes are upgraded.
  10. After all the nodes which are running CA Identity Manager were upgraded, proceed to upgrade additional nodes (if applicable) one after the other.
Post Upgrade
Post upgrade, ensure that all services have started. You can examine the status of a service in the Virtual Appliance dashboard.
If services have not started, start them manually and review the corresponding product log files.
Master Password
Starting from Virtual Appliance 14.1, the system is shipped with no default passwords.
Instead, a 
Master Password
 set by the user (when the Virtual Appliance 14.1 (or higher) solution is deployed for the first time) is used to manage user accounts of newly deployed services when they are deployed for the first time.
When upgrading a 14.0.x Virtual Appliance to 14.3, the existing admin passwords for all deployed products will be retained.However, upon the next deployment operation in the Virtual Appliance web-UI → Setup page, you will be prompted for a 
Master Password
.
This master password is used to set the default password for the following newly deployed services:
 
  1. Management password for newly deployed 
    CA Identity Portal
     nodes
  2. Management password for newly deployed 
    Connector Server
     nodes
Existing services on previously deployed nodes have their management passwords retained.
Deployments with Custom Provisioning Server Domain (Migrated Environments)
When the Provisioning Server domain is different from the domain that comes by default - “
im
”, you must perform the following steps:
  1. Before the upgrade, 
    export
     the existing Provisioning Directory definition (Example, ProvStore) to an XML file.
  2. The upgrade overwrites the Provisioning Directory domain. As a result, CA Identity Manager environment (IME) fails to start after the upgrade.
  3. After the upgrade, perform the following steps to restore the Provisioning Directory definition from backup:
    1. Navigate to the CA Identity Manager Management console
    2. Click 
      Directories
      ProvStore
      .
    3. Click 
      Update
      .
    4. Browse and select the backed-up file.
    5. Click 
      Next
      .
    6. Click 
      Finish
      .
    7. Restart the environment and ensure that the startup is successful.