Instant Messaging 7.3 Initial Configuration

h1. Completing the Sun Java System Instant Messaging 7.3 Installation: Initial Configuration

After you install the Instant Messaging software with the Communications Suite installer, you must configure the Instant Messaging server and client to complete the installation. You perform this initial runtime configuration by running the Instant Messaging configuration program, {{configure}}.

This chapter describes these configuration steps in the following sections:
{toc:minLevel=2|maxLevel=2}

Before you configure Instant Messaging, you should read and understand the information in the [_Sun Java Communications Suite 5 Deployment Planning Guide_|http://docs.sun.com/doc/819-4439], perform the installation as described in [_Sun Java Communications Suite 6 Installation Guide_|Communications Suite 6 Installation Guide], complete the configuration checklist, and finally configure the software. In addition, if you are configuring Instant Messaging with Sun Cluster for High Availability, you need to read [Chapter 4, Configuring Instant Messaging for High Availability (Solaris Only)|http://docs.sun.com/app/docs/doc/819-4412/6n6ikpsqa?a=view], in the _Sun Java System Instant Messaging 7.3 Administration Guide_ before completing the steps in this chapter.

h2. {anchor:ACHAQ} Completing the Configuration Checklist
You should gather this information before you begin. You will be prompted for some or all of the information depending on the components you installed.

Print out the [Instant Messaging Configuration Worksheet|Configuration Worksheets - Instant Messaging] and write the values for your deployment in the space provided. You can reuse this checklist for multiple installations of Instant Messaging. This table contains passwords and other sensitive information, so you should store this information in a safe place.

(Solaris Only) If you will be configuring High Availability service for Instant Messaging, see [Instant Messaging HA Overview|http://docs.sun.com/app/docs/doc/819-4412/6n6ikpsqc?a=view] for specific information about values you can use for these parameters and additional parameters for your checklist.

h2. {anchor:ACHAR} 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}} in order to allow access to the Access Manager configuration.

h6. {anchor:FVBYC} To Create the Appropriate UNIX User and Group
# Log in as superuser.
# Create a group to which your system user will belong. \\
\\For example, to create a group named {{imgroup}} on Solaris, type the following:
{code}
# groupadd imgroup
{code}
# 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 Solaris, type the following:
{code}
# useradd -g imgroup imuser
{code}
For more information on adding users and groups, refer to your operating system documentation.
# Ensure that the user and group have been added to the {{/etc/groups}} file.

h2. {anchor:GAMLA} Overview of the configure Utility
You use the {{configure}} utility after you install the software to configure information about your deployment and to generate the configuration files you use to administer and run Instant Messaging.

If you want to customize the resource files for your deployment, you should run the {{configure}} utility, customize the files, then redeploy the resource files. You need to run configure first because the {{configure}} utility creates some of the index and {{.jnlp}} files that you can customize. See [Redeploying Resource Files|http://docs.sun.com/app/docs/doc/819-4412/6n6ikpt1b?l=en&a=view] in the _Sun Java System Instant Messaging 7.3 Administration Guide_ for more information. Also see [Instant Messaging Configuration Worksheet|Configuration Worksheets - Instant Messaging] for information on locating these files after configuration.

The utility displays panels that prompt you for information and provide additional instructions for you to configure your Instant Messaging system.

h2. {anchor:ACHAS} Configuring Instant Messaging After Installing or Upgrading
The Instant Messaging software is not configured by the installer. Instead, you need to run the {{configure}} utility after you install the software.

h6. {anchor:FVBYR} To Configure Instant Messaging After Installation
# Change to the directory in which you installed Instant Messaging.\\
\\By default, this directory is {{/opt/sun/comms/im}} on Solaris and Linux.
# Run the configure utility in one of the following ways:\\
\\Graphical user interface:\\
{{configure}}\\
\\
Command-line:\\
{{configure --nodisplay}}\\
\\
From a state file:
\\
{{configure --nodisplay --noconsole --state}} _statefile_\\
\\where {{statefile}} is the path to the state file you want to use. If you are configuring using a state file, you will 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|Instant Messaging 7.3 Initial Configuration#ACHAT] for information on generating a state file.\\
\\If you are configuring using the graphical user interface or the command line, a series of prompts appears, requesting information that will set 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|#ACHAQ].\\
\\
{note:title=Convergence and the XMPP/HTTP Gateway} If you are configuring the Instant Messaging Server to support Convergence, do not enable the XMPP/HTTP Gateway Deployment when you are prompted for it. Set this value to {{false}}. The XMPP/HTTP Gateway is deployed through the Convergence server; its value is set when you configure Convergence. {note}\\
# 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:\\
a. Locate the {{imService_*.properties}} files on the Instant Messaging server host.\\
\\By default, these files are located under {{/opt/sun/comms/im/lib/}} on Solaris and Linux.
b. Copy the files to the {{locale}} directory on the Access Manager host.\\
\\By default this directory is {{/opt/SUNWam/locale}} on Solaris and {{/opt/sun/identity/locale}} on Linux.
# If you are using Access Manager to manage Instant Messaging policies, run the {{imadmin assign_services}} command.
{code}
imadmin assign_services
{code}
You will be 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.
# Restart Web Container. \\
\\If Instant Messaging will use Access Manager policies in an Application Server deployment, you need to restart the Web Container where Access Manager is installed when you finish configuring Instant Messaging. If you do not restart the Application Server, Instant Messaging services will not appear in the Access Manager console ({{amconsole}}).
# 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 Solaris, you chose to use a location for logs other than the default
#* On Linux, regardless of the path you chose
To do this:
a. 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:
{code}
im-cfg-base/httpbind_log4j.conf
{code}
b. Set the value of the {{log4.appender.appender_ID.file}} parameter to the location where log files are stored.\\
\\By default, on Linux, this value is {{/var/opt/sun/comms/im/default/log}}. If you chose another location for log files when you ran {{configure}}, enter that path as the value for the parameter.
# 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|#GDVWD] for information.
# Configure the web container and client systems to support Instant Messaging. \\
\\For instructions, see [Setting up and Launching Instant Messenger|#ACHAU].


h2. {anchor:GDVWD} 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 Communications Suite server products, 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 only automatically adds these services to the top-level organization and only if you select {{yes}} when prompted if you are planning to leverage an Access Manager deployment for SSO or policy management.
h6. {anchor:GDVXB} To Manually Assign Instant Messaging and Presence Services to a Sub-organization in Access Manager
# In a web browser, log into the Access Manager admin console:
{code}
http://hostname:port/amconsole
{code}
For example:
{code}
http://amserver.company22.example.com:80/amconsole
{code}
# 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.
# In the navigation pane, click the name of domain under the top-level organization to which you want to add services.\\
\\For example:
{code}
mydomain.example.com
{code}
# 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.
# Click Add in the navigation pane.\\
\\The data pane (right pane) displays a list of services you can add to the domain.
# Under Instant Messaging Configuration in the data pane, select the Instant Messaging service and Presence Service checkboxes 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.

h2. {anchor:ACHAT} 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. Next, you will create a platform-appropriate state file ID and modify the state file to include this ID.

You can then run the {{configure}} utility on many hosts using the state file as input. This process allows you to quickly propagate one configuration across multiple hosts in your enterprise. See [Configuring Instant Messaging After Installing or Upgrading|#ACHAS] for information on using the state file to configure a new instance of Instant Messaging.

h6. {anchor:FVBYG} To Generate a Configure State File and ID for Instant Messaging
# Log in as superuser.
# Change to the directory in which you installed Instant Messaging.\\
\\By default, this directory is {{/opt/sun/comms/im}} on Solaris and Linux.
# Run the {{configure}} utility by typing the following at the command-line:\\
{{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, use the following command:\\
{{configure --nodisplay --noconsole --silent -state}} _{{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.
# You may need to generate a new platform-appropriate state file ID if you meet either of the following criteria:
#* You already have a state file you generated for a previous version or patch of Instant Messaging.
#* You already have a state file generated for a previous version and have applied a patch that contains a new or modified version of {{config.class}}.
In either case, the old state file ID will no longer be valid. Complete the following to generate a new ID and replace the old one as follows:
a. Run the {{configure}} utility again, but this time with the \--id option as follows:
{code}
configure --id
{code}
The command generates an encrypted identifier.
b. Copy the identifier and paste the value into the state file as the value for the {{STATE_BEGIN}} and {{STATE_DONE}} parameters.\\
\\For information on using the state file to configure a different installation of Instant Messaging, see [Configuring Instant Messaging After Installing or Upgrading|Instant Messaging 7.3 Initial Configuration#ACHAS].

h2. {anchor:GANJN} 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 may want to do this in order 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.
h6. {anchor:GANJS} 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 would be as follows:\\
\\Solaris and Linux: {{/var/opt/sun/comms/im/default}}\\
\\If you used paths other than the defaults, you will need to substitute your paths for the paths used in this procedure.
# Create a runtime directory for the new instance:\\
\\For example, to create a new runtime directory for instance {{xyz}}:\\
\\Solaris and Linux: {{*mkdir /var/opt/sun/comms/im/xyz*}}\\
# Create a log directory for the new instance:\\
\\For example, to create a new log directory for instance {{xyz}}:\\
\\Solaris and Linux: {{*mkdir /var/opt/sun/comms/im/xyz/log*}}\\
# 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}}:\\
\\Solaris and Linux: {{*mkdir /var/opt/sun/comms/im/xyz/db*}}\\
# Copy the contents of the _im-svr-base_ directory and all of its subdirectories into the newly created directories:\\
\\For example:\\
\\Solaris and Linux: {{*cp -r /etc/opt/sun/comms/im/default /etc/opt/sun/comms/im/xyz*}}\\
# 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:\\
\\Solaris and Linux: {{/etc//opt/sun/comms/im/xyz/imadmin}}\\
# In the {{imadmin}} script, change the configuration file path to the path for the new configuration file for the new instance\\
\\For example:\\
\\On Solaris and Linux, change {{/etc/opt/sun/comms/im/default/config/iim.conf}} to {{/etc/opt/sun/comms/im/xyz/config/iim.conf}}.\\
# Save and close the {{imadmin}} script.
# Open the new instance's {{iim.conf}} file in a text editor.\\
\\By default, the {{iim.conf}} file is stored in the _im-cfg-base_ directory you created for the new instance:\\
\\Solaris and Linux: {{/etc/opt/sun/comms/im/xyz/config/iim.conf}}\\
# Modify the port numbers in {{iim.conf}} so they do not conflict with the original instance.\\
\\The default port numbers are as follows:
#* Server port ({{iim_server.port}}) – 5269
#* Multiplexor listen port ({{iim_mux.listenport}}) – 5222
#* Multiplexor to server communication port ({{iim_mux.serverport}}) – 45222
For more information about these parameters, see [Appendix A, Instant Messaging Configuration Parameters in iim.conf|http://docs.sun.com/app/docs/doc/819-4412/6n6ikpt2u?a=view].
# Modify {{iim.instancedir}} to point to _im-svr-base_.\\
\\See [Instant Messaging Server Directory Structure|http://docs.sun.com/app/docs/doc/819-4412/6n6ikpsq7?a=view] for information on _im-svr-base_.
# Modify {{iim.instancevardir}} to point to the runtime directory for the new instance.\\
\\For example:\\
\\On Solaris and Linux, change {{/var/opt/sun/comms/im/default}} to {{/var/opt/sun/comms/im/xyz}}.\\
# Save and close {{iim.conf}}.
# Ensure that file and directory ownership and permissions are the same for all instances.

h2. {anchor:ACHAU} Setting up and Launching Instant Messenger
This section contains information about configuring the web container and client systems to support Instant Messenger in the following sections:
* [Enabling Java Web Start|#ACHAV]
* [Configuring Client Systems for Instant Messaging|#ACHAW]
* [Launching Instant Messenger|#ACHAX]

h3. {anchor:ACHAV} Enabling Java Web Start
To use Instant Messenger with Java Web start, you need to install the software, then configure your web container to work with Java Web Start. For instructions on installing Java Web Start, go to [http://java.sun.com/products/javawebstart|http://java.sun.com/products/javawebstart].\\
\\To enable Java Web Start support in your web container, you need to edit the web container’s {{mime.types}} file to include the following definition for JNLP:\\
\\Content Type: {{application/x-java-jnlp-file}}\\
\\Suffix: {{jnlp}}\\
\\This section provides the following instructions:
{toc-zone:minLevel=6|maxLevel=6|location=top|type=list}

h6. {anchor:FVBYO} To Add the MIME Type to Sun Java System Web Server Enterprise Edition
# Type the following URL to access the administration server in your browser:
{code}
http://hostname.domain-name:administration-port
{code}
For example: {{http://budgie.siroe.com:8888}}\\
\\Web Server displays a window prompting you for a user name and password.
# Type the administration user name and password you specified during the web container installation.\\
\\The web container displays the Administration Server page.
# On the Manage Servers page, click Manage.\\
\\The web container displays the Server Manager page.
# Click the MIME Types link.
# From the MIME file drop-down list, choose a MIME type to edit and click OK.
# In the Global MIME Types page, select {{type}} from the Category drop-down list.
# In the Content-Type text box, type:
{code}
application/x-java-jnlp-file
{code}
# In the File-Suffix text box, type:
{code}
jnlp
{code}
# Click New Type to create the MIME type.
# Restart the web container for this change to take effect.

h6. {anchor:FVBYM} To Add the MIME Type to Apache Web Container
# Add the following line to the {{mime.types}} file:
{code}
application/x-java-jnlp-file jnlp
{code}
By default, this file is located in the Apache Web Container configuration directory.
{toc-zone}

h3. {anchor:ACHAW} Configuring Client Systems for Instant Messaging
If the client machine has the appropriate version of Java installed, there are no additional requirements to use either Java Plug-in or Java Web Start. Netscape Navigator v7 as well as the recent versions of the Mozilla browser include the latest version of Java, while Internet Explorer does not. See the [Sun Java Communications Suite 6 Release Notes|Communications Suite 6 Release Notes] for version requirements.\\
\\If the client machine does not have the required version of Java installed, you need to install Java Web Start. You can download and Install Java from [http://www.java.sun.com/j2se|http://www.java.sun.com/j2se].\\
\\You can download and install Java Web Start from [http://www.java.sun.com/products/javawebstart|http://www.java.sun.com/products/javawebstart].

h3. {anchor:ACHAX} Launching Instant Messenger
You can run Instant Messenger as an applet within a web browser, or as a standalone application as described in the following sections:
{toc-zone:minLevel=4|maxLevel=4|location=top|type=list}

h4. {anchor:ACHAY} Running Instant Messenger From a Web Browser
Follow these instructions to run Instant Messenger as an applet within a web browser.
h6. {anchor:FVBYB} To Run Instant Messenger as an Applet Within a Web Browser:
# Start the web browser.\\
\\For information on supported browsers, see the [Sun Java Communications Suite 6 Release Notes|Communications Suite 6 Release Notes].
# Go to the Instant Messaging home page. \\
\\By default, the home page is stored as {{index.html}}. Use the following format to locate the Instant Messaging home page:\\
\\ {{http://}}_codebase_{{/index.html}}\\
\\Where _ codebase_ is the URL that corresponds to the location of the resource files on the web container.
# Click Use Java Plug-In.\\
\\If you customized the home page and changed the link text, click the link that corresponds to running Instant Messenger as an applet within a browser. The link points to either {{im.jnlp}} (standard and TLS mode) or {{imssl.jnlp}} (legacy SSL mode).\\
\\When the Instant Messenger session is established using the Java Plug-in, the browser window must be dedicated to its use.\\
\\You cannot locate any other URLs with this browser window, nor can you close the browser window without terminating the Instant Messenger session.

h4. {anchor:ACHAZ} Running Instant Messenger as a Standalone Application
Follow these instructions to run Instant Messenger as a standalone application.
h6. {anchor:FVBYE} To Run Instant Messenger as a Standalone Application
# Start the web browser.\\
\\For information on supported browsers, see the Sun Java System Instant Messaging 7 2006Q4 Release Notes.
# Go to the Instant Messaging home page. \\
\\By default, the home page is stored as {{index.html}}. Use the following format to locate the Instant Messaging home page:\\
\\ {{http://}}_codebase_{{/index.html}}\\
\\Where _ codebase_ is the URL that corresponds to the location of the resource files on the web container.
# Click Start.\\
\\If you customized the home page and changed the link text, click the link that corresponds to running Instant Messenger using Java™ Web Start. The link points to either {{im.html}} (standard or TLS mode) or {{imssl.html}} (legacy SSL mode).\\
\\See [Customizing Instant Messenger|#ACHCN] for information on customizing the resource pages.
{toc-zone}