Chapter 2 Administering Sun™ ONE Instant Messaging Server and Multiplexor

This chapter explains how to administer the Sun™ ONE Instant Messaging server and Sun™ ONE Multiplexor, and perform other administrative tasks, such as changing configuration parameters and managing end-user privileges. This chapter also lists the administrative tasks for Sun ONE Portal Server deployments.

This chapter contains the following sections, which describe the various administrative tasks in Instant Messaging:

Administering Instant Messaging: End Users

The administrative tasks in Instant Messaging are listed in the preceding section and are described throughout the rest of this chapter. Take note of the methods—as explained subsequently—for provisioning and managing end users.

Instant Messaging does not provide user provisioning tools. You need to use a directory provisioning tool for provisioning Instant Messaging end users. Instant Messaging does not provide specific commands to add, modify, or delete Instant Messaging end users.

Likewise in an LDAP-only deployment, you cannot prevent an end user from using Sun™ ONE Instant Messenger. In an LDAP-only deployment, the only way to prevent end users from using Instant Messaging is to delete them from the directory. In an Identity deployment using the policy attributes, you can prevent an end user from accessing Sun ONE Instant Messenger.

The administrator can manage Instant Messaging end users, using the Instant Messaging Administrator Access Control mechanism. For more information on Instant Messaging Administrator Access Control, see "Sun ONE Privacy, Security, and Site Policies". In an Identity deployment, Sun ONE Identity Server is used for provisioning Instant Messaging end users. For more information, see "Sun ONE Identity Server".


Caution	If you deny end users the privilege to set up watches on other end users by editing the sysWatch.acl file, the Sun ONE Instant Messenger’s Main window is not displayed for these end users. This effectively denies end users the ability to send instant messages. However, end users would still be able to see alerts and news channels.

Stopping and Starting the Server and Multiplexor (On Unix)

Start and stop the Instant Messaging server and multiplexor

Start and stop only the multiplexor or only the server

Refresh the Instant Messaging server and multiplexor configuration

Refresh only the multiplexor or server configuration

The imadmin command-line utility can be executed only by the end user who has administration rights to the system(s) on which the Sun ONE Instant Messaging server and multiplexor are running. This end user is typically the identity that the server runs as and is designated during installation:

On Solaris - inetuser

On Windows - the end user with full administration privileges, such as an administrator.

In an Identity deployment, if the Portal Server and the Instant Messaging server are installed on the same host, the end user is the one who is running the Sun ONE Identity Server, as root.

On Solaris: instant-messaging-installation-directory/SUNWiim/sbin

Starting the Sun ONE Instant Messaging server enables Sun ONE Instant Messenger to connect to it. Stopping the Instant Messaging server closes all connections and disconnects all the Instant Messengers.

If required, you can start and stop the multiplexor instance separately. For example, if you have changed a configuration parameter which only affects the multiplexor, or if you only have the multiplexor installed on a different host, you can start and stop the multiplexor instance separately.

To Start the Instant Messaging Server and Multiplexor

For a given instance, the configuration specifies whether only the multiplexor or only the server or both these components are enabled.

Use the imadmin command to start the Sun ONE Instant Messaging Server and/or multiplexor, depending on which component is enabled:

If both server and multiplexor are enabled, this command first starts the Instant Messaging server, and then starts the multiplexor.

To Stop the Instant Messaging Server and Multiplexor

Use the imadmin command to stop the Sun ONE Instant Messaging server and/or multiplexor, depending on which component is enabled.

This command stops the server and the multiplexor, terminates all end user connections, and disconnects any inbound and outbound servers configured.

To Refresh the Configuration (Instant Messaging Server and Multiplexor)

Use the imadmin command with the refresh parameter to refresh the server and/ or multiplexor configuration, as shown in the following example:

This command stops and restarts the enabled server and/or multiplexor components.


Note	Whenever you change a configuration parameter in the iim.conf file, make sure to refresh the configuration.

If necessary, you can stop, start or refresh the multiplexor or server only, regardless of which components are enabled in the configuration. To do this, use the multiplexor or server argument with the imadmin command.

To Start the Multiplexor only, type:

To Stop the Server only, type:

To Start and Stop the Instant Messaging Server and Multiplexor (Windows Only)

On Windows, open the Services dialog box from the Control Panel to start and stop the Instant Messaging server and the multiplexor. For more instructions on starting and stopping services, refer to the documentation provided with the Windows operating system.

Changing Instant Messaging Server and Multiplexor Configuration Parameters

To change configuration parameters, manually edit the configuration parameters and values in the iim.conf file, then refresh the Sun ONE Instant Messaging server configuration. If you change a multiplexor parameter, you only need to refresh the multiplexor using the following imadmin command:

To Change Configuration Parameters

Change to the config directory. For example, on Solaris type:

cd /etc/opt/SUNWiim/default/config

Edit the iim.conf file. For example:

vi iim.conf

Save your changes.

Refresh the configuration.



Caution	If you change the multiplexor listen port (iim_mux.listenport) or the multiplexor host, update the im.html or the im.jnlp files accordingly. Failure to do so disables Sun ONE Instant Messenger from connecting to the server. For more information, see the section on Managing Sun™ ONE Instant Messenger.

Managing Logging

Instant Messaging creates log files that record events, related status of various software components, system errors, and other aspects of the server and multiplexor. By examining the log files, you can monitor many aspects of the server’s operation.

You can configure the level of logging for both the Sun ONE Instant Messaging server and the multiplexor by specifying the parameters in the iim.conf file. For information on configuring the level of logging in the iim.conf file, see the section on To Change Configuration Parameters.

The location of the log files are specified during Instant Messaging installation.

On Solaris, the default directory is:

On Linux, the default directory is:

On Windows, the default directory is:

As part of the regular Instant Messaging server system maintenance, you need to periodically review and trim the log files from occupying more disk space. The server does not perform this action.

Logging Levels

The level or priority of maintaining the error log defines how detailed, or verbose, the log should be. A higher priority level implies less details as only events of high priority (high severity) are recorded in the log file. In contrast a lower priority level implies greater details as more events are recorded in the log file.

You can set the logging level separately for the Instant Messaging server and the multiplexor.

Table 2-1 contains the logging levels for the Instant Messaging server and their description. These logging levels are a subset of the levels defined by the Unix syslog facility.

Table 2-1 Logging Levels for the Instant Messaging Server and the Multiplexor
Level	Description
FATAL	This priority level records minimum logging details in the log file. A log record is added to the log file whenever a severe problem or critical condition occurs. If a FATAL problem occurs, the application might stop functioning.
ERROR	A log record is added to the log file whenever a recoverable software error condition occurs or a network failure is detected. For example, when the server fails to connect to a client or to another server.
WARNING	A log record is added to the log file whenever a user error is detected. For example, when the server cannot understand the communication sent by the client.
NOTICE	A periodic event is written to the log file to report the status of the server. This includes state (running), the number of clients connected, and number of inbound and outbound servers connected.
INFO	A log record is added to the log file whenever a significant action takes place. For example, when an end user successfully logs in or logs out.
DEBUG	The tasks are recorded in the log file. This information is useful for debugging purposes only. Each event with individual steps within each process or task are written to the log file, to help the end user identify the problems while debugging the application.

When you select a particular logging level, events corresponding to that level and to all higher and less verbose levels are logged.

To Set Log File Levels


Note	If you specify DEBUG as the logging level, your log files will occupy more disk space. Monitor and trim your log files to prevent them from occupying more disk space.

The log file levels are set within the iim.conf file. The following are the two log file logging level options:

The parameter for the logging to the server is: iim.log.iim_server.severity.

The parameter for the logging to the multiplexor is: iim.log.iim_mux.severity.

Managing End-User Privileges

The Administrator can control end-user access to Instant Messaging information by restricting privileges to the end user. These privileges determine if the end user can add and delete news channels, send alerts, and setup watches on other end users. These features provide the end users the access to the required features and views in the Instant Messaging. All the Instant Messaging features are controlled by the privilege system that determines what a end user can view or perform on Instant Messaging.

Conference and News Channel Access Controls

User privacy

Conference Room and News Channel Access Controls

For each Conference room and News channel, you can define the default access end users can have. The access privileges end users can have on Conference rooms and News channels are:

MANAGE

WRITE

READ

NONE

End users with the MANAGE privilege can set the default privilege level for all the other end users. They can also define the exception rules to grant an access level that is different from the default access level to specific end users or groups.

The conference room and news channel privileges are set through Sun ONE Instant Messenger. These files are updated automatically when you use Sun ONE Instant Messenger to manage conference rooms and news channels.


Note	Setting the WRITE privilege, grants end users the READ privilege.

Table 2-2 lists the Conference room and News channel access control files and the privileges that these files provide end users. These access control files are located in the db/acls directory.

Room and News Channels Access Control File Format

Table 2-2 Conference Room and News Channel Access Control Files
ACL File	Privileges
roomname.acl	This file sets access privileges that end users can have on conference rooms.
news channelname.acl	This file sets access privileges that end users can have on news channels.

The format of the roomname.acl and news channelname.acl files is slightly different from the system level access control files. For more information on the system level access control files, see "Access Control File Format". The roomname.acl and news channelname.acl files contain an additional number entry after the user or group entry that defines the access level. The access levels are:

1 - None

2- Read

6 - Write

14 - Manage

In the following news channel access control file example, the default access is Read, with Manage access given to user1, Write access given to user2, and an access of None to user3.

User Privacy

You can specify if other end users can see your presence or not. By default, all end users can see your presence status. You can also set exceptions for denying this access to certain end users and groups.

If you have denied other end users from accessing your presence status, then these end users will see your availability status as offline in their contact lists. These end users will not be able to send alerts or chat invitations to you, as your presence status is offline.

User privacy can be configured using the User Settings window in the Instant Messenger. For more information on configuring user privacy, see Sun ONE Instant Messaging Online Help.


Note	The line v:3.0.1 in the newschannel.acl file, tells the server how to interpret the values. If this line is not included, the server will not be able to associate the value of 2 with Read access, and the value 6 with Write access.


Note	Do not edit the roomname.acl and news channelname.acl files manually. These files are updated automatically as you use Sun ONE Instant Messenger to manage conference rooms and news channels. Because Sun ONE Instant Messaging server reads and writes these files when end users change access using Sun ONE Instant Messenger, end users can lose their changes if the files are edited manually while the server is running.

Federating Deployment of Multiple Instant Messaging Servers

In an LDAP-only deployment, when you federate multiple Sun ONE Instant Messaging deployments you form a larger Instant Messaging community. End users from different servers can communicate with each other, user conference rooms on other domains, and subscribe to news channels on remote servers based on the access privileges.

In an Identity deployment, a single Sun ONE Instant Messaging server can host multiple domains. You can designate a single domain as the default domain for a Sun ONE Instant Messaging server instance. End users in different domains hosted by the same server cannot interact with each other. When you federate multiple Sun ONE Instant Messaging deployments, end users in default domains can see the end users in default domains of other remote Sun ONE Instant Messaging servers.

For enabling communication between multiple Sun ONE Instant Messaging servers in your network, you need to configure your server to identify itself to the other Sun ONE Instant Messaging servers in the network. A Sun ONE Instant Messaging server identifies itself with its domain name, host and port number, serverID, and password.

Within the server configuration, you can assign each Sun ONE Instant Messaging server a symbolic name, consisting of letters and digits, for example, IMserver1.

To Configure Communication Between Instant Messaging Servers


Caution	It is recommended that the server-to-server communication is secured using TLS (SSL). This is required to prevent third party infringement of security when data is exchanged between two servers. This precaution is extremely desirable in the case where the link between the two servers uses the public internet. Follow the instructions outlined below to configure SSL between Instant Messaging servers.

This procedure describes how to enable communication between two Instant Messaging servers, iim.company22.com and iim.i-zed.com.

Gather the following information listed in Table 2-3.

Table 2-3 lists the parameters in the iim.conf file for server-to-server communication and the values for these parameters in the Instant Messaging servers, iim.company22.com and iim.i-zed.com.

Table 2-3 Configuration Information for Server-to-Server Communication
Parameter in iim.conf File	Value for Server iim.company22.com	Value for Server iim.i-zed.com
iim_server.serverid	Iamcompany22	Iami-zed
iim_server.password	secretforcompany22	secret4i-zed
iim_server.coservers	coserver1	coserver1
iim_server.coserver1.host	iim.i-zed.com:9919	iim.company22.com:9919
iim_server.coserver1.serverid	Iami-zed	Iamcompany22
iim_server.coserver1.password	secret4i-zed	secretforcompany22

For more information on the configuration parameters, see Instant Messaging Configuration Parameters.



Note	You can configure your server to communicate with other Instant Messaging servers. Each Instant Messaging server is identified by its symbolic name. The symbolic name of the server is added in the iim_server.coservers parameter in the iim.conf file. This parameter has multiple values and each value is separated by a comma.

Change to the config directory on the server iim.company22.com. For example, on Solaris:

cd /etc/opt/SUNWiim/default/config

Edit the iim.conf file, for example:

vi iim.conf



Note	The iim.conf file should be owned by the Instant Messaging server account you created during installation. If the iim.conf file cannot be read by the Instant Messaging server account, Instant Messaging server and multiplexor would be unable to read the configuration. Additionally, you might lose the ability to edit the iim.conf file.

The following example shows the section of the iim.conf file on iim.company22.com corresponding to the server-to-server communications that you can modify:

iim_server.serverid=Iamcompany22

iim_server.password=secretforcompany22

iim_server.coservers=coserver1

iim_server.coserver1.host=iim.i-zed.com:9919

iim_server.coserver1.serverid=Iami-zed

iim_server.coserver1.password=secret4i-zed

Follow Step 2 through Step 3 for the iim.conf file on server iim.i-zed.com.

The following example shows the section of the iim.conf file on iim.i-zed.com corresponding to the server-to-server communications that you can modify:

iim_server.serverid=Iami-zed

iim_server.password=secret4i-zed

iim_server.coservers=coserver1

iim_server.coserver1.host=iim.company22.com:9919

iim_server.coserver1.serverid=Iamcompany22

iim_server.coserver1.password=secretforcompany22

Save the changes and refresh the configurations on both servers.

Configuring SSL

Instant Messenger communicates with the multiplexor component of the server. For a secured connection between the Instant Messaging server and the Instant Messenger, you need to configure SSL between Sun ONE Instant Messenger and the multiplexor.

The following are the steps necessary to configure SSL between Sun ONE Instant Messenger and Multiplexor:


Note	The Instant Messaging server implements SSL differently when compared to the multiplexor. For this reason the steps to configure SSL in multiplexor is enumerated in this section separately.

Requesting a Certificate from the Certificate Authority

Installing the Certificate



Note	For more information about managing certificates, see Sun ONE Web Server Administrator’s Guide.

Configuring the Instant Messaging Server to Enable SSL between the Multiplexor and the Instant Messenger

To Activate SSL for Server to Server Communication

Invoking the Secure Version of Instant Messenger

Requesting a Certificate from the Certificate Authority

To enable SSL between Instant Messenger and multiplexor, you need to install the certificate and create databases for secure communication. You can request and install the certificate using Sun ONE Web Server.

Type the following URL for starting the administration server in your browser:

http://hostname.domain-name:administration_port

Sun ONE Web Server then displays a window prompting you for a user name and password.

Type the administration user name and password you specified during the Web Server installation.

Sun ONE Web Server displays the Administration Server page.

Create a separate Web Server instance. For more information on installing multiple instances of the server, see Installing Multiple Instances of the Server in Sun ONE Web Server, Enterprise Edition Administrator's Guide at:

http://docs.sun.com/source/816-5682-10/esgstart.htm#1003083

Create a trust database to store the public and private keys, referred as the key-pair file. The key-pair file is used for SSL encryption.

For information on creating a trust database, see Creating a Trust Database in Sun ONE Web Server, Enterprise Edition Administrator's Guide at:

http://docs.sun.com/source/816-5682-10/esecurty.htm#1004127

Request a certificate from the Certificate Authority.

For more information on requesting a certificate, see Requesting and Installing Other Server Certificates in Sun ONE Web Server, Enterprise Edition Administrator's Guide at:

http://docs.sun.com/source/816-5682-10/esecurty.htm#1004981

Installing the Certificate

When you receive the server certificate from your Certificate Authority, you need to install the certificate.

Type the following URL for starting the administration server in your browser:

http://hostname.domain-name:administration_port

Sun ONE Web Server then displays a window prompting you for a user name and password.

Type the administration user name and password you specified during the Web Server installation.

Sun ONE Web Server displays the Administration Server page.

Install the server certificate.

For more information on installing the certificate, see Requesting and Installing Other Server Certificates in Sun ONE Web Server, Enterprise Edition Administrator's Guide at:

http://docs.sun.com/source/816-5682-10/esecurty.htm#1004981

Change to your Web Server alias directory.

Copy the database files from your Web Server alias directory to the Instant Messenger config directory.

To copy the database files from Web Server alias directory to the Instant Messenger config directory, type the following:

cp https-serverid-hostname-cert7.db /etc/opt/SUNWiim/default/config/cert7.db

cp https-serverid-hostname-key3.db /etc/opt/SUNWiim/default/config/key3.db

cp secmod.db /etc/opt/SUNWiim/default/config/secmod.db



Note	The end user on which the Instant Messaging server runs should have Read permission on cert7.db, key3.db,and secmod.db files.

Change to your Instant Messaging config directory.

cd /etc/opt/SUNWiim/default/config

Create the sslpassword.conf file using an editor of your choice. For example, you could type:

vi sslpassword.conf

Enter the following line to the sslpassword.conf file

Internal (software) Token:password

Password: The password specified during the creation of the trust database.

Save the file.



Note	All Instant Messenger end users should have Ownership and Read permission on the sslpassword.conf file.

After verifying the functioning of SSL, log in to Sun ONE Web Server as an administrator and remove the web server instance that you have created while requesting the certificate.

Configuring the Instant Messaging Server to Enable SSL between the Multiplexor and the Instant Messenger

Table 2-4 lists the parameters in the iim.conf file for enabling SSL between Sun ONE Instant Messenger and multiplexor. It also contains the description and the default value of these parameters:

Table 2-4 Configuration Information for enabling SSL Between Sun ONE Instant Messenger and Multiplexor
Parameter	Default Value	Description
iim_mux.usessl	off	If the value is set to “on”, the multiplexor requires an SSL handshake for each connection it accepts, before exchanging any application data.
iim_mux.secconfigdir	/etc/opt/SUNWiim/default/config	This directory contains the key and certificate databases. It usually contains the security module database.
iim_mux.keydbprefix	None	This value should contain the key database filename prefix. The key database file name must always end with key3.db. If the Key database contains a prefix, for example This-Database-key3.db, then value of this parameter is This-Database.
iim_mux.certdbprefix	None	This value should contain the certificate database filename prefix. The certificate database file name must always end with cert7.db. If the certificate database contains a prefix, for example Secret-stuff-cert7.db, then value of this parameter is Secret-stuff.
iim_mux.secmodfile	secmod.db	This value should contain the name of the security module file.
iim_mux.certnickname	Server-Cert	This value should contain the name of the certificate you entered while installing the certificate. The certificate name is case-sensitive.
iim_mux.keystorepasswordfile	sslpassword.conf	This value should contain the relative path and the name of the file containing the password for the key database. This file should contain the following line: Internal (software) Token:password Where password is the password protecting the key database.

To enable SSL between Sun ONE Instant Messenger and Multiplexor:

Change to the config directory. For example, on Solaris:

cd /etc/opt/SUNWiim/default/config

Edit the iim.conf file, for example:

vi iim.conf

Add the values mentioned in the Table 2-4 to the Multiplexor configuration parameters.

The following is an example of the iim.conf file with the Multiplexor configuration parameters:

! IIM multiplexor configuration

! =============================

! Multiplexor specific options

! IP address and listening port for the multiplexor.

! WARNING: If this value is changed, the port value of ’-server’ argument

! in the client’s im.html and im.jnlp files should also be changed to match th

is.

iim_mux.listenport = "siroe.com:49909"

! The IM server and port the multiplexor talks to.

iim_mux.serverport = "siroe.com:49999"

! Number of instances of the multiplexor.

iim_mux.numinstances = "1"

! Maximum number of threads per instance

iim_mux.maxthreads = "10"

! Maximum number of concurrent connections per multiplexor process

iim_mux.maxsessions = "1000"

iim_mux.usessl = "on"

iim_mux.secconfigdir = "/etc/opt/SUNWiim/default/config"

iim_mux.keydbprefix = "This-Database"

iim_mux.certdbprefix = "Secret-stuff"

iim_mux.secmodfile = "secmod.db"

iim_mux.certnickname = "Server_Cert"

iim_mux.keystorepasswordfile = "sslpassword.conf"

Invoking the Secure Version of Instant Messenger

The secure version of Instant Messenger can be invoked by accessing the imssl.html file or imssl.jnlp file from your browser. These files are located under the resource directory, the base directory under which all the Sun ONE Instant Messenger resources are stored.

The links to these applet descriptor files can also be added to index.html file.

To Activate SSL for Server to Server Communication

Before you can activate SSL, you must create a certificate database, obtain and install a server certificate, and trust the CA’s certificate as described earlier.

Set these iim.conf parameters:

iim_server.usesslport=true

iim_server.sslport=9910

These parameters should already be in the iim.conf file.

Set the server-to-server configurations as described in Federating Deployment of Multiple Instant Messaging Servers, and add the following:

iim_server.coserver1.usessl=true

Change the port number of the following:

iim_server.coserver1.host=hostname:9910

The port number should be the SSL port of the other server.

Following is a section of iim.conf file with the required SSL configuration:

! Server to server communication port.

iim_server.port = "49919”

! Should the server listen on the server to server communication port

iim_server.useport = "True”

! Should this server listen for server-to-server communication using ssl port

iim_server.usesslport = "True”

iim_server.sslport=49910

iim_server.coservers=coserver1

iim_server.coserver1.serverid=Iamcompany22

iim_server.coserver1.password=secretforcompany22

iim_server.coserver1.usessl=true

iim_server.coserver1.host=iim.i-zed.com:49910

iim_server.serverid=Iami-zed

iim_server.password=secret4i-zed

iim_server.secconfigdir = "/etc/opt/SUNWiim/default/config"

iim_server.keydbprefix = "This-Database"

iim_server.certdbprefix = "Secret-stuff"

iim_server.secmodfile = "secmod.db"

iim_server.certnickname = "Server_Cert"

iim_server.keystorepasswordfile = "sslpassword.conf"

Configuring the Instant Messaging server to enable SSL between two Instant Messaging servers

Table 2-5 lists the parameters in the iim.conf file for enabling SSL between two Sun ONE Instant Messaging servers. It also contains the description and the default value of these parameters:

Table 2-5 Configuration Information for Enabling SSL Between Two Sun ONE Instant Messaging Servers
Parameter	Default Value	Description
iim_server.secconfigdir	/etc/opt/SUNWiim/default/config	This directory contains the key and certificate databases. It usually contains the security module database.
iim_server.keydbprefix	None	This value should contain the key database filename prefix. The key database file name must always end with key3.db. If the Key database contains a prefix, for example This-Database-key3.db, then value of this parameter is This-Database.
iim_server.certdbprefix	None	This value should contain the certificate database filename prefix. The certificate database file name must always end with cert7.db. If the certificate database contains a prefix, for example Secret-stuff-cert7.db, then value of this parameter is Secret-stuff.
iim_server.secmodfile	secmod.db	This value should contain the name of the security module file.
iim_server.certnickname	Server-Cert	This value should contain the name of the certificate you entered while installing the certificate. The certificate name is case-sensitive.
iim_server.keystorepasswordfile	sslpassword.conf	This value should contain the relative path and the name of the file containing the password for the key database. This file should contain the following line: Internal (software) Token:password Where password is the password protecting the key database.
iim_server.trust_all_cert	false	If this value is true than the server will trust all certificates and will also add the certificate information into the log files.

Managing Sun ONE Instant Messaging's LDAP Configuration

An LDAP-only deployment of Sun ONE Instant Messaging server requires a directory server. In an LDAP-only deployment, the Instant Messaging server uses the directory server to perform end-user authentication and to search for end users.

In an Identity deployment, Sun ONE Instant Messaging server uses the directory used by Sun ONE Portal Server. When installed in an Identity deployment environment, Sun ONE Instant Messaging server uses the directory used by the Sun ONE Identity Server to search for end users, and not for end-user authentication. In an Identity deployment, Sun ONE Identity Server performs the authentication.

If you use an LDAP directory to maintain your user namespace, the default configuration makes the following assumptions regarding the schema used by this directory:

End user entries are identified by the inetOrgPerson object class.

Group entries are identified by the groupOfUniqueNames object class.

Sun ONE Instant Messenger user ID attribute of an end user is provided by the uid attribute (from inetOrgPerson objectclass).

The email address of an end user is provided by the mail attribute.

The display name of an end user or group is provided by the cn attribute.

The list of members of a group is provided by the uniqueMember attribute (groupOfUniqueNames object class).

Searching the Directory as Anonymous Users

Instant Messaging needs to be able to search the directory to function correctly. If your directory is configured to be searchable by anonymous users, Instant Messaging has the capability to search the directory. If the directory is not readable by anonymous users, you must take additional steps to configure the iim.conf file with the credentials of a user ID that has at least read access to the directory.

A distinguished name (dn)

The password of the above dn

To Enable Instant Messaging server to Conduct Directory Searches as a Specific End User (Not Anonymous)

Identify values for the following parameters in the iim.conf file:

iim_ldap.usergroupbinddn - Specifies the distinguished name (dn) to use to bind to the directory for searches.

iim_ldap.usergroupbindcred - Specifies the password to use with the distinguished name (dn)

For example:

iim_ldap.usergroupbinddn="cn=iim server,o=i-zed.com"

iim_ldap.usergroupbindcred=secret



Note	You do not have to use administrator-level credentials with write level access, as all that is necessary is read access to the domain tree. Thus, if there is an LDAP user with read level access, use its credentials instead. This is a safer alternative as it does not force you to disseminate the administrator-level credentials.

In an Identity deployment, the directory is generally not searchable by anonymous users. In an Identity deployment set the iim_ldap.useidentityadmin configuration parameter to true. Also you can delete or comment out the following configuration parameters:

iim_ldap.usergroupbinddn

iim_ldap.usergroupbindcred.

Edit the iim.conf file.

See "To Change Configuration Parameters" for instructions on editing the iim.conf file.

If the iim_ldap.usergroupbinddn and iim_ldap.usergroupbindcred parameters do not appear in the iim.conf file, you can add them anywhere in the file.

Configuring Dynamic LDAP Server Group

In the LDAP Server, the dynamic groups filter end users based on their DN and include them in a single group. The dynamic groups are defined in Sun ONE Directory Server as the groupOfUrls objectclass.

To enable end users to view the dynamic groups in search results and add them to their contact list, you need to include the groupOfUrls objects to search results.

The following modifications need to be made to the server configuration file iim.conf:

Change to the config directory. For example, on Solaris:

cd /etc/opt/SUNWiim/default/config

Edit the iim.conf file. For example:

vi iim.conf

Add the following information to the iim.conf file:

iim_ldap.usergroupbynamesearchfilter=(|(&(|(objectclass=groupofuniquenames) (objectclass=groupofurls)))(cn={0}))(&(objectclass=inetorgperson)(cn={0})))

iim_ldap.groupbrowsefilter=(|(objectclass=groupofuniquenames)(objectclass=g roupofurls))

iim_ldap.groupclass=groupOfUniqueNames,groupOfURLs

The attribute and objectclass names are configurable.By default, the memberOfUrls attribute is used as the membership attribute of a dynamic group. If you want to use an attribute name other than memberOfUrls, set the iim_ldap.groupmemberurlattr option to the attribute name you want to use.

Displaying Calendar Reminders and Notifications as Instant Messenger Popups

You can configure the Instant Messenger to display calendar reminders and notifications as Instant Messenger popups if you have deployed Sun ONE Calendar Server and Sun ONE Instant Messaging server. The calendar notifications that are formatted as text/xml or text/calendar are parsed by Instant Messaging and are displayed as popups in Instant Messenger.

To access only the popup feature the calendar users can use the “POPUP” Messenger Flavor instead of using the full Instant Messenger capability. For more information on setting the Messenger Flavor, see "Controlling the Exposed Messenger Feature Set".

The Instant Messenger popups architecture for displaying calendar reminders and notifications as can be explained as follows:


Note	As Single Sign-on is not provided between Sun ONE Calendar Server and Sun ONE Instant Messaging, the user has to authenticate separately on both these services. You need not reauthenticate if these services are deployed in a portal environment.

Java Messaging Service (also referred as JMS) Subscriber subscribes for the calendar events to the Calendar Event Notification Server (ENS).

Calendar Server publishes events or notification to the Event Notification Server (ENS).

The JMS Subscriber receives these reminders and events as messages from the Calendar Event Notification Server (ENS).

From these messages the JMS Subscriber generates text or calendar Instant Messaging messages.

If the owner of the calendar is online, the server sends these Instant Messaging messages to the owner.

The text/calendar message handler in the Instant Messenger generates the HTML alerts based on the content of these messages that is parsed by the Instant Messaging server.

Displaying calendar reminders and notifications as Instant Messenger popups contain the following components:

JMS Message Listener or Subscriber. This module implements the JMS javax.jms.MessageListener interface. For each JMS message received, it builds Instant Messaging notification (alert) message. The following server configuration and contents of incoming JMS messages is used:

The Calendar ID Event URI parameter is used to determine the User ID of the calendar owner. The User ID is then used to build the recipient address of the alert.

The comptype parameter determines the type of calendar object (event or task) described by the message body.

The subject of the generated message is derived from the configuration and the component type.

The originator of the message is provided in the configuration.

The message contents can either be text/xml or text/calendar. If the incoming message is of type text/xml, it is converted to a text/calendar. This text/calendar representation is used to generate the Instant Messenger alert by the Text/Calendar Message Handler.

Text/Calendar Message Handler. This module is a Messenger Bean defined by the Messenger Bean specification. It intercepts all Instant Messaging messages or message type. For each message it intercepts, it generates an HTML alert and displays this alert in the Instant Messenger. It uses the following attributes of the incoming Instant Message to convert it to an HTML alert:

The subject of the incoming message provides information on the message type, such as reminders, calendar database notifications, events and tasks. Each type of calendar event corresponds to a localized subject and is displayed in the popup.

The text of the alert is generated from the information contained in the text/calendar message content. One template is provided for each of the event and the task.

Configuring Calendar Server for Displaying Calendar Reminders and Notifications as Instant Messenger popups

The following needs to be configured in the Calendar Server for displaying calendar reminders and notifications as Instant Messenger popups:

Enabling Alarms

Alarms need to be enabled in the Calendar server and the Calendar Event Notification Server (ENS) needs to be configured to send and receive alarm notifications.

Code Example 2-1 shows the values for alarm configuration parameters in the file ics.conf in the directory calendar-server-install-dir/cal/bin/config/.

A custom alarm URL must be defined in the ics.conf file to enable text/xml or text/calendar formatted notifications.

Code Example 2-2 shows an example of the custom alarm URL and content type defined in the file ics.conf.

Configuring Instant Messaging Server for Displaying Calendar Reminders and Notifications as Instant Messenger Popups

The Instant Messaging server has to be configured for displaying calendar reminders and notifications as Instant Messenger popups. The JMS client in Instant Messaging server needs to be provided with the instructions on how to communicate to the ENS broker as the Calendar Server uses the Event Notification Server (ENS) as a JMS Bus.This is performed using the server configuration options in the file iim.conf.

Table 2-6 shows the server configuration options in the file iim.conf and their description.

Table 2-6 The Server Configuration Options in the file iim.conf and their description.
Option	Description
jms.consumers	This option contains the list of consumers identifiers separated by comma. Each consumers identifier is used to build option names whose values describe a specific consumer.
jms.providers	This option contains the list of JMS provider identifiers separated by comma. Each identifier is associated with a JMS provider and used in option names whose values describe the provider
jms.consumer.consumer.provider	Identifier of the JMS provider is associated with the JMS consumer module called consumer. Consumer is replaced by an actual consumer identifier specified in the option iim.jms.consumers.
jms.consumer.consumer.name	This option contains JMS topic or queue name associated with consumer consumer.
jms.consumer.consumer.type	This option contains the JMS consumer consumer type. It may contain the following values: topic for JMS Topic subscription or queue for JMS queue bindings. The default value is topic.
jms.consumer.consumer.factory	Using JMSMessageListenerFactory a Message Listener for consumer consumer can be instantiated and registered as a JMS callback.
jms.consumer.consumer.param	This option contains a free-form ascii string which is made available to the Message Listener. The string may contain additional information needed to process the incoming JMS messages that is specific to the consumer.
jms.provider.provider.broker	This option contains the JMS broker host and port used while initializing the JMS provider provider.
jms.provider.provider.factory	This option contains the ConnectionFactory class name for the provider

Code Example 2-3 shows the JMS provider definition that is to be provided in the file iim.conf.

Code Example 2-4 contains JMS consumers definition for the calendar in the file iim.conf.

Code Example 2-5 contains the JMS consumer type and the JMS provider for the Calendar Server in the file iim.conf.

Code Example 2-6 contains the JMS consumer topic name for the Calendar Server in the file iim.conf file.

Additional parameters need to be added to build the Instant Messenger message. The jms.consumer.consumer.param option is used for building the message. Calendar Server message listener uses a list of parameters in the following URL style:

eventtype contains the calendar event type. The values of the parameter eventtype is equivalent to the subject properties used by the Messenger Calendar Bean.

originator contains the address of the originator. This value is used in the generated message

Table 2-7 contains the values for the parameter eventtype and their description.

Table 2-7 Values for the parameter eventtype and their description.
eventtype Value	Description
calendar.alarm.event	This value contains the event reminder.
calendar.alarm.todo	This value contains the task reminder.
calendar.alarm	This value contains both the event and the task reminder. The event or the task nature is determined from comptype URL parameter.
calendar.notification.new.event	This value contains the event creation notification.
calendar.notification.new.todo	This value contains the task creation notification
calendar.notification.new	This value contains the component creation notification. The event or task nature is determined from the comptype URL parameter.
calendar.notification.mod.event	This value contains the event modification notification.
calendar.notification.mod.todo	This value contains the task modification notification.
calendar.notification.mod	This value contains the component modification notification. The event or the task nature is determined from the comptype URL parameter.
calendar.notification.del.event	This value contains the subject to be used for event deletion notification.
calendar.notification.del.todo	This value contains the subject to be used for task deletion notification.
calendar.notification.del	This value contains component deletion notification. The event or the task nature is determined from the comptype URL parameter.

The following example shows jms.consumer.calendar.param option with the parameters eventtype and originator:

Example for Displaying Calendar Reminders and Notifications as Instant Messenger Popups

In this example, lets assume Sun ONE Calender Server 5.1.1 is installed on cal.example.com and Sun ONE Instant Messaging server 6.0 is installed on im.example.com. After configuring the Calendar Server and Instant Messaging server the Instant Messaging users should be able to receive reminders for calendar events and tasks.

Configuring Calendar Server

Ensure that you have installed Sun ONE calendar server with the latest patch. Based on the assumption that Calendar is installed on cal.example.com and Instant Messaging is installed on im.example.com, the following are the options that needs to be configured in the file ics.conf:

If the configuration changes are made, restart the calendar server with the following commands:

Configuring Instant Messaging Server

! JMS Consumers

jms.consumers=cal_reminder

jms.consumer.cal_reminder.destination=enp:///ics/customalarm

jms.consumer.cal_reminder.provider=ens

jms.consumer.cal_reminder.type=topic

jms.consumer.cal_reminder.param="eventtype=calendar.alarm"

jms.consumer.cal_reminder.factory=com.iplanet.im.server.JMSCalen darMessageListener

! JMS providers

jms.providers=ens

jms.provider.ens.broker=cal.example.com:7997

jms.provider.ens.factory=com.iplanet.ens.jms.EnsTopicConnFactory

After configuring the Instant Messaging server, restart the server with the following command:

Enabling Calendar Alerts in Instant Messenger

Click Settings icon in the Main window or select Settings from the Tools menu to display the User Settings window.

Select the Alerts tab, and check “Enable calendar alerts” options.

Troubleshooting Display Calendar Reminders and Notifications as Instant Messenger Popups

If calendar alerts are not displayed, follow the steps outlined below to troubleshoot the problem.

Check whether the reminder was generated. The best way to do this is to check if the email reminder was received.

Does the Instant Messaging server receive reminders from the Calendar Server (ENS). Check the Instant Messaging server log file to see whether any data is received from calendar. In the log file, look for records which have CalendarReminder in them. Change the log severity in the server (iim.log.iim_server.severity) to debug in order to gather this information. If you observe that the log file has not logged in any reminders it means that the Instant Messaging server has not received any reminders from the Calendar Server. This may have occurred due to a problem in connecting with ENS or a mismatch between ENS event references used by Calendar and Instant Messaging (enp:///ics/customalarm in the example above).

If calendar reminders are logged in to the log file but the events and tasks are not displayed on the Instant Messenger then move to the next step.

Instant Messenger may have received the calendar alert but is unable to display it. More information on this problem can be obtained by enabling the Java console. For more information on the debug applet parameter, set the value of the parameter to true in the applet page im[ssl].html or im[ssl].jnlp or jnlpLaunch.jsp or pluginLaunch.jsp.

Backing Up Instant Messaging Data

Instant Messaging does not come with any disaster recovery tools. Use your site’s backup system to backup the configuration and database directories periodically.

Backup Information

The Instant Messaging information that needs to be backed up are of the following types:

Configuration Information

Instant Messaging end user data

Instant Messenger resources

The configuration information is stored in the Instant Messaging configuration directory as follows:

Solaris: /etc/opt/SUNWiim/default/config

Linux: /etc/opt/soim/default/config

Windows: instant-messaging-installation-directory\config

(Optional) If you customized any of the files mentioned in Customizing Sun ONE Instant Messenger, back them up from the resource directory.

The Sun ONE Instant Messaging end user data is stored in the following database directories:

Solaris: /var/opt/SUNWiim/default/db

Linux: /var/opt/soim/default/db

Windows: instant-messaging-installation-directory\db

The Instant Messenger resources must be backed up if they have been customized. The location of the Instant Messenger resources are provided during installation.

Performing Backup

While the configuration information does not change frequently, the Instant Messaging end-user data changes rapidly and to prevent any loss of end-user data it is recommended that the Instant Messaging end-user data is backed up on a periodic basis. Backup needs to be performed before running the installation program and the uninstallation program.

To backup the end user data and the configuration information you do not have to stop the Instant Messaging server as all the disk commits by the server are automatically performed.

Restoring the Back Up Information

The back up of the end-user data and the configuration information needs to be restored when there is a disk failure and all the end-user data and the configuration information is lost.