This chapter describes how to install and configure Oracle Communications Mobile Synchronization Gateway.
Before installing Mobile Synchronization Gateway, read these chapters:
The instructions in this chapter assume:
You are deploying Mobile Synchronization Gateway on a single host or Solaris zone, or multiple hosts or Solaris zones.
Oracle Directory Server Enterprise Edition is already installed.
Oracle Communications Messaging Server is already installed, and optionally, Oracle Communications Calendar Server, and Oracle Communications Contacts Server or Oracle Communications Convergence Personal Address Book. The services must be configured and running for Mobile Synchronization Gateway to be able to communicate with them during the installation. See "Required Software" for product versions required by Mobile Synchronization Gateway.
You have installed and configured Oracle GlassFish Server as the web container for Mobile Synchronization Gateway.
The ldapsearch command exists on the GlassFish Server host in the /usr/bin/ directory.
The tasks to install Mobile Synchronization Gateway are as follows:
Downloading the Mobile Synchronization Gateway and Additional Software
Running the Mobile Synchronization Gateway Initial Configuration Script
Download the Mobile Synchronization Gateway software, the Oracle Communications Directory Server Setup comm_dssetup.pl script, and other Unified Communications Suite software (for example, Messaging Server), if necessary, from the Oracle software delivery website, located at:
You can either download the comm_dssetup.pl script separately, or as part of the Mobile Synchronization Gateway software.
Copy the Mobile Synchronization Gateway ZIP file to a temporary directory on your Mobile Synchronization Gateway hosts and extract the files, to be able to install the Mobile Synchronization Gateway software.
Copy the Directory Server Setup ZIP file to a temporary directory on your Directory Server hosts and extract the files, to be able to install and run the comm_dssetup.pl script.
If necessary, copy the other Unified Communications Suite ZIP file(s), such as the Messaging Server ZIP file, to temporary directories on your Unified Communications Suite hosts, and extract the files, to be able to install the software.
You prepare your Directory Server by running the comm_dssetup.pl script against it. You can run the comm_dssetup.pl script in either interactive or silent mode. For silent mode instructions, see "Running the comm_dssetup.pl Script in Silent Mode".
To prepare Directory Server and run the comm_dssetup.pl script in interactive mode:
On the host where Directory Server is installed, log in as or become the superuser (root).
Start Directory Server, if necessary.
Change to the directory where you extracted the Directory Server Setup ZIP file and run the installer.
commpkg install
For more information about running the installer, see "commpkg Reference".
Select Comms DSsetup and proceed with the installation.
Run the comm_dssetup.pl script in interactive mode (without any arguments), then enter your choices when prompted.
/usr/bin/perl comm_dssetup.pl
For more information, see "comm_dssetup.pl Reference".
Note:
You can use either LDAP Schema 2 or Schema 1.If necessary, provision users in the Directory Server.
If Directory Server is already installed at your site, users have already been provisioned. If you have just installed Directory Server at your site, then you need to provision users. For information, see the discussion on provisioning users and schema in Unified Communications Suite Schema Reference.
Mobile Synchronization Gateway requires at least Messaging Server 8.0. For more information on installing or upgrading Messaging Server, see Messaging Server Installation and Configuration Guide.
To install the Mobile Synchronization Gateway software:
On the Mobile Synchronization Gateway host, log in as or become the superuser (root).
Go to the directory where you extracted the Mobile Synchronization Gateway distribution files.
Run the installer.
commpkg install
For more information about running the installer, see "commpkg Reference".
Select Mobile Synchronization Gateway and proceed with the installation.
When you run the Mobile Synchronization Gateway installer in silent mode, you are running a non-interactive session. The installation inputs are taken from the following sources:
A silent installation file (also known as a state file)
Command-line arguments
Default settings
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.
This section includes:
To perform a Mobile Synchronization Gateway silent installation:
Obtain the state file by one of the following means.
Run an interactive installation session and use the state file that is created in the /var/opt/CommsInstaller/logs/ directory. The state file name is similar to silent_CommsInstaller_20070501135358. A state file is automatically created for every run of the installation.
Create a silent state file without actually installing the software during the interactive session by using the --dry-run option, then modifying the state file. For example:
commpkg install --dry-run
Copy the state file to each host machine and edit the file as needed. See "Silent Mode File Format".
Run the silent installation on each host. For example:
commpkg install --silent input_file
where input_file is the path and name of the silent state file, for example /var/opt/CommsInstaller/logs/silent_CommsInstaller_20070501135358.
For details about the --silent option, see "install Verb Syntax".
Note:
Command-line arguments override the values and arguments in the state file.By default, shared components that require user acceptance for upgrading are not upgraded when you run a silent installation. The option to upgrade shared components in the silent state file is automatically disabled. That is, the option is set to UPGRADESC=No. This is true even if you explicitly asked to upgrade shared components when you ran the interactive installation that generated the silent 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.
You can upgrade shared components when you run a silent installation by performing either of the following actions:
Use the --upgradeSC y option when you run the silent installation. (The command-line argument overrides the argument in the state file.)
Edit the UPGRADESC=No option in the silent state file to: UPGRADESC=Yes.
Caution:
If you do not upgrade shared components your installation might not work properly.The silent mode file (also known as a 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 shows which options you can change and provides examples:
Table 5-1 Silent Mode File Options
| Option | Description | Example |
|---|---|---|
|
VERB |
Indicates which function to perform. For a silent install, this is set to install. |
VERB=install |
|
ALTDISTROPATH |
Indicates an alternate distro path. |
ALTDISTROPATH=SunOS5.10_i86pc_DBG.OBJ/release |
|
PKGOVERWRITE |
A boolean indicating whether to overwrite the existing installation packages. (See the --pkgOverwrite switch). |
PKGOVERWRITE=YES |
|
INSTALLROOT |
Specifies installation root. |
INSTALLROOT=/opt/sun/comms |
|
ALTROOT |
A boolean indicating whether this is 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. |
COMPONENTS=MSG |
|
ACCEPTLICENSE |
This option is no longer used. |
Not applicable |
|
UPGRADESC |
Indicates whether all shared components should or should not be upgraded without prompting. |
UPGRADESC=no |
|
INSTALLNAME |
The friendly name for the INSTALLROOT. |
INSTALLNAME= |
|
COMPONENT_VERSIONS |
This option is unused. |
Not applicable |
To display a complete list of the product names (such as MS, MS64, CS) to use with the COMPONENTS property, run the commpkg info --listPackages command. This command displays the mnemonics for each product. For more information, see the discussion on the commpkg info command in "commpkg Reference".
This information explains how to install Mobile Synchronization Gateway on Solaris OS Zones.
The topics in this section include:
You can install Mobile Synchronization Gateway in the global zone, whole root non-global zones, and sparse non-global zones. Follow these guidelines:
Treat the global zone as an ”administration zone.”
Install shared components and OS patches in the global zone that are to be shared among all zones. However, do not install and run products from the global zone.
Use whole root non-global zones to run Mobile Synchronization Gateway.
Do not use the global zone or sparse zones. A whole root zone can have versions that are different from other whole root zones, thus giving it a measure of being ”self-contained.”
Be aware of the following zone aspects:
You can have different shared component versions in the whole root non-global zone, but it isn't entirely insulated. If you do a packaging or patching operation in the global zone for a shared component, that operation is also attempted in the whole root zone. Thus, to truly have different shared component versions, use an alternate root.
To avoid affecting whole root zones you can attempt to never install and patch shared components in the global zone. However, it might not be realistic to never have to install or patch a shared component in the global zone. For example, NSS is a shared component, but it is part of Solaris OS. So to expect to never install and patch NSS in the global zone seems unrealistic, especially given it is a security component.
Although it isn't a recommended best practice, you can use Mobile Synchronization Gateway in sparse non-global zones. Do note that shared components cannot be installed into the default root because many of them install into the read-only shared file system (/usr). Thus, you must run the installer in the global zone to install shared components into the default root. Prepend your selection with ~ in the global zone to install only the dependencies (that is, shared components). You do not have to install in the global zone first before installing in the sparse zone. The installer allows you to continue even when you do not install all the dependencies. However, upgrading the shared components in the global zone affects the sparse non-global zones, thus requiring downtime for all affected zones simultaneously.
Note:
Sparse root zones are not available beginning with Oracle Solaris 11.The non-global whole root zone scenario is the equivalent of installing Mobile Synchronization Gateway on a single box with no zones. Simply install Mobile Synchronization Gateway as you normally would.
Caution:
Any operations performed in the global zone (such as installations, uninstallations, and patching) affect the whole root zones.Although it isn't a recommended best practice, you can use Mobile Synchronization Gateway in a non-global sparse root zone on Solaris 10. To install Mobile Synchronization Gateway in a non-global sparse root zone, you first need to install or upgrade the applicable OS patches and shared components in the global zone. You are unable to do so in the sparse root zone, because the /usr directory (where the shared components reside) is a read-only directory in the sparse root zone.
Follow the pre-installation requirements as described in "Mobile Synchronization Gateway Pre-Installation Tasks".
Verify that you are about to install the shared components and OS patches in the global zone and not the sparse root zone. To verify you are in the global zone, run zonename. The output should be global.
Run the installer in the global zone and only install or upgrade the OS patches and the Shared Components. Do not install Mobile Synchronization Gateway in the global zone. To do this, add a ~ (tilde) to the component number you want to install in the sparse zone.
For example, if you plan to install Mobile Synchronization Gateway in the sparse zone, you select ~1 during the global zone installation. The installer will know to only install dependencies and not the product itself.
Once you have the shared components and OS patches installed, install Mobile Synchronization Gateway in the sparse root zone.
You must configure Mobile Synchronization Gateway to complete the installation. You use the Mobile Synchronization Gateway configuration command-line script, init-config, to perform this initial runtime configuration.
Before running the Mobile Synchronization Gateway init-config script, ensure that you have satisfied the following prerequisites.
(Linux only) On Mobile Synchronization Gateway front-end hosts, install the openldap-clients RPM, which installs LDAP tools such as /usr/bin/ldapsearch and /usr/bin/ldapmodify.
On the GlassFish Server hosts, the ldapsearch command exists in the /usr/bin/ directory.
If you plan to configure Mobile Synchronization Gateway to use SSL, make sure you have configured the back-end Unified Communications Suite hosts for SSL.
If you are using a CA-signed certificate, you do not need to install the certificate on the Mobile Synchronization Gateway host, as long as the instance of GlassFish Server you are using contains the root certificate of that CA. If you are using a self-signed certificate, you must import the certificate into the trustStore file that is used by GlassFish Server on the Mobile Synchronization Gateway host.
Do the following on the Mobile Synchronization Gateway front-end hosts so that Mobile Synchronization Gateway locates the proper JDK:
Create a symbolic link between /usr/jdk/latest and the desired JDK in the /usr/jdk directory. For example:
ln -s /usr/jdk/jdk1.7.0_79 /usr/jdk/latest
Define the JAVA_HOME variable in the GlassFish Server user's login profile. (Defining the variable in the current shell session running the init-config script is insufficient in itself.)
If the GlassFish Server user is referencing a JDK in a different location, set that location by adding the following line to the user's .profile file or to the system-wide profile file, /etc/profile, instead.
export JAVA_HOME=JDK_location
To run the Mobile Synchronization Gateway initial configuration script:
Log in as or become the superuser (root).
Note:
Log in as "su -" when running init-config if you installed GlassFish Server with secure mode.Change to the MobileSyncGateway_home/sbin directory.
The default installation directory is /opt/sun/comms/mobile.
Run the initial configuration script and respond to the prompts.
See "Mobile Synchronization Gateway Configuration Script" for more information.
init-config
Note:
Refer to "Information Requirements" for information about the values you need to provide during initial configuration.When prompted, enter the Mobile Synchronization Gateway settings:
Directory to store configuration and data files
Mobile Synchronization Gateway runtime user
Mobile Synchronization Gateway runtime group
Fully qualified host name of this system.
Enter the GlassFish Server Configuration Details.
Install Directory
Domain Directory
Document Root Directory
Server Target Name
Virtual Server Identifier
GlassFish Server access host
GlassFish Server access port
GlassFish Server administration server host
GlassFish Server administration server port
Is GlassFish Server secure?
Administrative User ID
Administrative Password
Full URL of the deployed server (default: /)
Use / (root) as the default context URI for production deployments. See "Deploying Mobile Synchronization Gateway to GlassFish Server" for information on why to use / (root) as the default context.
Enter the User/Group Directory Server Details.
LDAP URL
Specify to use LDAP over SSL (ldaps://) if you want Mobile Synchronization Gateway to communicate by using SSL with Directory Server in the runtime configuration. See "LDAP Information" for more information on using LDAP over SSL with Directory Server.
User/Group Directory Manager Distinguished Name (DN)
Directory Manager Password
The following message appears if you do not have the correct password:
ldap_bind: Invalid credentials (49) Error validating password for cn=Directory Manager
In this case, you are prompted again to enter the password.
User/Group default domain (The default value is set when you run the comms_dssetup.pl script against the Directory Server.)
Enter the domain name for the LDAP users in the deployment.
Default organization DN (The default value is set when you run the comms_dssetup.pl script against the Directory Server.)
Enter the organization DN under which all users and groups that belong to the default domain are located in the LDAP tree.
If other messages appear when validation failed, you are prompted to re-enter all the Directory Server settings in this step.
Enter the Messaging Server Details.
IMAP server host name
IMAP server port number
Is IMAP server port secure?
IMAP server administrative user ID
IMAP server administrative password
SMTP server host name
SMTP server port
Is SMTP server port secure?
SMTP server administrative user ID
SMTP server administrative password
Enter Convergence Server Details:
Convergence host name
Convergence port number
Is Convergence port secure?
Convergence Proxy Administrative user
Convergence Proxy Administrative user password
For more information about the Convergence Proxy Administrative user, see the topic on configuring Convergence to use proxy authentication in the Convergence System Administrator's Guide.
Enter the Contacts/WABP Server Details:
Do you want to configure CardDAV?
Contacts Server host name
Contacts Server port number
Contacts Server Message Queue broker port
Is Contacts Server port secure?
Contacts Server administrative user
Contacts Server administrative user password
Do you want to enable WABP?
Answer yes if you have deployed Convergence and want to use the address book data from WABP. The init-config script uses the Convergence information that you previously entered.
Enter the Calendar Server Details:
Do you want to configure CalDAV?
Calendar Server host
Calendar Server port number
Calendar Server Message Queue broker port
Is Calendar Server port secure?
Calendar Server administrative user
Calendar Server administrative user password
When prompted whether to proceed with configuring Mobile Synchronization Gateway, answer Y.
The configurator displays messages indicating its actions and progress. The last messages indicate the location where the installation log file was written.
The init-config command-line script creates the following configuration files:
mgserver.properties: Contains the Mobile Synchronization Gateway system-wide configuration
mgservercreds.properties: Contains the Mobile Synchronization Gateway passwords
See the topic on configuration files and parameters in Mobile Synchronization Gateway System Administrator's Guide for more information about Mobile Synchronization Gateway configuration files.
After configuring Mobile Synchronization Gateway, continue with the following chapters:
Go to "Configuring Mobile Synchronization Gateway With Multiple Hosts" if you have multiple hosts in your deployment.
Follow the instructions in "Mobile Synchronization Gateway Post-Installation Tasks" to perform post-installation tasks, such as updating the URIs of services that have been installed in non-default locations.