| Sun ONE Instant Messaging Administrator's Guide |
Chapter 2
Administering Instant Messaging Server and MultiplexorThis chapter explains how to administer Instant Messaging server and Multiplexor, and perform other administrative tasks, such as changing configuration parameters and managing user privileges. This chapter also lists the administrative tasks for Sun ONE Portal Server deployments.
This chapter contains the following sections:
Administering Instant Messaging an OverviewThe administrative tasks in Instant Messaging are:
- Starting, stopping, and refreshing the server and the multiplexor with the imadmin command
- Changing the configuration parameters, such as host names and LDAP search filters, by manually editing the iim.conf file
- Managing server and multiplexor log files
- Managing user privileges (Access Control files)
- Configuring communication between multiple Instant Messaging servers
- Setting up and using Secure Sockets Layer (SSL)
- Backing up and restoring Instant Messaging server files
User Administration
Instant Messaging does not provide user provisioning tools. You need to use a directory provisioning tool for provisioning Instant Messaging users. Instant Messaging does not provide specific commands to add, modify, or delete Instant Messaging users.
Likewise in a standalone deployment, you cannot prevent a user from using Sun ONE Instant Messenger. In a standalone deployment, the only way to prevent users from using Instant Messaging is to delete them from the directory. In a portal deployment using the policy attributes, you can prevent a user from accessing Instant Messenger.
The administrator can manage Instant Messaging users, using the Instant Messaging Administrator Access Control mechanism. For more information on Instant Messaging Administrator Access Control, see Sun ONE Instant Messaging Access Control. In a portal deployment, Sun ONE Identity Server is used for provisioning Instant Messaging users. For more information, see Sun ONE Identity Server.
Stopping and Starting the Server and Multiplexor (On Unix)The imadmin command enables you to:
The imadmin command-line utility can be executed only by the user who has administration rights to the system(s) on which the Sun ONE Instant Messaging server and multiplexor are running. This user is typically the identity that the server runs as and is designated during installation:
The imadmin command-line utility is located in the following directory:
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:
imadmin start
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.
imadmin stop
This command stops the server and the multiplexor, terminates all 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:
imadmin refresh
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 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 ParametersInstant Messaging stores configuration parameters in the iim.conf file. For a complete list of configuration parameters, see Instant Messaging 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:
imadmin refresh multiplexor
To Change Configuration Parameters
For a complete list of parameters and their values, see Instant Messaging Configuration Parameters.
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 the Sun ONE Instant Messenger from connecting to the server. For more information, see the section on Managing Instant Messenger.
Managing LoggingInstant 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.
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.
When you select a particular logging level, events corresponding to that level and to all higher and less verbose levels are logged.
NOTICE is the default level for both the server and the multiplexor log files.
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.
To Set Log File Levels
The log file levels are set within the iim.conf file. The following are the two log file logging level options:
For more information on configuring Instant Messaging, see To Change Configuration Parameters.
Managing User PrivilegesThe Administrator can control user access to Instant Messaging information by restricting privileges to the user. These privileges determine if the user can add and delete news channels, send alerts, and setup watches on other users. These features provide the 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 user can view or perform on Instant Messaging.
Sun ONE Instant Messaging provides the following access control mechanisms:
Global Access Control
Global access control provides all the users the privilege to access the following Instant Messaging features:
By default, the end user is provided the privileges to access the presence status of other users, send alerts to users, and save properties to the server. In most of the deployments, the default values need not be changed. These default values need to be changed when Instant Messaging is used exclusively for the popup functionality.
The location of the global access control ACL files are:
Table 2-2 contains the global access control ACL files for Sun ONE Instant Messaging and the privileges these ACL files provide the users.
Conference Room and News Channel Access Controls
For each Conference room and News channel, you can define the default access the users can have. The access privileges the users can have on Conference rooms and News channels are:
Users with the MANAGE privilege can set the default privilege level for all the other users. They can also define the exception rules to grant an access level that is different from the default access level to specific 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.
Table 2-3 lists the Conference room and News channel access control ACL files and the privileges that these files provide the users. These ACL files are located in the db/acls directory.
Presence Access Control
You can specify if other users can see your presence or not. By default, all users can see your presence status. You can also set exceptions for denying this access to certain users and groups.
If you have denied other users from accessing your presence status, then these users will see your availability status as offline in their contact lists. These users will not be able to send alerts or chat invitations to you, as your presence status is offline.
Presence access control can be configured using the User Settings window in the Instant Messenger. For more information on configuring presence access control, see Sun ONE Instant Messaging Online Help.
Instant Messaging Administrator Access Control
The Instant Messaging Administrator has access to all Instant Messaging features. The Administrator has MANAGE access to all conference rooms and news channels. They can also see the presence information of any user, view and modify properties such as Contact Lists and Instant Messenger Users Settings of any user. The global access control settings have no impact on the Administrator.
Table 2-4 lists the Administrator access control ACL file and the privileges this ACL file provides the Administrator. This ACL file is located in the config/acls directory:
Access Control File Format
The access control file contain a series of entries that define the privileges. Each entry starts with a tag as follows:
The tag is followed by a colon (:). In case of the default tag it is followed by true or false.
The user and group tags are followed by the user or group name.
Multiple users and groups are specified by having multiple users (u)and groups (g) in lines.
If default is set to true, all other entries in the file are redundant. If default is set to false, only the users and groups specified in the file will have that particular privilege.
The following are the default d: tag entries in the ACL files for a new installation:
Note
The format and also the existence of all the ACL files might undergo changes in the future release of the product.
Access Control File Examples
This section consist of sample ACL files that show privileges set at the system level, (sysTopicsAdd.acl) and at the conference room or news channel level (newschannel.acl).
sysTopicsAdd.acl File
In the following example, the default d: tag entry for sysTopicsAdd.acl file is false. So the Add and the Delete news channels privileges are available to the users and groups that appear before the default, namely user1, user2, and the sales group.
Room and News Channels ACL Files
The format of the roomname.acl and news channelname.acl files is slightly different from the system level ACL files. 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:
In the following news channel ACL example, the default access is Read, with Manage access given to user1, Write access given to user2, and an access of None to user3.
Changing User Privileges
To change user privileges:
Federating Deployment of Multiple Instant Messaging ServersWhen you federate multiple Sun ONE Instant Messaging deployments, you form a larger instant messaging community with multiple domains. Users in different domains can communicate with each other, use conference rooms on other domains, and subscribe to news channels on other domains based on the access privileges.
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 Instant Messaging servers in the network. The Instant Messaging server identifies itself with its domain name, host and port number, serverID, and password.
Within the server configuration, you can assign each Instant Messaging server a symbolic name, consisting of letters and digits, for example, IMserver1.
To Configure Communication 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-5.
Table 2-5 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.
For more information on the configuration parameters, see Instant Messaging Configuration Parameters.
- 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
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:
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 SSLThis section describes how to set up the Secure Sockets Layer (SSL) security protocol for use between Sun ONE Instant Messaging servers. Before following the procedures in this section, become familiar with public-key cryptography concepts. See Appendix B in the Sun ONE Console and Administration Server 5.0 Management Guide for public-key cryptography concepts.
The high-level steps to configure SSL for Instant Messaging servers are:
- Generating a self-signed certificate.
- Generating a Certificate Signing Request.
- Sending a Certificate Signing Request to a Certificate Authority (CA) and getting back a signed certificate.
- Installing the Certificate on the Sun ONE Instant Messaging server, and the CA’s certificate on other servers. This means that you also have to install the other server’s CA certificate on your system.
- Activating SSL.
To configure SSL, Instant Messaging server requires a key file that contains the public and private key installed in a directory that you specify using the iim.conf parameter, iim_server.sslkeystore. In most of the installations these files are stored in the config directory.
To verify certificates Sun ONE Instant Messenger server uses the keys stored in the nlcacerts file in its Java install directory on Solaris, Javahome/lib/security/ and on Windows, Javahome\lib\security\.
You need to create the nlcacerts file by including the CA’s certificate into the file, if the CA is not in the nlcacerts file. The nlcacerts file can be located:
On Unix - Javahome/lib/security/cacerts
On Windows - Javahome\lib\security\cacerts.
The cacerts file is created by the Java install.
When enabling SSL for use with the Instant Messaging server, choose one of the following methods:
When enabling SSL for use with the Instant Messaging server remember that your Instant Messaging server is the “client” of the other servers, and therefore you might have to import the CA’s certificate for that server.
To Generate a Self-Signed Certificate
- Run the following command on the Sun ONE Instant Messaging server from its config directory. For example, on Solaris:
Javahome/bin/keytool -genkey -alias iim -keypass value -keystore iimkeys -storepass value -validity 365
Substitute your own values for value.
- When prompted, enter the information to create a distinguished name.
This creates a keystore entry containing a private key and a self-signed certificate for the public key. The certificate is signed using the corresponding private key.
Note
If you are using the self-signed certificate for your Sun ONE Instant Messaging server, then this certificate is put in the nlcacerts file:
On Unix - Javahome/lib/security/nlcacerts
On Windows - Javahome\lib\security\nlcacerts).
If you are using self-signed certificate, skip the section To Get Your Self-Signed Certificate Signed by a Certificate Authority and Install it.
To Get Your Self-Signed Certificate Signed by a Certificate Authority and Install it
Getting the Instant Messaging certificate signed by a Certificate Authority enables the other Sun ONE Instant Messaging servers to verify the Instant Messaging certificate. This occurs because the servers’ CA keystore (on Solaris, Javahome/lib/security/cacerts; on Windows, Javahome\lib\security\cacerts) already has the certificates from Verisign and Thawte Certificate Authorities.
Follow these steps to send the certificate information to the CA and install it:
- Generate a Certificate Signing Request (CSR) to send to a Certificate Authority (CA). For example, on Solaris:
Javahome/bin/keytool -certreq -keystore iimkeys -alias iim -file iim.csr
- Submit the iim.csr file to your chosen CA.
You can email your iim.csr file, or cut and paste it in a browser window, if the CA, such as Thawte, allows it.
Note
Once you have emailed your request, you must wait for the CA to assign you with your certificate. The response time for your certificate request varies. For example, if your CA is internal to your company, it might only take a day or two to respond to your request. If your selected CA is external to your company, it could take several weeks to respond to your request.
- When the CA sends a response, be sure to save the information in a text file. For example, a file named careplyfile. You will need the data when you install the certificate.
You should also back up the certificate data in a safe location. If your system ever loses the certificate data, you can reinstall the certificate using your backup file.
Once you receive your certificate, you are ready to install it in your Sun ONE Instant Messaging server’s certificate database.
- Import the Certificate Reply from the CA.
This might require that you import the certificate of the CA that signed your certificate first as a “trusted certificate.”
Caution
Ensure that the CA’s certificate is valid prior to importing it as a “trusted” certificate. View it first (by using the keytool -printcert command or the keytool -import command without the -noprompt option), and make sure that the displayed certificate fingerprints match the expected ones. You can contact the person who sent the certificate and compare the fingerprints that you see with the ones that the certificate show or that a secure public key repository shows. Only if the fingerprints match is it guaranteed that the certificate has not been replaced in transit with someone else’s (for example, an attacker’s) certificate.
If you trust that the certificate is valid, you can add it to your keystore.
Assuming the CA’s certificate is in a file called myfavca.cert, run the following command on the Sun ONE Instant Messaging server in the config directory.
keytool -import -alias myfavca -file myfavca.cert -keystore iimkeys
Then import your new certificate on the Sun ONE Instant Messaging server to replace your self-signed certificate. Run this command on the Sun ONE Instant Messaging server in the config directory:
keytool -import -trustcacerts -keystore iimkeys -alias iim -file careplyfile
- Your server is now ready for SSL activation. See To Activate SSL For Server To Server Communication.
To Export a Public Key Certificate and Import it on other Instant Messaging Servers
The cacerts file is used by Java to verify code signing but can also be used for SSL. The following is the location of the cacerts file:
On Unix- Javahome/lib/security/cacerts
On Windows - Javahome\lib\security\cacerts
If the nlcacerts file exists then that will be used by the Sun ONE Instant Messaging server. The following is the location of the nlcacerts file:
On Unix - Javahome/lib/security/nlcacerts
On Windows - Javahome\lib\security\nlcacerts
Use this procedure if you are using a self-signed certificate or a certificate that is signed by a CA that is not in the default trusted CA keystore:
- Export the Public Key Certificate.
If you are self-signed, export your self-signed certificate. For example, run the following command on the Sun ONE Instant Messaging server, in the config directory:
keytool -export -keystore iimkeys -alias iim -file export.cert
If your certificate is signed by a CA not in the existing cacerts file on the other server, then export your signing CA’s certificate to the other server. For example, run the following command on the Instant Messaging server, in the config directory:
keytool -export -keystore iimkeys -alias myfavca -file export.cert
Then copy the export.cert file to the other server, in the Javahome/lib/security directory.
- Import the Public Key Certificate as trusted on every other Sun ONE Instant Messaging server that will talk SSL to this server. To import Public Key Certificate create the Javahome/lib/security/nlcacerts file with the command:
keytool -import -keystore nlcacerts -alias iimca -file export.cert
Enter a password when prompted.
For more information see the complete documentation for keytool at:
http://java.sun.com/j2se/1.3/docs/tooldocs/solaris/keytool.html
http://java.sun.com/j2se/1.3/docs/tooldocs/win32/keytool.html
- Your server is now ready for SSL activation. See To Activate SSL For Server To Server Communication.
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:
- 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.sslkeystore=/opt/SUNWiim/config/iimkeys
iim_server.sslkeystorepassphrase=somepassword
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
Configuring SSL between Sun ONE Instant Messenger and MultiplexorInstant 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.
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.
The following are the steps necessary to configure SSL between Sun ONE Instant Messenger and Multiplexor:
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 Enterprise Edition.
To request and install a certificate using Sun ONE Web Server Enterprise Edition:
- 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:
Installing the Certificate
When you receive the server certificate from your Certificate Authority, you need to install the certificate.
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 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. 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.
- 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-6 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-6 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-6 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 imdocroot, the base directory under which all the messenger resources are stored.
The links to these applet descriptor files can also be added to index.html file.
Managing Sun ONE Instant Messaging's LDAP ConfigurationA standalone deployment of Instant Messaging requires a directory server. In a standalone deployment, the Instant Messaging server uses the directory server to perform user authentication and to search for users.
In a portal deployment, Instant Messaging Server uses the directory used by Sun ONE Portal Server. When installed in a portal deployment environment, Instant Messaging server uses that directory used by the Portal Server to search for users, and not for user authentication. In a portal deployment, Sun ONE Portal 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:
- User entries are identified by the inetOrgPerson object class.
- Group entries are identified by the groupOfUniqueNames object class.
- The Sun ONE Instant Messenger user ID attribute of a user is provided by the uid attribute (from inetOrgPerson objectclass).
- The email address of a user is provided by the mail attribute.
- The display name of a 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).
You can change these default settings by editing the iim.conf file.
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.
These credentials consist of:
To Enable Instant Messaging server to Conduct Directory Searches as a Specific User (Not Anonymous)
- In a portal deployment, the directory is in general not accessible by anonymous users. In a portal deployment, the following values are added to the iim.conf file:
- iim_ldap.usergroupbinddn= "bind dn"
- iim_ldap.usergroupbindcred= ldap credentials/password
where:
bind dn
Specifies the value of the distinguished name (dn) the super user has to use bind to the directory from the
AMSERVER_BASEDIR/SUNWam/lib/AMConfig.properties file.
ldap credentials/password
The password will be taken from the package parameters.
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.
- Edit the iim.conf file.
For instructions on editing the iim.conf file, see To Change Configuration Parameters.
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 users based on their DN and include them in a single group. The dynamic groups are defined in Sun ONE Directory Server as the memberOfUrls objectclass.
To enable the users to view the dynamic groups in search results and add them to their contact list, you need to include the memberOfUrls objects to the group search filters in the contact list.
The following modifications need to be made to the server configuration file iim.conf:
The attribute and objectclass names are configurable. The membership attribute of a dynamic group which contains the LDAP filter or LDAP URL, can be specified using the iim_ldap.groupmemberurlattr option.
Displaying Calendar Reminders and Notifications as Instant Messenger PopupsYou 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.
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.
Figure 2-1 Instant Messenger Pop-up Architecture.
The Instant Messenger popups architecture for displaying calendar reminders and notifications as can be explained as follows:
- 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 calserver-root/cal/bin/config/.
Code Example 2-1 Alarm configuration parameters in the file ics.conf.
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.
Code Example 2-2 Custom alarm URL 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-7 shows the server configuration options in the file iim.conf and their description.
Table 2-7 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:
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-3 JMS Provider definition in the file iim.conf.
jms.providers = ens
jms.provider.ens.broker = ical.example.com:7997
jms.provider.ens.factory = com.iplanet.ens.jms.ENSConnectionFactory
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-5 JMS consumer type and the JMS provider for the Calendar Server.
jms.consumer.calendar.type = topic
jms.consumer.calendar.provider = ens
Code Example 2-6 contains the JMS consumer topic name for the Calendar Server in the file iim.conf file.
Code Example 2-6 JMS consumer topic name for the Calendar Server
jms.consumer.calendar.topic = enp:///ics/customalarm
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:
The following parameters are supported by the Calendar Server message listener:
Table 2-8 contains the values for the parameter eventtype and their description.
Table 2-8 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:
caldb.serveralarms = "yes"
caldb.serveralarms.contenttype = "text/xml"
caldb.serveralarms.dispatch = "yes"
caldb.serveralarms.dispatchtype = "ens"
caldb.serveralarms.url = "enp:///ics/customalarm"
If the configuration changes are made, restart the calendar server with the following commands:
stop-cal
start-cal
Configuring Instant Messaging Server
The following options needs to be configured in the file iim.conf:
! 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:
/opt/SUNWiim/sbin/imadmin refresh
Enabling Calendar Alerts in Instant Messenger
To enable the Calendar alert in Sun ONE Instant Messenger:
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.
Taking a Back Up of Instant Messaging DataInstant 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:
The configuration information is stored in the following directories:
- Solaris: /etc/opt/SUNWiim/default/config
- Linux: /etc/opt/soim/default/config
- Windows: im_install_dir\config
- (Optional) If you customized any of the files mentioned in Customizing Instant Messenger, back them up from the $imdocroot.
The Instant Messaging user data is stored in the following directories:
Performing Backup
While the configuration information does not change frequently, the Instant Messaging user data changes rapidly and to prevent any loss of user data it is recommended that the Instant Messaging 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 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 user data and the configuration information needs to be restored when there is a disk failure and all the user data and the configuration information is lost.
To restore the backed up user data:
- Change to the runtime directory. For example:
cd $runtimedir
- Grant read-only permission to the db directory, type:
chmod -R 400 db
- Stop the Instant Messaging server, type:
imadmin stop
- Grant Write permission on the user data files for the server user, type:
chmod -R 600 $runtimedir/db/.
- To restore the data, copy the backed up data to the db directory.
- Start the Instant Messaging server, type:
imadmin start
