This chapter describes how to install and configure Oracle Communications Convergence.
The instructions in this chapter assume the following:
That you have installed and configured GlassFish Server or Oracle WebLogic Server.
That you have installed and configured all required and optional Unified Communications Suite software needed to deliver your Convergence services.
Download the Convergence software for your operating system from the Oracle software delivery web site:
The Convergence software is included in the Oracle Communications Messaging Server and Oracle Communications Calendar Server software package.
Extract the Convergence software to a temporary directory (dir).
You can install Convergence in either interactive mode or in silent mode. See one of the following topics for more information:
To install Convergence in interactive mode:
From dir, run the installer:
./commpkg install
Note:
To install Convergence on Oracle Linux 7, run the installer as:./commpkg -OSversionOverride install
See "commpkg Reference" for more information about the commpkg command.
From the list of available Unified Communications Suite software products for installation, select Convergence and proceed with the installation.
You can use silent mode to install multiple instances of the same software component and configuration without having to manually run an interactive installation for each instance.
To run a silent installation:
Obtain a silent installation state file using one of the following means:
Use a state file from a previous installation. The installer creates a state file in the /var/opt/CommsInstaller/logs/ directory each time it installs software. The state file name resembles silent_CommsInstaller_20070501135358.
Create a state file by running the installer in interactive mode with the --dry-run option. This option runs the installer, but does not actually install the software. For example:
commpkg install --dry-run
Copy the state file to each host and modify the file as needed.
The state file is formatted like a property file: blank lines are ignored, comment lines begin with a number sign (#), and properties are key/value pairs separated by an equals (=) sign. Table 5-1 lists the state file options.
| Option | Description | Example |
|---|---|---|
|
VERB |
Specifies which function to perform. For a silent install, VERB is set to install. |
VERB=install |
|
ALTDISTROPATH |
Specifies an alternate distro path. |
ALTDISTROPATH=SunOS5.10_i86pc_DBG.OBJ/release |
|
PKGOVERWRITE |
Specifies a boolean indicating whether to overwrite the existing installation packages. |
PKGOVERWRITE=YES |
|
INSTALLROOT |
Specifies the installation root. |
INSTALLROOT=/opt/sun/comms |
|
ALTROOT |
Specifies a boolean indicating whether to use an alternate root install. |
ALTROOT=yes |
|
EXCLUDEOS |
Specifies to not upgrade operating system patches. |
EXCLUDEOS=YES |
|
EXCLUDESC |
Specifies to exclude shared component patches. |
EXCLUDESC=no |
|
COMPONENTS |
A space separated list of mnemonics of the components to be installed. You can precede the mnemonic with a ~ to indicate that only the shared components for that product be installed. |
To specify Indexing and Search Service: COMPONENTS=JISS To view a list of mnemonic product names, run the commpkg info --listPackages command. |
|
ACCEPTLICENSE |
This option is no longer used. |
NA |
|
UPGRADESC |
Specifies whether to upgrade all shared components without prompting. |
UPGRADESC=no |
|
INSTALLNAME |
The friendly name for the INSTALLROOT. |
INSTALLNAME= |
|
COMPONENT_VERSIONS |
This option is unused. |
NA |
Run the installer in silent mode on each host:
commpkg install --silent input_file
where input_file is the path and name of the state file. For example: /var/opt/CommsInstaller/logs/silent_CommsInstaller_20070501135358.
See "install Verb Syntax" for more information about the --silent option.
By default, the option to upgrade shared components in the state file is automatically disabled (the UPGRADESC option is set to No.) This is true even if you explicitly asked to upgrade shared components when you ran the interactive installation that generated the state file. That is, you ran either commpkg install --upgradeSC y or you answered yes when prompted for each shared component that needed upgrading.
Disabling upgrading shared components in the silent state file is done because the other hosts on which you are propagating the installation might have different shared components installed, or different versions of the shared components. Therefore, it is safer to not upgrade the shared components by default.
If you want to upgrade shared components when you run a silent installation, do one of the following:
Use the --upgradeSC y option when you run the silent installation. (The command-line argument overrides the argument in the state file.)
Edit the value of the UPGRADESC option in the silent installation state file: UPGRADESC=Yes.
This section explains how to complete the initial configuration for Convergence, and how to configure Convergence to integrate with other Unified Communications Suite software applications.
The Convergence initial configuration program automatically creates a silent configuration file when the program completes successfully. You can use the silent configuration file to automate future configurations. See "Running the Convergence Initial Configuration Script in Silent Mode" for more information.
If you set up GlassFish Server as a non-root user, you must do one of the following:
Create a symbolic link between /usr/jdk/latest and the desired installed JDK in the /usr/jdk directory. For example:
ln -s /usr/jdk/jdk1.7.0_75 /usr/jdk/latest
Define the JAVA_HOME and PATH variables in the GlassFish Server user profile. It is not enough to only define the variable in the current shell that you are using to run the initial configuration script.
If the GlassFish Server user is referencing a JDK in a different location, set that location in the user .profile file by adding the following line.
export JAVA_HOME=JDK_location
Alternatively, you can add the line to the system-wide profile (/etc/profile) instead.
If you are deploying Convergence on GlassFish Server 5, set the Java path with the AS_JAVA property in the GlassFish_Home/config/asenv.conf file.
where, GlassFish_Home is the directory in which the GlassFish Server software is installed
Example, AS_JAVA=/usr/jdk/jdk1.8.0_152
The Convergence initial configuration script launches a program that gathers the required information from you to configure Convergence. See "Information Requirements" for details about the information required to configure Convergence.
The configuration program can launch a GUI or run at the command line. This section describes the GUI version of the program, even though both are similar and collect the same information.
To configure Convergence using the initial configuration script:
Verify that GlassFish Server is running.
Verify that the directory server is running.
Verify that all the Unified Communications Suite software applications with which you intend to integrate Convergence are running.
Run the Convergence initial configuration script for GlassFish Server:
./Convergence_Home/sbin/init-config
The Convergence configuration Welcome screen appears.
Note:
To run the configuration program at the command line, enter the following command instead:
./Convergence_Home/sbin/init-config -nodisplay
Click Next. The Select the Directory to Store Configuration and Data Files screen appears.
When prompted, select the directory in which to store the Convergence configuration and data files.
Do not select Convergence_Home as the location directory.
Click Next. The Select Services to Configure screen appears.
Select the services to configure with Convergence:
Mail Service
Calendar Service
Instant Messaging Service
Indexing and Search Service
Address Book Service
Click Next. The Convergence Server Host Name and DSN Domain Name screen appears.
Enter the host name of the system on which Convergence is being configured. Also, enter the DNS domain name of the Convergence host system.
Click Next. The GlassFish Server Configuration Details screen appears.
Specify the following:
Installation directory
Domain directory
Document root directory
Server target name
Virtual server identifier
Server instance port
Click Next. The GlassFish Server Administration Instance Details screen appears.
Specify the following:
GlassFish administration server port
GlassFish server administration user ID
GlassFish server administration password
Whether HTTP access to the administration server is secure.
Click Next. The program tests the connection to the GlassFish administration server. The Web Container User and Group screen appears.
Specify the GlassFish Server installation user ID and group.
Click Next. The Enter the URI Path Where Convergence Will be Deployed screen appears.
Specify the URI path to where you want to deploy Convergence.
For example: /iwc.
Click Next. The Specify Whether You Want Hosted Domain Support screen appears.
Specify whether you want to support for hosted domains in the Convergence deployment.
Click Next. The Specify LDAP User/Group Configuration Details screen appears.
Provide the following:
User/Group LDAP URL: URL for the User/Group LDAP used by Messaging Server, Calendar Server, and Instant Messaging Server.
For example: ldaps://MyDomain.com:port
Bind DN: Enter the LDAP distinguished name (DN) of the administrator used to bind to the directory server.
For example: cn=Directory Manager
Bind Password: The Bind DN password.
Click Next. The Confirm the Base DN of the DC Tree Suffix screen appears.
Confirm the base DN.
The configuration program retrieves the base DN from the directory server. You can accept the retrieved value or change it.
This base DN is used to perform domain lookups. If the back-end servers are using Schema 1, this configuration setting specifies the DN of the DC Tree suffix. If the back-end servers are using Schema 2, this setting specifies the DN of the root suffix under which the User/Group tree is located. You must enter (confirm) a value for this item whether you are using Schema 1 or Schema 2.
In a Schema 1 directory layout, Convergence uses the DC Tree suffix to search for domain information. In a Schema 2 directory layout, there is only one root suffix; both domain and user/group data are located under this one suffix.
Click Next. The Enter the Default Domain Name screen appears.
Enter the default domain name.
The default domain name is used during login when the user does not provide the domain as part of their user name.
For example, if a user attempts to login as John.Smith, the user name qualifies as John.Smith@DefaultDomain.com.
Click Next.
If you chose to configure the mail service, the Specify the Mail Service Configuration Details screen appears.
Specify the following:
Webmail host name
Webmail server port number
The SSL port is provided by default.
Access in SSL mode
Webmail server administration user ID
Webmail server administration password
Click Next. The program tests the connection to the Messaging server.
If you chose to configure the calendar service, the Calendar Server Version screen appears.
Specify the version of Calendar Server you are integrating with Convergence to deliver the calendar service.
For example, select CS 7 and up for Calendar Server version 8.x.
Click Next.
If you chose to configure the calendar service, the Specify the Calendar Service Configuration Details screen appears.
Specify the following:
Calendar server host name
Calendar server port number
The SSL port is provided by default.
Access in SSL mode
Service URI
Calendar server admin user ID
Calendar server admin password
Click Next. The program tests the connection to the Calendar server.
If you chose to configure the instant messaging service, the Specify the Instant Messaging Service Configuration Details screen appears.
Specify the following:
Server domain name
Server host name
Server port number
httpbind component JID
httpbind component password
Avatar component JID
Avatar component password
Click Next.
If you chose to configure the indexing and search service, the Specify the Indexing and Search Service Configuration Details screen appears.
Specify the following:
Indexing and search service host name
Indexing and search service port number
The SSL port is provided by default.
Access in SSL mode
Indexing and search service user ID
Indexing and search service password
Click Next. The program tests the connection to Instant Indexing And Search Service.
If you chose to configure the address book service, the Specify the Contacts Server Selection screen appears.
Select how to provide the address book service:
Select Convergence Address Book Service to provide the address book service through Convergence and the directory server.
Select Contacts Server Address Book Service to provide the address book service with Contacts Server.
If you chose to provide the address book service with Contacts Server, the Specify Contacts Server Configuration Details screen appears.
Specify the following:
Contacts server host name
Contacts server port number
The SSL port is provided by default.
Access in SSL mode
Service URI
Contacts server admin user ID
Contacts server admin password
Click Next. The program tests the connection to the Contacts server.
The Specify the Convergence Administrator Details screen appears.
Provide the Convergence administrator user name and password.
The Administrator user name and password are used for Convergence administration. The user details for the Convergence administrator are stored in the Convergence configuration files, not in the directory server. This administrator user is not tied to any back-end server administrator accounts.
Click Next. The Ready to Configure screen appears.
Review the list of items to be configured.
Click Next. The Task Sequence screen appears.
The Task Sequence screen displays the configuration tasks being performed.
Click Cancel to stop the configuration process.
When the screen displays the message All Tasks Passed, click Next. The Installation Summary screen appears.
The Installation Summary screen displays a summary of the completed configuration tasks.
Click Details to display more information about the completed configuration tasks.
Click Close to exit the configuration program.
When you complete the configuration process, the initial configuration program creates a configuration file that you can use to automate future configurations. See "Running the Convergence Initial Configuration Script in Silent Mode" for more information.
Before you install and configure Oracle WebLogic Server for Convergence, prepare the System user and groups for the installation:
Create a system user and group for Oracle WebLogic Server setup.
Note:
You must install Oracle WebLogic Server by using a non-root user. For example, to install Oracle WebLogic Server, you can use a Unix non-root user as uadmin and a Unix group user as staff. You can install Convergence by using a root user or any other user who is added to the staff group and possess the same permissions or access as uadmin.Create an Oracle WebLogic Server home directory for installation and ensure that the permissions for the required setup directories are set as shown in the following example:
mkdir WL_Home
chmod 755 WL_Home
chown -R uadmin WL_Home
chgrp -R staff WL_Home
Install JDK 1.8.0 update version on the platform. Ensure JAVA_HOME and PATH environment variables are set in the user environment
To install and configure Oracle WebLogic Server for Convergence:
Download and unzip the ZIP file that you have obtained for the Generic package. See Oracle WebLogic Server Installers for information on Oracle WebLogic Server download location.
Create a Domain, Administration Server, and Managed Server. See Configuring the WebLogic Domain for more information.
See the following Oracle WebLogic Server resources for more information:
Navigate to the WebLogic Domain directory that you have created. For example, WL_Home/user_projects/base_domain/bin.
Modify setDomainEnv.sh to add the following applicable settings.
The following modification is only for the Solaris 11.4 version:
JAVA_OPTIONS="${JAVA_OPTIONS} -Dsun.security.pkcs11.enable-solaris=false"
export JAVA_OPTIONS
(Optional) If you get a Random number related error when you restart the server, ensure to add the following:
JAVA_OPTIONS="${JAVA_OPTIONS} -Djava.security.egd=file:/dev/./urandom"
export JAVA_OPTIONS
To disable DERBY, add the following settings at the end of the file:
DERBY_FLAG=false
export DERBY_FLAG
Ensure to set the environment in the terminal that is used to start the servers by sourcing the setDomainEnv.sh file as shown below:
cd WL_Home/user_projects/base_domain/bin
source ./setDomainEnv.sh or . ./setDomainEnv.sh
Start the Administration Server.
Configure the Managed Server for default HTTP and HTTPS ports and start the Managed Server.
Configure Oracle WebLogic Server in a secure mode using the following details if you want to configure Convergence in a secure mode:
To enable SSL and configure keystores in Oracle WebLogic Server:
For more information about setting up keystores, see the Oracle WebLogic Server documentation at:
https://docs.oracle.com/middleware/12213/wls/SECMG/identity_trust.htm#SECMG365
Oracle WebLogic Server offers four keystore options in its configuration. However, only the following two keysotore options are recommended for Convergence:
CustomIdentityandCustomTrust
CustomIdentityandJavaStandardTrust
Note:
You must always set the keystore type to JKS.The keystore configuration must be same for an Administration Server and Managed Servers. It means, you should configure the same options or certificates for hosting Convergence.
You must set keystore passwords identical to the Oracle WebLogic Server Administration Sever password.
Note:
Convergence is deployed on Oracle WebLogic Server securely only if the keystore passwords and Oracle WebLogic Server passwords match.Ensure that the Administration Server and Managed Server are started successfully.
When you configure Convergence for the first time with Oracle WebLogic Server in a secure mode, run the extractSSLArgs.sh script. This script validates the SSL configuration details in Oracle WebLogic Server and stores the valid details in a format that is required by Convergence for all future deployments and processing.
To validate and store Oracle WebLogic Server SSL details for Convergence in a secure mode:
Open a new terminal and prepare the terminal by sourcing the setDomainEnv.sh script of the Oracle WebLogic Server domain:
cd WL_Home/user_projects/base_domain/bin
source ./setDomainEnv.sh OR . ./setDomainEnv.sh
Set the WLST_PROPERTIES environment variable depending on the selected Oracle WebLogic Server keystore configuration.
If the CustomIdentityandCustomTrust keystore option is configured as the Oracle WebLogic Server keystore configuration, set the WLST_PROPERTIES variable to:
export WLST_PROPERTIES="-Dweblogic.security.TrustKeyStore=CustomTrust , -Dweblogic.security.CustomTrustKeyStoreFileName=/WLHOME/user_projects/domains/base_domain/mytrust.jks"
Where WLHOME/user_projects/domains/base_domain/mytrust.jks is the location of truststore file location.
If the CustomIdentityandJavaStandardTrust keystore option is configured as the Oracle WebLogic Server keystore configuration, set the WLST_PROPERTIES variable to:
export WLST_PROPERTIES="-Dweblogic.security.TrustKeyStore=JavaStandardTrust"
Run the extractSSLArgs.sh bash shell script extractSSLArgs.sh which is available under the Convergence installed location: Convergence_Server_Installedlocation/sbin:
sh ./extractSSLArgs.sh -u weblogic_admin_user -p weblogic_admin_user_password -l t3s://weblogic_server_host:SSL_port
If the execution of the script is successful, it creates .wls_sslargs under the configuration directory of your Oracle WebLogic Server domain. You can verify the creation of .wls_sslargs by navigating to WLS_DOMAIN_DIRECTORY/config
The Convergence initial configuration script launches a program that gathers the required information from you to configure Convergence. See "Information Requirements" for details about the information required to configure Convergence.
The configuration program can launch a GUI or run at the command line. This section describes the GUI version of the program, even though both are similar and collect the same information.
Set the environment variable for Oracle WebLogic Server:
export ORACLE_IWC_APPSERVTYPE=WebLogic
To configure Convergence using the initial configuration script:
Verify that Oracle WebLogic Server is running.
Verify that the directory server is running.
Verify that all the Unified Communications Suite software applications with which you intend to integrate Convergence are running.
Run the Convergence initial configuration script:
./Convergence_Home/sbin/init-config
The Convergence configuration Welcome screen appears.
Note:
To run the configuration program at the command line, enter the following command instead:
./Convergence_Home/sbin/init-config -nodisplay
Click Next. The Select the Directory to Store Configuration and Data Files screen appears.
When prompted, select the directory in which to store the Convergence configuration and data files.
Do not select Convergence_Home as the location directory.
Click Next. The Select Services to Configure screen appears.
Select the services to configure with Convergence:
Mail Service
Calendar Service
Indexing and Search Service
Address Book Service
Click Next. The Convergence Server Host Name and DSN Domain Name screen appears.
Enter the host name of the system on which Convergence is being configured. Also, enter the DNS domain name of the Convergence host system.
Click Next. Oracle WebLogic Server Configuration Details screen appears.
Specify the following:
Oracle WebLogic Server Installation directory
Oracle WebLogic Server Domain directory
Oracle WebLogic Server Document root directory
Oracle WebLogic Server target name
Oracle WebLogic Server Virtual server identifier
Oracle WebLogic Server instance port
Click Next. Oracle WebLogic Server Administration Instance Details screen appears.
Specify the following:
Oracle WebLogic Server Administration server port
Oracle WebLogic Server Administration user ID
Oracle WebLogic Server Administration password
Is Administration Server port secure
Whether HTTP access to the administration server is secure.
Click Next. The program tests the connection to Oracle WebLogic administration server. The Web Container User and Group screen appears.
Specify Oracle WebLogic Server installation user ID and group.
Click Next. The Enter the URI Path Where Convergence Will be Deployed screen appears.
Specify the URI path to where you want to deploy Convergence.
For example: /iwc.
Click Next. The Specify Whether You Want Hosted Domain Support screen appears.
Specify whether you want to support for hosted domains in the Convergence deployment.
Click Next. The Specify LDAP User/Group Configuration Details screen appears.
Provide the following:
User/Group LDAP URL: URL for the User/Group LDAP used by Messaging Server, and Calendar Server.
For example: ldaps://MyDomain.com:port
Bind DN: Enter the LDAP distinguished name (DN) of the administrator used to bind to the directory server.
For example: cn=Directory Manager
Bind Password: The Bind DN password.
Click Next. The Confirm the Base DN of the DC Tree Suffix screen appears.
Confirm the base DN.
The configuration program retrieves the base DN from the directory server. You can accept the retrieved value or change it.
This base DN is used to perform domain lookups. If the back-end servers are using Schema 1, this configuration setting specifies the DN of the DC Tree suffix. If the back-end servers are using Schema 2, this setting specifies the DN of the root suffix under which the User/Group tree is located. You must enter (confirm) a value for this item whether you are using Schema 1 or Schema 2.
In a Schema 1 directory layout, Convergence uses the DC Tree suffix to search for domain information. In a Schema 2 directory layout, there is only one root suffix; both domain and user/group data are located under this one suffix.
Click Next. The Enter the Default Domain Name screen appears.
Enter the default domain name.
The default domain name is used during login when the user does not provide the domain as part of their user name.
For example, if a user attempts to login as John.Smith, the user name qualifies as John.Smith@DefaultDomain.com.
Click Next.
If you chose to configure the mail service, the Specify the Mail Service Configuration Details screen appears.
Specify the following:
Webmail host name
Webmail server port number
The SSL port is provided by default.
Access in SSL mode
Webmail server administration user ID
Webmail server administration password
Click Next. The program tests the connection to the Messaging server.
If you chose to configure the calendar service, the Calendar Server Version screen appears.
Specify the version of Calendar Server you are integrating with Convergence to deliver the calendar service.
For example, select CS 7 and up for Calendar Server version 8.x.
Click Next.
If you chose to configure the calendar service, the Specify the Calendar Service Configuration Details screen appears.
Specify the following:
Calendar server host name
Calendar server port number
The SSL port is provided by default.
Access in SSL mode
Service URI
Calendar server admin user ID
Calendar server admin password
Click Next. The program tests the connection to the Calendar server.
If you chose to configure the indexing and search service, the Specify the Indexing and Search Service Configuration Details screen appears.
Specify the following:
Indexing and search service host name
Indexing and search service port number
The SSL port is provided by default.
Access in SSL mode
Indexing and search service user ID
Indexing and search service password
Click Next. The program tests the connection to Instant Indexing And Search Service.
If you chose to configure the address book service, the Specify the Contacts Server Selection screen appears.
Select how to provide the address book service:
Select Convergence Address Book Service to provide the address book service through Convergence and the directory server.
Select Contacts Server Address Book Service to provide the address book service with Contacts Server.
If you chose to provide the address book service with Contacts Server, the Specify Contacts Server Configuration Details screen appears.
Specify the following:
Contacts server host name
Contacts server port number
The SSL port is provided by default.
Access in SSL mode
Service URI
Contacts server admin user ID
Contacts server admin password
Click Next. The program tests the connection to the Contacts server.
The Specify the Convergence Administrator Details screen appears.
Provide the Convergence administrator user name and password.
The Administrator user name and password are used for Convergence administration. The user details for the Convergence administrator are stored in the Convergence configuration files, not in the directory server. This administrator user is not tied to any back-end server administrator accounts.
Click Next. The Ready to Configure screen appears.
Review the list of items to be configured.
Click Next. The Task Sequence screen appears.
The Task Sequence screen displays the configuration tasks being performed.
Click Cancel to stop the configuration process.
When the screen displays the message All Tasks Passed, click Next. The Installation Summary screen appears.
The Installation Summary screen displays a summary of the completed configuration tasks.
Click Details to display more information about the completed configuration tasks.
Click Close to exit the configuration program.
When you complete the configuration process, the initial configuration program creates a configuration file that you can use to automate future configurations. See "Running the Convergence Initial Configuration Script in Silent Mode" for more information.
The Convergence initial configuration program automatically creates a silent configuration file when the program completes successfully. You can use the silent configuration file to automate future configurations.
The silent configuration file is called saveState and is created in the Convergence_Home/data/setup/Iwc-config-YYYYMMDDHHMMSS directory, where YYYYMMDDHHMMSS represents the date and time of the saveState file.
To configure Convergence using the initial configuration script in silent mode:
Verify that GlassFish Server or Oracle WebLogic Server is running.
Verify that the directory server is running.
Verify that Oracle Communications Messaging Server, Oracle Communications Calendar Server, and any other Unified Communications Suite software applications with which you intend to integrate with Convergence are running.
As the root user or super user, run the Convergence initial configuration script:
./Convergence_Home/sbin/init-config -nodisplay -noconsole -state path/saveState
Where path is the directory in which the saveState file is located.