Difference between revisions of "Automatic Updater"

From WHMCS Documentation

(Troubleshooting)
(Manually checking for updates)
 
(44 intermediate revisions by 6 users not shown)
Line 1: Line 1:
<div class="docs-alert-info"><i class="fa fa-question-circle"></i> This page describes a feature available in version 7.0 and above</div>
+
<div class="docs-alert-info">
 +
<i class="fa fa-question-circle"></i> We added this feature in WHMCS 7.0.
 +
</div>
  
The Automatic Update utility allows admin users to update WHMCS quickly and easily in just a few clicks.
+
The Automatic Update utility allows admins to update WHMCS quickly and easily from directly within the Admin Area.
  
== System Requirements ==
+
You can access this feature at '''Utilities > Update WHMCS'''.
  
For updates to be able to be completed successfully, the following requirement must be met:
+
For more information on the way in which updates change files, see [[Updater File Changes]].
  
* At least 250 MB of free disk space
+
== System Requirements ==
* 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 ==
+
WHMCS has several system requirements for automatic updates:
  
New updates are checked for automatically at periodic intervals.
+
* A PHP memory limit of at least 128MB.
 
+
* At least 250 MB of free disk space.
When an update becomes available, a notification will appear in the top left corner of admin area.
+
* The PHP <tt>allow_url_fopen</tt> setting is enabled.
 
+
* The PHP <tt>max_execution_time</tt> setting is 60 seconds or more.
In addition, you can check for updates on-demand by navigating to ''Utilities > WHMCS Update'' and clicking the '''Check for Updates''' button.
+
* The PHP Zip Extension or the <tt>proc_open</tt> PHP function are enabled.
 
+
* The PHP <tt>open_basedir</tt> setting includes the entire WHMCS document root.
If a newer version is available, the Latest Version display will update to show the version available to update to.  The status of the update check will also be displayed top right as a notification.
 
 
 
[[File:UpdateAvailable.png|center]]
 
 
 
== Performing an Update ==
 
 
 
To perform an update, navigate to ''Utilities > Update WHMCS'' and click the '''Update Now''' button (pictured above).
 
 
 
You will then be guided through the update process.  The update process can take anywhere from 30 seconds to a few minutes to complete.
 
 
 
<div class="docs-alert-info"><i class="fa fa-info-circle"></i> Please note this option will only show if an update is available based on your current Update Channel Preferences.</div>
 
 
 
<div class="docs-alert-success"><i class="fa fa-warning"></i> Providing you have followed the recommended methods for customising things such as [[Customising_the_Six_Theme|templates]], [[WHOIS_Servers|WHOIS servers]], [[Additional Domain Fields]] and [[Customising Countries and Calling Codes|Countries]], your customisations will be preserved through the update process.</div>
 
 
 
<div class="docs-alert-warning">Before beginning an update, it is strongly recommended to take a full backup of your current installation (files and database).</div>
 
 
 
<div class="docs-alert-info"><i class="fa fa-file-text-o"></i> We also recommend that you review the release notes before updating to ensure you are aware of any changes that may affect you.</div>
 
  
 
== Configuring Your Update Settings ==
 
== Configuring Your Update Settings ==
  
=== Choosing an Update Channel ===
+
=== Update Channel ===
  
The WHMCS automatic updater allows you to choose an update channel that defines the type of updates you will receive.
+
The Automatic Updater allows you to choose the update channel for the least stable version you are willing to update to:
 
 
For most users, we recommend choosing the '''Stable''' channel which will only apply Stable updates to your installation.
 
  
 
<table class="table table-striped">
 
<table class="table table-striped">
Line 54: Line 33:
 
<tr>
 
<tr>
 
<td>Stable</td>
 
<td>Stable</td>
<td>'''Recommended''' for most installations of WHMCS, the Stable channel will track the latest stable version that has been released.</td>
+
<td>'''Recommended'''<br/>Only receive Stable updates to your installation.</td>
 +
</tr>
 +
<tr>
 +
<td>Current Version</td>
 +
<td>Only receive maintenance updates for the currently-installed major and minor version. For example, if you are on a version in [[Long Term Support]] and we release a patch for it, this channel applies the patch but will not upgrade you to a later WHMCS version.<div class="docs-alert-info">This is useful for applying minor updates and security releases (see below).</div></td>
 
</tr>
 
</tr>
 
<tr>
 
<tr>
 
<td>Release Candidate</td>
 
<td>Release Candidate</td>
<td>Subscribing to the Release Candidate channel will allow you to receive releases after beta testing but before they are released to the Stable tier.</td>
+
<td>Receive releases after beta testing but before we release them to the Stable tier.</td>
 
</tr>
 
</tr>
 
<tr>
 
<tr>
 
<td>Beta</td>
 
<td>Beta</td>
<td>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.</td>
+
<td>Receive the latest versions of WHMCS as we release them to the Beta tier. Only select this tier for development and testing installations.</td>
</tr>
 
<tr>
 
<td>Current Version</td>
 
<td>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.</td>
 
 
</tr>
 
</tr>
 
</table>
 
</table>
  
=== Setting a Temporary Update Path ===
+
==== Patch and Maintenance Release Updates ====
 +
 
 +
If you are on a WHMCS version that is in [[Long Term Support]] and we issue a patch for that version, you can use the Automatic Updater to apply the patch without moving to a newer WHMCS version.
 +
 
 +
To do this:
 +
 
 +
# Select the '''Current Version''' update channel (see above).
 +
# Click '''Check for Updates''' to refresh the available version.
 +
# Proceed with your update as usual.
 +
 
 +
<div class="docs-alert-warning">
 +
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.
 +
</div>
 +
 
 +
=== Temporary Update Path ===
 +
 
 +
The temporary path allows you to stage files during an update. For security reasons, ensure that this directory is outside of the public document root, like the <tt>attachments</tt>, <tt>downloads</tt>, and <tt>templates_c</tt> directories.
 +
 
 +
* The path must be an absolute path (for example, <tt>/home/username/tmp</tt> instead of <tt>~/tmp</tt>).
 +
* The path must be writable by the user that is running PHP.
 +
 
 +
=== Maintenance Message ===
  
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.  
+
Use this option to set a message to display to other admins and users whenever an update is in progress.
  
=== Setting a Maintenance Message ===
+
<div class="docs-alert-info">
 +
Modifying the update configuration requires the '''Modify Update Configuration''' [[Administrator Roles|administrator role permission]], which is separate from the '''Update WHMCS''' permission.
 +
</div>
  
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 ==
  
<div class="docs-alert-info">Modifying the update configuration requires the '''Modify Update Configuration''' administrator role permission, which is separate from the "Update WHMCS" permission.</div>
+
The system automatically checks for updates periodically. When an update becomes available, a notification will appear in the Admin Area.
  
[[File:Configureupdatesettings.png|center]]
+
===Manually checking for updates===
  
== Troubleshooting ==
+
You can check for updates on demand by clicking '''Check for Updates'''. You may need to do this to see recent releases prior to the next automated check.
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.
 
  
===Permission Errors===
+
<div class="docs-alert-info">
Permission errors may manifest themselves in the tblupdatelog table as the following:
+
For Owned licenses, the version that this fetches 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.
<div class="source-cli">
 
[WHMCS\Exception] Failed to perform early file copy during WHMCS file relocation: init.php
 
 
</div>
 
</div>
or
+
 
<div class="source-cli">
+
For a step-by-step tutorial, see [https://help.whmcs.com/m/updating/l/678174-checking-for-updates-manually Checking for Updates Manually].
[RuntimeException] /path/to/whmcs/whmcs does not exist and could not be created.
+
 
 +
== Performing an Update ==
 +
 
 +
<div class="docs-alert-info">
 +
We recommend using the '''Automatic Updater''' utility every time you update WHMCS. However, you can also perform an update [https://go.whmcs.com/1709/Updating-WHMCS-Manually manually through the browser] or [[Install On The Command Line|on the command line]].
 
</div>
 
</div>
  
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:
+
To perform an update:
 +
 
 +
# Make certain that your server meets the [[System_Requirements|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'''. <div class="docs-alert-warning"><i class="fa fa-info-circle"></i>This option only displays if an update is available for your current update channel.</div>
 +
# Follow the prompts to complete the update process. The update process can take anywhere from 30 seconds to a few minutes to complete.
 +
# Perform the necessary steps for your customizations:
 +
#* If you use any custom file permissions, you '''must''' update the relevant files (for example, for <tt>/crons/pipe.php</tt>).
 +
#* If you have custom template files, review and update your custom templates using the '''Template Changes''' section of the [[Release Notes|release notes]].
  
<div class="docs-alert-warning">
+
<div class="docs-alert-success">
configuration.php - 400<br/>
+
The update will not alter your customizations if you follow our official customization guidelines (for example, our guidelines for [https://developers.whmcs.com/themes/ templates], [[WHOIS_Servers|Whois servers]], [[Additional Domain Fields|additional domain fields]], and [[Customising Countries and Calling Codes|country and calling codes]].
/crons/pipe.php - 755<br/>
 
All other PHP files 644<br/>
 
All directories 755<br/>
 
 
</div>
 
</div>
  
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'''.
+
== Troubleshooting ==
 +
 
 +
You can find the log of Automatic Updater actions in the <tt>tblupdatelog</tt> table in the WHMCS database. To troubleshoot upgrade problems, review this table for the most recent entries (the highest <tt>id</tt> values). You can use a tool like phpMyAdmin to browse the table's contents.
 +
 
 +
For more information on troubleshooting update issues, see [[Upgrading New Installation Prompt]] and [http://help.whmcs.com/m/updating our update troubleshooting guides].
 +
 
 +
===Please ensure you have selected a valid Update Channel and then try again===
  
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'''.
+
Receiving this error message in the cron job report email or activity log indicates that you need to select an update channel.  
  
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.
+
To fix this issue:
 +
 
 +
# Click '''Configure Update Settings'''. 
 +
# Select one of the four available update channel options ([[#Choosing an Update Channel|see above]]).
 +
# Click '''Save Changes'''.
 +
 
 +
===Permission Errors===
 +
 
 +
Permission errors in the update log may resemble the following examples:
 +
 
 +
* <tt>[WHMCS\Exception] Failed to perform early file copy during WHMCS file relocation: init.php</tt>
 +
* <tt>[RuntimeException] /path/to/whmcs/whmcs does not exist and could not be created.</tt>
 +
* <tt>failed to open stream: Permission denied</tt>
 +
* <tt>Apply update dry-run detected 1 permission issues</tt>
 +
 
 +
The exact file permission and ownership issues 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:
 +
 
 +
* <tt>configuration.php</tt> — <tt>400</tt>
 +
* <tt>/crons/pipe.php</tt> — <tt>755</tt>
 +
* All other PHP files — <tt>644</tt>
 +
* All directories — <tt>755</tt>
 +
 
 +
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 <tt>/home/username/public_html/</tt>, <tt>username</tt> would own the files and the group would also use the name <tt>username</tt>.
 +
 
 +
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 <tt>/home/username/public_html/</tt>, the PHP process owner and group would both be <tt>username</tt>.
 +
 
 +
Other types of server and PHP handlers may have different configuration requirements.
 +
 
 +
===Unable to connect to the WHMCS Update Server===
 +
 
 +
This error indicates that your server could not connect to the WHMCS update server.
 +
 
 +
You may see it in two locations:
 +
 
 +
* While attempting an automatic update.
 +
* In the '''Activity Log''' section at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > [[System Logs]]''' or, prior to WHMCS 8.0, '''Utilities > Activity Log'''. 
 +
 
 +
To resolve this, attempt the following cURL connections from your server's command line:
  
===Curl 77 Error===
 
CURL77 errors may manifest as the following in the tblupdatelog table:
 
 
<div class="source-cli">
 
<div class="source-cli">
[WHMCS\Installer\Composer\ComposerUpdateException] Failed to get certificate metadata from keyserver. Error: Unable to download file from URL: https://pki.whmcs.com/certs.json 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] [--] []...
+
<nowiki>curl -v https://releases.whmcs.com/v2/packages.json</nowiki>
</div>
+
 
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.
+
<nowiki>curl -v https://pki.whmcs.com/
 +
</nowiki></div>
  
Please work with your server administrator or hosting provider to ensure the root CA bundles are fully updated on your server.
+
If these commands succeed, they will return <tt>StatusCode: 200</tt>. If they do not, ask your hosting provider or system administrator to investigate the connectivity problem between your server and the WHMCS update server.

Latest revision as of 18:21, 31 January 2023

We added this feature in WHMCS 7.0.

The Automatic Update utility allows admins to update WHMCS quickly and easily from directly within the Admin Area.

You can access this feature at Utilities > Update WHMCS.

For more information on the way in which updates change files, see Updater File Changes.

System Requirements

WHMCS has several system requirements for automatic updates:

  • A PHP memory limit of at least 128MB.
  • At least 250 MB of free disk space.
  • The PHP allow_url_fopen setting is enabled.
  • The PHP max_execution_time setting is 60 seconds or more.
  • The PHP Zip Extension or the proc_open PHP function are enabled.
  • The PHP open_basedir setting includes the entire WHMCS document root.

Configuring Your Update Settings

Update Channel

The Automatic Updater allows you to choose the update channel for the least stable version you are willing to update to:

Channel Description
Stable Recommended
Only receive Stable updates to your installation.
Current Version Only receive maintenance updates for the currently-installed major and minor version. For example, if you are on a version in Long Term Support and we release a patch for it, this channel applies the patch but will not upgrade you to a later WHMCS version.
This is useful for applying minor updates and security releases (see below).
Release Candidate Receive releases after beta testing but before we release them to the Stable tier.
Beta Receive the latest versions of WHMCS as we release them to the Beta tier. Only select this tier for development and testing installations.

Patch and Maintenance Release Updates

If you are on a WHMCS version that is in Long Term Support and we issue a patch for that version, you can use the Automatic Updater to apply the patch without moving to a newer WHMCS version.

To do this:

  1. Select the Current Version update channel (see above).
  2. Click Check for Updates to refresh the available version.
  3. Proceed with your update as usual.

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.

Temporary Update Path

The temporary path allows you to stage files during an update. For security reasons, ensure that this directory is outside of the public document root, like the attachments, downloads, and templates_c directories.

  • The path must be an absolute path (for example, /home/username/tmp instead of ~/tmp).
  • The path must be writable by the user that is running PHP.

Maintenance Message

Use this option to set a message to display to other admins and 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.

Checking for Updates

The system automatically checks for updates periodically. When an update becomes available, a notification will appear in the Admin Area.

Manually checking for updates

You can check for updates on demand by clicking Check for Updates. You may need to do this to see recent releases prior to the next automated check.

For Owned licenses, the version that this fetches 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.

For a step-by-step tutorial, see Checking for Updates Manually.

Performing an Update

We recommend using the Automatic Updater utility every time you update WHMCS. However, you can also perform an update manually through the browser or on the command line.

To perform an update:

  1. Make certain that your server meets the system requirements and review the Release Notes for any important notices and information.
  2. Make a full backup of your current installation.
  3. In WHMCS, click Update Now.
    This option only displays if an update is available for your current update channel.
  4. Follow the prompts to complete the update process. The update process can take anywhere from 30 seconds to a few minutes to complete.
  5. Perform the necessary steps for your customizations:
    • If you use any custom file permissions, you must update the relevant files (for example, for /crons/pipe.php).
    • If you have custom template files, review and update your custom templates using the Template Changes section of the release notes.

The update will not alter your customizations if you follow our official customization guidelines (for example, our guidelines for templates, Whois servers, additional domain fields, and country and calling codes.

Troubleshooting

You can find the log of Automatic Updater actions in the tblupdatelog table in the WHMCS database. To troubleshoot upgrade problems, review this table for the most recent entries (the highest id values). You can use a tool like phpMyAdmin to browse the table's contents.

For more information on troubleshooting update issues, see Upgrading New Installation Prompt and our update troubleshooting guides.

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 you need to select an update channel.

To fix this issue:

  1. Click Configure Update Settings.
  2. Select one of the four available update channel options (see above).
  3. Click Save Changes.

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 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.php400
  • /crons/pipe.php755
  • 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/, username 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 indicates that your server could not connect to the WHMCS update server.

You may see it in two locations:

  • While attempting an automatic update.
  • In the Activity Log section at Configuration () > System Logs or, prior to WHMCS 8.0, Utilities > Activity Log.

To resolve this, attempt the following cURL connections from your server's command line:

curl -v https://releases.whmcs.com/v2/packages.json

curl -v https://pki.whmcs.com/

If these commands succeed, they will return StatusCode: 200. If they do not, ask your hosting provider or system administrator to investigate the connectivity problem between your server and the WHMCS update server.