Automatic Updater

From WHMCS Documentation

Revision as of 20:35, 7 December 2017 by John (talk | contribs) (Curl 77 Error)

This page describes a feature available in version 7.0 and above

The Automatic Update utility allows admin users to update WHMCS quickly and easily in just a few clicks.

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

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.

Screenshot 2017-06-01 10.32.27.png

Manually checking for updates

You can check for updates on-demand by navigating to Utilities > WHMCS Update and 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.

UpdateAvailable.png

Performing an Update

To perform an update, navigate to Utilities > Update WHMCS and click the Update Now button (pictured above).

Please note this option will only show if an update is available based on your current Update Channel Preferences.

You will then be guided through the update process. The update process can take anywhere from 30 seconds to a few minutes to complete.

Before beginning any update, it is strongly recommended to make a full backup of your current installation and review the Release Notes for any important notices and information.

Watch our video tutorial here: https://vimeo.com/whmcs/automatic-updates-tutorial

Your customisations will be preserved during the update provided you are leveraging the recommended methods for customising things such as templates, WHOIS servers, Additional Domain Fields and Countries
If you have customised the permissions on any of the files eg. /crons/pipe.php. These changes will need to be re-applied after the upgrade is complete.

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.

For most users, we recommend choosing the Stable channel which will only apply Stable updates to your installation.

Channel Description
Stable Recommended for most installations of WHMCS, the Stable channel will track the latest stable version that has been released.
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.
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 the installed version of WHMCS is 7.0.0-GA, admins will be offered upgrades to 7.0.1-GA and 7.0.2-GA, but not 7.1.0.

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.

Modifying the update configuration requires the Modify Update Configuration administrator role permission, which is separate from the "Update WHMCS" permission.
Configureupdatesettings.png

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.

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, navigate to Utilities > Update WHMCS and click Configure Update Settings.

Next select one of the four available update channel options, and Click Save Changes. The options are described above.

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:

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.

Permission Errors

Permission errors may manifest themselves in the tblupdatelog table as the following:

[WHMCS\Exception] Failed to perform early file copy during WHMCS file relocation: init.php

or

[RuntimeException] /path/to/whmcs/whmcs does not exist and could not be created.

These kinds of file permission and ownership issues are multi-faceted and dependant upon the individual server configuration. However for a standard cPanel server using the suPHP PHP Handler an appropriate posix file permissions permissions would be:

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. Eg. On a cPanel box where the web-root is located at /home/david/public_html/, files should be owned by david, and the group should be david.

Finally, the owner and group of the PHP process seeking to take action should be the same as the user directory name. Eg. On a cPanel box where the web-root is located at /home/david/public_html/, PHP process owner and group should be david.

Other types of server and PHP handlers may have different configuration requirements, the above is intended as a guide for one particular possible combination only.

Curl 77 Error

CURL77 errors may manifest as the following in the tblupdatelog table:

[WHMCS\Installer\Composer\ComposerUpdateException] Failed to get certificate metadata from keyserver. Error: Unable to download file from URL: Message cURL error 77: Problem with the SSL CA cert (path? access rights?) update [--prefer-source] [--prefer-dist] [--dry-run] [--dev] [--no-dev] [--lock] [--no-plugins] [--no-custom-installers] [--no-autoloader] [--no-scripts] [--no-progress] [--with-dependencies] [-v|vv|vvv|--verbose] [-o|--optimize-autoloader] [-a|--classmap-authoritative] [--ignore-platform-reqs] [--prefer-stable] [--prefer-lowest] [-i|--interactive] [--root-reqs] [--] []...

This error indicates that the server was unable to connect to the WHMCS update server because the security of the connection could not be verified. The connection is secured using SSL certificates and to verify the certificate your server needs up-to-date root certificates to know which to trust.

Please work with your server administrator or hosting provider to ensure the root CA bundles are fully updated on your server.