cPanel Version 11 - Update Checklist

BACK TO HOMEPAGE

Contents

1. Accessing the Command Line Interface
2. Upgrade to Perl 5.8.8
3. Mail Format Conversion
4. cPanel 11 Update
5. X3 Skin Migration
6. Fantastico Update
7. RvSkin Update
8. Sprites
9. Miscellaneous Extras

Recently cPanel.net released the latest stable version of the cPanel/WHM system, version 11.2.0.

More information on this new update may be found at http://www.cpanel.net/products/cPanelandWHM/linux/cpanel11/index.html

We have found that several important updates are either necessary or recommended for optimal performance under this new version of the cPanel/WHM system. This article provides very thorough instruction on how you can perform these updates yourself, however the possibility that the updates may not complete as this article expects does exist.

If you feel that you cannot perform these updates yourself, or would rather have our staff perform these updates for you to avoid any issues, please contact our Support Division at https://desk.hostdime.com/ and request that our staff perform these updates for you.

NOTE: It is very important that we perform these updates for you at an appropriate time to avoid any situation which you or your clients may interpret as downtime. To achieve this it is best that these updates occur during a time period where the server is receiving the least amount of activity (i.e. high traffic, CPU, and memory usage). If you decide to request our staff to perform these updates please let us know what time of day (including time zone) you believe your server has the lowest amount of CPU and memory usage. Typically such usage occurs during non-peak/low traffic hours during the early morning (2 AM EST - 7 AM EST), however since many of our clients provide services to global regions of the world other than North America, we will need you to provide us with what you believe to be the best time for these updates. As always, please also provide our support team with the necessary information so they may log into your server (IP address, hostname, root pass, SSH port, su user credentials).

If any custom configurations have been made to your server regarding your Apache, Exim, MySQL, or other systems which are provided by the cPanel/WHM system, we advise that you open a ticket via our helpdesk (link is provided above) with a description of these customizations and request that we perform the updates for you. Our support team will be more experienced in dealing with the most common conflicts with such custom configurations, and thus will be able to avoid them or at least handle them in the quickest fashion possible once the conflicts or issues are detected.

Disclaimer

While the instructions below are very thorough, and presented for clients which do not have a high level of technical proficiency, there is a chance that unexpected conflicts or issues may occur during these updates. We would rather perform these updates for you than risk any downtime or issues for your websites or clients in the event that any unexpected issues occur. We are providing the instructions for this update below for customers which feel they are technically proficient enough to perform these updates themselves (and thus retain control over the process). Be advised that by following these instructions that you do so at your own risk.

If you decide to follow these instructions yourself and run into any issues, please do not hesitate to contact our Support Division team via the HostDime Helpdesk at https://desk.hostdime.com/ with a description of what you have done and what issues have occured during the update.

1. Accessing the Command Line Interface - Back to Top

Some of the steps of this update require that you access the command line interface of your server using a secure shell (SSH) client program, and running the commands as instructed. Below are instructions for those using the Windows and Macintosh platforms.

Windows Users

If you are using Windows, you can access the command line interface of your server by using a secure shell (SSH) client program known as Putty. You can download the Putty.exe file by clicking here.

When you run this program you will see a window such as the following:

Under the 'Host Name (or IP address)' field enter the hostname or IP address of your server (or just use one of your domain names if you like). Under the 'Port' field you should just leave it as '22', unless you happen to know that your server is using a different SSH port. After you've entered the information in, click on the 'Open' button at the bottom.

Next you will be prompted to enter your login name after 'login as:'. Enter the username 'root' then press the ENTER key.

Next enter the root password for your server (the same one you use for WHM) then press ENTER again.

After a message which indicates the last login made with your username (along with the IP address which the root user logged in from) you will see the command prompt. It is from this line that you will enter the commands as instructed in the sections which follow.

If you wish to copy and paste the commands provided in the sections below, just copy the commands to your clipboard, then click on the title bar of the window to make sure the Putty window is selected. Next right click with your right mouse button, inside of the black area of the window, and your command will automatically paste into the window at the command line. If you are copying a block of commands, all commands except for the last one will automatically be run. Make sure you press the ENTER key once after pasting a block of commands to make sure all commands are successfully run.

Mac OS X Users

If you are a Macintosh user running the Mac OS X operating system you can use the program called "Terminal" which is included with your operating system inside of the Applications -> Utilities folder. Double click on this program to open it, and then connect to the server using the following command:

ssh -l<username> <servername> -p<port>

For example, to connect to a server named 'myserver.mydomain.com' as the 'root' user, with the server using port 1234 (standard secure shell port is normally 22), you would use this command:

ssh -lroot myserver.mydomain.com -p1234

2. Upgrade to Perl 5.8.8 - Back to Top

Since the cPanel/WHM system heavily relies on scripts programmed in Perl version 5.8.8, it is necessary that you update to the latest Perl version. If you are not running the latest Perl version, then you should expect to have some problems with either the upgrade or cPanel/WHM version 11.

To check if you are already running Perl version 5.8.8, you can run the 'perl -v' command. In this example the server is running version 5.8.5.

If you are already running Perl version 5.8.8, continue to the next step of this tutorial (Mail Format Conversion ). If you are not running Perl version 5.8.8, continue with the steps below.

Performing Update

You can copy the following command block from this webpage, and then right click in your Putty window so it will paste the commands to the command line. Press enter a couple times to make sure the commands complete. This will install the new Perl version all at once.

wget http://layer1.cpanel.net/perl588installer.tar.gz;
tar xfvz perl588installer.tar.gz;
cd perl588installer;
./install;
	  

I will continue with instructions which show how these commands are run separately for those who wish to make sure they receive the same results just as I have in the example screenshots. If you receive any errors, its best to contact our support instead of continuing with this update.

The next step is to download the Perl source code package. You can do this by running 'wget http://layer1.cpanel.net/perl588installer.tar.gz' then pressing ENTER. You will see some output which indicates how far the download has progressed. After the download of the package has completed, you should see something similar to this:

Next use the command 'tar xfvz perl588installer.tar.gz' to unpackage (like unzip) the file.

Then use the 'cd perl588installer' command to change to the directory of the new folder of files we've placed into the 'root' users home directory.

Last run the './install' command to run the installer script. You will see something similar to this window as the actual Perl source code is downloaded from the cPanel system file repository server. Many more commands will fly up the screen as the new Perl version is compiled and installed.

If you see many errors at the end of the process, with a message that indicates a test failure, then contact our support team to perform this Perl update for you.

If instead you receive a message such as this which indicates no failures, then you should continue. Note that it says 'Tested 107, 107 ok, 0 failed.' This is the message you want to see at the end of the process.

After you are done performing the Perl update, use the command 'cd ..' to return to the directory you were in before.

Next run the following command to remove the files which you downloaded for the update. This will remove both the directory and the original package file you downloaded.

rm -rf perl588installer; rm -rf perl588installer.tar.gz;

Verifying Update

Run this command to verify that the cPanel 11 update is completed: perl -c /scripts/wwwacct

If you do not see any errors, then everything should be fine. If you do receive any errors, then run the following commands to ensure that everything is updated.

/usr/local/cpanel/bin/checkperlmodules

Then run this command to force the update of cPanel 11 (updating anything which was originally missed)

/scripts/upcp --force

3. Mail Format Conversion - Back to Top

There are two mail formats which were available for the cPanel/WHM system under version 10.

Mbox

Mbox is a mail format which stores all of the email messages for a particular mailbox (such as a users Inbox or Trash folder) to be stored inside of a single file on the servers hard drive. Under this mail format, an Inbox with 1 GB of messages will cause an increased amount of memory and CPU resources just to open the file and obtain the messages when the user checks their email via POP3, IMAP, or webmail. This obviously results in poor performance for the server.

Originally this mail format was to be discontinued in cPanel version 11, however by high demand the cPanel developers decided to leave support for this format available in cPanel 11 to avoid the widespread issues which the update would cause for the servers which have not been converted away from the Mbox mail format. It is expected that cPanel version 12 will not support the Mbox mail format, and thus it is critical that you make sure that your server is converted to the new Maildir format before the cPanel 12 update occurs.

It is also recommended that the mail conversion take place before the cPanel 11 update occurs to avoid any issues. If your server has already updated to cPanel 11, please do continue with the mail conversion. This is merely a recommendation we are making to avoid issues which may occur.

MailDir

Unlike the Mbox mail format, a mailbox on a server using the Maildir mail format is represented as an individual folder on the servers hard drive, with each email message stored as a separate file under this folder. This obviously makes for a more efficient mail system, and improved server performance (or lack of possible poor performance).

This mail format is not supported by the NeoMail webmail program (the NeoMail development project has also been discontinued), and thus all cPanel/WHM systems which are converted to the MailDir format will no longer provide the NeoMail program as an option.

Disclaimer

During the conversion, all incoming mail will be stored in the Exim mail server queue until the conversion is completed. After the conversion is completed the mail server will begin to deliver the mail which was queued to the local mailboxes hosted by the server. If your clients send mail from the server during the conversion, the messages will be sent without any issues, however as stated the incoming mail will wait inside of the queue until the conversion is completed.

Due to this delay with incoming mail, its important that the mail conversion occur during non-peak usage of the server otherwise you will receive complaints from your clients indicating that they have not received email which they have expected. The mail conversion from may take several hours, and will increase the load average for your server while the conversion occurs, which may result in the server responding very slow. It is highly recommended that you perform the conversion on your server during non-peak hours when the server is receiving the least amount of traffic.

Optimizing the Conversion

All cPanel accounts have usernames which reflect the same username of an actual Linux user account located on the server. Due to Linux user standards, this account is able receive mail. The cPanel system is designed to allow you to access the mail inside of this account via the cPanel or webmail, even though there is not a direct email address assigned to the account. On many older cPanel servers this primary account was assigned as the catch-all mail account by default when it was created on the server. This Default Catch-All setting specifies where email messages should be routed if they are not addressed to an actual mail account or forwarding address on the server. Typically this primary cPanel user email account goes unused, and thus causes the cPanel accounts to exceed their disk quota after several megabytes or gigabytes of spam messages (sent to non-existing addresses) are received. Fortunately the latest cPanel versions setup new accounts to bounce back email messages received for email addresses which do not exist.

Since your server may still have many of these types of accounts with extremely large mailboxes which are full of spam, it is recommended that you advise your clients to clear out these mailboxes of unnecessary messages before you continue with the mail conversion. The primary cPanel user mail account can be cleared by setting up a temporary IMAP mail account setting inside of a mail client program such as Outlook Express (included by default with Windows XP) or Thunderbird, then connecting to the server and deleting all the mail. IMAP will be more efficient than POP3 as a mail access method as the IMAP method does not download the content of the messages unless you select a single message to view it (unlike POP3 which downloads all messages before removing them from the server).

If you advise your clients to clear out the primary mailbox, make sure you also instruct them to reconfigure the default catch-all setting for their cPanel account so that it bounces back the messages using the ' :fail: no such address here' setting. This is done via the Mail > Default Address area of the cPanel.

Already Converted

To perform the conversion you will need to access the command line of your server as instructed in the first section above.

Run this command from the command line to check to see if your server is already using the 'maildir' mail format:

/scripts/convert2maildir

If the script reports that 'maildir is enabled' above the numerical menu of options, then your server is already using the maildir mail format.

Type '*' and press Enter to exit the script, then skip this step and proceed to the next step (cPanel 11 Update).

If the script outputs 'maildir is not active, this system is using mbox', then continue with this section.

Rebuilding RPM Database

Some of our technicians have found that the Redhat Package Manager (RPM) database on the servers was corrupted, and this led to the mail conversion not completing as it should have. Run the following commands to ensure this database is not corrupted before you proceed:

rm -fv /var/lib/rpm/__db.*;
rpm --rebuilddb;

Checking for Free Space

Before you continue with the conversion, its important that you make sure you have at least 5 gigabytes of disk space (10 gigabytes recommended) available on your servers primary drive. To do this you can run the following command to view the partitions which are mounted to the file system on your server:

df -h;

As you can see from the example above, the /dev/hda5 partition has 106 GB total, 31 GB used, and 70 GB avaialble for use. This is the primary partition of the server as it is indicated as mounted on '/'. If you see a line which details a partition mounted to /home, make sure the partition is also noted to have at least 5 - 10 GB of available disk space.

To proceed with the next step, Backup Email Accounts, you will need to make sure that at least 10 GB of disk space is available on the backup drive attached to your server (if one is present). This is denoted in the same output mounted to /backup.

If you do not have enough space on the server to continue with the backup or the conversion, or you have no backup drive setup on your server, please contact our Support Division at https://desk.hostdime.com/ for further assistance.

Backup Email Accounts

Run the backup script using the following command: /scripts/convert2maildir

After you run this command you will be prompted with a menu like so. Select option #1 to backup all the mail folders on the server. This will ensure that if any issues occur during the conversion, you will be able to restore from the backup.

You will be prompted to confirm that you wish to continue, as the backup will overwrite any previous backup. Since you haven't run this script before, enter 'y' and press ENTER to continue.

You will begin to see all of the accounts being backed up as they are performed.

Performing Conversion

After the backup is completed you will be prompted to select the next action. Enter the number '3' and press enter to begin the mail conversion. !!Remember!! Do not continue with this process unless you are sure the server is not experiencing peak usage during normal business hours.

From this point forward the mail conversion will begin.

Once the conversion is completed it will return to the command line.

Its recommended that you run the script again and choose option #3 (Convert partially converted mail accounts) to ensure that all accounts are properly converted. The output of the process should look exactly the same, however it should complete much sooner than the original process.

NeoMail Address Book Migration

After you are finished with the mail conversion, its a good idea to run the following script to ensure that all the Neomail address books that your clients might have used are converted to the Horde address book.

/scripts/neomail2hordeaddrbook

If you happen to get some sort of MySQL errors from this script instead of the type of output shown in the screenshot above, log into WHM and reset the root password for MySQL via the 'MySQL Root Password' option under the 'SQL Services' area of the WHM menu, then try running the script again.

4. cPanel 11 Update - Back to Top

First log into your server to make sure you are not already running the latest cPanel 11 system. The version is displayed in the upper-right corner of the WHM interface. If it states that you are running version WHM 10.8.0 or less, then your system is not already configured to perform automatic updates, and thus you will need to perform the update manually before proceeding with the other instructions below. If you are already running WHM 11.2.0, continue to step 5 - X3-Skin Migration.

Update Configuration

Before the system will allow you to manually perform the cPanel/WHM update the server must be configured to allow such a manual update. Some server owners choose to disable updates so they do not occur even when when manually prompted. This is usually the situation regarding server which have some sort of custom configuration settings which will conflict with updates to the cPanel/WHM system.

To check your update settings, choose the 'Update Config' option under the 'Server Configuration' section of the WHM interface.

If your configuration for "cPanel/WHM Updates" is already set with one of the "Manual Updates Only" options, leave this setting as is. If your system is set to "Never Update", change this to "Manual Updates Only (STABLE tree)", then click on the 'Save' button at the bottom of the window.

Mail Server Conflicts

Before you begin the process of updating your cPanel/WHM system to version 11, its important to log into the command line interface of the server and run the following command. One of our 3rd level technicians may have changed the configuration of your email server at some point and locked these files so they could not be modified. This command ensures that the files are unlocked so the cPanel update is able to proceed properly without any problems.

chattr -ia /etc/exim*;

Starting the Update

To begin the cPanel/WHM version 11 update, c lick on the WHM version link in the upper-right corner of the window.

Next click on the 'Click to Upgrade' button.

Once you've done this you will begin to see the upgrade process run.

At the top of the page it will display the percentage of progress it has made as the upgrade is completed.

Once the updates have finished, you will see the following at the top of the page:

After the upgrade has finished, log out of the WHM interface, then log back in to access the new version 11 interface. If your system was originally configured to use the 'Never Update' option under Server Configuration > Update Config, go back and switch the setting back now that the update has been performed.

5. X3 Skin Migration - Back to Top

cPanel 11 will work with the x or x2 skins, however it has been found that not all of the cPanel 11 features are properly supported by the x and x2 themes. You can use the X Skin Migration Wizard to migrate all accounts and packages to the x3 skin.

To do this select the "X Skin Migration Wizard" option beneath the "Themes" section of the WHM interface.

If you do not see a list of users or packages which are listed for conversion, skip this section and continue to the next (Fantastico Update).

All of the users on your server should be selected in the list to the left. Click on the "Click Here" button to perform the migration.

After the migration is completed, you will see messages indicating each user which was converted to the x3 theme. At the end it will state "Migration Complete".

Just the same you may be prompted to update all packages, which are using the old themes, to be updated to use the new x3 theme. Make sure to perform this update to avoid the need to use this migration tool in the future to fix newer accounts which are still using the old themes.

Next click on the "Basic cPanel/WHM Setup" option beneath the "Server Configuration" menu in the WHM interface.

Scroll down the menu and find the "Default cPanel Theme" setting. Make sure the theme reflected in this area reflects "x3" and not "x" or "x2".

6. Fantastico Update - Back to Top

Click on the "Fantastico De Luxe WHM Admin" link under the Plugins area of the WHM interface.

Security Clean Up

If you see the security cleanup notification, click on Delete, otherwise continue below. This will remove the master files for the current installation. If you have made any modifications to your Fantastico installation, its recommended that you follow the instructions provided on the screen to ensure your customizations are not removed.

After the cleanup of master files is finished, you will see a confirmation such as the one in the screenshot below. Click on the 'Main' link on the left to proceed to the next step.

Updating Version

If you see a message which indicates that the Fantastico is the latest version, such as in the following screenshot, then proceed with the next step (RvSkin Update).

If you see a message displayed such as the one in the following screenshot (which indicates that there is an update available), click on the "Click here" link to make sure the update is performed. If any security warnings are displayed, make sure to follow any instructions to take care of the issues posted by the security warnings as advised.

As the update occurs you will see the list of programs which have been fetched/updated listed on in the window. When the update is done it will look similar to the screenshot below.

7. RVskin Update - Back to Top

Click on the "RVSkin Manager" link under the Plugins menu in the WHM interface.

In the middle of the page it will display the current version number of the RVskin software. In this example its indicating that the current RvSkin version on the server is version 6.90. Below this you will see that it indicates that the latest released version is 8.04 for cPanel 11.1.0 and above. If you see this, along with the cooresponding 'Update Now' link, click on the 'Update Now' link. If the output indicates that you are already using the current version for cPanel 11, continue to the next section (Sprites).

On the next screen click on the 'Update RV Skin Now' button to begin the update. Other instructions will be displayed on the screen to setup automated updates, however this information is not relevant to this article.

As the update is performed you will see the output of the process as it runs, much like the output in the example screenshot below. Make sure you leave your browser window open and stay connected to the internet for the entire process to complete.

At the very bottom you should see something like the following. This will let you know that the process is completed.

RvSkin Theme Switcher

If you wish to enable the option for your clients to choose which theme their account uses, you may use the RvSkin Theme Switcher option. The RVSKIN theme switcher allows x3 (and optionally x and x2) theme users to switch to RVSKIN and back again on their own. You should check this setting to make sure the theme switcher is shown or not shown as you prefer.

Simply click on the "RVSKIN Manager" link in WHM.

Next place your mouse over the "Themes" menu and select "Selectable Themes".

From this menu you can choose to enable the theme switcher enabled for your users. Simply check off the themes you want your users to be to select from, then also place a checkbox in the "Show RVSkin change themes in x skin." box. After you are finished click on the 'Submit' button at the bottom of the window to save your settings.

After you have enabled this setting, you will also need to make sure the theme changer is enabled for your default feature list. First click on the 'Feature Manager' option from the Packages menu.

Next select the feature list under which you wish to enable the theme switcher, then click on the 'Edit' button.

Scroll to the bottom of the list and make sure there is a checkmark placed in the 'RVSkin Theme Changer' box, then click on the 'Save' button at the bottom.

Alternately if you do not want to enable this feature for your clients, make sure the option is unchecked under the feature list, and also unchecked under the Selectable Themes are of the RVSkin Manager.

8. Sprites - Back to Top

After upgrading to cPanel 11, there may be cases where some of the add on components (such as ClickBe or Fantastico) might be missing from the cPanel menus for the accounts. To avoid support requests regarding this issue it won't hurt to run the following command just to ensure this issue doesn't occur with your accounts:

/usr/local/cpanel/bin/rebuild_sprites

9. Miscellaneous Extras - Back to Top

Fixing Email Configuration

Our support team has found that many clients have received 'Unrouteable Domain' errors when trying to send email from their server after performing a cPanel upgrade. The new cPanel has a completely new set of configurations as compared to the older version, and some servers which have custom ACL (access control list) configurations may not work properly due to these differences. Do the following to ensure that this does not happen with your server.

NOTE: These steps only apply to your server AFTER you've updated to cPanel/WHM version 11.2.0 or above.

Select the 'Exim Configuration Editor' option from the 'Service Configuration' menu in the WHM interface.

Scroll to the bottom of the page and click on the 'Reset ACL config to defaults' button.

This will rebuild the configuration and you will see output similar to this:

After the update has finished, click on the 'Exim Configuration Editor' link again from the 'Service Configuration' menu in the WHM.

Under the ACLS menu, place a checkmark in the box next to 'Reject mail at SMTP time if the sender host is in the zen.spamhaus.org, or bl.spamcop.net rbl'. This will cause the two options above it to disappear.

Scroll down the page to the Mail area. Place a checkmark next to the 'Reject email at SMTP time for users who have exceeded their quota rather than keeping it in the queue. This is probably a good idea, but it does mean people will lose mail so its not on by default.' listing, then click on the 'Save' button at the bottom of the page.

cPHulk Brute Force Detector

Under the 'Security Center' option, which is avaialble from the WHM 'Security' menu, there is an option for a new feature known as cPHulk Brute Force Protection.

Brute Force is the term used to describe attempts to gain access to account(s) on your server through the process of running a program which attempts use random usernames and/or passwords to login several (hundred or thousands) times until a successful login is detected. To fight against this the cPHulk software will monitor various server logs to detect when a non-typical number of failed login attempts have been made by a certain user on the internet. When such a scenario is detected the server will block the IP address of the offending hacker.

By default this software is not enabled. Simply click on the 'Enable' button at the top of the screen to activate this new feature of the WHM/cPanel system.

Keep in mind that this feature may temporarily ban legitimate users of your server, however this can be remedied by finding the appropriate settings for your server. While going through the following recommended proceedure for finding the correct settings may be inconvenient, enabling this software and reconfiguring this feature appropriately will in the end result in a more secure server, and thus less headaches which result from brute force breakins (mail issues, slow websites, modified websites, 5-6 hour downtime due to restore).

If you find that legitimate users of your server are being banned by this feature, you may want to return to this area and increase the values for some of the numeric settings which are avaialble for you to adjust. We recommend that you increase the numbers by 5 each time you make an adjustment, until complaints from legitimate clients have stopped. Don't go crazy and increase the numbers too much as this will defeat the purpose of enabling the feature in the first place.

Back to Top