Chapter 2 Installing and Configuring Instant Messaging

This chapter describes installing, upgrading, and migrating Instant Messaging in the following sections:

Before You Begin

Before you install, upgrade, or migrate Instant Messaging, you should read and understand the information in Chapter 1, "Preparing for Installation," and then complete the installation checklist in this section.

Completing the Installation Checklist

During installation, upgrade, and migration, you will be prompted for some basic configuration information. You should gather this information before you begin. You will be prompted for some or all of the information depending on the components you decide to install.

Print out Table 2-1 and write the values for your deployment in the space provided. You can reuse this installation worksheet for multiple installations of Instant Messaging, uninstallation, or for Instant Messaging upgrades. This table contains passwords and other sensitive information, so you should store this information in a safe place.

Table 2-1 Instant Messaging Installation Parameters
Parameter	Description	Your Answers
Installation Directory	instant-messaging-install-dir or installation directory Directory in which Instant Messaging is installed. Defaults: Solaris: /opt/SUNWiim Linux: /opt/soim Windows: C:\Program Files\Sun\Instant Messaging
Instant Messaging Server Host and Domain Name	Host name on which Instant Messaging is installed and the domain name associated with the host. For example: Host Name: instantmessaging.siroe.com Domain Name: siroe.com
Instant Messaging Server Port Number	The port number on which the Instant Messaging Server listens for incoming requests other than those sent by Instant Messenger clients. Default: 49999
Multiplexor Port Number (Multiplexor Configuration Only)	The port number on which the Instant Messaging Server listens for incoming requests from Instant Messenger clients. Default: 49909
Disable Server	Select this option if the instance you installed will act as a multiplexor and not a server. If you select this option, you must provide a value for Remote Instant Messaging Server Host Name (Multiplexor Configuration Only).
Remote Instant Messaging Server Host Name (Multiplexor Configuration Only)	The host name of the Instant Messaging Server for which this multiplexor routes messages. Do not enter a value for this parameter if the installed instance you are configuring is an Instant Messaging Server and not a multiplexor. Dependencies: The Disable Server parameter must be selected, that is, server functionality is disabled.
Assign Instant Messaging Services to existing users (Solaris Only, Optional)	If selected, this option enables Instant Messaging for existing Sun ONE Identity Server users. Dependencies: Sun ONE Portal Server and Sun ONE Identity Server.
Secure Mode (Solaris Only, Optional)	When selected, enables integration with Sun ONE Portal Server Secure Remote Access. Secure Remote Access provides secure access to remote users in an intranet. Users can access Secure Remote Access by logging in to the web-based Portal Server Desktop through the portal gateway. Dependencies: Requires Sun ONE Portal Server and Sun ONE Identity Server. You can run Instant Messaging in secure mode only if Sun ONE Portal Server, Secure Remote Access is configured. See Sun ONE Instant Messaging Administrator’s Guide and Sun ONE Portal Server, Secure Remote Access Administrator’s Guide for instructions. If you enable this feature, you must provide values for the following parameters: Netlet Instant Messaging Port Number (Solaris Only, Optional) Messenger Secure Download Port (Solaris Only, Optional)
Netlet Instant Messaging Port Number (Solaris Only, Optional)	If you enabled Secure Mode (Solaris Only, Optional), this is the port number on which Netlet listens for incoming requests. Default: 49917 Dependencies: Secure Mode (Solaris Only, Optional) enabled, Sun ONE Portal Server and Sun ONE Identity Server.
Messenger Secure Download Port (Solaris Only, Optional)	If you enabled Secure Mode (Solaris Only, Optional), this is the port number from which Instant Messenger resources will be downloaded through Netlet. Default: 49916 Dependencies: Secure Mode (Solaris Only, Optional) enabled, Sun ONE Portal Server and Sun ONE Identity Server.
Enable Instant Message Archive (Solaris Only, Optional)	If selected, enables Sun ONE Portal Server search-based archiving for Instant Messaging. Dependencies: Sun ONE Portal Server and Sun ONE Identity Server.
LDAP Host Name	The host name of the LDAP server that contains user and group information for Instant Messaging. For example, directory.siroe.com. Dependencies: LDAP server such as Sun ONE Directory Server.
LDAP Port Number	The port number on which the directory server listens for incoming requests. For example, 389. Dependencies: LDAP server such as Sun ONE Directory Server.
Base DN	The base distinguished name in the directory tree that contains user and group information for Instant Messaging. For example, o=airius.com. Dependencies: LDAP server such as Sun ONE Directory Server.
Bind DN	During installation, you must use the Directory Manager Bind DN and password. The information is used to update the directory schema with the Instant Messaging and presence service templates and attributes only. This requires Directory Manager access. The Directory Manager Bind DN and password are not saved or used beyond installation and initial configuration. For server configuration, Instant Messaging uses this Bind DN to search users and groups in the directory. Leave this blank if the directory can be searched anonymously. Dependencies: LDAP server such as Sun ONE Directory Server.
Bind Password	The Bind DN password.
SMTP Server Host Name (Optional)	The host name of the SMTP server used to send email notification of messages to offline users. For example, mail.siroe.com. If the SMTP server does not use port 25, specify the port along with the host name. For example, if the SMTP server uses port 1025: mail.siroe.com:1025 Dependencies: SMTP server such as Sun ONE Messaging Server.
Database, Logs, and Runtime File Pathname	The location where the runtime files, database, and logs are stored. Defaults: Solaris: /var/opt/SUNWiim/default Linux: /var/opt/soim Windows: C:\Program Files\Sun\Instant Messaging
Resources and Help Files Pathname	instant-messaging-resource-directory or resource directory The directory in which the resource and online help files are installed. Defaults: Solaris: /opt/SUNWiim/html Linux: /opt/soim/html Windows: C:\Program Files\Sun\Instant Messaging\html
Code Base	The URL from which Instant Messenger downloads resources. You install the resources into the web server’s doc root. For example, assume that the web server www.example.com listens on port 89, the doc root for this web server is /opt/web/, and you choose to install the messenger resources in /opt/web/im, then the messenger resources codebase is as follows: http://www.example.com:89/im/ If you do not provide the correct codebase during installation, you need to update the messenger launch pages codebase/lang/im[ssl].html and codebase/lang/im[ssl].jnlp with the correct URL. On UNIX, it is possible to install the resources in a directory and use a symbolic link to make the resources visible to the web server. For instance, if in the above example you installed the resources in /opt/SUNWiim/html, the messenger resources can be made visible to the web server by creating the following symbolic link. ln -s /opt/SUNWiim/html /opt/web/im See the Sun ONE Instant Messaging Administrator’s Guide, and your web server documentation for more information.

Installing and Configuring Instant Messaging

Use the JES installation program to install Instant Messaging on Solaris. For Linux and Windows, use the setup program provided on the Instant Messaging for Windows and Linux Media Kit installation CD.

Before installing, ensure that you have completed the steps in "Before You Begin", and installed and configured any additional servers required for your Instant Messaging deployment. For information on which servers you may need to install, see "Dependencies on Other Servers".

You use the same procedure to install the server and the multiplexor. When you install the server, the multiplexor is also installed and enabled. If you want to support a multiplexor only on a host, you disable the server installed on that host. A multiplexor is used to balance the load of routing messages in large installations. See Chapter 1, "Preparing for Installation," for more information about multiplexors.

If the web server and Instant Messaging server do not reside on the same host, install the Instant Messenger resources on the web server host.

Instructions for installing Instant Messaging are detailed in the following sections:

Installing and Configuring Using the JES Installation Program (Solaris Only)

Installing and Configuring Using the Graphical User Interface (Linux and Windows)

When you run setup to install Instant Messaging, you install the new software and provide initial configuration information.

Extract the Instant Messaging archive file to a temporary directory.

Do not extract the archive file to the directory in which you want to install Instant Messaging.

Change to the directory in which you extracted the archive file, and then type ./setup (Linux) or run setup.exe (Windows).



Note	Linux only: Do not run the installation program in the background. If you are installing on a remote machine or if root does not own the display, set the DISPLAY environment variable to your host name. For example in C shell type: setenv DISPLAY myhost:0.0

The installation program displays the Welcome screen.

Click Next to continue.

The License Agreement appears.

Read the license agreement and click Yes (Accept License) to accept it, or click No to exit without installing.

The Software Requirements dialog box appears, displaying requirements and dependencies for Instant Messaging.

Confirm that the information matches the requirements for your deployment and that you have the required servers installed, then click Next.

If you do not have the proper servers installed, click Exit to quit the Instant Messaging installation. See "Dependencies on Other Servers" for information about other servers required for Instant Messaging.

Select the directory in which you want to install the Instant Messaging software and click Next.

The default directory is /opt/soim for Linux and C:\Program Files\Sun\Instant Messaging for Windows.

The Select Components dialog box appears, displaying the following options:

Instant Messaging Server

This component includes both the server and multiplexor software.

The multiplexor routes Instant Messenger messages from multiple clients to an Instant Messaging server.

Sun ONE Instant Messenger Resources

The resources are a collection of files including those used to launch the Instant Messenger client, customizable properties, stylesheets, images and audio files, and online help for Instant Messenger.

Select the software components you want to install and click Next.

The Confirm Upgrade and Addition of Components dialog box appears, displaying a list of components to be installed.

Confirm the list of components, and click Next.

If you are installing the Instant Messenger Resources, the Instant Messenger Resource Directory dialog box appears, displaying the location where the installation program will install the resource files. The default directories for resources are as follows:

For Linux: /var/opt/soim/html

For Windows: C:\Program Files\Sun\Instant Messaging\html

Click Next.

The installation program verifies that there is adequate disk space and then displays the Ready to Install dialog box.

Click Install Now.

When the installation process completes, the Summary Information dialog box appears.

Click Details to review the summary information about the installation. When you have finished reviewing the summary information, click Dismiss to close the Summary Information dialog box.

Click Next to begin configuring Instant Messaging.

A series of dialog boxes appears requesting information that will set up the initial configuration for Instant Messaging. The dialog boxes that appear vary depending on the components you selected. Fill in the requested information using the values from your checklist. See "Completing the Installation Checklist" for more information.

Click Exit to exit the installation program.

Installing and Configuring from the Command-Line (Linux Only)

When you run setup to install Instant Messaging, you install the new software and provide initial configuration information.

To install the Instant Messaging components from the command-line, follow these steps:

In a local terminal window, log in as root.

Extract the Instant Messaging archive file to a temporary directory.

Do not extract the archive file to the directory in which you want to install Instant Messaging.

Change to the directory in which you extracted the archive file, and then type:

./setup -nodisplay

The installation program runs in the current window, and text appears explaining how the command-line installation works.

Press Enter to continue.

A welcome message appears.

Press Enter to continue.

Preparatory text appears.

Press Enter to display the Sun ONE Software License Agreement.

Read the license agreement and type Yes (Accept License) and press Enter to accept it and continue. Type No and press Enter to abort the installation program without installing Sun ONE Instant Messaging.

The Software Requirements screen appears, displaying requirements and dependencies for Instant Messaging.

Confirm that the information matches the requirements for your deployment and that you have the required servers installed, then press Enter.

If you do not have the proper servers installed, type Exit to quit the Instant Messaging installation. See "Dependencies on Other Servers" for information about other servers required for Instant Messaging.

Select the directory in which you want to install the Instant Messaging software and press Enter.

The default directory is /opt/soim.

The Select Components screen appears, displaying the following options:

Instant Messaging Server

This component includes both the server and multiplexor software.

The multiplexor routes Instant Messenger messages from multiple clients to an Instant Messaging server.

Sun ONE Instant Messenger Resources

Select the software components you want to install and press Enter.

The Confirm Upgrade and Addition of Components screen appears, displaying a list of components to be installed.

Confirm the list of components, and press Enter.

If you are installing the Sun ONE Instant Messenger Resources, the Instant Messenger Resource Directory screen appears, displaying the location where the installation program will install the resource files. The default directory for resources is /var/opt/soim/html.

Either accept the default or type a different directory and then press Enter.

The installation program verifies that there is adequate disk space and then displays the Ready to Install screen.

Press Enter to begin the installation.

When the installation process completes, the Summary Information screen appears.

Press Enter to begin configuring Instant Messaging.

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 selected. Fill in the requested information using the values from your checklist. See "Completing the Installation Checklist" for more information.

Type Exit to exit the installation program.

Migrating and Upgrading Instant Messaging From a Previous Version

You can upgrade Instant Messaging from a previous version of the software; however, the process by which you upgrade differs depending on the platform you use. On Solaris, you perform a clean installation then migrate your existing data. On Linux and Windows, you can upgrade directly on top of the previous version of Instant Messaging.

Obtain the Instant Messaging software.

Plan time for shutting down the Instant Messaging server.

Inform your users ahead of time about the planned shutdown.

Back up the database and any existing resource and configuration files you have customized. This includes files in the DB, installation, and resource directories. Default locations for these directories are as follows:


Solaris	DB directory: /var/opt/SUNWiim/default/db Installation directory: /opt/SUNWiim Resource directory: /var/opt/SUNWiim/html
Linux	DB directory: /var/opt/soim/db Installation directory: /opt/soim Resource directory: /var/opt/soim/html
Windows	DB directory: C:\Program Files\Sun\Instant Messaging\db Installation directory: C:\Program Files\Sun\Instant Messaging Resource directory: C:\Program Files\Sun\Instant Messaging\html

(Solaris Only) Uninstall Instant Messaging and then delete any directories and security packages, such as NSRP and NSS, that were not removed during the uninstallation. Instructions on uninstalling are provided in the Sun Java Enterprise System Installation Guide.

Ensure that you have completed the checklist in "Completing the Installation Checklist". You will need this information to configure Instant Messaging after you upgrade.

If you have previously installed IM Portal Channel and Portal Archive, you must remove them prior to upgrading Instant Messaging.

Ensure that you have any other required servers installed and configured.

See "Dependencies on Other Servers" for more information.

Shut down the Instant Messaging server and any multiplexors.

Perform the upgrade or migration.

This includes installing the new software and configuring Instant Messaging.

Perform the post-upgrade procedures.

Solaris: Migrate your data. See "Migrating Instant Messaging (Solaris Only)".

Linux and Windows: During upgrade, the setup program creates .new files in the config and html directories. These files contain all the changes added in this version. For example, the installer creates a iim.conf.new file if you customized the existing iim.conf file. After you upgrade, you need to merge the changes back into your customized files. "Upgrading Instant Messaging (Linux and Windows)".

Migrating Instant Messaging (Solaris Only)

In order to upgrade to this release of Instant Messaging, you need to back up your current installation, perform a fresh installation using the JES installation program, then migrate your existing data from the backup to the new installation.

To migrate your data to the new version of Instant Messaging, after you finish installing, copy the following directories from your backup to the new installation directory:

Upgrading Instant Messaging (Linux and Windows)

On Linux, you can upgrade Instant Messaging using the setup program’s graphical user interface, or the command-line interface. On Windows, you must use the graphical user interface to upgrade Instant Messaging.

Upgrade Instant Messaging Using the Graphical User Interface (Linux and Windows)

When you run setup to upgrade an existing installation, you install the new software and provide initial configuration information for Instant Messaging.

To upgrade the Instant Messaging Server, multiplexor, and resources, follow these steps:

Shut down the Instant Messaging server and multiplexor:

Linux: imadmin stop

Windows: Stop the server from the Services Control Panel.

Extract the Instant Messaging archive file to a temporary directory.

Do not extract the archive file to the directory in which Instant Messaging is installed.

Change to the directory in which you extracted the archive file, and then type ./setup (Linux) or run setup.exe (Windows).



Note	Linux only: Do not run the installation program in the background. If you are installing on a remote machine or if root does not own the display, set the DISPLAY environment variable to your host name. For example in C shell type: setenv DISPLAY myhost:0.0

The installation program displays the Welcome dialog box.

Click Next to continue.

The License Agreement appears.

Read the license agreement and click Yes (Accept License) to accept, or click No to exit without upgrading.

The Software Requirements dialog box appears, displaying requirements and dependencies for Instant Messaging.

Confirm that the information matches the requirements for your deployment and that you have the required servers installed, then click Next.

The Select Components dialog box appears, displaying the following options:

Instant Messaging Server

This component includes both the server and multiplexor software.

The multiplexor routes Instant Messenger messages from multiple clients to an Instant Messaging server.

Sun ONE Instant Messenger Resources

The installation program automatically selects the components that are already installed on the system. If the same or a higher version of a component is already installed on the system, the component appears disabled in the list.

Select any additional software components you want to upgrade and click Next.

The Confirm Upgrade and Addition of Components dialog box appears, displaying a list of components to be upgraded.

Confirm the list of components and click Next.

If you are upgrading the resources, the Instant Messenger Resource Directory dialog box appears, displaying the location where the setup program will install the resource files. The default directories for messenger resources are as follows:

For Linux: /var/opt/soim/html

For Windows: C:\Program Files\Sun\Instant Messaging\html

Click Next.

The setup program verifies that there is adequate disk space and then displays the Ready to Install dialog box.

Click Install Now.

When the upgrade process completes, the Summary Information dialog box appears.

Click Details to review the summary information about the upgrade. When you have finished reviewing the summary information, click Dismiss to close the Summary Information dialog box.

Click Next to begin configuring Instant Messaging.

A series of dialog boxes appears requesting information that will set up the initial configuration for Instant Messaging. The dialog boxes that appear vary depending on the components you selected in Step 7. Fill in the requested information using the values from your checklist. See "Completing the Installation Checklist" for more information.

Click Exit to exit the setup program.

If you made a backup of your old installation and want to restore the database or customized files from the backup, see "Post-upgrade Instructions (Linux and Windows)".

Upgrade from the Command-Line (Linux Only)

When you run setup to upgrade an existing installation, you install the new software and provide initial configuration information for Instant Messaging.

To upgrade the Instant Messaging Server, multiplexor, and resources from the command-line, follow these steps:

In a local terminal window, log in as root.

Extract the Instant Messaging archive file to a temporary directory.

Do not extract the archive file to the directory in which Instant Messaging is installed.

Change to the directory in which you extracted the archive file, and then type:

./setup -nodisplay

The setup program runs in the current window, and text appears explaining how the command-line installation works.

Press Enter to continue.

A welcome message appears.

Press Enter to continue.

Preparatory text appears.

Press Enter to display the Sun ONE Software License Agreement.

Read the license agreement and type Yes (Accept License) and press Enter to accept it and continue. Type No and press Enter to exit the setup program without upgrading.

The Software Requirements screen appears, displaying requirements and dependencies for Instant Messaging.

Confirm that the information matches the requirements for your deployment and that you have the required servers installed, then press Enter.

If you do not have the proper servers installed, type Exit to exit the setup program. See "Dependencies on Other Servers" for information about other servers required for Instant Messaging.

The Select Components screen appears, displaying the following options:

Instant Messaging Server

This component includes both the server and multiplexor software.

The multiplexor routes Instant Messenger messages from multiple clients to an Instant Messaging server.

Sun ONE Instant Messenger Resources

Select any additional software components you want to upgrade and press Enter.

The Confirm Upgrade and Addition of Components screen appears, displaying a list of components to be upgraded.

Confirm the list of components, and then press Enter.

If you are upgrading Sun ONE Instant Messenger resources, the Instant Messenger Resource Directory screen appears, displaying the location where the setup program will install the resource files. The default directory for Instant Messenger resources is /var/opt/soim/html.

Press Enter.

The setup program verifies that there is adequate disk space and then displays the Ready to Install screen.

Press Enter.

When the upgrade process finishes installing the software, the Summary Information screen appears.

Press Enter to begin configuring Instant Messaging.

A series of prompts appear requesting information that will set up the initial configuration for Instant Messaging. The prompts that appear vary depending on the components you selected in Step 8. Fill in the requested information using the values from your checklist. See "Completing the Installation Checklist" for more information.

Type Exit to exit the setup program when you have finished upgrading and configuring Instant Messaging.

If you made a backup of your old installation and want to restore the database or customized files from the backup, see "Post-upgrade Instructions (Linux and Windows)".

Post-upgrade Instructions (Linux and Windows)

To restore the database from the backup you created, copy the backup DB directory and all its contents into the new DB directory. By default, the DB directory created during upgrade is installed in the following location:

During upgrade, the setup program creates .new files in the config and html directories. These files contain all the changes added in this version. For example, the installer creates a iim.conf.new file if you customized the existing iim.conf file.

After you upgrade to the new version, you need to locate the .new files, and merge the changes into your existing files. If you do not want to save the changes you made, delete the old file, and rename the corresponding .new file.

When merging the changes, compare the old files with the .new files, line by line, and edit your existing files to incorporate these changes.

Table 2-2 lists files that can be customized, and for which .new files are created during upgrade.

Table 2-2 .new Files
Type of Files	Linux	Windows
Configuration	installation directory/default/config/iim.conf installation directory/default/config/acls/sysAdmin.acl installation directory/default/config/acls/sysTopicsAdd.acl installation directory/default/config/acls/sysRoomsAdd.acl installation directory/default/config/acls/sysSendAlerts.acl installation directory/acls/sysWatch.acl installation directory/default/config/acls/sysSaveUserSettings.acl	installation directory\config\iim.conf installation directory\config\acls\sysAdmin.acl installation directory\config\acls\sysTopicsAdd.acl installation directory\config\acls\sysRoomsAdd.acl installation directory\config\acls\sysSendAlerts.acl installation directory\config\acls\sysWatch.acl installation directory\config\acls\sysSaveUserSettings.acl
Resource	resource directory/im.html resource directory/im.jnlp resource directory/index.html resource directory/language/imres.jnlp resource directory/language/imbrand.jar resource directory/imssl.jnlp resource directory/imssl.html	resource directory\im.html resource directory\im.jnlp resource directory\index.html resource directory\language\imres.jnlp resource directory\language\imbrand.jar resource directory\imssl.jnlp resource directory\imssl.html
For Linux the default value for installation directory is /opt/soim/config and resource directory is /opt/soim/html. For Windows the default value for installation directory is c:\Program Files\Sun\InstantMessaging, and resource directory is c:\Program Files\Sun\InstantMessaging\html.