Ensim® Pro and Ensim Basic 4.0.3 for Linux® (Standalone) Upgrade Guide

Ensim Corporation

Ensim^® Pro and Ensim Basic 4.0.3 for Linux^®(Standalone) Upgrade Guide

February 24, 2005

Introduction

This guide provides instructions for upgrading to Ensim® Pro and Ensim Basic 4.0.3 for Linux® (Standalone) running on the Red Hat® Enterprise Linux® Release 3 or the Fedora™ Core 1 operating systems.

For simplicity, we refer to Ensim Pro and Ensim Basic 4.0.3 for Linux (Standalone) as “Ensim Control Panel,” Fedora Core 1 as “Fedora 1,” and Red Hat Enterprise Linux ES Release 3 as “RHEL 3” throughout the document.

You can upgrade from:

Ensim Control Panel 4.0.1 (RHEL 3) to Ensim Control Panel 4.0.3 (RHEL 3)

Ensim Control Panel 4.0.1 (Fedora 1) to Ensim Control Panel 4.0.3 (Fedora 1)

Ensim Control Panel 4.0.2 (RHEL 3) to Ensim Control Panel 4.0.3 (RHEL 3)

Ensim Control Panel 4.0.2 (Fedora 1) to Ensim Control Panel 4.0.3 (Fedora 1)

Topics in this guide include:

About the upgrade

Before you upgrade

Upgrading to the latest version of Ensim Control Panel

Reviewing the status of Ensim Ignite services after the upgrade

Post-upgrade tasks

Appendix A: Overview of the Ensim Control Panel System Checker

Appendix B: Reviewing customizations

Appendix C: Troubleshooting upgrade issues

Feedback and support

Legal and copyright notice

About the upgrade

Upgrading to the latest version of Ensim Control Panel simply requires you to run the Installer script on the target server.

Sites hosted on Ensim Control Panel will be accessible during the upgrade and services such as Web, FTP, and Email will continue to function, except when the site is being upgraded. However, the control panels will be inaccessible during the length of the upgrade. This could typically range from a few minutes to a few hours depending on the number of sites hosted on the server.

Estimated upgrade time

The time required to upgrade may vary depending on your server hardware (CPU and memory resources available), the speed of your network connection, and the number of sites hosted on Ensim Control Panel server.

The time required to upgrade the core Ensim Control Panel server is approximately 10 minutes and the time required to upgrade the sites hosted on Ensim Control Panel is approximately 1 minute per site. So, assuming there are 20 sites hosted on the Ensim Control Panel server, it will take approximately 30 minutes to complete the upgrade (10 minutes for the server and 20 minutes for 20 sites).

Before you upgrade

The following section describes the minimum system requirements and provides a checklist to help you prepare for the upgrade.

System requirements

To upgrade to the latest version of Ensim Control Panel, your system needs to meet the following requirements.

Table 1. System requirements for upgrading to Ensim Control Panel

System requirements

Disk space

At least 20 GB

Connectivity

Network connectivity with access to Internet

Ensim Control Panel CD-ROM (if you want the Installer to obtain the installation files from the CD-ROM)

One Ensim Control Panel CD-ROM

Web server requirements: Before the upgrade, configure Apache 2.0 as the Production Web server, then restart the Production and Test Web servers. Ensim Control Panel no longer supports Apache 1.3. For instructions on configuring your Web server, refer to the Appliance Administrator’s Help.

Important: You must restart both the Web servers after setting Apache 2.0 as the Production Web server, otherwise the upgrade will fail.

Other requirements

DNS server on network

“root” user access

Upgrade checklist

Use the following checklist to verify that you have adequately prepared your system for a successful upgrade.

Table 2. Upgrade checklist

Task

Status

Have you reviewed the current license information?

¨

Have you configured Apache 2.0 as your Production Web server and subsequently restarted the Production and Test Web servers?

Ensim Control Panel no longer supports Apache 1.3. Before you upgrade, you must configure Apache 2.0 as your Production Web server, then restart the Web servers, otherwise the upgrade will fail.

¨

Have you backed up the hard disk?

Note: Before upgrading, please back up the entire hard disk to prevent loss of data if the upgrade fails.

¨

Are all sites in a consistent state?

To verify the status of the sites:

Log on to the Appliance Administrator control panel.

On the left navigation bar, click Site Manager.

At the bottom of the page, click the Display arrow and select All Sites.

Sites that are inconsistent display the following message:

This site is currently in an inconsistent state. This may be the result of an active or failed edit.

For resolving related issues, please search Ensim’s knowledge base articles. You can find the knowledge base articles on the Web at
http://onlinesupport.ensim.com/kb_search.asp?product=lwp.

¨

Is Microsoft® FrontPage® consistent on all your sites?

A successful upgrade requires Microsoft FrontPage to be consistent on all your sites.

To verify that Microsoft FrontPage is consistent on all your sites, log on to the server as the root user and run the following command at the prompt:

#/usr/local/frontpage/currentversion/bin/owsadm.exe -o check -p all

If Microsoft Frontpage is consistent, the message Check Completed is displayed, otherwise errors related to the observed inconsistency is displayed.

See Sites that use Microsoft Frontpage Server Extensions in an inconsistent state for information on restoring a site to its consistent state.

¨

Have you replaced the period (.) character in a MySQL database name with a valid character?

MySQL database names that include a period (.) must be replaced with a valid character before an upgrade. Note that usage of the characters—forward slash (/), period (.), and equal to (=)—is invalid. For instructions on renaming the database, please refer to the Site Administrator online Help (accessible through the Help option on the Site Administrator control panel.)

¨

Have you reviewed your customizations and completed the necessary pre-upgrade steps?

Refer to the section, Appendix A: Overview of the Ensim Control Panel System Checker to review your customizations for compatibility. Also review the section Customizations that require pre-upgrade or post-upgrade actions for more information on additional pre-upgrade tasks you may need to perform.

¨

If you have configured the Installer to obtain the Ensim Control Panel files from a local FTP server or the Ensim Control Panel CD-ROM, verify that the Installer has access to these repositories.

Local FTP server: The Installer obtains the installation files from the specified FTP server. You need to specify the server name or the IP address. The local FTP server must mirror the directory structure for Ensim Control Panel installation on Ensim’s FTP server. For instructions, please refer to the document Setting up a local FTP server to install Ensim Pro and Ensim Basic 4.0.3 for Linux (Standalone) at http://www.ensim.com/support/pro/linux/index.html.

Ensim Control Panel CD-ROM: Ensure that the Installer has access to the CD-ROM for obtaining the Ensim Control Panel files.

¨

Upgrading to the latest version of Ensim Control Panel

The following section provides instructions for upgrading to the latest version of Ensim Control Panel. The Installer upgrades Ensim Control Panel in the text mode; curses-based upgrade is no longer supported.

Before you upgrade:
* Ensure that your system meets the requirements specified in the section Before you upgrade.
* Configure Apache 2.0 as the Production Web server, then restart the Production and Test Web servers, otherwise the Installer will fail with an error. Ensim Control Panel no longer supports Apache 1.3. For instructions on configuring your Web server, refer to the Appliance Administrator’s Help.

If you use the apt tool for updating Linux packages, please uninstall the apt RPMs— apt, atrpms, atrpms-package-config, libapt-pkg—before you upgrade, otherwise the upgrade may fail. Beginning with this release, the Installer uses the yum tool for providing the requisite package management environment. The presence of apt RPMs can cause RPM conflicts during the upgrade. If you want to use apt to obtain updates, you must install the tool after upgrading Ensim Control Panel.

To upgrade to the latest version of Ensim Control Panel:

Log on to the server on which you want to upgrade Ensim Control Panel.

Obtain access to the Installer script ensim-installer.sh from one of the following repositories.

Option 1: Ensim Control Panel CD-ROM

You must purchase the Ensim Control Panel CD-ROM from the storefront
https://buy.ensim.com.

Mount the CD-ROM to access the Installer script.

Insert the Ensim Control Panel CD-ROM into the CD-ROM drive of the server.

To access the contents of the CD-ROM, mount the CD-ROM by typing the following command.

#mount /mnt/cdrom

You do not have to mount the CD-ROM if you have enabled AutoMount on your server.

Browse to the Installer script ensim-installer.sh (located at /mnt/cdrom).

Option 2: FTP server

Download the Installer script ensim-installer.sh from the Ensim support Web site
http://www.ensim.com/support/downloads.html.

Run the script by typing the following command at the prompt. Use the --help option with the script to learn more about the various command line options you can use with the script.

The upgrade events are temporarily logged in the file /tmp/install.log.<pid_no> where <pid_no> is the process ID of the upgrade process. The contents of the temporary log file are later appended to the file /var/log/ensim/installer.log, which can be viewed after the completion of the upgrade process. To examine the log messages during the upgrade, you must refer to the temporary log file /tmp/install.log.<pid_no>. The name of the log file can be obtained from the message Logging to file /tmp/install.log.<pidno> displayed at the start of the upgrade. Please note the file name in the message for future reference.

#sh ensim-installer.sh --email=<email_address>

where --email is the email address to which success or error messages are sent

You must use the --email option with the script to receive email messages on the status of the upgrade.

Example

In the following example, the command upgrades Ensim Control Panel to the latest version by obtaining the necessary files from Ensim’s FTP server.

#sh ensim-installer.sh --email=admin@example.com --cdrom=n

Optional: If you chose the Ensim Control Panel CD-ROM option, you will be prompted to insert the CD-ROM.

The Installer starts upgrading the existing version of Ensim Control Panel.

The Installer first performs a system check to ensure that your system provides a compatible system environment for the upgrade. At the end of the check, it displays the number of errors or warnings encountered. The results of the check (list of checks, status of each check, and details about errors or warnings) are logged in the file /var/log/ensim/installer.log and can be viewed after the completion of the upgrade process. If you want to view the details during the upgrade, please refer to the temporary log file created. See Appendix A: Overview of the Ensim Control Panel System Checker for details on the System Checker and its results.

After the system check completes successfully, the Installer installs or upgrades the services and add-ons provided by Ensim Control Panel.

You may refer to the setup.log file located at /var/log/appliance/ for details on the upgrade process. If you encounter problems during the upgrade, please use the information in Appendix C: Troubleshooting upgrade issues to resolve the issues.

Do not disconnect if the upgrade has been initiated over a remote connection, using Telnet or SSH. However, if you are disconnected due to technical reasons, reconnect to your server and locate the message WEBppliance is upgraded to 4.0.3 in the file /var/log/appliance/history. The message indicates that the Ensim Control Panel upgrade has successfully completed.
If you are unable to locate the message, run the command, ps -ax.
If there are RPM processes active, the command will list the RPMs (running RPM processes indicate that the upgrade is in progress). Do not interrupt the upgrade.

After the upgrade completes successfully, restart the server manually using the command: #/etc/rc.d/init.d/webppliance restart

Reviewing the status of Ensim Ignite services after the upgrade

You may want to review the status of the Ensim Ignite services after you upgrade before you customize the provisioning of these services in accordance with your business needs.

This section describes the status of the services on each of the control panels after the upgrade.

On the Appliance Administrator and Reseller Administrator control panels:

Existing Service Plans or sites that had the Ensim Ignite service enabled or disabled before the upgrade will retain their existing configuration after the upgrade.

If the Ensim Ignite service was hidden before the upgrade, the service is not visible on any of the control panels.

The Ensim Ignite service is not selected in the default Service Plan or in the Add Site forms.

On the Site Administrator control panel:

If the Ensim Ignite service was disabled or hidden, the services will not be visible on the control panel.

If the Ensim Ignite service was enabled, the services retain their existing status and configuration after the upgrade.

Post-upgrade tasks

This section explains the tasks that you need to perform after you upgrade to the latest version of Ensim Control Panel.

Upgrading the SquirrelMail file config.php

After the upgrade, some sites are unable to access SquirrelMail. To resolve this, you will need to upgrade the SquirrelMail file config.php.

To upgrade the SquirrelMail file config.php:

Log on to the Ensim Control Panel server as the root user.

Back up the original configuration file /home/virtual/<domain>/var/www/squirrelmail/config/config.php using the following command:

#cp /home/virtual/<domain>/var/www/squirrelmail/config/config.php <directory>/config.php.bak where <directory> is the directory in which you want to copy the file.

Copy the file /etc/virtualhosting/templates/sqmail/var/www/squirrelmail/config/config.php to the broken site’s directory (/home/virtual/<domain>/var/www/squirrelmail/config/config.php).

After copying the file, change the file owner and group to match that of the original file.

If the original config.php file has been modified by Site Administrators, then they should merge the old and the new config.php files.

Regenerating the Sendmail configuration file after an upgrade

Ensim Control Panel does not regenerate the Sendmail configuration file after an upgrade in order to retain any customizations made to the file. However, you may need to regenerate the file after an upgrade to take advantage of new service features or security fixes.

To regenerate the file after an upgrade:

Log on to the Ensim Control Panel server as the root user.

Back up your existing Sendmail configuration file using the following command.

#cp /etc/mail/sendmail.cf <directory>/sendmail.cf.bak
where <directory> is the directory in which you want to copy the file.

Regenerate the Sendmail configuration file by typing the following command at the prompt.

#/usr/bin/m4 /usr/lib/opcenter/sendmail/install/sendmail.mc > /etc/mail/sendmail.cf

Restart the Sendmail service.

#/etc/rc.d/init.d/sendmail restart

Migrating MySQL databases to the site’s file system

After upgrade, the MySQL databases continue to remain under the ownership of the Appliance Administrator leading to the following functional snags.

Disk space consumed by the databases does not count toward consumption of the site’s disk quota.

Existing databases are not listed when you attempt to view the list of databases from the Site Administrator control panel.

To resolve these, you need to migrate the MySQL databases of a site from the file system of the appliance to the file system of the site. You will need to stop the MySQL service and run the following command, as the root user.

ensim-python /usr/lib/opcenter/mysql/mysqlmig.pyc <-f | -m | -h | -u > < -a | <Database name> <domain name>>

where:

-f: Adds an entry for the database to the list of databases owned by <domain name>

Existing databases cannot be viewed from the Site Administrator control panel after an upgrade. To resolve this, the -f option must be used.

-m: Moves the database to the <domain name>

The -m option moves the database into the site’s file system. You will be required to stop the database and restart it. This action is recommended during a period of low activity.

-u: Adds entry from localhost and localhost.localdomain for users

For 3.1 Compatibility or High Security sites, your database users will be unable to connect to their databases as the localhost and localhost.localdomain entries are not present in the mysql database. This can be resolved by using the -u option after you have moved your databases to the site’s file system.

-a: Indicates that the action (depending on the other parameters selected, -f, -m) be performed on all the sites

-h: Display this help.

<Database name>: Name of the database to be migrated

<domain name>: Name of the domain to which the database is migrated

To synchronize a single database, specify the <Database name>. If this argument is not given then default value will be used. The default value is formed by replacing every "." in the domain’s name with “_”. For example, for the domain name “ensim.com” the default database will be “ensim_com”. Do not use the -a parameter if your are synchronizing a single database.

Examples of the mysqlmig command

ensim-python /usr/lib/opcenter/mysql/mysqlmig.pyc -f example_com example.com

Lists the example_com database for the example.com site in the Site Administrator control panel

ensim-python /usr/lib/opcenter/mysql/mysqlmig.pyc -f -a

List all the database for all the sites in the Site Administrator control panel

ensim-python /usr/lib/opcenter/mysql/mysqlmig.pyc -m -a mysqlmig.py -m example_com example.com

Moves the example_com database to the example.com site’s file system

ensim-python /usr/lib/opcenter/mysql/mysqlmig.pyc -m -a

Moves all the database to the respective site’s file system

ensim-python /usr/lib/opcenter/mysql/mysqlmig.pyc -u example.com

Adds the localhost and localhost.localdomain entry for the site into the mysql database

Upgrading the ProFTPD service (optional)

Earlier versions of Ensim Control Panel automatically upgraded the ProFTPD service during the upgrade. However, the naming convention used by the service in its latest release, version 1.2.10, constrains Ensim Control Panel from automatically upgrading the service. If you want to upgrade to the latest version of the service, you must manually upgrade the service as described in the procedure.

The ProFTPD RPM proftpd-1.2.10 has been tested successfully on Ensim Control Panel 4.0.3 by Quality Assurance.

To manually upgrade the ProFTPD service:

Log on to the Ensim Control Panel server as the root user.

Download the ProFTPD RPM proftpd-1.2.10-1.fc1.i386.rpm from the Web site ftp://ftp.proftpd.org/distrib/packages/RPMS/.

Run the following command to upgrade the existing RPM.

rpm -Uvh proftpd-1.2.10-1.fc1.i386.rpm --oldpackage

Restart the service.

service proftpd restart

Appendix A: Overview of the Ensim Control Panel System Checker

The Ensim Control Panel System Checker is a tool that evaluates the compatibility of customizations (on an existing Ensim Control Panel server) with the latest version of Ensim Control Panel. It reports potential conflicts and ways to resolve them.

The Installer automatically runs the System Checker before upgrading an existing version of Ensim Control Panel. At the end of the check, it displays the number of errors or warnings encountered. The results of the system check (list of checks, status of each check, and details about errors or warnings) are logged in the file /var/log/ensim/installer.log and can be viewed after the completion of the upgrade process. If you want to view the log details after the system check, please refer to the temporary log file.

Interpreting the results of the check

As the System Checker performs each check, it displays the name and brief description of the check and the outcome of the check.

The outcome can be any of the following:

OK. Displayed when the check is successful

WARNING. Displayed when the check encounters an exception that may interfere with the upgrade process

ERROR. Displayed when the check encounters an exception that will interfere with the upgrade process and cause it to fail

When the outcome of the check is a warning or an error, details about the exception are provided.

The System Checker report provides the following information:

A detailed list of exceptions observed on hosted sites

A detailed list of exceptions observed on the server

Recommended actions to be performed

Recommended actions to be performed after the upgrade

The actions recommended provide broad solutions for resolving the observed exceptions. If these actions for resolving the exceptions are appropriate for your server, you must execute them as mentioned. After performing the recommended pre-upgrade actions, you must restart the upgrade by running the
ensim-installer.sh script. To restart the upgrade, please follow the instructions from step 3 specified in the section Upgrading to the latest version of Ensim Control Panel.

At the end of the check, a summary of the results is displayed, in the following format:

SUMMARY for <hostname>: <n> error(s), <m> warning(s), <k> domain(s) with issues

Where:

<hostname> is the name of your Ensim Control Panel server

<n> indicates the number of errors

<m> indicates the number of warnings

<k> indicates the number of domains for which exceptions have been observed

Appendix B: Reviewing customizations

The following sections list additional customizations that need to be reviewed before or after the upgrade.

If you have customized Ensim Control Panel, we recommend that you contact Ensim Support to verify the impact of these customizations on the upgrade process. Ensim provides professional services that help you with the upgrade process.

Customizations that do not require pre-upgrade or post-upgrade actions

The following customizations do not require any pre-upgrade or post-upgrade actions.

Files added to /usr/lib/opcenter/fastcgi/extras

Customization files added to /usr/lib/ensim_python/site-packages/vh3/custom/

Files modified in /etc/virtualhosting/ipranges

Files modified in /etc/appliance/customization

Files modified in /etc/virtualhosting/templates that do not belong to SquirrelMail

Customizations that require pre-upgrade or post-upgrade actions

The following customizations require either pre-upgrade or post-upgrade actions.

Bind mounting directories under a site’s file system

Ensim Control Panel disables sites before upgrading them resulting in loss of bind mounted directories. If the bind mounted directory is essential for Ensim Control Panel to proceed with the upgrade, then the upgrade fails. This has been observed with the bind mounted directory /usr/lib/perl.

Pre-upgrade action required?

Yes.

Unmount the bind mounted directory using the following command:

#umount <dir_name>
where <dir_name> is the absolute path of the bind mounted directory.

Post-upgrade action required?

Yes. Your bind mounted directories will be lost. You will require to bind mount the unmounted directories using the following command.

#mount -b <dir_to_mnt> <bindmount_dir>

where:
<dir_to_mnt> is the absolute path of the directory you want to mount
<bindmount_dir> is the absolute path of the location where you want to mount the directory

Files modified in /usr/lib/opcenter/bind/named_conf_zone.tmpl

Pre-upgrade action required?

Yes. Back up the file named_conf_zone.tmpl.

Post-upgrade action required?

Yes. Your modifications may be lost after the upgrade. To resolve this issue, re-apply your changes to the file /usr/lib/opcenter/bind/named_conf_zone.tmpl.

DTML modifications to files under /usr/lib/opcenter

Pre-upgrade action required?

Yes. Back up your custom DTML files.

Post-upgrade action required?

Yes. Your modifications may be lost after the upgrade. To resolve this issue, re-deploy your custom DTML files to /usr/lib/opcenter.

PHP binaries installed over files owned by the PHP RPMs

Pre-upgrade action required?

Yes. Your custom PHP binaries may be replaced with binaries of the PHP RPM shipped with Ensim Control Panel during the upgrade. To prevent your custom binaries from being replaced during the upgrade, run the script
ensim-installer.sh with the option --exclude=<pkg1,pkg2,...>. This step will exclude the specified packages from getting replaced during the upgrade process.
For more information on usage of the option, use the --help option with the script.
For example, to exclude the PHP packages php, php-devel, run the script as follows:
#sh ensim-installer.sh --exclude=php,php-devel

Post-upgrade action required?

No.

MySQL installed with InnoDB support binaries replaced with files owned by the MySQL RPMs

Pre-upgrade action required?

Yes. To prevent your custom binaries from being replaced during the upgrade, run the script ensim-installer.sh with the option --exclude=<pkg1,pkg2,...>. This step will exclude the specified packages from getting replaced during the upgrade process. For more details on usage of the option, use the --help option with the script.
For example, to exclude the MySQL package mysql run the script as follows:
#sh ensim-installer.sh --exclude=mysql

Post-upgrade action required?

No.

Modifications made to the file /usr/lib/opcenter/fastcgi/httpd-tmpl.conf replaced during the upgrade

Pre-upgrade action required?

Yes. Back up your httpd-tmpl.conf file.

Post-upgrade action required?

Yes. Your modifications may be lost after the upgrade. To resolve this issue, re-apply your changes to the file /usr/lib/opcenter/fastcgi/httpd-tmpl.conf.

Modifications made to the non-config files owned by the RPM database replaced during the upgrade

Pre upgrade action required?

Yes. Back up the binaries.

Post-upgrade action required?

Yes. Custom-compiled files owned by an RPM (which is part of Ensim Control Panel) may get replaced during the upgrade.

To see if a file is owned by an RPM, run the command rpm -qf <full_path_of_binary>. If the command returns the name of a RPM, the file is replaced during the upgrade. To ensure compatibility, recompile your binaries under a Fedora 1/RHEL 3 system, or obtain the appropriate RPMs/source-RPMs that are compatible with Fedora 1/RHEL 3.

Upgraded or replaced MySQL RPM

Pre-upgrade action required?

Yes. To prevent the MySQL RPM from getting replaced during the upgrade, run the script ensim-installer.sh with the option --exclude=<pkg1,pkg2,...>. This step will exclude the specified packages from getting replaced during the upgrade process. For more details on usage of the option, use the --help option with the script.
For example, to exclude the MySQL packages, mysql-server, mysql, mysql-devel, run the script as follows:
#sh ensim-installer.sh --exclude=mysql-server,mysql,mysql-devel

Post-upgrade action required?

No.

Modifications made to the file /var/www/html/index.shtml

Pre upgrade action required?

Yes. Back up the file /var/www/html/index.shtml.

Post-upgrade action required?

Yes. Modifications made to the Ensim Control Panel root level file /var/www/html/index.shtml may be lost after the upgrade. To resolve this issue, re-apply your changes to the file /var/www/html/index.shtml.

Modifications made to the file /etc/php.ini

Pre-upgrade action required?

Yes. Back up the file /etc/php.ini.

Post-upgrade action required?

Yes. Modifications made to the /etc/php.ini file may be lost after the upgrade. To resolve this issue, re-apply your changes to the file or restore from your backup.

Modifications made to the files /etc/httpd/conf/virtual/site<n>

Pre-upgrade action required?

Yes. Back up changes to any of the /etc/httpd/conf/virtual/site<n> files.

Post-upgrade action required?

Yes. Modifications made to any of the /etc/httpd/conf/virtual/site<n> files may be lost after the upgrade (your changes will be lost even when performing an enable or disable operation). To resolve this issue, you must re-apply the modifications to the files manually.

Modifications made to the files /etc/proftpd/site<n> or /etc/proftpd/site<n>.anonftp

Pre upgrade action required?

Yes. Back up your changes to any of the /etc/proftpd/site<n> or /etc/proftpd/site<n>.anonftp files.

Post-upgrade action required?

Yes. Modifications made to the files /etc/proftpd/site<n> and /etc/proftpd/site<n>.anonftp will be lost after the upgrade (your changes will be lost even when performing an enable or disable operation). To resolve this issue, re-apply your changes to the file or restore from your backup.

Modifications made to the file /etc/logrotate.conf

Pre-upgrade action required?

Yes. Back up the file /etc/logrotate.conf.

Post-upgrade action required?

Yes. Modifications to the Ensim Control Panel root level file /etc/logrotate.conf may be lost after the upgrade. To resolve this issue, re-apply your changes to the file or restore from your backup.

Modifications made to default Service Plans

Pre-upgrade action required?

Yes. Back up the settings of your default Service Plan.

Post-upgrade action required?

Yes. The Ensim Control Panel upgrade will overwrite the default Service Plan. To resolve this issue, you must restore the Service Plan backup, which you backed up before the upgrade.

Sites that use Microsoft Frontpage Server Extensions in an inconsistent state

Pre-upgrade action required?

No.

Post-upgrade action required?

Yes. When sites that use Microsoft Frontpage Server Extensions go into an inconsistent state, the following error message displays.

The document root of the web server where you are trying to install the server extensions already contains a disk-based web.

To resolve this issue:

Open the file /home/virtual/<domain>/var/www/html/_vti_pvt/service.cnf.

Remove the following lines and save your changes.

vti_httpdversion:SX|FrontPage DBW

vti_webservertype:SR|diskweb

Appendix C: Troubleshooting upgrade issues

If you encounter problems that you cannot troubleshoot or resolve using the information in Table 3, contact Ensim for online support at https://onlinesupport.ensim.com. You may also refer to the log file installer.log to review the list of successful and unsuccessful events recorded during the upgrade. The log file is located at /var/log/ensim and is emailed to the specified email address.

Table 3. Troubleshooting upgrade issues (Installer)

Symptom

Description

Solution

When you run the command,
“hostname” the value "myhost" is returned by the command instead of “myhost.mydomain.com”.

The host name of the server is incorrect.

Check the file /etc/sysconfig/network. The host name must be a fully qualified domain name. See the following example.

Incorrect: myhost

Correct: myhost.mydomain.com

During upgrade, the following message is displayed: check_hostname <FAILED>.

The host file is
incorrect.

The file /etc/hosts should contain the host name and IP address of your server (see the following example). If it does not, use an editor to modify the file.

Example

---/etc/hosts begin file--

127.0.0.1 localhost.localdo- main localhost

1.2.3.4 myhost.mydomain.com my- host

---/etc/hosts end file--

where 1.2.3.4 is the IP address of myhost.mydomain.com

Unable to connect to Ensim’s FTP server.

Failed to download the metadata from ftp.ensim.com.

Error initializing setup.

Ensure that you are connected to the Internet.

Cannot download or install updates.

Error downloading/installing updates.

The error log contains a list of all the updates that could not be downloaded. Download these updates and install them on the server, before re-starting the server to upgrade Ensim Control Panel.

Cannot download Ensim Control Panel.

Error downloading Ensim Control Panel.

Ensure that you are connected to the Internet.

Feedback and support

To take advantage of Ensim's support services or to find additional product documentation, visit the Ensim support site, http://support.ensim.com.

To log in to Ensim online support, go to https://onlinesupport.ensim.com.

To provide feedback about Ensim products or documentation, please use the feedback form at http://www.ensim.com/about/feedback.asp.

Legal and copyright notice

This document contains information proprietary to Ensim Corporation and its receipt or possession does not convey any rights to reproduce, disclose, manufacture, or sell anything it might describe. Reproduction, disclosure, or use without Ensim’s specific written authorization is strictly forbidden.

Ensim Corporation makes no representations or warranties with respect to the content or use of this document. It also reserves the right to revise this document at any time without the obligation to notify any person of such revision.

Ensim, the Ensim logo, and ServerXchange are registered trademarks of Ensim Corporation.

All other trademarks and copyrights are the property of their respective owners.

© 2005 Ensim Corporation. All rights reserved.

Table 1. System requirements for upgrading to Ensim Control Panel
System requirements
Disk space	At least 20 GB
Connectivity	Network connectivity with access to Internet
Ensim Control Panel CD-ROM (if you want the Installer to obtain the installation files from the CD-ROM)	One Ensim Control Panel CD-ROM
Web server requirements: Before the upgrade, configure Apache 2.0 as the Production Web server, then restart the Production and Test Web servers. Ensim Control Panel no longer supports Apache 1.3. For instructions on configuring your Web server, refer to the Appliance Administrator’s Help. Important: You must restart both the Web servers after setting Apache 2.0 as the Production Web server, otherwise the upgrade will fail.
Other requirements	DNS server on network “root” user access

Table 2. Upgrade checklist
Task	Status
Have you reviewed the current license information?	¨
Have you configured Apache 2.0 as your Production Web server and subsequently restarted the Production and Test Web servers? Ensim Control Panel no longer supports Apache 1.3. Before you upgrade, you must configure Apache 2.0 as your Production Web server, then restart the Web servers, otherwise the upgrade will fail.	¨
Have you backed up the hard disk? Note: Before upgrading, please back up the entire hard disk to prevent loss of data if the upgrade fails.	¨
Are all sites in a consistent state? To verify the status of the sites: Log on to the Appliance Administrator control panel. On the left navigation bar, click Site Manager. At the bottom of the page, click the Display arrow and select All Sites. Sites that are inconsistent display the following message: This site is currently in an inconsistent state. This may be the result of an active or failed edit. For resolving related issues, please search Ensim’s knowledge base articles. You can find the knowledge base articles on the Web at http://onlinesupport.ensim.com/kb_search.asp?product=lwp.	¨
Is Microsoft® FrontPage® consistent on all your sites? A successful upgrade requires Microsoft FrontPage to be consistent on all your sites. To verify that Microsoft FrontPage is consistent on all your sites, log on to the server as the root user and run the following command at the prompt: #/usr/local/frontpage/currentversion/bin/owsadm.exe -o check -p all If Microsoft Frontpage is consistent, the message `Check Completed` is displayed, otherwise errors related to the observed inconsistency is displayed. See Sites that use Microsoft Frontpage Server Extensions in an inconsistent state for information on restoring a site to its consistent state.	¨
Have you replaced the period (.) character in a MySQL database name with a valid character? MySQL database names that include a period (.) must be replaced with a valid character before an upgrade. Note that usage of the characters—forward slash (/), period (.), and equal to (=)—is invalid. For instructions on renaming the database, please refer to the Site Administrator online Help (accessible through the Help option on the Site Administrator control panel.)	¨
Have you reviewed your customizations and completed the necessary pre-upgrade steps? Refer to the section, Appendix A: Overview of the Ensim Control Panel System Checker to review your customizations for compatibility. Also review the section Customizations that require pre-upgrade or post-upgrade actions for more information on additional pre-upgrade tasks you may need to perform.	¨
If you have configured the Installer to obtain the Ensim Control Panel files from a local FTP server or the Ensim Control Panel CD-ROM, verify that the Installer has access to these repositories. Local FTP server: The Installer obtains the installation files from the specified FTP server. You need to specify the server name or the IP address. The local FTP server must mirror the directory structure for Ensim Control Panel installation on Ensim’s FTP server. For instructions, please refer to the document Setting up a local FTP server to install Ensim Pro and Ensim Basic 4.0.3 for Linux (Standalone) at http://www.ensim.com/support/pro/linux/index.html. Ensim Control Panel CD-ROM: Ensure that the Installer has access to the CD-ROM for obtaining the Ensim Control Panel files.	¨

Table 3. Troubleshooting upgrade issues (Installer)
Symptom	Description	Solution
When you run the command, “hostname” the value "myhost" is returned by the command instead of “myhost.mydomain.com”.	The host name of the server is incorrect.	Check the file /etc/sysconfig/network. The host name must be a fully qualified domain name. See the following example. Incorrect: myhost Correct: myhost.mydomain.com
During upgrade, the following message is displayed: check_hostname <FAILED>.	The host file is incorrect.	The file /etc/hosts should contain the host name and IP address of your server (see the following example). If it does not, use an editor to modify the file. Example `---/etc/hosts begin file--` `127.0.0.1 localhost.localdo- main localhost` `1.2.3.4` myhost`.mydomain.com` my- host `---/etc/hosts end file--` where `1.2.3.4` is the IP address of myhost.mydomain.com
Unable to connect to Ensim’s FTP server.	Failed to download the metadata from ftp.ensim.com. Error initializing setup.	Ensure that you are connected to the Internet.
Cannot download or install updates.	Error downloading/installing updates.	The error log contains a list of all the updates that could not be downloaded. Download these updates and install them on the server, before re-starting the server to upgrade Ensim Control Panel.
Cannot download Ensim Control Panel.	Error downloading Ensim Control Panel.	Ensure that you are connected to the Internet.

Ensim Corporation
www.ensim.com

Contact Ensim
www.ensim.com/about/contact.html