Completing the Instant Messaging 9 Initial Configuration

Skip to end of metadata
Go to start of metadata

Completing the Oracle Communications Instant Messaging Server 9 Initial Configuration

After you install the Instant Messaging software by using the Communications Suite installer, you must configure the Instant Messaging server to complete the installation. You perform this initial runtime configuration by running the Instant Messaging configuration program, configure. Starting with Instant Messaging 9, the configure program generates an XML-based configuration file unlike the text-based configuration file from previous releases.

Topics:

Before Configuring Instant Messaging

Before you configure Instant Messaging, read and understand the information in the Communications Suite Deployment Planning Guide, perform the installation as described in most current Communications Suite Installation Guide, complete the configuration checklist, and finally configure the software. In addition, if you are configuring Instant Messaging with Oracle Solaris Cluster (formerly Sun Cluster) for High Availability, you need to read Configuring Instant Messaging 9 for High Availability before completing the steps in this information.

Completing the Configuration Checklist

The Instant Messaging Worksheet lists the Instant Messaging properties and their descriptions that you configure during the initial configuration. Gather this information before you begin the initial configuration. You are prompted for some or all of the information depending on the components you installed.

(Oracle Solaris Only) If you are configuring High Availability service for Instant Messaging, see Configuring Instant Messaging 9 for High Availability for specific information about values you can use for these parameters and additional parameters for your checklist.

Creating a UNIX System User and Group

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, you need to create them manually as described in this section. After you create the user and group for Instant Messaging, you should then set permissions appropriately for the directories and files owned by that user.

Do not choose root as a server user ID unless you are deploying Instant Messaging with Access Manager. In this case, you need to use root to allow access to the Access Manager configuration.

To Create the Appropriate UNIX User and Group

  1. Log in as superuser (root).
  2. Create a group to which your system user belongs.
    For example, to create a group named imgroup on an Oracle Solaris platform, type the following:
    groupadd imgroup
  3. 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, type the following:

    For more information on adding users and groups, refer to your operating system documentation.

  4. Ensure that the user and group have been added to the /etc/groups file.

Running the configure Utility

You use the configure utility after you install Instant Messaging to configure the software and to generate the configuration files you use to administer Instant Messaging.

This section has the following topics:

Syntax and Options of the configure Utility

This section describes the configure utility syntax.

configure Syntax

configure [options]

configure Options

The following table shows the options for the configure utility.

Note
The --id, --noconsole, and --loglevel options were removed in Instant Messaging 8.

configure Options

Option Description
--nodisplay Required if the --silent option is not used. Optional if the --silent option is used. Use this option to configure the Instant Messaging server in command-line mode.
--help Optional. Displays the help content for this command.
--verbose Optional. Prints information messages to the standard output.
--savestate statefilename Optional. Should be used with the --nodisplay option. If you use this option, the inputs that you provide during configuration are saved in the state file. Specify the name and location of the state file along with this option. Your responses are stored as a list of parameters in the state file. Each parameter represents a single entry or field value.
--silent statefilename Required if the --nodisplay option is not used. Use this option to run the configure command in the silent mode. Specify the name and path of the state file with this option. If you are configuring the Instant Messaging server by using a state file, you are not prompted to specify the configuration information. Instead, the values from the state file are used to configure the server.
--state statefilename Optional. During configuration, the configure utility provides default values for configuration. You can either use the default values or specify your own value. If you use this option, the configure utility uses all the default values for configuration.
--no Optional. Use this option to perform a dry run of the configuration.
--novalidate Optional. If you use this option, the configure utility does not validate the inputs that you provide during configuration.
--debug Optional. Use this option to view the debug messages on your terminal.

Note
The configure utility ignores any incorrect or invalid command-line options and proceeds with the configuration process by using the valid options.

Configuring Instant Messaging After Installation

  1. Change to im-svr-base/sbin directory.
    By default, the im-svr-base directory is /opt/sun/comms/im/.
  2. Invoke the configure utility.
    • Command-line:
    • From a state file:

      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 Configuration for information on generating a state file.
      If you are not performing a silent installation, series of prompts appears, requesting information that sets up the initial configuration for Instant Messaging. The prompts that appear vary depending on the components you installed. Fill in the requested information using the values from your Instant Messaging checklist. See Completing the Configuration Checklist.

  3. If you install Access Manager on a different host from the Instant Messaging server, you need to manually copy the imServices files from the Instant Messaging server host to the Access Manager host after you run the configure utility.
    To do this:
    1. Locate the imService_*.properties files on the Instant Messaging server host.
      By default, these files are located under /opt/sun/comms/im/lib/ on both Oracle Solaris and Oracle Linux and Red Hat Linux.
    2. Copy the files to the locale directory on the Access Manager host.
      By default this directory is /opt/SUNWam/locale on Oracle Solaris and /opt/sun/identity/locale on Oracle Linux and Red Hat Linux.
  4. If you are using Access Manager to manage Instant Messaging policies, run the imadmin assign_services command.

    You are prompted for the Base DN of the organization under which user entries are stored. This command adds Instant Messaging and presence services to existing users under the organization you specify.

  5. Restart GlassFish Server.
    If Instant Messaging uses Access Manager policies in a GlassFish Server deployment, you need to restart GlassFish Server when you finish configuring Instant Messaging. If you do not restart GlassFish Server, Instant Messaging services do not appear in the Access Manager console (amconsole).
  6. If you intend to use the XMPP/HTTP Gateway, you may need to modify the location of the default log file for the XMPP/HTTP gateway in httpbind_log4j.conf if:
    • On Oracle Solaris, you chose to use a location for logs other than the default
    • On Red Hat Linux, regardless of the path you chose
      To do this:
    1. Open the httpbind_log4j.conf file.
      This file is stored at the location you specified in 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 instance:
      im-cfg-base/httpbind_log4j.conf
    2. 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.
  1. If necessary, configure Access Manager-based services for SSO and policy management.
    See Adding Instant Messaging and Presence Services to a Sub-organization in Access Manager for Single Sign-On and Policy Management Support for information.
  2. Configure client systems to support Instant Messaging.
Note
If httpbind and im are configured to run on different machines, the user must explicitly add the c2s protocol to the s2s listener using the set-listener-prop of imconfutil. 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 configurator tool.

Performing a Silent Instant Messaging Configuration

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 using the state file as input. This process enables you to quickly propagate one configuration across multiple hosts in your enterprise. See Syntax and Options of the configure Utility for information on using the state file to configure a new instance of Instant Messaging.

To generate a state file, perform the following steps:

  1. Log in as superuser (root).
  2. Change to im-svr-base/sbin directory.
    By default, the im-svr-base directory is /opt/sun/comms/im/.
  3. Run the configure utility by typing the following at the command-line:

    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, use the following command:

    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.

Examples of the configure Utility

This section lists a few examples of using the configure command.

  • To configure through the Command-Line Interface (CLI) mode and save the inputs that you provide in the state file:
  • To configure through the CLI mode and use the values from the state file:
  • To configure through the silent mode and use the values from the state file:
  • To configure through the CLI mode and use the values from the state file, type the following command. The command saves a state file. It does not do the actual configuration as the --no option is used.

Sample Configuration by Using the configure Utility

The following lists a sample configuration using default values for all options.

  1. Component Selection
  2. User Management Options
  3. Service Runtime Options
  4. Network Access Points

    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.

  5. LDAP Configuration
  6. Mail Server Options
  7. HTTP Gateway Deployment Configuration
  8. IMPS Gateway Deployment Configuration
  9. Calendar Agent configuration
  10. SMS Gateway Configuration
  11. MSN Gateway Configuration
  12. AIM Gateway Configuration
  13. YAHOO Gateway Configuration
  14. Facebook Gateway Configuration
  15. Instant Messaging Services Startup

Adding Instant Messaging and Presence Services to a Sub-organization in Access Manager for Single Sign-On and Policy Management Support

If you are using Instant Messaging with other server products in the Communications Suite, such as Messaging Server, and you want to use Access Manager for single sign-on (SSO) or policy management, you need to manually configure Access Manager-based services for Instant Messaging. This is because configuration of some Communications Suite products, for example Messaging Server, creates one or more domains under the top-level organization in Access Manager. The configure utility automatically adds these services to the top-level organization if you select yes when prompted to leverage an Access Manager deployment for SSO or policy management.

To Manually Assign Instant Messaging and Presence Services to a Sub-organization in Access Manager

  1. In a web browser, log into the Access Manager admin console:
    http://hostname:port/amconsole
    For example,
    http://amserver.company22.example.com:80/amconsole
  2. Select Organizations from the View drop-down list in the navigation pane (left pane).
    A list of the domains under the top-level organization is displayed in the left pane.
  3. In the navigation pane, click the name of domain under the top-level organization to which you want to add services.
    For example:
    mydomain.example.com
  4. In the navigation pane, select Services from the View drop-down list.
    A list of services assigned to the domain appear in the navigation pane.
  5. Click Add in the navigation pane.
    The data pane (right pane) displays a list of services you can add to the domain.
  6. Under Instant Messaging Configuration in the data pane, select the Instant Messaging service and Presence Service check boxes and click OK.
    The services you selected are now listed in the navigation pane and have been assigned to the domain under the top-level organization.

Creating Multiple Instances from a Single Instant Messaging Installation

You can create multiple instances of Instant Messaging on a single host from one installation. You might want to do this to create a secure version of Instant Messaging, 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 on a single host share binaries but have unique versions of runtime and configuration files.

To Create an Additional Instance of Instant Messaging from an Existing Installation

This procedure assumes that you have used default installation and configuration values for im-svr-base and im-runtime-base. If you installed using the default values, the original runtime directory is:

Oracle Solaris: /var/opt/sun/comms/im/default
Red Hat Linux and Oracle Linux: /var/opt/sun/im/default

If you used paths other than the defaults, you will need to substitute your paths for the paths used in this procedure.

  1. Create a runtime directory for the new instance.
    For example, to create a new runtime directory for instance xyz, type:
    mkdir /var/opt/sun/comms/im/xyz on Oracle Solaris
    mkdir /var/opt/sun/im/xyz on Red Hat Linux and Oracle Linux
  2. Create a log directory for the new instance.
    For example, to create a new log directory for instance xyz, type:
    mkdir /var/opt/sun/comms/im/xyz/log on Oracle Solaris
    mkdir /var/opt/sun/im/xyz/log on Red Hat Linux and Oracle Linux
  3. If you are using a file-based property store for user data, you need to create a database directory (im-db-base) for the new instance.
    For example, to create a new database directory for instance xyz, type:
    mkdir /var/opt/sun/comms/im/xyz/db on Oracle Solaris
    mkdir /var/opt/sun/im/xyz/db on Red Hat Linux and Oracle Linux
  4. Copy the contents of the im-svr-base directory and all of its subdirectories into the newly created directories:
    For example:
    cp -r /etc/opt/sun/comms/im/default /etc/opt/sun/comms/im/xyz on Oracle Solaris
    cp -r /etc/opt/sun/im/default /etc/opt/sun/im/xyz on Red Hat Linux and Oracle Linux
  5. Open the new instance's imadmin script in a text editor.
    By default, this script is stored under the im-svr-base directory you just created for the new instance.
    Oracle Solaris: /etc/opt/sun/comms/im/xyz/imadmin
    Red Hat Linux and Oracle Linux: /etc/opt/sun/im/xyz/imadmin
  6. In the imadmin script, 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
    Note that the .xml suffix is not required for iim.conf and the imadmin script automatically adds the the .xml suffix.
  7. Save and close the imadmin script.
  8. Use the imconfutil command to set the following configuration properties for the new instance.
    By default, the iim.conf.xml file is stored in the im-cfg-base directory you created for the new instance.
    Oracle Solaris: /etc/opt/sun/comms/im/xyz/config/iim.conf.xml
    Red Hat Linux and Oracle Linux: /etc/opt/sun/im/xyz/config/iim.conf.xml
    iim_server.port (default=5269)
    iim_mux.listenport (default=5222)
    iim_mux.serverport (default=45222)
    iim.instancedir (Set to 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.)
  9. Ensure that file and directory ownership and permissions are the same for all instances.
  10. Start the new instance:
    Oracle Solaris: /etc/opt/sun/comms/im/xyz/imadmin start
    Red Hat Linux and Oracle Linux: /etc/opt/sun/im/xyz/imadmin start
Labels:
instantmessaging9 instantmessaging9 Delete
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.

Sign up or Log in to add a comment or watch this page.


The individuals who post here are part of the extended Oracle community and they might not be employed or in any way formally affiliated with Oracle. The opinions expressed here are their own, are not necessarily reviewed in advance by anyone but the individual authors, and neither Oracle nor any other party necessarily agrees with them.