Configuring Virtual Appliance

Post deployment of the Virtual Appliance, you can perform the following configuration changes, as required:
cislp143
Post deployment of the Virtual Appliance, you can perform the following configuration changes, as required:
Configure an Add-On Datasource
Virtual Appliance supports configuration of an additional datasource on CA Identity Manager and CA Identity Portal application servers. The supported databases are Oracle and Microsoft SQL Server.
When you deploy Virtual Appliance in the Sandbox or Custom mode, you can optionally configure an additional database instead of an embedded database. When you deploy the Virtual Appliance in the Non-Production or Production mode, you must configure an additional database.
  • We recommend a separate database for task persistence as it provides best performance.
  • While creating a database, ensure that you configure the collation to
    SQL_Latin1_General_CP1_CI_AS
    to avoid collation conflicts during the CA Identity Manager server startup.
  • CA Identity Manager requires the Oracle schema user to have specific permissions to use Oracle XA. Contact your database administrators and ask them to grant the necessary permissions. For more information, see the following technical documents:
  • If JBoss/WildFly is used with Microsoft SQL server as database, then enabling XA transaction is mandatory.
Supported Configuration Parameters for an Add-On Datasource
Virtual Appliance supports the following configuration parameters for an add-on datasource:
  • DB_TYPE:
    Specifies the database type. The supported database types are
    MSSQL
    and
    ORACLE
    .
  • DB_URL:
    Specifies the connection URL for the supported database.
  • DB_USER:
    Specifies the database user name.
  • DB_PASSWORD:
    Specifies the database user password.
  • DB_POOL_MINSIZE:
    Specifies the minimum number of connections for a pool.
  • DB_POOL_MAXSIZE:
    Specifies the maximum number of connections for a pool.
  • DB_VALIDATION_SQL:
    An SQL statement to check the validity of a pool connection. The SQL statement can be called when a managed connection is obtained from the pool.
    Ensure that you escape whitespaces in the DB_VALIDATION_SQL value by inserting a backward (\) slash before a whitespace.
    For example, DB_VALIDATION_SQL=select\ 1\ from\ dual
  • DB_VALIDATE_ON_MATCH:
    Specifies if the connection validation should be done when a connection factory attempts to match a managed connection.
  • DB_BACKGROUND_VALIDATION:
    Specifies if the connections should be validated on a background thread versus being validated prior to use. This value can be changed only on a disabled datasource, else requires a server restart.
  • DB_BACKGROUND_VALIDATION_MILLIS:
    Specifies the amount of time, in milliseconds, for the background validation to run. This value can be changed only on a disabled datasource, else requires a server restart.
  • DB_IDLE_TIMEOUT_MINUTES:
    Specifies the maximum time, in minutes, for a connection to be idle before being closed. This value can be changed only on a disabled datasource, else requires a server restart.
Create an Add-On Datasource
Perform the following steps to add an additional datasource while deploying the Virtual Appliance.
  1. Create the datasource property file in the following location:
    For CA Identity Manager:
    /opt/CA/VirtualAppliance/custom/IdentityManager/dataSources
    For CA Identity Portal:
    /opt/CA/VirtualAppliance/custom/IdentityPortal/dataSources
    Create the property file using the following format:
    IMAG_PACKAGE=IP or IM DB_TYPE=MSSQL or ORACLE DATASOURCE_NAME=my-ds DB_URL=jdbc:sqlserver://<host>:<port> or jdbc:sqlserver://<host>:<port>\;DatabaseName=<database name> or jdbc:oracle:thin:@<host>:<port>:<sid> or jdbc:oracle:thin:@//<host>:<port/<service name> DB_USER=<username> DB_PASSWORD=<password> DB_POOL_MINSIZE=<value> DB_POOL_MAXSIZE=<value> DB_VALIDATION_SQL=<SQL Query> DB_VALIDATE_ON_MATCH=true or false DB_BACKGROUND_VALIDATION=true or false DB_BACKGROUND_VALIDATION_MILLIS=<value in milliseconds> DB_IDLE_TIMEOUT_MINUTES=<value in minutes>
    Note:
    Starting from Virtual Appliance 14.2 CP1, the
    addJBossDatasource
    (see step 2) command has removed the requirement to store the database password in the Datasource configuration file. On invoking the
    addJBossDatasource
    command, it prompts the user for database password.
    Examples:
    CA Identity Portal with Oracle datasource, with SID specification:
    IMAG_PACKAGE=IP DB_TYPE=ORACLE DATASOURCE_NAME=test-ds DB_URL=jdbc:oracle:thin:@10.0.0.163:1521:xe DB_USER=test_user DB_PASSWORD=1234 DB_POOL_MINSIZE=5 DB_POOL_MAXSIZE=20 DB_VALIDATION_SQL=select\ 1\ from\ dual DB_VALIDATE_ON_MATCH=false DB_BACKGROUND_VALIDATION=false DB_BACKGROUND_VALIDATION_MILLIS=40 DB_IDLE_TIMEOUT_MINUTES=60
    CA Identity Manager with SQL Server datasource, with specific database name specification:
    IMAG_PACKAGE=IM DB_TYPE=MSSQL DATASOURCE_NAME=some-ds DB_URL=jdbc:sqlserver://db-cluster-01.corp.company.com:1433\;DatabaseName=vappip14 DB_USER=vappuser DB_PASSWORD=123456 DB_POOL_MINSIZE=5 DB_POOL_MAXSIZE=20 DB_VALIDATION_SQL=select\ 1\ from\ dual DB_VALIDATE_ON_MATCH=false DB_BACKGROUND_VALIDATION=false DB_BACKGROUND_VALIDATION_MILLIS=40 DB_IDLE_TIMEOUT_MINUTES=60
  2. Run the following alias:
    addJBossDatasource <DS FILE NAME>
    The datasource is automatically created or updated. The following message appears in the application server log file, indicating the JNDI datasource name:
    INFO [org.jboss.as.connector.subsystems.datasources] (MSC service thread) JBAS010400: Bound data source [java:jboss/datasources/jdbc/my-test-ds]
  3. You can reference the datasource within Java/Rhino code using the following syntax:
    var dataSource = initialContext.lookup("java:jboss/datasources/jdbc/test-ds");
Remove an Add-On Datasource
Perform the following step to remove an additional datasource from your Virtual Appliance deployment:
Run the following alias with a parameter referencing an absolute path to the datasource property file created while adding the additional datasource:
removeJBossDatasource <DS FILE NAME>
Example:
removeJBossDatasource /opt/CA/VirtualAppliance/custom/IdentityPortal/dataSources/my-ds.prop
The following message appears in the application server log file, indicating the removal of the datasource:
INFO [org.jboss.as.connector.subsystems.datasources] (MSC service thread) JBAS010409: Unbound data source [java:jboss/datasources/jdbc/test-ds]
Configure an Additional JDBC Driver Module
The Virtual Appliance supports configuring an additional JDBC driver module on the CA Identity Manager and CA Identity Portal application servers.
When you deploy the Virtual Appliance, you can optionally configure an additional JDBC driver module. The driver jar files need to be provided by the user.
Add an Additional JDBC Driver Module
Perform the following steps to add an additional driver module while deploying the Virtual Appliance.
  1. Create the driver module property file in the following location:
    For CA Identity Manager:
    /opt/CA/VirtualAppliance/custom/IdentityManager/drivers
    For CA Identity Portal:
    /opt/CA/VirtualAppliance/custom/IdentityPortal/drivers
  2. Create the property file by using the following format:
    IMAG_PACKAGE=IP or IM
    DB_TYPE=Any AlphaNumeric string identifying the DB
    DRIVER_CLASSNAME=<driver classname> for the DB
    DRIVER_JARS=<comma separated driver jar files>
    DEPENDENCIES=<comma separated driver module dependencies>
    For example:
    CA Identity Portal with DB2 Driver module:
    IMAG_PACKAGE=IP
    DB_TYPE=DB2
    DRIVER_CLASSNAME=com.ibm.db2.jcc.DB2Driver
    DRIVER_JARS=db2jcc4.jar,db2jcc_license_cisuz.jar
    DEPENDENCIES=javax.api,javax.transaction.api,javax.servlet.api
    CA Identity Manager with DB2 Driver module:
    IMAG_PACKAGE=IM
    DB_TYPE=DB2
    DRIVER_CLASSNAME=com.ibm.db2.jcc.DB2Driver
    DRIVER_JARS=db2jcc4.jar,db2jcc_license_cisuz.jar
    DEPENDENCIES=javax.api,javax.transaction.api,javax.servlet.api
    The driver jar files need to be present in the respective package location.
    • For CA Identity Manager, the location is:
      /opt/CA/VirtualAppliance/custom/IdentityManager/drivers
    • For CA Identity Portal, the location is:
      /opt/CA/VirtualAppliance/custom/IdentityPortal/drivers
  3. Run the following alias:
    addJBossDrivers <DR FILE NAME>
The driver modules are automatically created. The following message appears on the terminal, indicating the JDBC driver module added:
[INFO] Successfully created driver module folder: DB2
[INFO] Successfully created driver in Configuration XML for: DB2
Remove an Additional JDBC Driver Module
Perform the following step to remove an additional JDBC driver module from your Virtual Appliance deployment:
Run the following alias with a parameter referencing an absolute path to the driver module property file created while adding the additional driver module:
removeJBossDrivers <DR FILE NAME>
For example
:
removeJBossDrivers /opt/CA/VirtualAppliance/custom/IdentityPortal/drivers/my-dr.prop
The following message appears on the terminal, indicating the removal of the JDBC driver module:
[INFO] Successfully removed driver: DB2 from configuration XML
[INFO] Successfully removed driver module: DB2
: The out of the box driver modules "microsoft" and "oracle" cannot be removed.
Modify CA Identity Manager Application Log Level
CA Identity Manager that is shipped with the Virtual Appliance supports the
logging.jsp
file. This file controls logging of configuration logs during the run time. The file is available at /iam/im/logging.jsp.
By default, the logging.jsp file cannot be accessed by any user. To access this file, you must configure a WIldfly user as a member of the
IAMAdmin
application group. By default, the application does not have any users.
You can control access to the logging.jsp file by adding a user to the
IAMAdmin
application group.
Follow these steps:
  1. Log in to the command-line interface as
    config
    user.
  2. Run the following command:
    sudo /opt/CA/wildfly-idm/bin/add-user.sh
  3. Select option "b" (Application User) for the following question:
    “What type of user do you wish to add?”
  4. Respond with any one of the following options when asked to select a "Username"":
    • Type any previously defined user to add access for an existing user.
    • Type a different username to create a user. A user can access the logging.jsp file only when the user is a member of the
      IAMAdmin
      application group.
  5. Type
    IAMAdmin
    for the following question:
    ”What groups do you want this user to belong to? (Please enter a comma separated list, or leave blank for none): ”
  6. Type
    No
    for the following question:
    Is this new user going to be used for one AS process to connect to another AS process? e.g. for a slave host controller connecting to the master or for a Remoting connection for server to server EJB calls.
    You can now access the logging.jsp file using the following URL (replace “<IDM_NODE_ADDRESS>” with the IDM server IP address):
    http://<IDM_NODE_ADDRESS>:8080/iam/im/logging.jsp
Install VMware Tools
Perform the following steps on every Virtual Appliance node where you want to install VMware tools:
  1. Assign a Virtual CDROM/DVD drive to the Virtual Appliance VM host (this may require restarting the VM host).
  2. Mount the VMware tools installation media:
    • If you are using
      VMware ESX/vCenter
      :
      • Right-click the Virtual Appliance VM instance.
      • Select
        Guest
        .
      • Select
        Install/Update VMWare tools
        .
    • If you are using
      VMware workstation
      :
      • Right-click the Virtual Appliance VM instance.
      • Select
        Install VMware tools
        .
  3. Log in to the Virtual Appliance CLI/SSH console as
    config
    user.
  4. Run the alias
    install_vmware_tools.
  5. The VMware tools installation runs silently.
  6. After the installation, you can view a detailed Virtual Appliance log file at /opt/CA/VirtualAppliance/logs/ca_vapp_main.log.
    To view the file, run:
    vvl
    To watch (tail) the file, run:
    tvl
Configure Time and Network Time Protocol
Configure Date and Time
  • Run the following alias to change the system date and time:
    setTimeAndDate
    Alternatively, you can use the date alias to modify the system date and time using the Linux
    date
    command syntax.
  • Run the following alias to change the time-zone:
    selectTimeZone
  • Run the date alias to verify that the time-zone is set correctly:
    Example:
    Sun Aug 21 17:57:00 EST YYYY
Configure Network Time Protocol
You can configure the Network Time Protocol (NTP) on all servers in the Virtual Appliance solution using the following steps:
  1. Run the following command to edit NTP configuration:
    vim /etc/ntp.conf
  2. Make the required changes.
    See Network Time Protocol Setup for the format of the
    ntp.conf
    file.
  3. Run the following command to restart the service:
    sudo service ntpd restart
  4. Run the following command to trace Network Time Protocol synchronization state:
    ntpq –p
Modify CA Identity Manager Environment Base URL
The default Virtual Appliance CA Identity Manager environment (“identityEnv”) comes pre-populated with a default Base URL. You can modify the base URL to match the actual IP address of one of the CA Identity Manager servers in the deployment.
Follow these steps:
  1. Log in to the CA Identity Manager Management Console of any one server in the deployment.
  2. Click
    Environments
    .
  3. Click
    identityEnv
    .
  4. Modify the IP address of any one CA Identity Manager server in the deployment, in the following base URL:
    http: //
    <IP_Address>
    :8080/iam/im
    Example:
    http: //150.9.30.100:8080/iam/im
  5. Click
    Save
    .
  6. Click
    Restart Environment
    .
  7. On the remaining CA Identity Manager nodes, log in to the Management Console and restart the environment.
Configure Email for CA Identity Manager
Use the following files to configure email properties for CA Identity Manager. These files are available at /opt/CA/VirtualAppliance/custom/IdentityManager.
  • email.properties
    Defines SMTP host, port, SSL, TLS, user name, and password.
  • IDM_from_address.properties
    Defines the IM sender address.
  • WorkPoint_email.properties
    Defines various WorkPoint email properties (when it is the WorkPoint process that is sending the emails and not CA Identity Manager)
Configure Dashboard to Point Application URLs to a Custom DNS Name
You can configure the Dashboard to point application URLs to a custom DNS name.
Follow these steps:
  1. Edit the following file on every server in the Virtual Appliance solution:
    /opt/CA/VirtualAppliance/conf/externalips
  2. Enter a list of node IP addresses and their DNS name in the following format:
  3. Click
    refresh
    in the Virtual Appliance Web interface Dashboard.
The application links will now point to the DNS names specified in the
externalips
file, instead of pointing to the private IP addresses of the nodes.
Postfix Configuration
You can now configure postfix at "
/etc/postfix"
.
Toggle AJP Listener
By default, the AJP Listener is enabled in a Virtual Appliance deployment. To disable the AJP Listener, you must apply the hotfix - HF-AJPCONFIG_20200320_001 on each node. After applying the hotfix, the AJP Listener is disabled by default.
After applying the hotfix, you can
also
toggle AJP Listener ON/OFF.
Steps to Toggle AJP Listener ON or OFF:
  1. Apply the hotfix - HF-AJPCONFIG_20200320_001 on each node.
    All the application servers in your deployment will automatically restart while you apply the hotfix.
  2. Navigate to /opt/CA/VirtualAppliance/custom/<point-product>/config.
    Example:
    /opt/CA/VirtualAppliance/custom/IdentityManager/config
  3. Open the
    ajp_listener.conf
    file.
  4. Set the
    ajp_listener_enabled
    property true or false, as desired.
    Example:
    ajp_listener_enabled=true
  5. Navigate to /opt/CA/wildfly-<product_code>/standalone/configuration and open the
    ca-standalone-full-ha.xml
    file.
    • When the AJP property is set
      true
      , you will notice the following changes in the XML file.
      1. The AJP Binder line is uncommented.
        <ajp-listener name="ajp" socket-binding="ajp">
      2. The cluster mode is set to the AJP connector.
        <mod-cluster-config advertise-socket="modcluster" connector="ajp">
    • When the AJP property is set
      false
      , you will notice the following changes in the XML file.
      1. The AJP Binder line is commented.
        <!-- ajp-listener name="ajp" socket-binding="ajp"/-->
      2. The cluster mode is set to the default connector of WildFly.
        <mod-cluster-config advertise-socket="modcluster" connector="default">
  6. Restart the application server on each node for the changes to take effect.
    Example:
    restart_im
Rollback of hotfix does not revoke the AJP setting. Prior to rollback, ensure that you change the AJP setting to the desired state and then rollback the hotfix.