Sun Java System Instant Messaging 7.2 Administration Guide

Chapter 9 Administering Instant Messaging Components

This chapter explains how to administer the Instant Messaging components (server, multiplexor, Calendar agent, cluster agent, and watchdog) and perform other administrative tasks, such as changing configuration parameters and creating backups.

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

Stopping, Starting, Refreshing, and Checking Instant Messaging Components

The imadmin command enables you to:

Start and stop all Instant Messaging components (server, multiplexor, Calendar agent, cluster agent, and watchdog).
Start and stop an individual Instant Messaging component.
Refresh all Instant Messaging component configurations.
Refresh an individual Instant Messaging component.
Check the status of Instant Messaging components.

The imadmin command-line utility can be executed only by root or a user who has administration rights to the system(s) on which the 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.
In a deployment with Sun Java^TM System Access Manager, if the Sun Java System Portal Server and the Instant Messaging server are installed on the same host, the user is the one who is running the Access Manager, as root.

The imadmin command-line utility is located in the following directory:

im-svr-base/sbin

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

Starting Instant Messaging Components

You can start all the components together or a single component separately.

Use the imadmin command with the start option to start the Instant Messaging Server, multiplexor, Calendar agent, cluster agent, and watchdog depending on which components are enabled.

To Start All Components

At the command line, type the following:
imadmin start
If both server and multiplexor are enabled, this command first starts the Instant Messaging server, and then starts the multiplexor.

If the watchdog is enabled (default), this command starts the watchdog, then the watchdog reads the configuration file and starts the Instant Messaging Server and/or multiplexor as necessary.

To Start a Single Component

At the command line, type the imadmin start command with an argument that designates the component as follows:

Server:
imadmin start server
Multiplexor:
imadmin start multiplexor
Calendar agent:
imadmin start agent-calendar
Watchdog:
imadmin start watchdog

Stopping Instant Messaging Components

You can stop all the components together or a single component separately.

Use the imadmin command with the stop option to stop the Instant Messaging Server, multiplexor, Calendar agent, cluster agent, and watchdog depending on which components are enabled.

To Stop All Components

At the command line, type the following:
imadmin stop
If the watchdog is running, imadmin brings the watchdog down first, and then stops the server and/or the multiplexor.

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

To Stop a Single Component

At the command line, type the imadmin stop command with an argument that designates the component as follows:

Server:
imadmin stop server
Multiplexor:
imadmin stop multiplexor
Calendar agent:
imadmin stop agent-calendar
Watchdog:
imadmin stop watchdog

Refreshing Component Configuration

Use the imadmin command with the refresh option to stop and restart an individual Instant Messaging component and refresh that component’s configuration.

You can refresh all the components together or a single component separately.

Whenever you change a configuration parameter in the iim.conf file, you also need to refresh the configuration.

To Refresh All Components

At the command line, type the following:
imadmin refresh
This command stops the server, multiplexor, Calendar agent, cluster agent, and watchdog, terminates all end user connections, and disconnects any inbound and outbound servers configured.

If the watchdog is running, imadmin brings the watchdog down first, and then stops the server and/or the multiplexor. Then starts the watchdog which reads the configuration file and starts the Instant Messaging server and/or multiplexor as necessary.

To Refresh a Single Component

At the command line, type the imadmin refresh command with an argument that designates the component as follows:

Server:
imadmin refresh server
Multiplexor:
imadmin refresh multiplexor
Calendar agent:
imadmin refresh agent-calendar
Cluster agent:
imadmin refresh monitor
Watchdog:
imadmin refresh watchdog

Checking the Status of Instant Messaging Components

You can check the status of all the components together or a single component separately using the imadmin command with the status option. This command returns results in the following format:

Component  [status]

For example:

Server          [UP]
Multiplexor     [UP]
Agent:calendar  [DOWN]
Watchdog        [UP]

To Check the Status of All Components

At the command line, type the following:
imadmin status
This command returns the status of all enabled components.

To Check the Status of a Single Component

At the command line, type the imadmin status command with an argument that designates the component as follows:

Server:
imadmin status server
Multiplexor:
imadmin status multiplexor
Calendar agent:
imadmin status agent-calendar
Watchdog:
imadmin status watchdog

Changing Instant Messaging Server and Multiplexor Configuration Parameters

Instant Messaging stores configuration parameters in the iim.conf file. For a complete list of configuration parameters, see Appendix A, Instant Messaging Configuration Parameters in iim.conf.

To change configuration parameters, manually edit the configuration parameters and values in the iim.conf file, then refresh the Instant Messaging server configuration. If you change a multiplexor parameter, you only need to refresh the multiplexor as follows:

imadmin refresh multiplexor

For a complete list of parameters and their values, see Appendix A, Instant Messaging Configuration Parameters in iim.conf.

To Change Configuration Parameters

Change to the im-cfg-base directory.

See Instant Messaging Server Directory Structure for instructions on locating im-cfg-base.

Edit iim.conf using a text editor.

Save your changes.

Refresh the configuration using imadmin.

For example:
imadmin refresh
Note –
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 Instant Messenger from connecting to the server. For more information, see Chapter 15, Managing Instant Messenger.

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. This section describes backing up Instant Messaging in the following sections:

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 configuration directory (im-cfg-base). Default paths are described in Instant Messaging Server Directory Structure.

The Instant Messaging data is stored in the database directory (im-db-base). Defaults for im-db-base are also described in Instant Messaging Server Directory Structure.

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 a 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 you should back up the Instant Messaging end-user data on a periodic basis. You need to perform the backup 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 Backup 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.

To Restore End-user Data from Backup

Change to the im-runtime-base directory.

See Instant Messaging Server Directory Structure for information on locating im-runtime-base.

Stop the Instant Messaging server:
imadmin stop

Copy the backed up data to the im-db-base directory.

Be sure to maintain the directory structure of the backed up data.

Verify the permissions and owner of the newly restored data.

The files should be owned by the Instant Messaging system user. See Creating a UNIX System User and Group for information on this user. Permissions should be set as follows:
- Files: 600 (indicating read and write permissions for owner only)
- Directories: 700 (indicating read, write, and execute permissions for owner only)
Refer to your operating system documentation for information on changing permissions and owners.

Start the Instant Messaging server.

imadmin start