Smarty Security Policy

2016-10-03T14:37:28Z

Zoey: Default mail policy tag blocks added.

<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>

WHMCS 7.0 introduces a new security hardening measure called Smarty Security Policies. WHMCS utilizes a system policy for system wide use, and a mail policy specifically for stored and dynamic email based templates.

The settings enforced by a WHMCS Smarty Security Policy are the same as those defined by the Smarty library itself. You can learn more about about these settings from the Smarty documentation: http://www.smarty.net/docs/en/advanced.features.tpl

By default, WHMCS does not define any PHP functionality restrictions for the system policy (except to honor the pre-existing {php} tag setting as configured in Setup >> Security). All templates that use this policy are file based (for example, themes and order forms) which require file level access and therefore are automatically implicitly trusted. Because custom themes are much more likely to have additional PHP oriented logic, any restrictions defined by WHMCS could result in website rendering issues. It is completely within your discretion to determine if implicit trust at the file level is invalid and you may make any appropriate restrictions for this system policy.

The mail policy restricts what PHP functionality can be used in email based templates. The default mail policy will limit the use of variable modifiers (http://www.smarty.net/docs/en/language.modifiers.tpl) to the following:

*escape
*count
*urlencode
*ucfirst
*date_format

The default mail policy restricts the use of native PHP functions to the following:

*isset
*empty
*count
*sizeof
*in_array
*is_array
*time
*nl2br

Finally, the default mail policy blocks these smarty tags:

* block
* function
* include

The default mail policy will not allow for the inclusion of any calls to static classes, fetching any data from php streams, or accessing any super global variables.

If you want to redefine either the system or mail policy, you can do this by adding a $smarty_security_policy setting to your configuration.php. Here's an example that limits email templates (by modifying the mail policy) to 'ucwords' as the only native PHP function allowed, while not changing the default restrictions on variable modifiers:

<source lang="php">
// Smarty custom email based template policy:
$smarty_security_policy => array(
'mail' => array(
'php_functions' => array(
'ucwords',
),
),
);
</source>

Smarty has deprecated the {include_php} syntax, but WHMCS currently supports this behavior via Policies. If your template invokes & includes a PHP script by using the Smarty {include_php} syntax, the directory of that script will need to be whitelisted in the 'trusted_dir' setting of your Policy.

Please refer to the [http://www.smarty.net/docs/en/advanced.features.tpl#advanced.features.security/ Smarty documentation] for all possible settings and what behavior to expect when assigning array and boolean values.

Automatic Updater

2016-07-22T22:59:13Z

Zoey: Adding images for Cole!

== Requirements ==

*The Automatic Updater requires at least 250 MB of free disk space
*The Automatic Updater requires PHP setting allow_url_fopen = true
*The Automatic Updater requires PHP setting open_basedir to include entire WHMCS docroot
*The Automatic Updater can take a few minutes, so you'll need to ensure that you allow long running php processes in your webserver

== Checking for Updates ==

Introduced in WHMCS 7.0.0, the Automatic Updater provides admins with a quick and easy way to update to new versions of WHMCS with just a few clicks in the admin area interface. The system will check for new updates on each cron run. Upon logging into the WHMCS admin area, a notification will appear in the top right corner of admin area. This alert will let the admin know if a new version of WHMCS is available, or if the version of WHMCS that is currently installed is the latest version. Below are examples of what these notifications look like:

[[File:UpdateNotification.png|center]]

Admins can also manually check for updates by navigating to the Utilities top menu in the admin area interface and select Update WHMCS.

[[File:WHMCSUpdateMenu.png|center]]

Once selected, the admin will be asked to confirm their password, as only admin users that have the "Update WHMCS" admin role will be able to access the updater.

[[File:UpdateConfirmPassword.png|center]]

Once in the Automatic Update interface, admins can tell at a glance what version of WHMCS that is installed, as well as check for updates using the Check for Updates button.

[[File:NoNewUpdatesAreAvailable.png|center]]

[[File:UpdateAvailableNotice.png|center]]

By clicking Check for Updates, the version indicated in Your Version on the left side of the version summary will stay the same, but the information presented in the Latest Version on the right side of the version summary may be updated depending if a new update is available. It should also be noted that the Check Now button also indicates the last time an update check was performed. If a new version is available for upgrade, admins can then begin the update process by clicking the Update Now button.

[[File:UpdateAvailableBody.png|center]]

== Configuring Your Update Settings ==

The Automatic Updater also presents admins with the ability to configure update settings such as choosing an update channel, setting a temporary update path, and setting an update maintenance message for customers. Note that accessing the update configuration page requires "Modify Update Configuration" administrator role, which is separate from "Update WHMCS" role.

=== Choosing an Upgrade Channel ===

The automatic updater provides admins with the ability to set the release stability that they are comfortable receiving. Admins will be able to select from the following channels:
Channel
Description
Stable Recommended for most installations of WHMCS, the Stable channel will present admins with the latest stable version that has been released by WHMCS.
Release Candidate Admins subscribed to the Release Candidate will be able to upgrade to the latest Release Candidate builds of WHMCS, or the latest stable version of WHMCS - whichever is newer. This means if WHMCS is upgraded to 7.0.0-rc.1, when 7.0.0-GA is released, the admin will be prompted to upgrade to the general availability that was just released.
Beta Admins subscribed to the Beta release channel will be able to download the newest beta, release candidates, and stable versions of WHMCS. This is for testing installations, as it will allow admins to update to the latest WHMCS (beta, rc, or stable). WHMCS recommends development licenses use this channel.
Current Version By selecting this channel, admins are electing to only receive maintenance updates for the major/minor version they are on. For example if the installed version of WHMCS is running 7.0.0-GA, admins will be offered 7.0.1-GA, but not 7.1.0. This channel is useful if the installed version of WHMCS has a number of 3rd party modules and customizations that need to be tested before upgrading to a new production release.

=== Setting a Temporary Update Path ===

The temporary path is used for staging files during an update. For security reasons it is recommended that this directory be located outside the public doc root, just like the attachments, templates_c, and downloads directories. The path must be an absolute path (i.e. /home/whmcsuser/tmp instead of ~/tmp) and must be writable by the admin that is running PHP.

=== Setting a Maintenance Message ===

Admins can use this option to set a message that will be displayed to users in the client area whenever an update is in progress, as the client and admin areas will be unavailable during an update.

[[File:EmptyConfigureUpdateSettings.png|center]]

== Performing an Update ==

=== Beginning the Update Process ===

Once the update configuration options have been set, admins can begin the update process. Before the update process begins, WHMCS strongly recommends that admins backup their current installation and database. WHMCS also recommends that at least 250 MB of disk space is available before beginning the update process. Once comfortable with the available disk space and backups have been made to the current installation and database, the admin can start the update by clicking the Continue button.

[[File:UpdateNowFirstStep.png|center]]

=== Checking for Custom Files ===
The next step in the upgrade process checks the current installation for customized files, such as template files, language translations, whois server entries, and additional domain fields. It's important to review these files, as just like in previous updates, any update applied to the installation of WHMCS will override any custom changes. Before continuing to the next step in the upgrade process, it is wise to backup any customized files in order to quickly apply them again after the update has been complete. WHMCS has also included changes to how admins can customize the additional domain fields, country / calling codes, and whois server entries so that admins can preserve changes between updates. To view this documentation, please refer to following documentation pages:

*[http://docs.whmcs.com/Customising_Countries_and_Calling_Codes/ Customized Countries and Calling Codes]
*[http://docs.whmcs.com/WHOIS_Servers/ WHOIS Servers]
*[http://docs.whmcs.com/Additional_Domain_Fields/ Additional Domain Fields]

[[File:UpdateNowSecondStep.png|center]]

=== Starting the Update ===

Once an admin is comfortable with the status of their custom files, the next step in the update process is to start the update itself. It's important to note that this third step is the point of no return - one the update has started, there is no pausing or stopping the process, and it is strongly recommended that admins stay on this page and do not navigate away using their browser. When ready to begin, click the Update Now button.

[[File:UpdateNowThirdStep.png|center]]

=== Finalizing the Update ===

The final step of the update process is confirmation that the update has been completed. The system will present the admin with an Update Completed message, along with a link to the current version's release notes.

[[File:UpdateFinished.png|center]]

WHMCS Documentation - User contributions [en]

Smarty Security Policy

Automatic Updater