System Environment Guide
(Redirected from Database Setup)
WHMCS is compatible with most web server environments. Installing WHMCS in your web environment is usually straight forward. As well, WHMCS is continually providing updates which can seamlessly support environment updates from the upstream providers. However, as new technologies emerge and your current system's environment has access to new updates, it's important that you are aware of how they might affect your WHMCS deployment. This guide is designed help you and your system administrator prepare and manage your environment.
Overview
WHMCS is designed for a traditional LAMP (Linux, Apache, MySQL, PHP) environment. The minimum requirements and basic version compatibility related to those sub-systems are provided in our System Requirements.
The development of WHMCS is such that alternative technologies may be viable, however they are not tested and assistance from our Support Team will be limited. For example, if you wish to use NGINX instead of Apache, it may be technically possible. However, our Support will have limited knowledge about how to properly configure NGINX or debug behaviors that are specific to NGINX.
If you require the use of something other than Linux, Apache, or MySQL please consult with your system administrator to evaluate the immediate possibilities for (in)compatibility and long-term viability so that your environment management strategy accommodates for your specific requirements.
Operating System
WHMCS is designed to run in a standard Linux operating/file system. WHMCS relies on PHP for interaction with the file system. In some operating systems (such as Windows) or environments (such as jails or chroots) the file system may have restrictions or inherent behaviors which may be hard to detect or uncommon. When possible, WHMCS provides notices that indicates incompatibility. If you require a different operating/file system, please discuss with your system administrator. Our Support Team is available to provide limited assistance to your system administrator for your custom environment.
Also of note, WHMCS relies heavily on the Linux Cron sub-system to trigger background tasks and perform periodic automation tasks such as deferred provisioning, service synchronization, invoice generation, billing, and more. You may learn more at the crons documentation.
Web Server
WHMCS is designed to work with the Apache web server version 2.x. While there are no special Apache configurations required for WHMCS, there are some advantages available to you and your WHMCS deployment that you may wish to consider.
Extensions
- mod_rewrite
- The Apache mod_rewrite module allows Apache to inspect and modify URLs and redirects through the use of .htaccess files within your web server docroot. WHMCS can create and manage a .htaccess file, and thus generate and consume friendly URLs in various parts of the product. This feature is described in more detail at Friendly URLs.
Handler
The web server is responsible for all web applications on the server, and thus the Unix permissions granted to the php process (php handler) that operate with your web application are important. Some PHP handlers will execute all php code on the system as the same Unix user (server wide handlers like CGI & mod_php) while other handlers execute the PHP process as a specific user based on domain name (per vhost handlers like suphp, mod_ruid2). Both options are viable for WHMCS. However, as a matter of security, you need to ensure that no other applications on the server, outside your control, executes as the same Unix user. Your system administrator should be able to configure the web server so that this minimum level of security is met, or more conservatively, that the WHMCS web application process is executed by a user that is wholly unique amongst any other application on the server (even those within your control).
Directives
WHMCS uses configuration directives to alter the web server configuration on a per-directory basis. As Apache is the recommended web server software platform to run WHMCS on, these directives are included via the following .htaccess files.
- ~/.htaccess
- This file contains the mod_rewrite directives responsible for sending routable paths through the index.php file. This in turn allows the internal routing system to function, and furnishes WHMCS with the ability to create consumer friendly URLs. More information can be found on the Friendly URLs documentation page.
- ~/vendor/.htaccess
- This file prevents access to the ~/vendor directory. This ensures that the web server is not serving file requests directly from this location, and that WHMCS is still capable of accessing the libraries it needs to function. More information can be found on the Further Security Steps documentation page.
While other web server technologies are not officially supported, we understand that some users do wish to run WHMCS in environments other than Apache. For those that do, you must ensure that the functionality offered by the aforementioned directives has been implemented by your web server configuration.
How this is achieved depends on the web server itself. If uncertain, then you should consult with your server administrator. As an example, you can find a guide detailing how to secure the vendor directory on the NGINX web server on the Nginx Directory Access Restriction documentation page.
Database
WHMCS is designed to work with the MySQL database. Binary compatible alternatives (such as MariaDB) should be suitable, however their default configurations and optimizations are likely to be different and you should consult with your system administrator or database administrator.
Version Compatibility
| WHMCS Version (Status) | MySQL v5.2 | MySQL v5.3 | MySQL v5.4 | MySQL v5.5 | MySQL v5.6 | MySQL v5.7 | MySQL v8.0 |
|---|---|---|---|---|---|---|---|
| v6.3 (EOL) | Y | Y | Y | Y | Y | N | N |
| v7.0 (EOL) | Y | Y | Y | Y | Y | N | N |
| v7.1 (EOL) | Y | Y | Y | Y | Y | N | N |
| v7.2 (EOL) | Y | Y | Y | Y | Y | N | N |
| v7.3 (EOL) | Y | Y | Y | Y | Y | Y | N |
| v7.4 (EOL) | Y | Y | Y | Y | Y | Y | N |
| v7.5 (EOL) | Y | Y | Y | Y | Y | Y | N |
| v7.6 (EOL) | Y | Y | Y | Y | Y | Y | N |
| v7.7 (EOL) | Y | Y | Y | Y | Y | Y | Y |
| v7.8 (EOL) | Y | Y | Y | Y | Y | Y | Y |
| v7.9 (EOL) | Y | Y | Y | Y | Y | Y | Y |
| v7.10 (EOL) | Y | Y | Y | Y | Y | Y | Y |
| v8.0 (EOL) | Y | Y | Y | Y | Y | Y | Y |
| v8.1 (EOL) | Y | Y | Y | Y | Y | Y | Y |
| v8.2 (EOL) | Y | Y | Y | Y | Y | Y | Y |
| v8.3 (EOL) | Y | Y | Y | Y | Y | Y | Y |
| v8.4 (EOL) | Y | Y | Y | Y | Y | Y | Y |
| v8.5 (EOL) | Y | Y | Y | Y | Y | Y | Y |
| v8.6 (EOL) | Y | Y | Y | Y | Y | Y | Y |
| v8.7 (EOL) | Y | Y | Y | Y | Y | Y | Y |
| v8.8 (LTS) | Y | Y | Y | Y | Y | Y | Y |
| v8.9 (Active) | Y | Y | Y | Y | Y | Y | Y |
| v8.10 (RC) | Y | Y | Y | Y | Y | Y | Y |
Database Privileges
When installing or updating WHMCS, activating or deactivating modules, or resetting the Module Log entries at Configuration () > System Logs, you must grant the following privileges:
- ALTER
- CREATE
- DROP
- INDEX
For day to day use, only the following database privileges are required. All others may be disabled.
- DELETE
- INSERT
- SELECT
- UPDATE
- LOCK TABLES
If you choose to restrict the privileges for day to day use, don't forget to grant the former privileges so database schema changes and optimizations can be performed by the update process.
Database Interaction
WHMCS internals utilize the PDO database API. If the PHP environment is v5.6, both a PDO based connection and a MySQL handle will be used for compatibility with legacy code.
If you are developing code for the WHMCS platform, it is recommended that you interact with the database via the Local API, DBAL & ORM, or Models. All three methods will abstract database connection details and system compatibility for you and will be supported by WHMCS for the foreseeable future. The SQL Helper Functions are still present, although deprecated. Due to their ubiquitous usage, we anticipate supporting them as long as possible but recommend that you use one of the other methods above. You can learn more at Interacting with the Database on our developer's site.
Encrypted Database Connections
Support for encrypted MySQL connections uses the following configuration variables in the configuration.php file:
- db_tls_ca — The path to the CA .pem file (for example, /var/www/html/whmcs/ca.pem).
- db_tls_ca_path — The path to the directory that contains the CA certificate files.
- db_tls_cert — The path to the client's certificate.
- db_tls_cipher — A list of one or more ciphers to use for SSL encryption, in an OpenSSL-compatible format.
- db_tls_key — The path to the client's key.
- db_tls_verify_cert — Disable (0) or enable (1) the server certificate.
You can configure these variables before, during, or after installation using the command-line installation method or after installation using the browser-based installation method. For steps, see Enabling Encrypted MySQL Connections.
If you set db_tls_verify_cert to 1 (enabled), the db_host value in the configuration.php file must match the Common Name (CN) or be a Subject Alternative Name (SAN) of the certificate that you specify for db_tls_cert.
If the hostname does not match and db_tls_verify_cert is enabled, you will see a Could not connect to database error. To resolve this issue, set db_tls_verify_cert to 0 or provide a new certificate with a CN or SAN that matches the db_host value.
- For more information about the required MySQL configuration and variables, see Using Encrypted Connections and Server State Variables.
- For steps to configure encrypted MySQL connections on cPanel & WHM servers, see cPanel's How to Configure MySQL SSL Connections Documentation.
PHP
WHMCS is written in PHP. Your environment's PHP will need to be a version supported by the version of WHMCS you are using. In general, this will be one of the PHP versions that is either under active development or is receiving security fixes from the upstream PHP maintainers.
Whenever possible, it is usually preferable to utilize a version of PHP that is under active development. Unfortunately, there can be a number of circumstances that may complicate the viability of using the latest stable release of PHP. These can range from a lack of control panel build support to incompatibility for other web applications on your server to backwards breaking behavior in PHP that inhibit ionCube Loader® support. Regardless, WHMCS always provides support for a security-monitored PHP version available from the PHP maintainers and we are continually prioritizing compatibility with their releases.
Version Compatibility
| WHMCS Version (Status) | PHP v5.2 | PHP v5.3 | PHP v5.4 | PHP v5.6 | PHP v7.0 | PHP v7.1 | PHP v7.2 | PHP v7.3 | PHP v7.4 | PHP v8.1 |
|---|---|---|---|---|---|---|---|---|---|---|
| v6.3 (EOL) | Y | Y | Y | Y | N | N | N | N | N | N |
| v7.0 (EOL) | N | N | N | Y | Y | N | N | N | N | N |
| v7.1 (EOL) | N | N | N | Y | Y | N | N | N | N | N |
| v7.2 (EOL) | N | N | N | Y | Y | N | N | N | N | N |
| v7.3 (EOL) | N | N | N | Y | Y | N | N | N | N | N |
| v7.4 (EOL) | N | N | N | Y | Y | N | N | N | N | N |
| v7.5 (EOL) | N | N | N | Y | Y | Y | Y | N | N | N |
| v7.6 (EOL) | N | N | N | Y | Y | Y | Y | Y | N | N |
| v7.7 (EOL) | N | N | N | Y | Y | Y | Y | Y | N | N |
| v7.8 (EOL) | N | N | N | Y | Y | Y | Y | Y | N | N |
| v7.9 (EOL) | N | N | N | Y | Y | Y | Y | Y | N | N |
| v7.10 (EOL) | N | N | N | Y | Y | Y | Y | Y | N | N |
| v8.0 (EOL) | N | N | N | N | N | N | Y | Y | Y | N |
| v8.1 (EOL) | N | N | N | N | N | N | Y | Y | Y | N |
| v8.2 (EOL) | N | N | N | N | N | N | Y | Y | Y | N |
| v8.3 (EOL) | N | N | N | N | N | N | Y | Y | Y | N |
| v8.4 (EOL) | N | N | N | N | N | N | Y | Y | Y | N |
| v8.5 (EOL) | N | N | N | N | N | N | Y | Y | Y | N |
| v8.6 (EOL) | N | N | N | N | N | N | Y | Y | Y | Y |
| v8.7 (EOL) | N | N | N | N | N | N | Y | Y | Y | Y |
| v8.8 (LTS) | N | N | N | N | N | N | Y | Y | Y | Y |
| v8.9 (Active) | N | N | N | N | N | N | Y | Y | Y | Y |
| v8.10 (RC) | N | N | N | N | N | N | Y | Y | Y | Y |
Extensions
WHMCS requires most of the default compiled extensions (for example, PDO, mysqlnd, JSON, libxml, DOM, or Fileinfo). We assume that you will not intentionally disable them in the environment.
You must also compile and enable the following additional extensions:
Required
- cURL with SSL Support
- cURL is used when interacting with APIs of external systems such as the WHMCS Licensing & Update servers, payment gateways, servers that host your products, etc. cURL's SSL support must be enabled so that verified and encrypted communication is possible.
- GD2
- GD2 Image Library is used when performing graphic manipulation, such as image thumbnails and PDFs.
- IMAP**
- **IMAP is only required if you are utilizing support departments which access mailboxes.
- ionCube Loader
- See the ionCube Loader section below for more detail.
- JSON
- JSON exchanges data in the UI (for example, displaying success messages after completing an action like changing a password on a service).
- MYSQL**
- ** The original MySQL extension is required if, and only if, your environment uses PHP v5.6.
- PDO_MYSQL
- While the basic PDO API extension is compiled by default in PHP, you must also have the PDO MySQL driver enabled so that PDO can communicate with your MySQL database server.
- Reflection
- Reflection adds the ability to examine and identify classes, interfaces, functions, methods, and extensions within your application. As part of this, the extension can check also for and retrieve documented comments within the same classes, interfaces, functions, and methods.
- SOAP**
- **SOAP is only required by some specific, but possibly important, modules. It is used when interacting with their corresponding external services, such as EU VAT, OpenSRS, eWay Tokens, etc.
- XML
- WHMCS uses the SimpleXML extension that PHP compiles by default. It is highly used for communication with remote systems, such as registrars, payment gateways, and servers.
Recommended
- BC Math
- The functions provided by BC Math are used when available. They provide performance improvements for when generating cryptographic data.
- Fileinfo
- The functions provided by Fileinfo are used when available. They provide functionalities to aid in determining the content type and encoding of uploaded files.
- GMP
- The functions provided by GMP are used when available. They provide significant performance improvements for when generating cryptographic data.
- iconv
- The iconv extension is for character set conversion, i.e. managing different non-latin characters. If available, this extension provides significant performance improvements and is highly recommended.
- Intl
- Intl performs character inspection and transformation, such as in IDN to perform Punycode conversions and transliterations. While we provide a third party dependency to compensate for the absence of Intl, it is much more performant to have the actual extension in the environment.
- mbstring
- The mbstring extension is for multi-byte character support, i.e managing non-Latin characters and glyphs. If available, this extension provides significant performance, allows for broader support of characters and glyphs common throughout digital communications, and is highly recommended.
- OpenSSL
- OpenSSL is for secure communications and random number generation. If available, this extension will be used and provide significant performance improvements for cryptographic routines.
PHP INI Settings
- allow_url_fopen
- allow_url_fopen must be enabled for the WHMCS Updater.
ionCube
ionCube is a set of encoding and decoding tools that provide obfuscation and performance for PHP software. The decoder tool is a "loader" in the server environment. The encoder tool, an "encoder," is part of PHP developers' publication processes.
WHMCS is encoded with ionCube and requires that you install and enable the ionCube Loader extension in your server environment. We recommend running the latest version of the ionCube Loader for your PHP version. Our ionCube Installation Tutorial provides an overview for installing this extension in your environment.
Usually, ionCube will publish a complementing loader several weeks following a new PHP version.
Using this latest loader will afford you two benefits:
- You have the potential for running previously-encoded files using a new base PHP version and running unencoded (raw) PHP code that is compatible with the base PHP version.
- You can run newly-encoded files from a new ionCube Encoder (if one was published).
The ionCube Encoder requires the developer to itemize the PHP versions to support. This helps to mitigate the limitations for supporting certain PHP versions concurrently: it is common for PHP applications to not support the latest PHP version on the initial PHP release date. Applications may also have further requirements about the oldest supported PHP version and the required loader.
Each WHMCS version has always supported at least two PHP versions. Each new version of WHMCS has always supported at least one of the PHP versions supported in the previous WHMCS publication. This perpetual overlap of PHP version support across WHMCS publications means that you always have a path to upgrade your PHP environment without having to update the WHMCS software at the same time. As well, it allows the WHMCS Updater to safely automate updates for your current environment. Providing this overlap is integral to enabling your environment maintenance strategy, giving you the best balance of security, stability and forward compatibility as soon as possible.
Version Compatibility
| WHMCS Version (Status) | PHP v5.2 | PHP v5.3 | PHP v5.4 | PHP v5.6 | PHP v7.0 | PHP v7.1 | PHP v7.2 | PHP v7.3 | PHP v7.4 | PHP v8.1 |
|---|---|---|---|---|---|---|---|---|---|---|
| v6.3 (EOL) | 4.6.1 | 4.6.1 | 4.6.1 | 4.6.1 | -- | -- | -- | -- | -- | -- |
| v7.0 (EOL) | -- | -- | -- | 5.0.21 | 6.0.2 | -- | -- | -- | -- | -- |
| v7.1 (EOL) | -- | -- | -- | 5.0.21 | 6.0.2 | -- | -- | -- | -- | -- |
| v7.2 (EOL) | -- | -- | -- | 5.0.21 | 6.0.2 | -- | -- | -- | -- | -- |
| v7.3 (EOL) | -- | -- | -- | 5.0.21 | 6.0.2 | -- | -- | -- | -- | -- |
| v7.4 (EOL) | -- | -- | -- | 5.0.21 | 6.0.2 | -- | -- | -- | -- | -- |
| v7.5 (EOL) | -- | -- | -- | 10.1.0 | 10.1.0 | 10.1.0 | 10.2.0 | -- | -- | -- |
| v7.6 (EOL) | -- | -- | -- | 10.1.0 | 10.1.0 | 10.1.0 | 10.2.0 | 10.3.1 | -- | -- |
| v7.7 (EOL) | -- | -- | -- | 10.1.0 | 10.1.0 | 10.1.0 | 10.2.0 | 10.3.1 | -- | -- |
| v7.8 (EOL) | -- | -- | -- | 10.1.0 | 10.1.0 | 10.1.0 | 10.2.0 | 10.3.1 | -- | -- |
| v7.9 (EOL) | -- | -- | -- | 10.1.0 | 10.1.0 | 10.1.0 | 10.2.0 | 10.3.1 | -- | -- |
| v7.10 (EOL) | -- | -- | -- | 10.1.0 | 10.1.0 | 10.1.0 | 10.2.0 | 10.3.1 | -- | -- |
| v8.0 (EOL) | -- | -- | -- | -- | -- | -- | 10.2.0 | 10.3.1 | 10.4.3 | -- |
| v8.1 (EOL) | -- | -- | -- | -- | -- | -- | 10.2.0 | 10.3.1 | 10.4.3 | -- |
| v8.2 (EOL) | -- | -- | -- | -- | -- | -- | 10.2.0 | 10.3.1 | 10.4.3 | -- |
| v8.3 (EOL) | -- | -- | -- | -- | -- | -- | 10.2.0 | 10.3.1 | 10.4.3 | -- |
| v8.4 (EOL) | -- | -- | -- | -- | -- | -- | 10.2.0 | 10.3.1 | 10.4.3 | -- |
| v8.5 (EOL) | -- | -- | -- | -- | -- | -- | 10.2.0 | 10.3.1 | 10.4.3 | -- |
| v8.6 (EOL) | -- | -- | -- | -- | -- | -- | 10.2.0 | 10.3.1 | 10.4.3 | 12.0.1 |
| v8.7 (EOL) | -- | -- | -- | -- | -- | -- | 10.2.0 | 10.3.1 | 10.4.3 | 12.0.1 |
| v8.8 (LTS) | -- | -- | -- | -- | -- | -- | 10.2.0 | 10.3.1 | 10.4.3 | 12.0.1 |
| v8.9 (Active) | -- | -- | -- | -- | -- | -- | 10.2.0 | 10.3.1 | 10.4.3 | 12.0.1 |
| v8.10 (RC) | -- | -- | -- | -- | -- | -- | 10.2.0 | 10.3.1 | 10.4.3 | 12.0.1 |