How to customize the application using customizeACM.sh in RSA Identity Governance & Lifecycle

[#1]

Article Number

000038700

Applies To

RSA Product Set: RSA Identity Governance & Lifecycle
RSA Version/Condition: 7.0.x, 7.1.x, 7.2.x
Platform/Application Server: WildFly
 

Issue

You can customize RSA Identity Governance & Lifecycle by modifying the aveksa.ear file. Since the aveksa.ear file is redeployed each time the server starts, the .ear file must be modified for the changes to persist. RSA provides a utility called customizeACM.sh that allows you to extract an aveksa.ear file and use the utility to rebuild a customized version. This utility resides in $AVEKSA_HOME/deploy in versions 7.0.x and 7.1.x. Starting in 7.2.0 this utility resides in $AVEKSA_HOME/deploy/ACM-scripts. This utility uses the $AVEKSA_HOME/archive directory to store archived aveksa.ear files that have been deployed and to maintain information about the currently deployed aveksa.ear file.

The RSA Identity Governance & Lifecycle Installation Guide for your version under the section entitled Customize RSA Identity Governance and Lifecycle explains how to use the customizeACM.sh utlity. The purpose of this RSA Knowledge Base Article is to explain how to use this utility in more detail with sample output.
 

Resolution

The process of customizing RSA Identity Governance & Lifecycle consists of unpacking the.ear file, adding customized files, and repacking and deploying the customized .ear. Customizations should consist of new files or drivers and make no changes to existing RSA files. This ensures that customizations persist through patch upgrades. The patch process unpacks the ear and overwrites RSA files only while leaving any added customized files alone. When the .ear file is repackaged and deployed, the customizations are persisted.

The following parameters can be passed to the customizeACM.sh script. (To see a complete list of available parameters, execute customizeACM.sh without passing any parameters.)
 

-l, -- list
List the files in the archive directory

-c, -- customize
Expands the ear file into a temporary directory where you can customize the content. Optionally specify the fullname and path of the ear file to be customized. If you do not specify the name of the ear file, you will be prompted.

-d, --deploy
Repackages the .ear from the temporary directory and deploys it.
 

Starting in 7.2.0, customizeACM.sh is in the ACM-scripts subdirectory of the $AVEKSA_HOME/deploy directory. The following example taken from a 7.2.0 system, illustrates the customization process step by step.

1. Login as the oracle user.
2. Verify that RSA Identity Governance & Lifecycle is running. 

$ acm status

If RSA Identity Governance & Lifecycle is not running, start it up and check the status again.

$ acm start
$ acm status

3. Go to the $AVEKSA_HOME/deploy/ACM-scripts directory and run customizeACM.sh -l to list the files in the $AVEKSA_HOME/archive directory.

$ cd $AVEKSA_HOME/deploy/ACM-scripts
$ ./customizeACM.sh -l

Archived Files:

/home/oracle/archive/Archive_README.txt
/home/oracle/archive/DO_NOT_REMOVE_ARCHIVE_FILES.txt
/home/oracle/archive/aveksa_7.2.0_176311-2020-Apr-07-16.22.ear
/home/oracle/archive/aveksa_7.2.0_176311-2020-Feb-14-15.40.ear
/home/oracle/archive/wildfly_deployment.properties

4.   List the contents of the wildfly_deployment.properties file to determine which .ear file in the list is the one currently deployed. 

$ cat $AVEKSA_HOME/archive/wildfly_deployment.properties
CURRENTLY_DEPLOYED_ARCHIVE=aveksa_7.2.0_176311-2020-Apr-07-16.22.ear
INITIAL_ARCHIVE=aveksa_7.2.0_176311-2020-Feb-14-15.40.ear

5. Run customizeACM.sh -c to extract the .ear file.

Sample output without specifying the specific .ear file:

$ ./customizeACM.sh -c

You have not specified an archive ear file to customize.

The current ear file deployed to Wildlfy is stored at: /home/oracle/archive/aveksa_7.2.0_176311-2020-Apr-07-16.22.ear

Do you want to customize that archived ear file [yes/no]? yes

Cleaning customization directory : /tmp/customizeACM

Unzipping aveksa.ear and aveksa.war ...
    [unzip] Expanding: /home/oracle/archive/aveksa_7.2.0_176311-2020-Apr-07-16.22.ear into /tmp/customizeACM
    [unzip] Expanding: /tmp/customizeACM/aveksa_war into /tmp/customizeACM/aveksa.war

Ready for customization. Please go to /tmp/customizeACM to continue modifications.

  Sample output with specifying the location and name of the .ear file:

$ ./customizeACM.sh -c $AVEKSA_HOME/archive/aveksa_7.2.0_176311-2020-Apr-07-16.22.ear

Cleaning customization directory : /tmp/customizeACM

Unzipping aveksa.ear and aveksa.war ...
    [unzip] Expanding: /home/oracle/archive/aveksa_7.2.0_176311-2020-Apr-07-16.22.ear into /tmp/customizeACM
    [unzip] Expanding: /tmp/customizeACM/aveksa_war into /tmp/customizeACM/aveksa.war

Ready for customization. Please go to /tmp/customizeACM to continue modifications.

 

The contents of the .ear are extracted to a directory in the following location: /tmp/customizeACM.

Note: If you do not specify the path to the .ear file, the script prompts you to use the currently deployed .ear file. If you want to use the currently deployed .ear, enter yes; If you do not want to use the currently deployed .ear, enter no.

6. Go to the /tmp/customizeACM directory and add your customized files/drivers to the extracted files.  

$ cd /tmp/customizeACM

7. When you finish modifying the files, go back to $AVEKSA_HOME/deploy/ACM-scripts and run customizeACM.sh -d to rebuild the .ear file. 

$ cd $AVEKSA_HOME/deploy/ACM-scripts
$ ./customizeACM.sh -d

Verifying that wildfly is running

Apr 08, 2020 11:09:12 AM java_util_logging_Logger$info$0 call
INFO: checkIfWildflyRunning - Checking server status
Apr 08, 2020 11:09:13 AM java_util_logging_Logger$info$0 call
INFO: Connecting to check connection
Apr 08, 2020 11:09:13 AM org.xnio.Xnio <clinit>
INFO: XNIO version 3.4.0.Final
Apr 08, 2020 11:09:13 AM org.xnio.nio.NioXnio <clinit>
INFO: XNIO NIO Implementation Version 3.4.0.Final
Apr 08, 2020 11:09:14 AM org.jboss.remoting3.EndpointImpl <clinit>
INFO: JBoss Remoting version 4.0.21.Final
Apr 08, 2020 11:09:14 AM org.jboss.as.cli.impl.CommandContextImpl printLine
INFO: Warning! The CLI is running in a non-modular environment and cannot load commands from management extensions.
Warning! The CLI is running in a non-modular environment and cannot load commands from management extensions.
Apr 08, 2020 11:09:14 AM java_util_logging_Logger$info$0 call
INFO: checkIfWildflyRunning - Found server in running state
Apr 08, 2020 11:09:14 AM java_util_logging_Logger$info$0 call
INFO: Terminate session

Wildfly is running
Adding the application deployment timeout...
Overriding existing application deployment timeout...
Removed deployment timeout successfully...
Application deployment timeout is updated to 10080 minutes.

Verifying that wildfly is running

Apr 08, 2020 11:09:20 AM java_util_logging_Logger$info$0 call
INFO: checkIfWildflyRunning - Checking server status
Apr 08, 2020 11:09:20 AM java_util_logging_Logger$info$0 call
INFO: Connecting to check connection
Apr 08, 2020 11:09:20 AM org.jboss.as.cli.impl.CommandContextImpl printLine
INFO: Warning! The CLI is running in a non-modular environment and cannot load commands from management extensions.
Warning! The CLI is running in a non-modular environment and cannot load commands from management extensions.
Apr 08, 2020 11:09:20 AM java_util_logging_Logger$info$0 call
INFO: checkIfWildflyRunning - Found server in running state
Apr 08, 2020 11:09:20 AM java_util_logging_Logger$info$0 call
INFO: Terminate session

Wildfly is running

Repackaging aveksa.ear and aveksa.war ...

Archive name is: aveksa_7.2.0_176311-2020-Apr-08-11.09.ear

Creating aveksa.ear file for deployment
      [zip] Building zip: /tmp/customizeACM/aveksa.war
      [zip] Building zip: /tmp/customizeACM/aveksa.ear
     [copy] Copying 1 file to /home/oracle/archive

Undeploying current ear...

Deploying new customized ear...    this may take a while...
Aveksa.ear successfully redeployed
Aveksa.ear was deployed in 4 minutes, 5.904 seconds
Adding the application deployment timeout...
Overriding existing application deployment timeout...
Removed deployment timeout successfully...
Application deployment timeout is updated to 15 minutes.

Updating CURRENTLY_DEPLOYED_ARCHIVE to aveksa_7.2.0_176311-2020-Apr-08-11.09.ear

aveksa_7.2.0_176311-2020-Apr-08-11.09.ear archived


Verifying that wildfly is running

Apr 08, 2020 11:17:08 AM java_util_logging_Logger$info$0 call
INFO: checkIfWildflyRunning - Checking server status
Apr 08, 2020 11:17:08 AM java_util_logging_Logger$info$0 call
INFO: Connecting to check connection
Apr 08, 2020 11:17:08 AM org.jboss.as.cli.impl.CommandContextImpl printLine
INFO: Warning! The CLI is running in a non-modular environment and cannot load commands from management extensions.
Warning! The CLI is running in a non-modular environment and cannot load commands from management extensions.
Apr 08, 2020 11:17:08 AM java_util_logging_Logger$info$0 call
INFO: checkIfWildflyRunning - Found server in running state
Apr 08, 2020 11:17:08 AM java_util_logging_Logger$info$0 call
INFO: Terminate session

Wildfly is running

The customizeACM.sh -d command performs the following tasks:

• Archives the new .ear file to the $AVEKSA_HOME/archive directory and appends a time and date stamp to the new .ear file.
• Deploys the new customized .ear file.
• Deletes the /tmp/customizeACM directory.