cPanel Plugin for LiteSpeed Web Server

Where Did This Plugin Come From?

The LiteSpeed Web Cache Manager plugin for cPanel serves as an essential companion to the LiteSpeed plugin designed for WHM. This powerful integration enables hosting providers utilizing both LiteSpeed Web Server and the LiteSpeed plugin for WHM to seamlessly install this valuable tool for their cPanel end-users, enhancing their control over website caching and optimization features.

Installation

Installing the LiteSpeed Web Cache Manager plugin for cPanel is a straightforward process, made even simpler with the LiteSpeed WHM Plugin as of version 3.1.0. This integration streamlines deployment, allowing administrators to enable the plugin with minimal effort.

Upon successful installation, the cPanel Plugin section within the WHM plugin interface will reflect the updated status, as shown below:

Plugin Not Available For cPanel Users?

If the LiteSpeed Web Cache Manager plugin does not appear for your cPanel users following installation via the LiteSpeed WHM plugin, please follow these troubleshooting steps to ensure proper access:

1. Log in to WHM and navigate to the Feature List screen by selecting Packages > Feature Manager.
2. From this manager, you can effectively control user access to various plugins by creating new feature lists or editing existing ones.
3. Create or modify the specific feature list you intend to update.
4. Locate and click the checkbox labeled LS Web Cache Manager, then press the Save button. This action will either add or remove this plugin from your current feature list, which can then be assigned to a cPanel package if it hasn't been already.

After completing these steps, the plugin should now be visible in the Advanced section of the cPanel home screen for all users assigned to the updated package.

Should the LiteSpeed Web Cache Manager item still not appear in the advanced section of your cPanel home screen, it is essential to ensure that LiteSpeed Web Server is upgraded to at least v5.1.x. Furthermore, you must possess a license with LSCache enabled to utilize these features. For information on obtaining an LSCache license, please refer to the documentation on How To Get LSCache.

Note: If you wish to install the LiteSpeed Web Cache Manager plugin but do not have WHM access, please reach out to your server administrator or hosting provider for assistance.

The LiteSpeed Redis Cache Manager is exclusively available on sandbox-capable systems, such as CloudLinux or LiteSpeed Containers. This feature set focuses solely on the Redis functionalities detailed in the Redis Management section.

Configuration

The LiteSpeed Web Cache Manager plugin for cPanel offers a range of configurable options, which can be accessed and adjusted from the Settings page located within the cPanel Plugin section of the LiteSpeed WHM plugin. This centralized management ensures easy customization for hosting providers.

The following subsections provide a detailed explanation of each available setting, guiding you through their functionalities and optimal usage.

Auto Install

The Auto Install setting dictates whether the LiteSpeed Web Cache Manager plugin for cPanel is automatically deployed when the LiteSpeed WHM plugin is either installed for the first time or undergoes an upgrade. Enabling this option ensures a seamless and automated setup process for cPanel users.

Note: This option will be automatically checked after manually installing the LiteSpeed Web Cache Manager plugin for cPanel through the LiteSpeed WHM plugin. Conversely, this option will be automatically unchecked after manually uninstalling the LiteSpeed Web Cache Manager plugin for cPanel through the LiteSpeed WHM plugin, maintaining consistency with manual actions.

Enable EC Certificate Generation

Available in LiteSpeed WHM plugin v4.1+

The Enable EC Certificate Generation setting controls the availability of the EC (Elliptic Curve) certificate generation feature within the LiteSpeed Web Cache Manager plugin for cPanel. Once an EC certificate is generated for a domain, LiteSpeed Web Server leverages it to establish SSL connections with supporting browsers. This significantly improves performance and reduces computational overhead compared to SSL connections secured with traditional RSA certificates, offering a faster and more efficient browsing experience.

• Off: When set to Off, EC certificate generation will be disabled entirely. Consequently, the related EC Certificate Management section will not be displayed within the LiteSpeed Web Cache Manager plugin for cPanel, streamlining the interface for environments where this feature is not needed.
• On: Choosing On enables EC certificate generation, making the EC Certificate Management section visible and fully functional within the LiteSpeed Web Cache Manager plugin for cPanel. This allows users to manually generate and manage EC certificates.
• On + Auto: This setting provides similar behavior to On, with the added benefit of automatically generating an EC certificate. This automatic generation occurs when the Upload SSL Cert to QUIC.cloud feature is used, particularly if an existing SSL certificate cannot be detected for the associated domain, ensuring that a secure connection is established without manual intervention.

Warning: Changing this setting to Off will result in the removal of all EC certificates that were previously generated through this feature. Exercise caution when modifying this setting to avoid unintended data loss.

Use Custom Template

The Use Custom Template setting offers hosting providers a flexible way to customize or completely replace the content displayed on the LiteSpeed Web Cache Manager plugin's landing page for all cPanel users. This is achieved by loading a custom template, eliminating the need to directly modify existing plugin files. This feature is particularly useful for advertising specialized services, promoting unique features, or recommending/upselling relevant hosting packages, allowing providers to tailor the user experience to their brand and offerings.

Preparing And Setting A Custom Template

The process of preparing and implementing a custom template for the LiteSpeed Web Cache Manager plugin for cPanel is straightforward. Begin by navigating to the directory /usr/local/cpanel/base/frontend/paper_lantern/ls_web_cache_manager/landing and create a new directory for your custom template, for instance, myCustomTemplate.

Once your template directory is established, you have two options: either copy the existing index.php file from /usr/local/cpanel/base/frontend/paper_lantern/ls_web_cache_manager/landing/default into your new directory as a starting point, or integrate your own custom version of the file. This index.php file will serve as the entry point, responsible for calling any custom code or files you require. It will display your new landing page while maintaining relative access to all the existing classes, functions, and pages already integrated into the plugin, providing a robust and flexible customization environment.

Tip: We strongly recommend backing up all custom template code in an external location to prevent potential loss during uninstallations or upgrades of the LiteSpeed Web Cache Manager plugin. Therefore, utilizing a symlink in place of these files within the actual plugin location is also a highly recommended practice.

Note: To effectively set a custom template for use, first ensure that the LiteSpeed Web Cache Manager plugin has been properly installed through the LiteSpeed WHM plugin.

With your custom template prepared, you can now enter its directory name, such as myCustomTemplate, into the Use Custom Template setting field on the cPanel Plugin Settings page and save your changes. If the specified template folder exists and contains the necessary index.php file, the save operation will be successful. From this point forward, all cPanel users accessing the LiteSpeed Web Cache Manager plugin via their cPanel dashboard will be presented with your personalized custom landing page, providing a consistent and branded user experience.

Uninstallation

The LiteSpeed Web Cache Manager Plugin for cPanel can be easily and efficiently uninstalled directly through the LiteSpeed WHM Plugin. This streamlined process ensures quick removal when no longer needed, maintaining system integrity.

Warning: Uninstalling the LiteSpeed Web Cache Manager Plugin for cPanel will also result in the removal of all user-generated EC certificates. This applies specifically when either On or On + Auto was selected for the Enable EC Certificate Generation setting on the LiteSpeed cPanel Plugin Settings page. Ensure you have backups if these certificates are critical.

Plugin Breakdown

This section provides a detailed overview of the LiteSpeed Web Cache Manager plugin's interface and functionalities, guiding users through its various components and operations.

Main Page

The Main Page serves as the initial entry point when accessing the plugin. Here, users are presented with a concise layout featuring five distinct sections, alongside convenient links to the settings and advanced operations pages, offering a comprehensive starting point for cache management.

• Why Use LSCache? - This section offers valuable information regarding LSCache and provides access to a variety of available LSCache plugins through the Available LSCache Plugins link, helping users understand the benefits and options.
• Flush LSCache - This section features a dedicated button for flushing the contents of your LSCache folder. Executing this action will efficiently clear the cache for all owned sites that have LSCache enabled, ensuring that the most recent content is served.
• LiteSpeed Cache Management - This section includes a direct link to the LiteSpeed Cache Management page for owned WordPress sites. From here, users can selectively enable and disable the LiteSpeed Cache for WordPress (LSCWP) plugin on a per-site basis, providing granular control over caching.
• EC Certificate Management - This section provides a link to the "Manage EC Certificates" page for domains associated with the user's account. On this page, EC SSL certificates can be generated or removed individually for each domain, allowing for optimized SSL connections.
• Settings - Clicking this link will redirect you to the plugin's dedicated settings page, where various configurable options can be adjusted to suit specific requirements.
• Advanced - This link provides access to the advanced operations page, offering additional functionalities and tools for more intricate management tasks.

The functionalities and interfaces of the LiteSpeed Cache Management, EC Certificate Management, Settings, and Advanced Operations pages are explored in greater detail in the subsequent sections of this documentation.

LiteSpeed Cache Management - WordPress Cache

The LiteSpeed Cache Management view is where the core caching operations for WordPress installations occur. This intuitive interface empowers users to manage LSCWP for their WordPress sites, whether individually or in groups, ensuring optimal performance and efficiency.

The table presented on this page includes the following key fields:

• Discovered WordPress Installations: This field prominently displays the file path for each WordPress installation that was identified during the most recent scan operation, providing a clear overview of all detected sites.
• Cache Status: This column indicates the last known operational status of LSCWP for each listed WordPress installation, keeping users informed about their caching setup.
• Flag: This field will either be blank or display a distinctive flag icon. When an installation is flagged (indicated by the icon), it is specifically excluded from all subsequent Mass Enable/Disable LSCWP operations performed through the WHM plugin, allowing for precise control over bulk actions.
• Actions: This field contains a set of action buttons, each designed to perform a specific operation exclusively for the corresponding WordPress installation. These actions include options to Enable/Disable LSCWP, Flag/Unflag the installation, and Upload SSL Cert to QUIC.cloud for the associated domain, providing comprehensive individual management capabilities.

At the top of the interface, a row of buttons provides global controls:

• Refresh Status: Each listed WordPress installation features an LSCWP Status reflecting its current caching state. The Refresh Status button updates this value to the most current status for all displayed WordPress installations, ensuring up-to-date information.
• Scan/Re-scan: This function actively discovers all WordPress installations located under each cPanel user's designated document root. These identified installations are then securely saved to a data file and prominently displayed on the manager screen. Should this data file become corrupted or be removed, a simple re-scan will effectively repopulate the list.
• Flush All: Similar to its counterpart on the main page, this button clears the entire contents of your LSCache folder. This action effectively flushes the cache for all owned sites where LSCache is enabled, ensuring a fresh start for cached content.

Moving to the bottom of the page, a row of buttons facilitates group operations. These buttons work in conjunction with the checkboxes located next to each discovered installation, enabling users to perform basic actions efficiently on selected groups of WordPress sites.

• Enable Selected & Disable Selected: These buttons allow you to simultaneously enable or disable LSCWP for all the WordPress installations that have been specifically selected by the user, streamlining bulk management.
• Flag Selected & Unflag Selected: These buttons provide the ability to either set or unset the flag field for the chosen WordPress installations. Flagged installations are consequently excluded from any Mass Enable/Disable LSCWP operations initiated from the WHM plugin, offering fine-grained control over which sites are affected by bulk actions.

EC Certificate Management - Manage EC Certificates

This dedicated section allows users to efficiently manage generated EC certificates for their owned domains. Operations can be performed either individually for specific domains or in groups, providing flexible control over your SSL certificate landscape.

The table displayed in this section includes the following critical fields:

• Discovered Domains: This field provides a clear listing of the domain name and file path for each domain identified during the most recent scan operation, offering a comprehensive overview.
• EC Cert Exists: This column indicates whether a generated EC certificate is currently present for the listed domain. This status is determined by the result of the last performed EC certificate action and also displays the relevant generate/remove action button if applicable, facilitating immediate certificate management.
• Domains Covered By Cert: This field clearly lists all domains currently secured by the generated EC certificate. It will remain blank if no EC certificate exists for the entry, providing quick insight into certificate coverage.
• Last Generation Message: This column displays the most recent EC certificate generation message returned for the domain, offering crucial feedback on certificate issuance attempts.

At the top of the interface, a row of buttons provides global actions for certificate management:

• Update List: This function discovers all domains associated with your account. These identified domains are then securely saved to a data file and prominently displayed on the manager screen. If this data file is removed or corrupted, simply performing another scan will efficiently repopulate the list.
• Generate All: Clicking this button will initiate an attempt to generate an EC certificate for every discovered domain listed, streamlining the process for multiple domains.
• Remove All: This action will remove all previously generated EC certificates across all domains managed within the plugin, providing a comprehensive cleanup option.

Below the main table, a row of buttons facilitates group operations. These buttons function in conjunction with the checkboxes adjacent to each discovered domain, enabling users to perform basic actions efficiently on selected groups of domains.

• Generate Selected & Remove Selected: These buttons empower you to either generate new EC certificates or remove existing ones for the domains that have been specifically selected, offering precise control over certificate management for multiple entries.

Settings

The Settings page provides a centralized location for controlling various plugin-related configurations, ensuring that the LiteSpeed Web Cache Manager operates according to your specific requirements. Currently, one key setting is available.

• Log File Level: This crucial setting governs the highest severity level of log messages that will be recorded in the log file, which is conveniently located at /home/$user/lscmData/ls_webcachemgr.log. The default value for this setting is INFO, capturing a broad range of informational messages and warnings, aiding in debugging and monitoring plugin activity.

Advanced

The Advanced Operations page offers a specialized set of tools for performing various intricate plugin operations, catering to more advanced system management needs. Currently, one significant operation is available.

• Restart Detached PHP Processes: This function is designed to instruct the LiteSpeed Web Server to restart all detached PHP processes associated with the current user. This restart will occur the next time the server invokes that specific PHP handler, ensuring that any changes or updates to PHP configurations take immediate effect.

Redis Management

For users operating on sandbox-capable systems, such as CloudLinux or LiteSpeed Containers, the LiteSpeed Redis Cache Manager is available within the cPanel Advanced group. This powerful tool provides the functionality to enable or disable the Redis service with ease, offering critical control over your caching infrastructure.

If the Redis service has been properly set up or a default configuration is in place, you will be presented with the option to Enable Redis Service. Selecting this option will initiate the creation and subsequent startup of the Redis service, integrating it into your system.

Conversely, if the Redis service is already active, you will find the option to Disable Redis Service. Activating this will gracefully stop and disable the service. It is important to note that both enabling and disabling options take effect only after user confirmation, preventing accidental changes.

The Flush Cache button is available for clearing the Redis Cache. This action is typically performed after a significant software or data upgrade to invalidate all existing cache information, prompting the system to repopulate the cache with the most current data and ensuring optimal performance.

Translations

As of the cPanel user-end plugin version 1.2.2, a dedicated lang/ directory has been incorporated. This significant addition facilitates the implementation of custom translations for all plugin text, aligning the plugin's language with the cPanel dashboard locale selected by the user, thereby enhancing the user experience for a global audience.

The lang/ directory also serves as the repository for any translations officially submitted to LiteSpeed for inclusion in the plugin package. It is important to be aware that these official translations will be superseded if any custom translations for that specific locale exist within the lang/cust/ directory, allowing for prioritized local customization.

Comprehensive instructions for translating the plugin are detailed within the README file located in the plugin's lang/cust/ directory. For your convenience, the contents of this README file are provided below:

Welcome to the LiteSpeed Web Cache Manager user-end cPanel plugin's lang/cust directory. This directory is designated for any custom translations you wish to utilize with the LiteSpeed Web Cache Manager user-end cPanel plugin. This file will now guide you through the process of providing your own custom translations for this plugin, based on the language selected in a user's cPanel dashboard.

1. Choose a cPanel locale for which you intend to provide translations. A complete list of available locales can be found within WHM by navigating to Home >> Locales >> View Available Locales.
2. Once a locale has been selected, create a directory under this plugin's lang/cust directory, using the exact name of the locale (e.g., fr for French). Subsequently, create an en_US directory within that locale directory, and an LC_MESSAGES directory within the en_US directory.

   Using French as an illustrative example (cPanel locale fr), your directory structure should resemble the following:

   lang/
   -cust/
   --fr/
   ---en_US/
   ----LC_MESSAGES/

   Note: The en_US directory is included as a workaround for Linux systems that might not contain certain locales, as it is commonly installed on most systems. If you encounter issues with your translations appearing, please verify that the en_US.utf8 locale is installed on your system.

   Note: As long as the lang/cust/fr directory exists, this directory will always be prioritized when the plugin searches for translation files, regardless of whether any translation files actually exist within it. If you wish to revert to using the official translation directory located under lang, you must either remove or rename the custom locale directory within cust.

3. Generate a messages.po file for your desired language. You can either create this file based on the messages.pot file provided in the lang directory, or copy the existing messages.po file for your locale if it has already been officially provided within the lang directory.
4. Update the newly generated messages.po file with all your new translations. Additionally, you should ensure that the messages.po file header information is updated if you have not already done so.
5. Generate a messages.mo file based on your updated messages.po file. Place both the messages.po and messages.mo files within the custom LC_MESSAGES directory you created earlier.
6. Finally, visit the LiteSpeed user-end cPanel plugin through a cPanel dashboard and confirm that your custom translations are appearing correctly.

Caution: Any custom translation files will be lost upon uninstalling the LiteSpeed Web Cache Manager user-end cPanel plugin. It is highly recommended to keep a separate copy of all custom translation files in an alternative location to prevent their permanent loss.

These steps outline all that is required to begin implementing custom translations with the LiteSpeed user-end cPanel plugin. If you are interested in having your custom translations included as official translations in future versions of the LiteSpeed Web Cache Manager user-end cPanel plugin, or if you have updates for existing official translations, please send an email containing the locale, along with both the messages.po and messages.mo files, to [email protected].