This chapter describes how to install and configure Oracle Communications Instant Messaging Server.
Before installing Instant Messaging Server, read these chapters:
The instructions in this chapter assume:
You are deploying Instant Messaging Server on a single host, or multiple hosts or Solaris zones.
Oracle Directory Server Enterprise Edition is already installed.
(Optional) You have installed and configured a web container for Instant Messaging Server components that require one.
The tasks to install Instant Messaging Server are as follows:
Download the Instant Messaging Server software for your operating system, and the Oracle Communications Directory Server Setup comm_dssetup.pl script, from the Oracle software delivery website, located at:
Copy the Instant Messaging Server ZIP file to a temporary directory on your Instant Messaging Server hosts and extract the files.
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.
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 the Schema Reference.
To install the Instant Messaging Server software:
On the Instant Messaging Server host, log in as or become the superuser (root).
Go to the directory where you extracted the Instant Messaging Server files.
Run the Installer.
commpkg install
For more information about running the installer, see "commpkg Reference".
Select Instant Messaging Server and proceed with the installation.
When you run the Instant Messaging Server 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 Instant Messaging Server 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=IM |
|
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, IM) 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 Instant Messaging Server on Solaris OS Zones.
The topics in this section include:
You can install Instant Messaging Server 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 Instant Messaging Server.
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 Instant Messaging Server 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 Instant Messaging Server on a single box with no zones. Simply install Instant Messaging Server 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 Instant Messaging Server in a non-global sparse root zone on Solaris 10. To install Instant Messaging Server 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 "Instant Messaging Server 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 Instant Messaging Server 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 Instant Messaging Server 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 Instant Messaging Server in the sparse root zone.
You must configure Instant Messaging Server to complete the installation. You use the Instant Messaging Server configuration command-line script, configure, to perform this initial runtime configuration.
System users run specific server processes. Certain privileges need to be designated for these users to ensure they have appropriate permissions for the processes they run. Normally, the configure utility creates the following users and groups:
User: inetuser
Group: inetgroup
If the configure utility does not create a UNIX user and group for Instant Messaging Server, you need to create them manually as described in this section. After you create the user and group, set permissions appropriately for the directories and files owned by that user.
Do not choose root as a server user ID.
To create the appropriate UNIX user and group:
Log in as superuser (root).
Create a group to which your system user belongs. For example, to create a group named imgroup on an Oracle Solaris platform, enter the following command:
groupadd imgroup
Create the system user and associate it with the group you just created. In addition, set the password for that user. For example, to create a user named imuser and associate it with the group imgroup on an Oracle Solaris platform, enter the following command:
useradd -g imgroup imuser
For more information on adding users and groups, refer to your operating system documentation.
Examine the /etc/groups file to ensure that the user and group were added.
After you install Instant Messaging Server, use the configure utility to configure the software and to generate the configuration files.
This section contains the following topics:
Change to the InstantMessaging_home/sbin directory. By default, the InstantMessaging_home directory is /opt/sun/comms/im.
Use one of the following options to run the configure utility.
Command-line:
configure --nodisplay
From a state file:
configure --silent statefile
where statefile is the path to the state file you want to use. If you are configuring by using a state file and using the --silent option, you are not be prompted for configuration information. Instead, the values from the state file are used to configure the software. See "Performing a Silent Instant Messaging Server Configuration" for information on generating a state file. If you are not performing a silent installation, a series of prompts appears, requesting information that sets up the initial configuration for Instant Messaging Server. The prompts that appear vary depending on the components you installed. Fill in the requested information using the values from your Instant Messaging Server checklist. See "Configuring Instant Messaging Server".
Note:
Do not select the Disable Server option.To use the XMPP/HTTP Gateway, modify the location of the default log file for the XMPP/HTTP Gateway in the httpbind_log4j.conf file.
You need to do this on Linux, however, you only need to do this on Oracle Solaris if you chose to use a location for logs other than the default.
To do this:
Open the httpbind_log4j.conf file. This file is stored at the location you specified in the httpbind.conf file as the value for the httpbind.log4j.config parameter. By default the file is stored in the following directory under the default Instant Messaging Server instance: InstantMessaging_cfg_home/httpbind_log4j.conf.
Set the value of the log4.appender.appender_ID.file parameter to the location where log files are stored. By default, on Red Hat Linux and Oracle Linux, this value is /var/opt/sun/im/default/log. If you chose another location for log files when you ran configure, enter that path as the value for the parameter.
Configure client systems to support Instant Messaging Server.
Note:
If httpbind and im are configured to run on different hosts, you must explicitly add the c2s protocol to the s2s listener by using the imconfutil command to set the set-listener-prop property. This is common for all components, and not just httpbind. If httpbind or any other component is enabled on the same machine during im configuration, this step is not required, as it is automatically carried out by the configure utility.To run a silent configuration, you first complete a false configuration to create a state file. During this false configuration session, your responses to the configure utility are captured in the state file, but no software is modified. In the state file, your responses are retained as a list of parameters, each representing a single prompt or field.
You can then run the configure utility on many hosts by using the state file as input. This process enables you to quickly propagate one configuration across multiple hosts in your enterprise. See "Instant Messaging Server Configuration Script" for information on using the state file to configure a new instance of Instant Messaging Server.
To generate a state file:
Log in as superuser (root).
Change to the InstantMessaging_home/sbin directory. By default, the InstantMessaging_home directory is /opt/sun/comms/im.
Run the configure utility by entering the following:
configure --no --nodisplay --saveState statefile
Where statefile is the name you want to use for the state file. To use the state file to configure a different installation of Instant Messaging Server, use the following command:
configure --nodisplay --silent statefile
As you proceed through the configure utility, your answers are captured in the state file. When you complete the configuration, the state file is available in the location that you specified.
This section provides configure utility examples.
To configure and save the inputs that you provide in the state file:
configure --nodisplay --savestate /tmp/imstate
To configure and use the values from the state file:
configure --nodisplay --state /tmp/imsilent
To configure through the silent mode and use the values from the state file:
configure --silent statefile
To configure and use the values from the state file:
configure --nodisplay --state /tmp/imsilent --savestate /tmp/imstate --no
The command saves a state file. It does not perform the actual configuration as the --no option is used.
To generate a zip state file:
configure --nodisplay --savestate /tmp/imnew.zip
To configure and use the values from the zip state file:
configure --nodisplay --state /tmp/imnew.zip
To configure through silent mode and use the values from the zip state file:
configure --silent imnew.zip
To use a savestate file with encrypted passwords, first create the plaintext savestate file, change the passwords, then generate the passwords by using the imconfutil generate-password command.
The following shows a sample configuration in response to prompts presented by the configure utility. The configuration uses default values for all options.
Component Selection
Select all components you wish to configure.
1. [X] Server components
2. [X] Web components
Service Runtime Options
Runtime User ID : [inetuser]
Runtime Group ID: [inetgroup]
Runtime Directory [/var/opt/sun/comms/im]
Network Access Points
Domain Name example.com
XMPP Port [5222] Multiplexed XMPP Port [45222]
Gateway Connector Port [55222]
XMPP Server Port [5269]
Disable Server (enable only multiplexor) [no]
Enable SSL [yes]:
Server keystore file:
Server password file:
If you decide to enable SSL, the respective server configuration is mandatorily set to TLS for all communication. To disable mandating TLS, set iim_server.requiressl=false by using the imconfutil command.
LDAP Configuration
LDAP Host Name [imhost.siroe.com]
LDAP Port Number [389]
SSL Enabled [no]
Base DN [dc=siroe,dc=com]
Base DN cn=Directory Manager
Base Password
Mail Server Options
Enable Email Integration [yes]
SMTP Server [smtphost]
Enable Email Archiving [yes]
HTTP Gateway Deployment Configuration
Deploy IM HTTP Gateway [yes]
Context Root [http://imhost:80/httpbind]
Web Container Path [Web container base directory]
Web Administrator URL [ ]
Web Administrator User ID [admin]
Web Administrator Password
Calendar Agent configuration
Enable Calendar Agent [no]
Enable local component [no]
SMS Gateway Configuration
Enable SMS Gateway [no]
Enable local component [no]
Instant Messaging Server Services Startup
Start Services After Successful Configuration [yes]
Start Services When System starts [yes]
You can create multiple instances of Instant Messaging Server on a single host from one installation. You might want to do this to create a secure version of Instant Messaging Server, or to support multiple directory namespaces. A namespace is a node in the directory under which each UID is unique. All instances of Instant Messaging Server on a single host share binaries but have unique versions of runtime and configuration files.
This procedure assumes that you have used default installation and configuration values for the InstantMessaging_home and InstantMessaging_runtime directories. If you installed using default values, the original runtime directory for Oracle Solaris is:
/var/opt/sun/comms/im/default
For Red Hat Linux and Oracle Linux, the original runtime directory is:
/var/opt/sun/im/default
If you used paths other than the defaults, substitute your paths for the paths used in this procedure.
Create a runtime directory for the new instance. For example, to create runtime directory xyz on Oracle Solaris, type:
mkdir /var/opt/sun/comms/im/xyz
On Red Hat Linux and Oracle Linux, type:
mkdir /var/opt/sun/im/xyz
Create a log directory for the new instance. For example, to create log directory xyz, on Oracle Solaris, type:
mkdir /var/opt/sun/comms/im/xyz/log
On Red Hat Linux and Oracle Linux, type:
mkdir /var/opt/sun/im/xyz/log
If you are using a file-based property store for user data, you need to create a database directory (InstantMessaging_database) for the new instance. For example, to create database directory xyz, on Oracle Solaris, type:
mkdir /var/opt/sun/comms/im/xyz/db
On Red Hat Linux and Oracle Linux, type:
mkdir /var/opt/sun/im/xyz/db
Copy the contents of the InstantMessaging_home directory and all of its subdirectories into the newly created directories: For example, on Oracle Solaris, type:
cp -r /etc/opt/sun/comms/im/default /etc/opt/sun/comms/im/xyz
On Red Hat Linux and Oracle Linux, type:
cp -r /etc/opt/sun/im/default /etc/opt/sun/im/xyz
Open the new instance's imadmin command in a text editor. By default, this command is stored under the InstantMessaging_home directory you just created for the new instance. For Oracle Solaris, the location is:
/etc/opt/sun/comms/im/xyz/imadmin
For Red Hat Linux and Oracle Linux, the location is:
/etc/opt/sun/im/xyz/imadmin
In the imadmin command, change the configuration file path to the path for the new configuration file for the new instance. For example, on Oracle Solaris, change
/etc/opt/sun/comms/im/default/config/iim.conf
to:
/etc/opt/sun/comms/im/xyz/config/iim.conf
On Red Hat Linux and Oracle Linux, change
/etc/opt/sun/im/default/config/iim.conf
to:
/etc/opt/sun/im/xyz/config/iim.conf
The .xml suffix is not required for the iim.conf file and the imadmin command automatically adds the .xml suffix.
Save and close the imadmin command.
Use the imconfutil command to set configuration properties for the new instance. By default, the iim.conf.xml file is stored in the InstantMessaging_cfg directory you created for the new instance. For Oracle Solaris, the location is:
/etc/opt/sun/comms/im/xyz/config/iim.conf.xml
For Red Hat Linux and Oracle Linux, the location is:
/etc/opt/sun/im/xyz/config/iim.conf.xml
The configuration properties you need to set are:
iim_server.port (default=5269)
iim_mux.listenport (default=5222)
iim_mux.serverport (default=45222)
iim.instancedir
Set to the runtime directory for the new instance, for example, on Oracle Solaris, change
/var/opt/sun/comms/im/default
to:
/var/opt/sun/comms/im/xyz
On Red Hat Linux and Oracle Linux, change
/var/opt/sun/im/default
to:
/var/opt/sun/im/xyz
Ensure that file and directory ownership and permissions are the same for all instances.
Start the new instance.
On Solaris OS:
/etc/opt/sun/comms/im/xyz/imadmin start
On Red Hat Linux and Oracle Linux:
/etc/opt/sun/im/xyz/imadmin start