Automatic Updater
The Automatic Update utility allows admin users to update WHMCS quickly and easily in just a few clicks.
You can access this feature at Utilities > Update WHMCS.
For more information on the way in which updates change files, see Updater File Changes.
Contents
System Requirements
For automatic updates to be possible, the following system requirements apply:
- A PHP Memory limit of at least 128MB
- At least 250 MB of free disk space
- PHP setting allow_url_fopen enabled
- PHP max_execution_time in excess of 60 seconds
- PHP Zip Extension or the proc_open PHP function enabled
- PHP setting open_basedir to include entire WHMCS docroot
Configuring Your Update Settings
Choosing an Update Channel
The WHMCS automatic updater allows you to choose an update channel that defines the type of updates you will receive. The update channel setting determines the least stable version you are willing to update to:
| Channel | Description |
| Stable | Recommended for most installations of WHMCS, the Stable channel will only apply Stable updates to your installation. |
| Current Version | Subscribing to this channel will restrict you to only receiving maintenance updates for the major/minor version that is currently installed. For example if you are on a version that is in Long Term Support and a patch is issued for that series, this channel allows you to apply the patch and remain on that series. This is useful for applying minor updates and security releases. More details below. |
| Release Candidate | Subscribing to the Release Candidate channel will allow you to receive releases after beta testing but before they are released to the Stable tier. |
| Beta | Subscribing to the Beta release channel will allow you to receive the very latest versions of WHMCS. This tier should only be selected for development and test based installations. |
Patch and Maintenance Release Updates
- If you are on a version that is in Long Term Support and a patch is issued for that series, you can use the Updater to apply the patch and remain on that series.
- To do this, select the Current Version update channel as described above.
- You many need to click Check for Updates after any setting changes in order to refresh the available version displayed within the page.
You may wish to change this setting back to "Stable" after updating to ensure future checks display the latest Active Development version available to you.
Setting a Temporary Update Path
A temporary path is required for staging of files during an update. For security reasons it is recommended that this directory be located outside the public doc root, similar to the attachments, downloads and templates_c directories. The path must be an absolute path (i.e. /home/whmcsuser/tmp instead of ~/tmp) and must be writable by the user that is running PHP.
Setting a Maintenance Message
This option can be used to set a message that will be displayed to both other admin and client users whenever an update is in progress.
Checking for Updates
New updates are checked for periodically automatically.
When an update becomes available, a notification will appear in the top left corner of admin area as shown below.
Manually checking for updates
You can check for updates on-demand by clicking the Check for Updates button.
If a release has just been published you may need to do this to see the update as available prior to the next automated check.
For Owned licenses, the version fetched by the utility will be the version of WHMCS that was available when your Support and Updates Subscription was active. Downloading the latest version of WHMCS requires an active Support and Updates Subscription.
Performing an Update
To perform an update:
- Make certain that your server meets the system requirements and review the Release Notes for any important notices and information.
- Make a full backup of your current installation.
- In WHMCS, click Update Now. This option only displays if an update is available for your current update channel.
- Follow the prompts to complete the update process. The update process can take anywhere from 30 seconds to a few minutes to complete.
If you have custom template files you will also need to review and make any necessary changes to your custom templates using the information provided in the Template Changes section of the Release Notes.
Troubleshooting
The actions performed by the Automatic Updater are recorded in the tblupdatelog table within the WHMCS database. To troubleshoot upgrade problems it is useful to review this table for the most recent entries (the highest id values). A tool such as phpmyadmin can be used to browse to the table contents.
For additional guides to troubleshooting auto-update problems, see Updating and Upgrading New Installation Prompt.
Please ensure you have selected a valid Update Channel and then try again
Receiving this error message in the cron job report email or activity log, indicates that an Update Channel setting needs selecting. To do this, click Configure Update Settings.
Next select one of the four available update channel options, and Click Save Changes. The options are described above.
Permission Errors
Permission errors in the update log may resemble the following examples:
- [WHMCS\Exception] Failed to perform early file copy during WHMCS file relocation: init.php
- [RuntimeException] /path/to/whmcs/whmcs does not exist and could not be created.
- failed to open stream: Permission denied
- Apply update dry-run detected 1 permission issues
The exact file permission and ownership issues will depend on the individual server configuration. However, for a standard cPanel & WHM server using the suPHP PHP handler, the following configuration would be an appropriate POSIX file permissions:
- configuration.php — 400
- /crons/pipe.php — 755
- All other PHP files — 644
- All directories — 755
The file ownership and group should be the same as the user directory name. For example, on a cPanel & WHM server with a web root at /home/username/public_html/, the username user would own the files and the group would also use the name username.
Finally, the owner and group of the PHP process must be the same as the user directory name. For example, on a cPanel & WHM server with a web root at /home/username/public_html/, the PHP process owner and group would both be username.
Other types of server and PHP handlers may have different configuration requirements.
Unable to connect to the WHMCS Update Server
This error message may be encountered when attempting to perform an automatic update or appear in the Activity Log. It means that your server was unable to connect to our update server. From your server's command line, attempt the following two cURL connections:
curl -v https://releases.whmcs.com/v2/packages.json
curl -v https://pki.whmcs.com/
The expected return is a StatusCode: 200. If any other results is returned please work with your server admin or hosting provider to investigate the connectivity problem between your server and the WHMCS update server.