Appendix B   Upgrading iPlanet Instant Messaging Server


Use this document to upgrade your iPlanet Instant Messaging Server standalone installation, for example, from 3.0 Beta Refresh to 3.0.

This appendix contains:

• Overview of Upgrading

• Protecting Your Files

• Upgrading from iPlanet Instant Messaging Server Beta Refresh to Release 3.0

• Post-Upgrade

  
  

  ---

  Note	The only way to preserve an existing installation is to use these upgrade procedures. Upgrading saves all database and configuration information.

  ---

  
  

Overview of Upgrading

---

To upgrade from iPlanet Instant Messaging Server, for example, from 3.0 Beta Refresh to 3.0, you run the setup program. When the setup program detects a previous version of iIM Server it gives you the option to upgrade or reinstall the product. See "Upgrading from iPlanet Instant Messaging Server Beta Refresh to Release 3.0" for the actual procedure to upgrade.

Upgrade vs. Reinstall Considerations

This section describes the difference between upgrading and reinstalling. In general, if you want to start over and reconfigure your installation, then use the reinstall option. If you do not need to change your configuration or where it is installed, but just need the updated version, then use the upgrade option. Table B-1 summarizes the difference between upgrading and reinstalling.

Table B-1    Upgrade vs. Reinstall Considerations

Type of Installation	Enables Changing Configuration Options?	Enables You to Add a Component to This Server?	Preserves Existing Database and Configuration?	Should You Back Up Existing iIM Server Files?
Upgrade	No.	No	Yes.	Not necessary, but should be done as a precaution.
Reinstall	Yes. You can change all installation options.	Yes	No.	Depends: Back up any customizations, configurations, or databases you want to keep.

The iPlanet Instant Messaging Server upgrade option does not enable you to change any options or configuration information. If, for instance, you want to change the directories your files are located in, or the ports your servers listen on, you should choose the reinstall option, rather than upgrade.

Only the component(s) you already have installed will be upgraded. If you want to add a component to this server, you must either use the reinstall option, or uninstall the existing component and then do a fresh installation of all components.

The upgrade option preserves your databases and configuration information, whereas the reinstall option does not. The reinstall option removes the previous installation completely before installing a fresh copy of the new version. If there are any related files you want to retain and you are performing a reinstall, you must back them up before starting the installation process and then restore them afterwards.

For instructions on reinstalling on Solaris, see Chapter 2 "Installing iPlanet Instant Messaging Server on Solaris", or for Windows NT, see Chapter 3 "Installing iPlanet Instant Messaging Server on Windows NT."

.new Files

When you upgrade iPlanet Instant Messaging Server, for example, from 3.0 Beta Refresh to 3.0, all customizable files are left in place by the installation process. If there are any changes to customizable files in the new version, a .new file will be created for each of the files that changed.

As part of the post-upgrade process, you must merge the changes into your old files. This step is necessary for the new features to take effect. When merging the changes, compare the old files with the .new files, line by line, and edit your existing files to incorporate these changes.

For example, if there were a change to the iim.conf file for the upgrade, you would see an iim.conf.new file in the config directory after the upgrade process had finished. To complete the upgrade, you merge the changes in the .new file into your existing iim.conf file, taking care to preserve your customizations.

Protecting Your Files

---

The upgrade option preserves your databases and configuration information, such as user profile data and preferences. However, to protect yourself from anything going wrong during the installation process, make sure you back up the files listed in Table B-2 before starting the upgrade.

Table B-2    iIM Server Files to Back Up Before Upgrading  

Type of File	Solaris Default Location	Windows NT Default Location
Database	/var/opt/SUNWiim/default/db	c:\Program Files\iPlanet\ InstantMessaging\db
User profiles and preferences	/var/opt/SUNWiim/default/db	c:\Program Files\iPlanet\ InstantMessaging\db
Configuration	/etc/opt/SUNWiim/default/config	c:\Program Files\iPlanet\ InstantMessaging\config
ACLs	/etc/opt/SUNWiim/default/config/acls	c:\Program Files\iPlanet\ InstantMessaging\config\acls
Customizable client files, such as index.html, iim.jnlp, iimres.jnlp, and iimres.jar.	/opt/SUNWiim/html	c:\Program Files\iPlanet\ InstantMessaging\html
Any other files you have customized for your site	Depends on your site.	Depends on your site.

Upgrading from iPlanet Instant Messaging Server Beta Refresh to Release 3.0

---

The upgrade procedure in this section can be used for both Windows NT and Solaris operating systems. Where applicable, operating system differences are called out.

The high-level steps are:

1. Obtaining the iPlanet Instant Messaging Server 3.0 package/software.

2. Planning the installation for a time when shutting down the iIM server will be least disruptive to your users.

3. Informing your users ahead of time of the planned shutdown.

4. Shutting down the iIM server and multiplexor.

5. Performing the upgrade with the setup command.

6. Performing the post-upgrade.

To Upgrade iPlanet Instant Messaging Server

Before beginning, download the iPlanet Portal Server: Instant Collaboration Pack software from the following site:

http://www.iplanet.com/downloads/download/

1. Shut down the iPlanet Instant Messaging Server.

   This includes both the server and multiplexor.

       iimadmin stop

2. Start the installer.

   For Solaris:

   • Log in as root. You must have superuser privileges (that is, be logged in as root) to run the installation program.

   • Create a directory (such as /tmp/imsvr) on the server that will host iPlanet Instant Messaging Server and download (or copy) the iIM server installation file to that directory. Make sure that the download directory has adequate disk space to store the extracted files.

   • Change to the directory where you downloaded or copied the file and extract the contents. For example:

     cd /tmp/imsvr

     gunzip -c filename.tar.gz | /usr/bin/tar xvf -

     where filename identifies the name of the file you downloaded or copied.

     
     

     ---

     Note	You must use /usr/bin/tar. This program should be the tar utility that is distributed with your operating system and not a third party tar utility, such as gnu.

     ---

     
     

   • In the installation directory in which you untarred the iIM server archive file, type:

     For graphical user interface: ./setup

     For command-line interface:

     1. Type ./setup -nodisplay

        The installation program runs in the current window.

     2. Text displays explaining how the command-line installation works. Press Enter to continue.

   For Windows NT:

   • Log in as Administrator. You must have superuser privileges (that is, be logged in with full administration rights to the system) to run the installation program.

   • Create a directory (such as c:\tmp\impsvr) on the machine that will host the iIM server and download (or copy) the iIM server self-extracting archive file to that directory. Make sure that the download directory has adequate disk space to store the extracted files.

     
     

     ---

     Caution

     Do not download the archive file to the same directory you will be installing into (base directory).

     ---

     
     

   • Change to the directory where you downloaded or copied the file and extract the contents.

   • Launch the installer.

     For the graphical user interface installation, double-click the setup.exe file. A message window opens and asks if you want to install iPlanet Instant Messaging. Click Yes to continue.

     For the command-line installation:

     1. Open a command prompt and change to the directory in which you
        placed the iIM server archive file. For example:

        cd tmp\impsvr

     2. Start the installer by typing the setup file name followed by the
        argument -nodisplay. For example:

        setup.exe -nodisplay

     3. A couple of informational screens display, after reading the information, press Enter to continue.

        
        

        ---

        Note	To exit the command-line installation, press CTRL-C.

        ---

        
        

From this point on, only the graphical user interface instructions will be given. The steps are identical. For the command-line install, instead of clicking on buttons, you will select an option and press Enter.

3. The Welcome window opens. Click Next to continue.

4. The Software License Agreement window opens.

   Read the license agreement and click Yes (Accept License) to accept it and continue. (If you click No, the installation program will end without installing iIM Server.)

5. The System Requirements window opens, listing other product dependencies.

   Before continuing with this installation, you should already have installed:

   • iPlanet Portal Server, for portal deployments (Solaris only).

   • A web server, such as iPlanet Web Server, to serve up HTML to the client. (Portal deployments use the web server that ships with iPlanet Instant Messaging Server.)

   • A directory (LDAP) server, such as iPlanet Directory Server, for user authentication. (Ignore this requirement if you are using iPlanet Portal Server's internal directory.)

   • A messaging server, such as iPlanet Messaging Server, to send alerts by email when users are unable to receive instant messages.

   Optionally, you may want to install:

   • A provisioning tool, such as iPlanet Delegated Administrator.

   If you have these products installed, click Next to continue installation. Otherwise, Click Exit to quit the installation and install and configure the necessary products. Then restart the installation.

6. Two informational windows open saying the program is determining and verifying the system's host name and DNS domain name. On faster systems, you might not see these windows.

   The installation program is automatically detecting the host name and DNS domain name of the system on which you are installing the server. If the installation program cannot detect the host name or DNS domain name, the "Unable to make network connection" window opens. Be sure that the host name and DNS domain name specified are correct, then click Next to continue the installation. The installation program will then try to establish a network connection using these values.

   
   

   ---

   Note	The Host Name or Domain Name fields will be blank if the installation program is unable to detect these values. In this case, you must enter a valid host name or DNS domain name, or both.

   ---

   
   

7. The Upgrade or Remove and Reinstall Existing Installation window opens.

   Whether you decide to upgrade or remove and reinstall, all running iIM services must be stopped. The installation program attempts to stop them for you. If it is unable to verify that all services are stopped, it opens a warning window. The warning window advises you that the installation may not be successful if any services are still running. If you are sure that all services have been stopped, click Continue; otherwise, click Cancel to return to the installation program. Stop all services before proceeding with the installation.

   To upgrade your existing system to the new version and retain existing databases and configuration information, click Next.

   
   

   ---

   Caution

   Even though the upgrade does not disturb your databases or customized files, in case of something going wrong with the upgrade, back up all databases, user profiles and preferences, and any files you may have customized. For a list of files to back up, refer to Table B-2.

   ---

   
   

   A reminder window opens advising you to back up existing databases and configuration information. If you have already done this, click Continue.

   If you want to change your mind about which option to pick, or to exit this installation so you can back up your files, click Cancel.

   After your upgrade is complete, be sure to follow the post-upgrade instructions in the section "Post-Upgrade".

8. The Instant Messaging Services Startup window opens.

   Unlike the regular install process where two options appear, on this panel there is only one option, you can choose to start iPlanet Instant Messaging Services after successful installation or not. After making your choice, click Next to continue.

9. A message window opens saying the installer is verifying if there is adequate disk space. You might not see this window on faster systems.

10. The Ready to Install window opens.

    Note that the size shown for the installation does not include the Java Runtime Environment, which is an additional 51 MB.

    To complete the installation, click Install Now.

11. The Installing window opens and displays installation progress.

12. When the installation procedure has completed, an installation Summary window opens. Click Details if you want to review summary information about the installation. When you are finished, Click Dismiss to close the summary information window, then click Exit to exit the installation program

Post-Upgrade

---

As part of upgrading your iIM Server installation, the installer creates .new files in your config and html directories. These files contain all the changes made to their various corresponding files for this new version. For example, if you found an iim.conf.new file, it would contain all the changes for the iim.conf file for the new version. It will be necessary for you to merge these files into the corresponding old files. This was done to prevent the installation from destroying your customizations to these files.

After upgrading, find the .new files, and merge the changes into your existing corresponding files, taking care to preserve your customizations. This step is necessary for the new version features to take effect.

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

The files that can be updated, and for which there could be a .new file, are listed in Table B-3:

Table B-3    .new Files for Solaris and Windows NT  

Type of Files	Solaris	Windows NT
Config	$BASEDIR/config/iim.conf $BASEDIR/config/acls/ sysAdmin.acl $BASEDIR/config/acls/ sysTopicsAdd.acl $BASEDIR/config/acls/ sysRoomsAdd.acl $BASEDIR/config/acls/ sysSendAlerts.acl $BASEDIR/config/acls/ sysWatch.acl $BASEDIR/config/acls/ sysSaveUserSettings.acl	$BASEDIR\config\iim.conf $BASEDIR\config\acls\sysAdmin.acl $BASEDIR\config\acls\sysTopicsAdd.acl $BASEDIR\config\acls\sysRoomsAdd.acl $BASEDIR\config\acls\sysSendAlerts.acl $BASEDIR\config\acls\sysWatch.acl $BASEDIR\config\acls\sysSaveUserSettings.acl
HTML	$HTMLDIR/iim.html $HTMLDIR/iim.jnlp $HTMLDIR/index.html $HTMLDIR/iimres.jnlp $HTMLDIR/iimres.jar	$HTMLDIR\iim.html $HTMLDIR\iim.jnlp $HTMLDIR\index.html $HTMLDIR\iimres.jnlp $HTMLDIR\iimres.jar
For Solaris: If you use the default directory, $BASEDIR = /etc/opt/SUNWiim/default/, and $HTMLDIR = /opt/SUNWiim/html. For Windows NT: If you use the default directory, $BASEDIR = c:\Program Files\iPlanet\InstantMessaging, and $HTMLDIR = c:\Program Files\iPlanet\InstantMessaging\html.