Upgrade Module

Upgrade Module Overview

The Upgrade Module is a module that is used to allow FreePBX to be upgraded from one major version number to a higher version. For example, to upgrade from version 2.3.X to 2.4.0. The way that FreePBX manages the Online repository is by providing an XML file associated with each X.X version of the product. FreePBX uses this XML file to detemine what the latest available modules are for your current version and where to find them. It then compares this against what you have installed to allow you to upgrade.

In order to upgrade from a version such as from 2.3.X to 2.4.X you need to have Module Admin download modules-2.4.xml instead of modules 2.3.xml. Since FreePBX uses its internal version number to detemine which one to pull, the upgrade process simply bumps the current FreePBX version to the lowest possible version so that it will download the proper XML file. The lowest version, in the case of 2.4, would be 2.4.0alpha0 which in fact never existed since we always start with version 1 for alpha, beta and RC releases.

Once you have bumped the version number, you need to go through the process of downloading modules. The Framework module is a special module that often has libraries and functions required by many other modules. So this module usually needs to be downloaded first, followed by all the other modules. Also - it is important during the upgrade process that you don't press the Apply Configuration bar. The Upgrade module has a mechanism that should keep the Apply Configuration bar from coming up until you have finished the upgrade process. This is to make sure you keep from running the configuration generation part of FreePBX (retrieve_conf) which may have other requirements not yet upgraded until all modules are brought up to date.

Upgrade Process

During each step of the upgrade process the top display of the Upgrade module will show the current version for FreePBX Base, FreePBX Framework and FreePBX Core since these are typcially the core critical modules that need to get fully upgraded before the module is satisified and removes itself. You should still be certain to upgrade ALL other modules that have upgrades available or you will have potential for errors.

The step that are involved in the upgrade process are:

  1. One might acquire the 2.4 Upgrade Tool through many methods but most will simply get it through the familiar Module Admin by clicking on the “Check for updates online” link/button.
  2. Install the module called "2.4 Upgrade Tool," by clicking on the module and selecting Install. Then click the process button at the bottom of this screen.
  3. Now we will see a typical module install screen requesting that we confirm the “2.4 Upgrade Tool 2.3.0 will be installed and enabled.” Click the “Confirm” button now to proceed.
  4. Once this tool is installed a new option will show up on the left navigation bar under the Admin Section titled “2.4 Upgrade Tool.” Think of this temporary tool as your guide through a healthy install process. Only once the upgrade process is complete and no longer necessary will this tool handily remove itself from the navigation bar.
    2.4 Upgrade Bar Left Navigation Bar

  5. We will return to this button several times as it will guide us through the complete multistep process dynamically providing status updates and instructions as we proceed. Go ahead and click the “2.4 Upgrade Tool” button now.
  6. Please take the time to read through the provided instructions.
    2.4 Upgrade Version Progress
  7. Please note, as tempting as it may be, the repeated instructions of IMPORTANT: Do NOT Apply Configuration Changes (reload bar) until you have gone through all the steps!
  8. Click on the Upgrade Now button and confirm the first part of the upgrade process at this time.
  9. Read the instructions (RTMF) as they have dynamically updated. Notice that the line FreePBX Base Version: now has a new value of “2.4.0alpha0.” Each of these three components, Base, Framework, and Core will display their currently respective versions on the local system and be updated as we progress.
    2.4 Upgrade Version Progress
  10. The instructions now say to go back to Module Admin and choose to ONLY upgrade “FreePBX Framework.” Do so now following the usual upgrade confirmation and return prompts.

    Framework Upgrade
  11. Now we may upgrade Core and everything else in this step. Once again do so now.
  12. As previously stated we have repeated been told to NOT press the reload bar until you have completed the previous step. We may do so now.
  13. Upgrade Complete.
  14. Notice that the “2.4 Upgrade Tool” has removed itself from the navigation bar as it has completed its task of guiding us through the easiest FreePBX upgrade to date.

Once you have completed these step you will be upgraded to the new version. Under normal circumstance, the module should delete itself. If it is still there, try clicking on it and see if that removes it. If not, read the status information to see if you have really finished the upgrade. If you have it should go away.