# CloudLinux WHMCS Plugin

The CloudLinux WHMCS Plugin provisions and manages CloudLinux, KernelCare, and Imunify360 licenses through CLN. A license can be sold as a standalone WHMCS product, as an optional product addon, or as a configurable option of another service such as a VPS. Bundle licenses are also supported for reseller accounts that have been explicitly granted access to them in CLN.

The plugin provides:

• IP-based and key-based license provisioning, depending on the selected product
• automatic license creation and termination
• IP license migration when the service IP changes for standalone products, module-backed addons, and configurable options
• deferred provisioning for module-backed addons and configurable options when a VPS receives its Dedicated IP after the order is accepted
• license and relation lists in the WHMCS admin area
• a global policy that prevents the checkout or operator IP from being used as the server IP

# Choose a provisioning model

# Supported license products

The following matrix shows which license modes the plugin supports for every value in the Product dropdown.

For Imunify360, the available tiers include Single User, up to 30 users, up to 250 users, Unlimited, and ImunifyAV+. The five-user tier is displayed only when it is enabled in the module installation.

The Create Key based license and Key Limit fields apply only to KernelCare and Imunify360. The module hides and ignores these fields for all IP-only products, including KernelCarePlus and Bundle Licenses.

# Install or update the plugin

1. Back up the WHMCS files and database.
2. Download the module archive:
   • Production build
   • Beta build
3. Extract the archive into the WHMCS installation directory. Allow it to overwrite the existing module files when updating.
4. Run the database migration from the WHMCS server:

php <whmcs_root>/clDeploy.php --migrate

5. In WHMCS, open System Settings → Addon Modules.
6. Activate CloudLinux Licenses Addon if it is not active.
7. Click Configure, grant access to the required administrator roles, and save the settings.

The migration is safe to run after every update. It creates or updates the module tables, including the durable license state used to track the exact registered IP or key. No manual database changes are required.

# CloudLinux Licenses Addon

The installation contains two cooperating WHMCS modules:

• CloudLinuxLicenses is the server module attached to a product or product addon. It creates, changes, suspends, unsuspends, and terminates an individual CLN license.
• CloudLinux Licenses Addon is the addon module that provides the administration page and registers the WHMCS lifecycle hooks. It manages relations between non-CloudLinux services and license products. For module-backed addons and configurable options, it also reconciles deferred provisioning, follows parent-service IP changes, and cleans up tracked licenses when services are removed.

The addon module must remain active for Product Relations, Addon Relations, Configurable Options Relations, deferred provisioning, and automatic parent/child lifecycle handling to work.

# Addon administration tabs

Open Addons → CloudLinux Licenses Addon. The page contains five tabs:

The list tabs support filtering by client, product or addon, IP address, and license key. Relation rows can be added, edited, and deleted from the corresponding relation tab.

# Module-backed and legacy product-addon workflows

There are two different ways to use a WHMCS product addon:

1. Module-backed addon — recommended for current WHMCS versions. Set the product addon's Module Name directly to CloudLinuxLicenses and configure its CLN product. The license belongs to the addon service itself and appears in Addon Licenses List. This is the workflow described in Scenario 2.
2. Addon Relation — legacy compatibility workflow. Keep the existing product addon independent of the CloudLinux module, create a separate hidden CloudLinuxLicenses product, and map the two under Addon Relations. Activating the addon creates a separate child license service, which appears in Licenses List.

Use an Addon Relation when an existing addon must remain independent or when compatibility with an older configuration is required. Do not configure the same addon as module-backed and also map it through Addon Relations, because these are separate provisioning models.

# Legacy relation workflows

Product Relations and Addon Relations are retained for compatibility with installations that use the plugin's older child-service architecture. Both workflows create a separate free child service for the linked license product and record its relationship with the parent service.

# Addon Relations

Use Addon Relations only when an existing regular product addon must remain independent of the CloudLinuxLicenses provisioning module:

1. Create and configure a hidden CloudLinuxLicenses product for the license.
2. Open Addons → CloudLinux Licenses Addon → Addon Relations.
3. Click Add Relation.
4. Select the existing regular addon under Product Addon and the hidden license product under Linked License Product.
5. Save the relation.

Activating the regular addon creates a separate free child service for the linked license product. For current WHMCS versions, prefer a module-backed product addon unless compatibility with an existing relation-based configuration is required.

# Product Relations

Use Product Relations when every instance of a VPS or hosting product must include a license without asking the customer to select it:

1. Create and configure a hidden CloudLinuxLicenses product for the license.
2. Open Addons → CloudLinux Licenses Addon → Product Relations.
3. Click Add Relation.
4. Select the parent product under Main product and the hidden license product under Linked License Product.
5. Save the relation.

The related license product is created as a free child service. Include its commercial cost in the parent product instead of pricing the hidden license product separately.

For an IP-based related license, enable Do not use Order IP on the hidden license product. After WHMCS creates the child license service, enter the correct server IP on that child and run its Create module action. If the parent IP changes later, update the related license service separately.

# Administrative and client operations

For a service using CloudLinuxLicenses, the WHMCS administrator can:

• create and terminate the license;
• suspend or unsuspend an IP-based license;
• view its registered IP or key and product details;
• change the license IP or replace an existing license key.

For key-based licenses, suspend and unsuspend do not remove or recreate the key. In the client area, the customer can view the license details and change the registered IP or key for an active service.

Module-backed addon and configurable-option licenses participate in deferred provisioning and follow parent-service IP changes. Their stored License IP is updated after a successful move. Hard-deleting a parent service also cleans up tracked module-backed addon and configurable-option licenses.

Product Relation child services receive suspend, unsuspend, and terminate actions when the corresponding module action runs for the parent service. An Addon Relation child is terminated when the mapped regular addon is terminated. These child services do not participate in automatic parent-IP reconciliation. Follow the operational precautions in Legacy relation workflows before canceling or deleting an order.

# Connect a product to CLN

Open the product or product addon, select the Module Settings tab, and set Module Name to CloudLinuxLicenses.

The following example configures an IP-based Imunify360 Single User license. The same IP settings apply to all IP-based products.

# Configure the server IP source

For a new IP-based license, the module resolves the IP in this order:

1. The custom field named in Name of the custom IP field
2. The WHMCS service Dedicated IP
3. The order originator IP, but only when the fallback is allowed

If the custom field and Dedicated IP contain different values, the custom field takes precedence. After successful provisioning, the module stores the exact registered IP and uses that value for later changes and cleanup.

# Recommended policy: never use the order IP

The order IP is the address from which checkout was submitted. For an order created or accepted by an administrator, it can be the operator IP. It is not a reliable server address.

There are two controls:

• Never use Order IP in System Settings → Addon Modules → CloudLinux Licenses Addon → Configure disables the fallback globally.
• Do not use Order IP in a product's Module Settings disables the fallback for that product.

The global setting overrides every product setting.

# Legacy order IP fallback

For compatibility with existing installations, the order IP can still be used when both controls are disabled. This can be useful in legacy workflows where the customer changes the address after activation, but it is not recommended for server licenses.

The order IP fallback is never written into the service Dedicated IP merely by reading it. This prevents a browser or operator address from appearing as if it were the customer's server address.

# Scenario 1: standalone license product

Use this model when the customer orders the license itself rather than a parent VPS product.

# Create the product

1. Open System Settings → Products/Services → Products/Services.
2. Create a product group, or select an existing license group.
3. Create a product with Product Type set to Other.
4. Configure its name, description, pricing, and welcome email.
5. Open Module Settings and select CloudLinuxLicenses.
6. Enter the CLN credentials and click Test credentials.
7. Select the license product. For Imunify360, also select the required License Type tier.
8. For an IP-based license, enter a custom field name such as IP in Name of the custom IP field.
9. Enable Do not use Order IP unless the legacy fallback is intentional.
10. Select the required WHMCS automatic setup rule and save the product.

# Require the customer IP at checkout

1. Open the product's Custom Fields tab.
2. Add a Text Box field with exactly the same name used in Name of the custom IP field.
3. Enable Required Field.
4. Enable Show on Order Form.
5. Save the product.

The customer must now enter the server IP while ordering:

# Scenario 2: optional product addon

Use a module-backed product addon when the customer can add a license to a VPS or hosting product. The parent product does not need to use the CloudLinux license module.

# Create and attach the addon

1. Open System Settings → Products/Services → Product Addons.
2. Create an addon and configure its name, description, billing cycle, and price.
3. Enable Show on Order.
4. In Applicable Products, select the parent VPS or hosting products.
5. Open Module Settings and select CloudLinuxLicenses.
6. Enter the CLN credentials, select Imunify360, and choose the required License Type tier.
7. Enable Do not use Order IP for a deferred-IP VPS workflow.
8. Select an automatic setup rule. Do not select Do not automatically setup this addon if the addon must activate automatically after the parent receives its IP.
9. Save the addon.

The addon is displayed during checkout for the applicable parent products:

# How deferred addon provisioning works

1. WHMCS accepts and provisions the parent service.
2. If the parent has no custom IP or Dedicated IP, the license addon stays Pending. The parent service is not blocked.
3. The missing-IP attempt is recorded in the WHMCS Module Queue.
4. When the order is Active and the parent receives a Dedicated IP or custom IP, save the parent service. The module retries the addon.
5. After CLN creates the license, the addon becomes Active and its License IP field stores the registered address.

If the parent IP later changes, the module removes the old registration, creates the license for the new IP, and updates License IP. Hard deletion of the parent service also cleans up its module-backed license addons.

# Scenario 3: configurable option

Use a configurable option when the customer must select a license product or tier from a dropdown on the parent product.

# Create hidden license products

Create one CloudLinux license product for every selectable value:

1. Create a product with Product Type set to Other.
2. Mark the product Hidden so it cannot be ordered separately.
3. Select CloudLinuxLicenses in Module Settings.
4. Configure the CLN credentials, product, license tier when applicable, IP field, and Order IP policy.
5. Repeat for the other license choices.

Pricing for this workflow is normally configured on the configurable option values, not on the hidden license products.

# Create the dropdown

1. Open System Settings → Products/Services → Configurable Options.
2. Create a group and assign it to the parent VPS product.
3. Add a configurable option with Option Type set to Dropdown.
4. Add one value for no license, followed by the license choices. WHMCS supports an internal value and a customer-facing label separated with |, for example:

none|No Imunify360 license
imunify_single|Imunify360 Single User
imunify_30|Imunify360 up to 30 Users

Configure the price and sort order for every value:

# Map the values to license products

1. Open Addons → CloudLinux Licenses Addon.
2. Select Configurable Options Relations.
3. Click Add Relation.
4. Select the hidden license product, configurable option group, and configurable option value.
5. Add one relation for every value that must create a license. Do not map the No license value.

The relation tab shows the license product associated with every selectable value:

The customer sees a single license dropdown on the parent product:

# How deferred configurable-option provisioning works

The parent service can become Active even when it has no IP. The license selection waits until the order is Active and the parent receives its custom IP or Dedicated IP. Saving the parent service or completing its module provisioning reconciles the selection and creates the missing license.

Changing the selected option terminates the old related license and provisions the new one. Removing the selection terminates the related license. Changing the parent IP moves all related IP-based licenses to the new address.

# Configure a Bundle license

Bundle licenses use the same standalone product, product addon, and configurable-option workflows described above. Use this product type only when bundles have been enabled for the reseller account in CLN.

1. Open the relevant product or addon Module Settings.
2. Select CloudLinuxLicenses as the module.
3. Select Bundle Licenses in Product.
4. Select one of the bundles returned for the reseller account.
5. Configure the IP field and Order IP policy as for any other IP-based license.
6. Save the product or addon.

If the Bundle list is empty or CLN rejects bundle provisioning, verify that the saved credentials belong to the expected reseller and ask CloudLinux to confirm that the bundle is assigned to that account.

# Provisioning behavior reference

Key-based licenses do not use the IP resolution or deferred-IP workflow.

# Verify provisioned licenses

Open Addons → CloudLinux Licenses Addon to access:

• Licenses List for standalone and related product licenses
• Addon Licenses List for module-backed product addons
• relation editors for addons, products, and configurable options

The lists can be filtered by client, product or addon, IP address, and license key.

Module-backed product addons are shown separately under Addon Licenses List:

After provisioning, verify all three locations:

1. The WHMCS service or addon is Active and displays the expected License IP or key.
2. The license appears in the appropriate CloudLinux Licenses list.
3. CLN contains the same IP or key and the correct license product.

# Troubleshooting

Enable Debug Mode only while diagnosing a problem, then review Utilities → Logs → Module Log and the WHMCS Module Queue. Avoid leaving credential-bearing debug logs enabled longer than necessary.