Username Password
Bookmark and Share


Upgrading WebGUI is relatively simple and painless, as long as you’re prepared. Read this entire chapter before attempting an upgrade.

Upgrade History

If you want to see what upgrades have been applied to your WebGUI install, the upgrade utility can tell you that. Simply run this command:

cd /data/WebGUI/sbin

perl --history --doit


You’ll get output that looks like this which tells you which upgrades have been applied to each site:

Testing site config versions…

Getting site configs...


Displaying upgrade history for each site.

7.3.4 2007-01-17 initial install

7.3.5 2007-01-17 upgrade

7.3.6 2007-01-25 upgrade

7.3.7 2007-01-25 upgrade


Note that it tells you which version numbers were applied, the date of the application, and also whether it was the initial installation, or an upgrade.

Upgrade history can be particularly useful when trying to diagnose problems that may have been caused by an old upgrade. For example, if in version 7.0.1 there was something that tweaked a particular setting you’re now having trouble with, and you’re now running 7.5.5, you can look back and see if the 7.0.1 upgrade was ever applied to your install. Perhaps you started with version 7.5.0, in which case it will be obvious that the 7.0.1 upgrade cannot be responsible for your current problem.

How Upgrades Work

Upgrades in WebGUI work by applying incremental patches to your existing WebGUI site. You first start by copying the new WebGUI distribution over the top of your existing one.

Then you apply the data patches using the methods described below. This applies each patch to each of your WebGUI site's data since your last upgrade to make your data compliant with the new version of the code. So if you're upgrading from 7.0.2 to 7.2.3 there might be several dozen patches applied to your site's data. It then repeats this process for every site you have configured. If you have a lot of sites, or you don't upgrade very often, the upgrade process can take a long time. So be prepared for down time.

Note: The upgrade process will overwrite any files you've customized.

Know Your Versions

The first thing to do is to find out if a new version of WebGUI is available. You can do this quickly and easily three different ways:

  1. Visit, which always has the latest version.

  2. From your web site go to Admin Console > Statistics and it will tell you what version you are running, and what the latest version is.

  3. From your server command line run the following command to find out your local version and the latest:

cd /data/WebGUI/sbin


This will deliver a lot of output, but what you want is near the end and will look like this (the bold line is the one you’re looking for):

WebGUI modules: OK

Getting current WebGUI version: OK

Your version: You are using 7.3.2-stable and 7.3.8-stable is available.

Locating WebGUI configs: OK

Checking config file:

Verifying uploads folder: OK

Verifying DSN: OK

Verifying database connection: OK

Testing complete!


Once you know what version is available, you should also check your own version to see if you’re out of date. Methods 2 and 3 (above) will tell you both your current version and the latest version available.

There is one more way to find out your current version number. Edit lib/ and look near the top of the file, though it may be as much as 20 lines into the file. There will be a $VERSION variable that will tell you what version the code base is. Here’s an example of that:

our $VERSION = "7.3.9";

our $STATUS = "stable";



Before you ever perform an upgrade, always run a complete backup of your environment. Usually upgrades will go smoothly, but if they don't, you're going to want a full backup so you can restore anything and everything. For more information about performing backups, see the chapter called Backups later in this book.

Note: WebGUI will perform incremental backups of your site databases(s) as it upgrades. This should not be misconstrued as a full backup. This does not relieve you of your obligation to maintain full backups and conduct one before you upgrade.

Upgrade Options

After you've found out if there is an upgrade, and have decided to upgrade, there are two ways to do it. First, if you're using the WRE you can use WebGUI Update, which is an automated upgrade system. If you did a source install, you can do a manual upgrade.

WRE WebGUI Update

To use WebGUI Update go to the command line, and then do the following:

Stop Spectre.

/data/wre/sbin/ ---stop spectre


Run WebGUI Update and follow the onscreen instructions.



Restart Apache and start Spectre.

/data/wre/sbin/ --restart web --start spectre



Test your site(s) to make sure everything is working.

Manual Upgrade

Note: Whether you do upgrades manually or use WebGUI Update, if the upgrade displays errors and the gotchas don't tell you to expect it, then your upgrade has likely failed. Restore from backup.

To perform a manual upgrade, run the following steps:

Download the new version of WebGUI from

Decompress the new version of WebGUI.

cd /tmp
tar xvfz /path/to/webgui-7.5.0-stable.tar.gz


Read the WebGUI/docs/gotcha.txt file to see what you should know about before upgrading. Follow any instructions in there.

more /tmp/WebGUI/docs/gotcha.txt


Read the WebGUI/docs/changelog/7.x.x.txt file to see what has changed since your current version.

more /tmp/WebGUI/docs/changelog/7.x.x.txt


Stop Spectre.

cd /data/WebGUI/sbin

perl --shutdown


Decompress the new version of WebGUI over the top of the old version of WebGUI

cd /data

tar xvfz /path/to/webgui-7.5.0-stable.tar.gz


Restart Apache.

Run the upgrade.

cd /data/WebGUI/sbin


Note that the above command won't work directly. You need to read the output of the upgrade script to find out how to make it work. This is our way of ensuring that you're not blindly following instructions without knowing what you're getting into.


cd /data/WebGUI/sbin



Restart Apache again to make it re-read the config files.

Start Spectre.

cd /data/WebGUI/sbin

perl --daemon


Test your site(s) to make sure everything is working.

Keywords: backups upgrade upgrading

Search | Most Popular | Recent Changes | Wiki Home
© 2022 Plain Black Corporation | All Rights Reserved