Quick Start LiteSpeed Web Server with cPanel

Quick Start Guide

This comprehensive guide details the process of replacing Apache and transforming a standard cPanel shared-hosting server into an optimized, high-performance environment powered by cPanel and LiteSpeed Web Server.

Video Demonstration

For a visual walkthrough, watch our video demonstration on How to Install LiteSpeed Web Server on a cPanel Server here.

Prepare for Installation

Before proceeding with the LiteSpeed Web Server installation, it is crucial to complete several preparatory steps to ensure a smooth and successful transition. Adhering to these guidelines will help prevent common issues and ensure optimal performance.

Obtain a License

To begin, visit the LiteSpeed store to acquire the appropriate license for your server. LiteSpeed offers flexible licensing options tailored to various needs.

• A Free Starter License is available for users planning to host a single domain on a physical server with less than 2GB of RAM.
• Other commercial licenses can also be purchased directly from the same store link.
• If your server has more than 2GB of RAM and hosts multiple domains, and you require a trial license, you can learn more about trial options here.

For assistance in selecting the most suitable license for your requirements, please consult our detailed licensing documentation.

Verify Root Access

The installation of LiteSpeed Web Server necessitates full root access to your server. Before proceeding, ensure that you have the necessary permissions for SSH and sudo commands.

Disable Apache mod_ruid2

The mod_ruid2 Apache module, which alters HTTP request permissions to match the domain owner, is incompatible with LiteSpeed Web Server. LiteSpeed does not permit changes to the process user mid-operation. Therefore, it is essential to disable mod_ruid2 in your WHM settings before initiating the switch to LiteSpeed. While LSWS is compatible with Apache's prefork and event Multi-Processing Modules (MPM), enabling mod_ruid2 can disrupt functionality, as WHM may create files inaccessible to the web server user.

Remove Existing Apache Replacements or Proxies

Prior to installing LiteSpeed Web Server, you must remove any existing Apache replacements, such as nginx, or reverse proxies like nginx over Apache or nginx/Varnish configurations. These conflicting installations can interfere with LiteSpeed's proper functioning.

Ensure Existing Sites are Operational

It is critical to confirm that all websites currently hosted on your cPanel/WHM installation are functioning correctly under Apache before proceeding with the LiteSpeed installation. If you are setting up a new server, consider adding a temporary test domain to verify functionality, which can be removed later.

Open Firewall Ports

LiteSpeed Web Server utilizes specific ports for its operation, including TCP 80 and TCP 443 for standard web traffic. Additionally, UDP 443 is used for QUIC, a highly valued feature of LiteSpeed that significantly enhances performance. Ensure that TCP 80, 443, and UDP 443 are open within your Firewall Configuration. Furthermore, TCP 7080 is required for the LiteSpeed WebAdmin Console, which is secured with a username and password (configured during installation). For security purposes, this port should ideally be restricted to Administrative IPs only.

Installation

The installation of LiteSpeed Web Server can be performed using one of two methods: a detailed, interactive process or a quick, automated approach.

The Detailed Installation method is highly recommended for first-time users, as it provides a comprehensive explanation for each configuration option. For those already familiar with LiteSpeed, the Quick/Automated Installation offers a streamlined and efficient setup experience.

Detailed Installation

Installing LiteSpeed is a straightforward process. Begin by logging into your server via SSH and executing the following command. Remember to replace your_serial_no with your specific LiteSpeed License Key:

bash <( curl https://get.litespeed.sh ) your_serial_no

This intelligent script automatically detects your server's environment, downloads only the necessary dependencies, and retrieves installation data directly from our servers. Depending on your specific setup, the script may prompt you for input on various configuration questions before completing the LiteSpeed Web Server installation.

bash <( curl https://get.litespeed.sh ) TRIAL

Once the script is initiated, it will recognize your cPanel/WHM installation and present a series of prompts for your input:

Installer Prompts and Configuration Options

Could not find an lsws.options file

Could not find an lsws.options file. We will ask you for your preferred settings instead, but for automated bulk provisioning, you may want to exit and create an lsws.options file. Continue Installer(Y/N) ?

This message is expected during a detailed installation, as the lsws.options file is primarily used for quick and automated installations. To proceed with the interactive setup, simply press Y and then Enter.

Enable PHP_SUEXEC

Enable PHP_SUEXEC. Run PHP processes as the account owner. Available values: 0 (off), 1 (on), and 2 (user home directory only).

This crucial option determines how PHP processes will operate on your server. For shared hosting environments, a value of 2 (user home directory only) is strongly recommended and is set as the default.

Apache port offset

Apache port offset. Run LiteSpeed in parallel with Apache. For example, if set to 1000, Apache will listen on port 80, and LiteSpeed on 1080. If set to 0, Apache and LiteSpeed will use the same port, and LiteSpeed will not automatically start after installation.

This setting configures the port to which LiteSpeed Web Server will bind upon installation. Initially, it is advisable to set the port offset to a value other than 0 (such as the default 1000). This configuration allows LiteSpeed and Apache to run simultaneously, providing an opportunity to thoroughly test LiteSpeed's compatibility and functionality on your server without disrupting live services.

Once you are confident that your websites are operating correctly with LiteSpeed, you can later change the port offset to 0. Choosing 0 at this stage will cause LiteSpeed to start immediately after installation and Apache to stop. This particular choice also necessitates enabling the "Switch to LiteSpeed Automatically" option, which will be discussed further below.

Admin username

Admin username. For accessing LiteSpeed WebAdmin console.

This option defines the username required to access the LiteSpeed WebAdmin Console, an essential interface for monitoring LiteSpeed statistics and managing its behavior post-installation. It is highly recommended to choose a secure and unique username. The default value is admin.

Admin email address

Admin email address. Receive important server notices, such as license expiration and server core dumps.

This setting specifies the email address where you will receive critical notifications, warnings, and error reports from the LiteSpeed Web Server. It is advisable to use an email address that you regularly monitor to stay informed about your server's status. The default value is root@localhost.

EasyApache integration

EasyApache integration. Automatically rebuild matching PHP for LiteSpeed under EasyApache 3. Does nothing under EasyApache 4. Available values are 1 (enable) and 0 (disable).

This option instructs the installer to build a compatible PHP environment for LiteSpeed. Its functionality is primarily relevant if you are still operating with EasyApache 3, which has reached its end-of-life. This value has no operational effect on EasyApache 4. The default value is 1.

Switch to LiteSpeed Web Server Automatically

Automatically switch to LiteSpeed at the end of installation. This setting will only take effect if port_offset is set to `0`. Most users will need to test and verify before they switch, so the default is to not automatically switch. Available values are `1` (enable) and `0` (disable).

This critical option determines whether the installer should automatically shut down Apache and transition to LiteSpeed Web Server immediately after the installation concludes. If you previously configured the Apache Port Offset to 0, then you should set this option to 1 to enable an immediate switch. For most users, it is recommended to test and verify LiteSpeed functionality before making a full switch; thus, the default value is 0.

Deploy LSCWP Automatically

Automatically scan for any WordPress installations and install + enable the LSCache plugin for WordPress on all found installations. If not already set, the server and virtual host cache root will also be set automatically. This option is disabled by default. Available values are 1 (enable) and 0 (disable).

This setting manages the automatic deployment of LiteSpeed Cache both at the server level and across all WordPress websites hosted on the server. If enabled, it will automatically configure default cache roots for the server and individual virtual hosts. Post-installation, it will scan for all WordPress installations and install the LiteSpeed Cache Plugin on them.

Install User-end cPanel Plugin Automatically

Automatically install the LiteSpeed Web Cache Manager user-end plugin for all cPanel users. This plugin will appear as "LiteSpeed Web Cache Manager" under the 'Advanced' section of a user's cPanel dashboard. This option is enabled by default. Available values are `1` (enable) and `0` (disable).

This value governs the automatic installation of the user-facing cPanel plugin for your server. When enabled, the LiteSpeed user-end cPanel plugin, along with its integrated features, will be readily accessible via each cPanel user's dashboard, enhancing user control over caching settings. This option is enabled by default.

After you have provided input for all the necessary values, the script will proceed to install LiteSpeed Web Server on your cPanel/WHM server.

Upon successful completion of the installation, a success message will be displayed, along with a randomly generated password. It is imperative to securely save this password, as it will be required for accessing the LiteSpeed WebAdmin Console. You will have the option to change this password at a later time.

Should you encounter any difficulties or problems during the installation process, please do not hesitate to create a support ticket with us. Our team will be happy to assist you.

Quick/Automated Installation

This method is designed to streamline and automate the installation and deployment of LiteSpeed Web Server on cPanel/WHM servers, providing the fastest possible setup.

While manually running the installer script is sufficient for most scenarios, the process can be fully automated for bulk provisioning. To achieve this, you can create an lsws.options file and host it on your organization's internal repository. This allows the installer to retrieve all necessary configuration options directly from the file, bypassing the need for manual user input.

A typical lsws.options file structure appears as follows:

php_suexec="2" port_offset="1000" admin_user="admin" admin_pass="a1234567" admin_email="root@localhost" easyapache_integration="1" auto_switch_to_lsws="0" deploy_lscwp="0" cpanel_plugin_autoinstall="1"

The admin_pass parameter sets the password for accessing your LiteSpeed WebAdmin Console. Ensure this is set to a secure value for internal use only.

If you are unfamiliar with the meaning of these options, it is strongly advised to review the detailed installation process once before attempting an automated setup.

To implement this, you can create your lsws.options file and store it on your local network for bulk provisioning, accessible via a URL such as yourlink.com/yourinternalrepo/lsws.options. Then, execute the following command:

curl -o lsws.options yourlink.com/yourinternalrepo/lsws.options && bash <( curl https://get.litespeed.sh ) your_serial_no

After Installation

Once the LiteSpeed Web Server installation is complete, it is essential to perform several post-installation checks and configurations to ensure everything is operating optimally and to fully leverage LiteSpeed's capabilities.

Verify LiteSpeed is Running

In most deployment scenarios, LiteSpeed Web Server (LSWS) is automatically configured as the default web server and initiated immediately upon installation. In such cases, there is no need to manually switch to LiteSpeed, as it should already be actively serving content.

However, if you configured the Apache Port Offset to a value other than 0, or if the Auto Switch to LSWS option was set to 0 during installation, LiteSpeed will be installed but will not be automatically started or designated as the default web server.

To confirm that LiteSpeed is actively running, navigate to WHM > Plugins > LiteSpeed Web Server. This dedicated page will clearly indicate which web server is currently in operation on your system.

Switch Between LSWS and Apache

The LiteSpeed WHM Plugin provides a convenient interface for switching between LiteSpeed Web Server and Apache. Within cPanel, access WHM > Plugins > LiteSpeed Web Server. On this page, you will see the current active web server. If Apache is running, simply click the Switch to LiteSpeed button to activate LSWS. Conversely, if LSWS is active, you can click the Switch to Apache button to revert to Apache.

Alternatively, server switching can be performed directly from the command line using the cp_switch_ws script:

• To switch to LiteSpeed:

  /usr/local/lsws/admin/misc/cp_switch_ws.sh lsws

• To switch to Apache:

  /usr/local/lsws/admin/misc/cp_switch_ws.sh apache

Set Up Cache Root and Enable LiteSpeed Cache

Beyond its excellence as a web server, one of LiteSpeed's most celebrated features is its comprehensive full-page cache, which significantly benefits popular Content Management Systems (CMS) like WordPress and Magento. While these powerful caching capabilities are included with every LiteSpeed license, you will need to manually enable LiteSpeed Cache and configure the cache root directory to fully utilize these features on your server.

To begin, within the LiteSpeed WHM Plugin, click on LSCWP Version Manager. Select your desired version (the latest version is always recommended for optimal performance and security) and then click Switch Version.

Next, navigate through the LiteSpeed Configuration options available on the main plugin page. On the subsequent screen, click Cache Root Setup. If any cache root folders are not yet configured, click Set Missing Cache Roots to establish them.

Once LiteSpeed Web Server has been successfully installed and LiteSpeed Cache configured, you are ready to activate the LSCache plugin on your server's WordPress sites. LiteSpeed offers a convenient, centralized dashboard to scan for and manage LSCache installations across all WordPress sites on the server.

From the plugin's homepage, click Manage Cache Installations. Then, click Scan to initiate a comprehensive check of your entire server for existing and valid WordPress installations.

Allow the scanning process a few minutes to complete. You may observe some error messages during the scan, typically related to invalid WordPress installations (e.g., unconfigured databases or WordPress versions older than 4.0). These messages can generally be safely disregarded, as LiteSpeed will automatically identify and skip installing the LSCache plugin on such non-valid installations.

Upon completion of the scan, click Mass Enable/Disable Cache, and then click Start to begin the activation process.

This step may also take several minutes, depending on the total number of installations identified in the preceding scan.

It is possible to encounter some "failed" messages, particularly for websites already using other WordPress caching plugins. LSCache will not be installed on these sites to avoid conflicts. In such instances, you might consider reaching out to the respective customers to inform them about the superior benefits of LiteSpeed Cache. For any other types of error messages, refer to the lsws/log/webcachemgr.log file for detailed diagnostics.

Verify LiteSpeed Web Server and LSCache are Working

With the installation and enablement processes for your server now finalized, the next crucial step is to verify that your websites are successfully operating under LiteSpeed and that LSCache is functioning correctly on your WordPress sites.

To do this, click List Accounts in WHM, then select and open any customer's website. Proceed to inspect its HTTP headers, as illustrated below:

The HTTP headers should clearly display Server as LiteSpeed. Additionally, if LiteSpeed Cache is active on the website, you should see X-LiteSpeed-Cache indicating either hit or miss. The X-LiteSpeed-Cache header will only be present on websites where LiteSpeed Cache is currently enabled. Other websites will still show Server as LiteSpeed and benefit from the web server's performance advantages, but without the additional caching layer.

HTTP headers can be inspected using various browser developer tools or extensions, or conveniently through the dedicated Check LSCache tool.

Install cPanel Front-end Plugin (Optional)

LiteSpeed also offers a user-friendly front-end cache management plugin specifically designed for cPanel users. This valuable tool empowers hosting providers to offer their clients a convenient method for managing their website's caching settings, allowing customers to control various aspects of their site's caching directly from their cPanel dashboard.

To install, simply click the Install button. Upon successful completion, a confirmation message will be displayed.

Once the cPanel plugin is installed, a Settings button will become visible on the plugin homepage, allowing you to customize its configurations to suit your preferences.

Set up WordPress Discovery and Cache Installation (Optional)

After the primary installation phase is complete, you can further enhance your WordPress management by utilizing the LiteSpeed Cache Manager tool. This powerful utility automates the process of scanning for new WordPress installations and subsequently enabling LSCache on those discovered sites. The tool is conveniently located at /usr/local/lsws/admin/misc/lscmctl.

To automate this process on a recurring basis, you can integrate the tool with your server's cron jobs. Consider using one of the following commands:

• Recommended: Scan for new installations and enable LSCache only for those recently discovered WordPress sites:

  ./lsmctl scannew -en

• Scan for new installations and enable LSCache for all known installations (not limited to only newly discovered ones):

  ./lsmctl scan -n -e

Executing this tool will generate an lscm.data file, which will be stored in the lsws/admin/lscdata directory, maintaining a record of its operations.

Frequently Asked Questions

Here are answers to some common questions you might have regarding LiteSpeed Web Server installation and operation:

What if I encounter a failure message when requesting a TRIAL license during installation?

LiteSpeed tracks all licenses based on the server's IP address. If your server has previously been assigned a trial license, it will not be able to automatically request another. However, we are able to reset trial licenses upon request for eligible servers. To request an additional trial license, please contact our support team.

What should I do if I see a timezoneDB error in my WHM Plugin?

The timezoneDB extension is crucial for optimizing your website's performance with LiteSpeed. You might encounter the following error message within your WHM LiteSpeed Plugin:

Some pre-built EasyApache PHP installations may be missing the timezoneDB extension."

To resolve this, simply click the Resolve Now button to install the necessary extensions for all matching PHP versions. In the future, if a timezoneDB extension update becomes available, you may be prompted to update. For users who prefer automated updates over manual intervention via the web GUI, a daily cron job can be configured using the following command:

0 0 * * * cd /usr/local/cpanel/whostmgr/docroot/cgi/lsws/ && ./buildtimezone.sh

What action should I take if I see "lvectl command not found" during installation?

If you encounter the message "lvectl command not found" during the installation process, there is generally no cause for concern. This message typically indicates that your cPanel/WHM installation is not running on a CloudLinux-based server. However, if your server is indeed a CloudLinux environment and you still receive this error, please create a support ticket with us, and our team will investigate the issue.

Will LiteSpeed automatically synchronize all my current and new domains?

Absolutely, yes! LiteSpeed is designed as a full-featured, drop-in replacement for Apache on cPanel servers. As such, it will seamlessly integrate with and automatically recognize all existing domains hosted on your server. Furthermore, it will automatically handle any new domains added in the future without requiring additional manual configuration.

Will LiteSpeed create matching PHP installations for all my versions?

Yes, LiteSpeed will indeed build compatible PHP environments for all currently installed PHP versions, including any new versions you add, along with their respective PHP extensions. This ensures that your Multi PHP Manager and PHP Selectors will function perfectly with LiteSpeed, maintaining full compatibility.

It is important to note that with the introduction of PHP auto-detection in LSWS 5.3.0 and later, automatically detected PHP versions will no longer explicitly appear in the WebAdmin Console's external app or script handler page. For more detailed information on this feature, please learn more here.

How can I troubleshoot errors encountered with LiteSpeed Web Server?

If you experience any errors on your websites while operating under LiteSpeed, we recommend referring to our dedicated Troubleshooting section for comprehensive guidance and solutions.

How do I change the WebAdmin Port?

Occasionally, other services, such as Bitninja, may also utilize TCP port 7080, which is the default port for the LiteSpeed WebAdmin Console. If this port is already in use, LiteSpeed may fail to start. To change the WebAdmin's port, follow these steps: Open the configuration file located at /usr/local/lsws/admin/conf/admin_config.xml using your preferred text editor. Locate the Listener value and modify it from 7080 to an alternative, available port of your choice.

Which Worker MPMs should I install on EasyApache for LiteSpeed?

LiteSpeed Web Server is fully compatible with mpm_worker or mpm_event Multi-Processing Modules (MPMs) within EasyApache. The use of any other MPMs is not recommended for optimal performance and stability with LiteSpeed.

Is the PHP-FPM setting in WHM necessary with LiteSpeed?

When running LiteSpeed Web Server on cPanel/WHM, LiteSpeed exclusively uses its highly optimized LSPHP + LSAPI to execute PHP processes, which offers superior performance compared to other PHP execution methods. Consequently, it is not possible to alter the PHP handler setting while LiteSpeed Web Server is active on cPanel/WHM, as this value is effectively ignored.

How do I change the LiteSpeed WebAdmin Console Password?

To update the password for your LiteSpeed WebAdmin Console, execute the following commands in your server's terminal:

cd /usr/local/lsws/admin/misc
./admpass.sh

How can I add the LSCache plugin to WordPress websites that were not included during the initial installation?

If some WordPress websites were bypassed during the initial mass enablement of the LSCache plugin, you have a couple of options. You can simply re-run the mass enablement step from the LiteSpeed WHM plugin to attempt to install the plugin on the remaining sites. Alternatively, you can manually install the plugin directly from the WordPress Plugin Directory through each site's WordPress Dashboard.

How do I install LiteSpeed Cache extensions on other Content Management Systems (CMS)?

LiteSpeed Cache offers robust support for a variety of other popular CMS platforms, including Joomla and Drupal. For comprehensive details on all supported CMS platforms, along with specific instructions for downloading and installing each respective LSCache extension, please visit our LiteSpeed Cache documentation.

How can I utilize LiteSpeed Cache on CMS platforms where no dedicated plugin exists?

For Content Management Systems that do not have a specific LiteSpeed Cache plugin available, you can still leverage LSCache's powerful features. Please refer to our documentation on using LSCache without a plugin for detailed instructions on manual configuration.

What happens if my LiteSpeed license domain/RAM limit is exceeded or if my license expires?

In scenarios where your LiteSpeed license becomes invalid—either due to exceeding its allocated domain or RAM limits, or if it reaches its expiration date—your system will automatically revert and switch back to Apache. This automatic failover mechanism ensures continuous web service, and has been a feature since LSWS v5.3.5.

Which LiteSpeed license should I choose for my needs?

To assist you in selecting the ideal license for your specific requirements, please consult our comprehensive licensing documentation. There's no need to be concerned if you are initially unsure about the most suitable license tier, as you have the flexibility to upgrade or downgrade your license at any point.