Configuring Virtual Appliance

Post deployment of the Virtual Appliance, you can perform configuration changes, as required:
144
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 Identity Manager and 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 Identity Manager server startup.
  • 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 Identity Manager:
    /opt/CA/VirtualAppliance/custom/IdentityManager/dataSources
    For 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>
    On invoking the
    addJBossDatasource
    command, it prompts the user for database password.
    Examples:
    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
    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 removal of the datasource:
INFO [org.jboss.as.connector.subsystems.datasources] (MSC service thread) JBAS010409: Unbound data source [java:jboss/datasources/jdbc/test-ds]
Troubleshooting:
Symptom:
You will come across the following error after executing the
removeJBossDatasource
alias to remove datasource. 
[INFO] Successfully removed datasource: <DATASOURCE_NAME> [ERROR] Failed to remove security-domain: <DATASOURCE_NAME> [ERROR] { [ERROR] "outcome" => "failed", [ERROR] "failure-description" => "WFLYCTL0171: Removing services has lead to unsatisfied dependencies: [ERROR] Service jboss.security.security-domain.<DATASOURCE_NAME> was depended upon by service jboss.data-source-config.<DATASOURCE_NAME>", [ERROR] "rolled-back" => true, [ERROR] "response-headers" => {"process-state" => "reload-required"} [ERROR] } [ERROR] Failed to remove the datasource <DATASOURCE_NAME>- Aborting...
Cause:
This error occurs because the datasource and security module are removed from the same script and the Wildfly 15 server expects a reload to remove them one after another in a single shell.
Solution:
To resolve this error, you must rerun
removeJBossDatasource
alias to remove the left over security-domain and return success.
Configure an Additional JDBC Driver Module
The Virtual Appliance supports configuring an additional JDBC driver module on the Identity Manager and Identity Portal application servers.
When you deploy the Virtual Appliance, you can optionally configure an additional JDBC driver module. The driver jar files must 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:
    Identity Manager:
    /opt/CA/VirtualAppliance/custom/IdentityManager/drivers
    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:
    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
    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 must be present in the respective package location.
    • For Identity Manager, the location is:
      /opt/CA/VirtualAppliance/custom/IdentityManager/drivers
    • For 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.
Troubleshooting:
Symptom:
You will come across the following error on removing the driver immediately after removing a datasource without restaring the JBoss service.
[ERROR] Failed to remove the driver: <DB_TYPE> in configuration XML [ERROR] { [ERROR] "outcome" => "failed", [ERROR] "failure-description" => "WFLYCTL0171: Removing services has lead to unsatisfied dependencies: [ERROR] Service jboss.jdbc-driver.<DB_TYPE> was depended upon by service jboss.driver-demander.java:jboss/datasources/jdbc/<DATASOURCE_NAME>, service org.wildfly.data-source.<DATASOURCE_NAME>", [ERROR] "rolled-back" => true, [ERROR] "response-headers" => {"process-state" => "reload-required"} [ERROR] } [ERROR] Failed to remove the driver module <DB_TYPE> - Aborting...
Cause:
Datasource dependency is cached until you restart the server. The WildFly 15 server expects a reload to remove the cached dependency.
Solution:
To resolve this error, you must restart the JBoss service and then run the
removeJBossDrivers
alias.
Modify Identity Manager Application Log Level
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
  • CentOS 6 requires install-vmware-tools.
  • CentOS Stream 8 has removed dependency on install-vmware-tools.
If you are using Virtual Appliance running on CentOS 6, install VMware tools on all the Virtual Appliance nodes.
Follow these steps:
  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 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:
[Platform v1 - Virtual Appliance running on CentOS 6 / Amazon Linux 1]
  1. Run the following command to edit the 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 the Network Time Protocol synchronization state:
    ntpq –p
[Platform v2 - Virtual Appliance running on CentOS Stream 8 / Amazon Linux 2]
  1. Run the following command to edit the NTP configuration:
    vim /etc/chrony.conf
  2. Make the required changes.
    See Network Time Protocol Setup for the format of the
    chrony
    .conf
    file.
  3. Run the following command to restart the service:
    sudo service chronyd restart
Modify Identity Manager Environment Base URL
The default Virtual Appliance 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 Identity Manager servers in the deployment.
Follow these steps:
  1. Log in to the 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 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 Identity Manager nodes, log in to the Management Console and restart the environment.
Configure Email for Identity Manager
Use the following files to configure email properties for 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 Identity Manager sender address.
  • WorkPoint_email.properties
    Defines various WorkPoint email properties (when it is the WorkPoint process that is sending the emails and not 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
You can toggle AJP Listener ON/OFF. Note that by default, the AJP Listener is disabled in a Virtual Appliance deployment.
Steps to Toggle AJP Listener ON or OFF:
  1. Navigate to /opt/CA/VirtualAppliance/custom/<point-product>/config.
    Example:
    /opt/CA/VirtualAppliance/custom/IdentityManager/config
  2. Open the
    ajp_listener.conf
    file.
  3. Set the
    ajp_listener_enabled
    property to true or false, as desired.
    Example:
    ajp_listener_enabled=true
  4. Restart the application server on each node for the changes to take effect.
    Example:
    restart_im
  5. Navigate to /opt/CA/wildfly-<product_code>/standalone/configuration and open
    ca-standalone-full-ha.xml
    for Identity Manager or
    standalone-full-ha-ca-gm.xml
    for Identity Governance.
    • When the AJP property is set
      true
      , notice that the following arguments are added to the XML file.
      <ajp-listener name="ajp" socket-binding="ajp"> <mod-cluster-config advertise-socket="modcluster" connector="ajp">
    • When the AJP property is set
      false
      , notice that the following arguments are removed from the XML file.
      <ajp-listener name="ajp" socket-binding="ajp"> <mod-cluster-config advertise-socket="modcluster" connector="ajp">