Chapter 1, Configuring Instant Messaging After Installation contains configuration steps you need to complete after you install or upgrade, before you can use Instant Messaging.
Chapter 2, Setting up and Launching Instant Messenger provides information about configuring client systems, enabling JavaTM Web Start, and adding additional localization client files. Also explains how to launch the client.
After installation, you need to complete a few configuration steps before using Sun JavaTM System Instant Messaging. This chapter describes these configuration steps in the following sections:
Before you configure Instant Messaging, you should read and understand the information in the Sun Java Communications Suite 5 Deployment Planning Guide, perform the installation as described in Sun Java Communications Suite 5 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) before completing the steps in this chapter.
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 following table 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 for specific information about values you can use for these parameters and additional parameters for your checklist.
Table 1–1 Configuration Parameters for Instant Messaging
Parameter |
Description |
Your Value |
---|---|---|
im-svr-base Directory in which Instant Messaging is installed. By default, Instant Messaging is installed into the /opt directory as follows: Solaris: /opt/SUNWiim Linux: /opt/sun/im (Solaris Only) If you will be configuring High Availability service for Instant Messaging, see Selecting the Installation Directory (im-svr-base) for information about choosing an installation directory. | ||
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 (Solaris Only) If you will be configuring High Availability service for Instant Messaging, use the logical host name. | ||
The port number on which the Instant Messaging Server listens for incoming requests from the multiplexor. Default: 45222 | ||
The port number on which the Instant Messaging server listens for incoming requests from other Instant Messaging servers. In addition, if no multiplexor is installed, the server listens for incoming requests from Instant Messenger clients on this port. Default: 5269 | ||
Multiplexor Port Number |
The port number on which the Instant Messaging Server listens for incoming requests from Instant Messenger clients. Default: 5222 | |
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. | ||
Remote Instant Messaging Server Host Name (Multiplexor Configuration Only) |
The host name of the Instant Messaging Server for which this multiplexor routes messages. If the multiplexor and server are installed on the same host, use localhost. (Solaris Only) If you will be configuring High Availability service for Instant Messaging, use the logical host's name. Dependencies: The Disable Server parameter must be selected, that is, server functionality is disabled. | |
Sun Java System Access Manager Configuration |
If the configure utility detects that you have installed the Access Manager SDK, you will be prompted to provide answers for the following questions related to Access Manager:
| |
Sun Java System Calendar Server and Calendar Agent Configuration |
The configure utility asks if you want to enable the Calendar agent. If you choose to enable the Calendar agent, you need to provide the following information:
If you choose not to enable the Calendar agent, you can manually configure the Calendar agent later. More information about the Calendar agent configuration parameters and acceptable values is described in Chapter 16, Using Calendar Pop-up Reminders. | |
Enable Instant Messaging Archive (Optional) |
If selected, enables Sun Java System Portal Server search-based archiving for Instant Messaging. Dependencies: Sun Java System Portal Server and Sun Java System Access Manager. | |
LDAP Host Name |
In a deployment with an LDAP server, 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 Java System Directory Server. | |
LDAP Port Number |
In a deployment with an LDAP server, the port number on which the directory server listens for incoming requests. For example, 389 . Dependencies: LDAP server such as Sun Java System Directory Server. | |
Base DN |
In a deployment with an LDAP server, 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 Java System Directory Server. | |
Bind DN |
In a deployment with Sun Java System Access Manager, during installation, you must provide the Directory Manager Bind DN and password. This Bind DN 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. In a deployment with an LDAP server but without Access Manager, Instant Messaging uses this Bind DN to search users and groups in the directory. Leave this blank if the directory can be searched anonymously. You can change the bind credentials later if required as described in To Configure Bind Credentials for the Instant Messaging Server. Dependencies: LDAP server such as Sun Java System Directory Server. | |
Bind Password |
In a deployment with an LDAP server, 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 Java System Messaging Server. | |
Database, Logs, and Runtime Files Pathname |
The location where the runtime files, database, and logs are stored. Also referred to as im-runtime-base. Runtime files are read, created, and modified by the server during its normal operations. Some examples include log files, and persistent state information tied to client actions such as alert messages, roster information, conferences, news channels, and so on. If you are configuring High Availability (HA) for Instant Messaging, this path must be globally available. See Chapter 4, Configuring Instant Messaging for High Availability (Solaris Only) for more information about HA. The configure utility appends a directory (/default) to the path you provide for the runtime files. The name of this directory is the instance to which the runtime files apply. Later, you can create multiple instances of Instant Messaging by creating additional instance directories with different names (for example /secure) and copying over files from the /default instance runtime directory. See Creating Multiple Instances from a Single Instant Messaging Installation for specific instructions. If you accept the following defaults when you run configure: Solaris: /var/opt/SUNWiim/ Linux: /var/opt/sun/im/ The configure utility creates the following directories for the runtime files: Solaris: /var/opt/SUNWiim/default Linux: /var/opt/sun/im/default In addition, the following two subdirectories are created under the runtime directory. The database directory (im-db-base) defaults are as follows: Solaris: /var/opt/SUNWiim/default/db Linux: /var/opt/sun/im/default/db The log directory defaults are as follows: Solaris: /var/opt/SUNWiim/default/log Linux: /var/opt/sun/im/default/log | |
Resources, Help Files, and HTTP Gateway Pathname |
Resource Directory. The directory in which the resource files, online help, and the XMPP/HTTP Gateway are installed. If you want to customize the resource files for your deployment, you should run 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 for information. Default: im-svr-base/html | |
XMPP/HTTP Gateway Deployment |
Determines whether or not the XMPP/HTTP gateway will be deployed. If you choose to deploy the gateway, the configure utility creates a default gateway configuration file (httpbind.conf) in the default Instant Messaging server instance's im-cfg-base directory if one does not already exist. If httpbind.conf already exists, the configure utility does not alter or overwrite the file. Default: True (gateway is deployed) | |
XMPP/HTTP Gateway URI |
Defines the URI for the HTTP component of the XMPP/HTTP gateway. Default: http://web-svr-host:80/httpbind | |
Codebase |
The URL from which Instant Messenger accesses resources, including the start page for initial downloads of the Instant Messaging client. The installation program installs the resource files into the following locations: Linux: /opt/sun/im/html Solaris: /opt/SUNWiim/html The configure utility uses the codebase to determine which web container instance to use. If it succeeds, the configure utility deploys the Instant Messenger resources as a web application in the web container, according to the URL provided. If no supported web container is detected, you will be prompted for a file system location in which to copy or link the resources. If you are using Instant Messaging with Sun Java System Application Server or Sun Java System Web Server, the configure utility automatically publishes the resource files to the web container for you. For Sun Java System Application Server, the configure utility uses the asadmin command, for Sun Java System Web Server 6, the configure utility uses the wdeploy command, for Sun Java System Web Server 7, the configure utility uses the wadm command. If you are using a different web container, the configure utility copies the files to a location you specify. This should include the web container’s doc root. Alternatively, you can add the resource files installation directory as a doc root in your web container’s configuration. See the documentation for your web container for more specific instructions. In addition, you can use a symbolic link to make the resources visible to the web container. For example, on Solaris the resources can be made visible to the web container by creating the following symbolic link: ln -s /opt/SUNWiim/html docroot/im Where docroot is the doc root of the web container, for example /opt/web. If you are using SSO with Sun Java System Access Manager, the Access Manager server and Instant Messaging server must be configured to use the same web container. See your web container documentation for more information about deploying resource files as a web application. See Changing the Codebase if you need to modify the location of the resource files after initial 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, 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.
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:
# groupadd imgroup |
Create the system user and associate it with the group you just created 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:
# useradd -g imgroup imuser |
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.
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 for information. Also see Completing the Configuration Checklist 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.
The Instant Messaging software is not configured by the installer. Instead, you need to run the configure utility after you install the software.
If you are using the BEA web container, you need to create a PASSFILE before you can configure Instant Messaging. If you are not using the BEA Web Container, skip to To Configure Instant Messaging After Installation.
Create a file named installation directory/SUNWiim/lib/PASSFILE.
Add the following lines to the file you created:
DS_DIRMGR_DN=Directory Manager Bind DN DS_DIRMGR_PASSWORD=Directory Manager Bind Password DS_HOST=LDAP Host Name DS_PORT=LDAP Port Number DS_BASE_DN=Base DN |
Fill in the values for each of the variables.
Change to the directory in which you installed Instant Messaging.
By default, this directory is /opt/SUNWiim on Solaris, and /opt/sun/im on 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 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.
If you install the Sun Java System 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:
Locate the imService_*.properties files on the Instant Messaging server host.
By default, these files are located under /opt/SUNWiim/lib/ on Solaris and /opt/sun/im/lib/ on Linux.
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.
imadmin assign_services |
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 Sun Java System Application Server.
If Instant Messaging will
use Access Manager policies in a Sun Java System Application Server deployment,
you need to restart the Application Server 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:
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 |
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/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 for information.
Configure the web container and client systems to support Instant Messaging.
For instructions, see Chapter 2, Setting up and Launching Instant Messenger.
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 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.
In a web browser, log into the Access Manager admin console:
http://hostname:port/amconsole |
For example:
http://amserver.company22.example.com:80/amconsole |
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:
mydomain.example.com |
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.
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 for information on using the state file to configure a new instance of Instant Messaging.
Log in as superuser.
Change to the directory in which you installed Instant Messaging.
By default, this directory is /opt/SUNWiim on Solaris, and /opt/sun/im on 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:
Run the configure utility again, but this time with the --id option as follows:
configure --id |
The command generates an encrypted identifier.
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.
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.
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: /var/opt/SUNWiim/default
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.
Create a runtime directory for the new instance:
For example, to create a new runtime directory for instance xyz:
Solaris: mkdir /var/opt/SUNWiim/xyz
Linux: mkdir /var/opt/sun/im/xyz
Create a log directory for the new instance:
For example, to create a new log directory for instance xyz:
Solaris: mkdir /var/opt/SUNWiim/xyz/log
Linux: 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 (im-db-base) for the new instance:
For example, to create a new database directory for instance xyz:
Solaris: mkdir /var/opt/SUNWiim/xyz/db
Linux: mkdir /var/opt/sun/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: cp -r /etc/opt/SUNWiim/default /etc/opt/SUNWiim/xyz
Linux: cp -r /etc/opt/sun/im/default /etc/opt/sun/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: /etc/opt/SUNWiim/xyz/imadmin
Linux: /etc/opt/sun/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, change /etc/opt/SUNWiim/default/config/iim.conf to /etc/opt/SUNWiim/xyz/config/iim.conf.
On Linux, change /etc/opt/sun/im/default/config/iim.conf to /etc/opt/sun/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: /etc/opt/SUNWiim/xyz/config/iim.conf
Linux: /etc/opt/sun/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.
Modify iim.instancedir to point to im-svr-base.
See Instant Messaging Server Directory Structure for information on im-svr-base.
Modify iim.instancevardir to point to the runtime directory for the new instance.
For example:
On Solaris, change /var/opt/SUNWiim/default to /var/opt/SUNWiim/xyz.
On Linux, change /var/opt/sun/im/default to /var/opt/sun/im/xyz.
Save and close iim.conf.
Ensure that file and directory ownership and permissions are the same for all instances.
Make renamed copies of im-svr-base/html/locale/im.html, im.jnlp, and index.html resource files , and modify the copies to point to the new instance's port number.
Redeploy the renamed resource files.
See Redeploying Resource Files for instructions.
Start the new instance:
Solaris: /etc/opt/SUNWiim/xyz/imadmin start
Linux: /etc/opt/sun/im/xyz/imadmin start
This chapter contains information about configuring the web container and client systems to support Instant Messenger in the following sections:
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.
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:
Type the following URL to access the administration server in your browser:
http://hostname.domain-name:administration-port |
For example: http://budgie.siroe.com:8888
Sun Java System 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:
application/x-java-jnlp-file |
In the File-Suffix text box, type:
jnlp |
Click New Type to create the MIME type.
Restart the web container for this change to take effect.
Add the following line to the mime.types file:
application/x-java-jnlp-file jnlp |
By default, this file is located in the Apache Web Container configuration directory.
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 System Instant Messaging 7 2006Q4 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.
You can download and install Java Web Start from http://www.java.sun.com/products/javawebstart.
You can run Instant Messenger as an applet within a web browser, or as a standalone application as described in the following sections:
Follow these instructions to run Instant Messenger as an applet within a web browser.
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 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.
Follow these instructions 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 for information on customizing the resource pages.