CPanel/WHM

From WHMCS Documentation

Revision as of 18:09, 13 September 2021 by SarahK (talk | contribs) (→‎Setting Up a cPanel Package)

Supported Features

Create Suspend Unsuspend Terminate
Yes Yes Yes Yes
Change Package Change Password Usage Updates Client Area Link
Yes Yes Yes Yes

The following ports should be open for outbound connections from your WHMCS server: 2086 & 2087

Adding a cPanel & WHM Server

The following steps guide you through the process of setting up a cPanel & WHM server in WHMCS for cPanel Hosting Accounts.

  1. You need to begin by creating a Server for your cPanel products to be assigned to in WHMCS.
  2. To do this navigate to Configuration () > System Settings > Servers or, prior to WHMCS 8.0, Setup > Products/Services > Servers and click on Add New Server
  3. Enter the server name, IP address, select the server type "cpanel" from the dropdown menu.
  4. Enter your WHM username into the username field.
    WHM API Setup
  5. Log in to WHM and navigate to Development >> Manage API Tokens.
  6. Click Generate Token.
  7. Enter a name for your token, such as "WHMCS". For assistance configuring the WHM API token privileges, see our API Token Permissions section below.
  8. Click Save and copy your API Token.
  9. Return to the WHMCS server configuration page and paste the newly generated API Token into the corresponding field..
  10. Ticking the SSL Mode checkbox is also recommended, but all other fields are optional.
  11. The default port will be displayed. If your server is configured to communicate on a different port, tick the Override with Custom Port checkbox and enter it into the Port field. For more information refer to Server Port Overrides.
  12. Click Create Server to complete the process and add your new cPanel Server.
  13. If this is the only cPanel server listed afterwards, click on the name and ensure it results in an asterisk (*) next to it. This ensures it is the default and used when any other non-specific configuration (server groups) doesn't apply.
If 2FA is enabled on your cPanel server, you must disable it for API requests. Click here for more information.

Setting Up a cPanel & WHM Package

Watch the video tutorial for this feature.

cPanel Module Settings
Adding a Package in WHM

To set up a cPanel & WHM hosting product, follow the steps to create a product at Configuration () > System Settings > Products/Services or, prior to WHMCS 8.0, Setup > Products/Services > Products/Services. When you do this, in the Module Settings tab, make sure to select cPanel from the menu and perform the appropriate steps below.

Simple Mode

This section describes a feature available in version 7.0 and above.

To create a hosting product that uses an existing WHM package, perform the steps in Products and Services using the following configuration:

  • Select Shared Hosting as the Product Type.
  • Select cPanel as the Module Name.
  • From the WHM Package Name menu, select the hosting plan to use when WHMCS provisions the account.

You can then configure the remaining settings as desired.

Advanced Mode

Advanced Mode

Instead of using a preconfigured WHM package, you can choose to define custom package options.

To configure quotas on a per-account basis, you will need root-level access to the server.

To create a hosting product with a custom package, perform the steps in Products and Services using the following configuration:

  • Select Shared Hosting as the Product Type.
  • Select cPanel as the Module Name.
  • Do not select a package in the WHM Package Name menu.
  • Click Switch to Advanced Mode on the right side of the page and enter the desired values for each package setting. If you do not enter a value, the quota will be unlimited.

You can then configure the remaining settings as desired.

For a reseller package

Creating an ACL List
cPanel Reseller Module Settings

To create a hosting product for a reseller account, perform the steps in Products and Services using the following configuration:

  • Select Reseller Hosting as the Product Type.
  • Select cPanel as the Module Name.
  • Do not select a package in the WHM Package Name menu.
  • Click Switch to Advanced Mode on the right side of the page and enter the desired values for each package setting. If you do not enter a value, the quota will be unlimited.
  • Enter a Reseller ACL List.
    • This ACL must exist already in WHM.
    • WHM requires that you create a reseller in order to create an ACL list. To do this:
      1. In WHM, navigate to Resellers > [Reseller Center].
      2. Activate an existing or test account as a reseller.
      3. Navigate to Resellers > [Edit Reseller Nameservers and Privileges].
      4. Create and save your ACL list.
  • Make certain to also configure Limit Reseller by Number, Limit Reseller by Usage, Reseller Disk Space, Reseller Bandwidth, Allow DS Overselling, Allow BW Overselling, Configure Nameservers, and Reseller Ownership.

Per Account Billing

This section describes a feature available in version 7.9 and above.

You can bill resellers for the number of cPanel accounts they provision. You can choose whether to include a certain number of cPanel accounts in the price and only charge for exceeding a certain limit, offer tiered pricing, or charge for every cPanel account resellers create.

We recommend only offering cPanel account usage billing on products with a monthly billing cycle.

Enable Usage Billing

To use this feature:

  1. Toggle the Sub-Accounts billing metric to On. (Do not confuse this with cPanel Subaccounts, which cPanel accounts can create within cPanel.)
  2. Click the Configure Pricing link to set the pricing for the accounts the reseller consumes.
  3. Click Save.

When a client orders this product, WHMCS will track the number of cPanel accounts that the reseller creates. On the service's Next Due Date, the system records the current number of created cPanel accounts and adds the cost to the service's renewal invoice.

A guide with pricing examples is available here.

Usage Billing is a powerful feature. For more information on the terms and possible configurations, see Usage Billing.

Other Options

  • Add Prefix to Package - Add the username_ prefix to the package name when the account is created on the server. This is useful when using multiple servers with the same package name, but different username.

Notes

Login to cPanel Link

The login to cPanel link displayed in the client area is based upon the server hostname if available, if not, the IP address will be used. The usage of http and https login links depends upon the state of the "Secure" checkbox in the server configuration eg. When ticked, the https link with port 2083 is used.

The login to control panel link displayed in the admin area is based upon the server hostname if available, if not, the IP address will be used. The usage of http and https login links depends upon the state of the "Secure" checkbox in the server configuration eg. When ticked, the https link with port 2087 is used. It uses the xfercpanel function, so when prompted, enter your WHM login details (not the client's cPanel details) and you will be logged into the client's account with reseller privileges.

Reseller Usage Calculation

Reseller usage limits and reporting is based on the behaviour of WHM's design & implementation of a "Reseller" account type. Most notably, resellers owned by root will not have their own usage aggregated into such boundary calculations.

WHMCS Connect

WHMCS Connect allows you and your administrators to quickly and easily access the control panels of all the servers configured in your WHMCS installation that support Single Sign-On, enabling you and your staff to administer and make changes without ever needing to re-authenticate.

For information on the benefits of WHMCS Connect and how to configure this functionality refer to this page.

API Token Permissions

With API Tokens for cPanel & WHM, it is possible to restrict what actions an API Token can perform. For WHMCS to be able to perform all the operations it supports, the following permissions must be granted in WHM at Development >> Manage API Tokens.

basic-whm-functions basic-system-info cpanel-api
create-acct create-user-session suspend-acct
upgrade-acct kill-acct passwd
acct-summary list-accts show-bandwidth
cpanel-integration list-pkgs ns-config
edit-mx manage-api-tokens ssl-gencrt

When creating an API Token for the root user, the viewglobalpackages permission is also required.

When using the Configurable Package Addon, the edit-account permission will need to be enabled.

Note for Reseller Accounts
For reseller products, the "Everything" permission needs to be enabled as the reseller API functions on a cPanel server require root access to work.

Keep DNS Zone on Termination

When terminating a cPanel & WHM account via the WHMCS admin area, an option is provided to "Keep DNS Zone".

Selecting this option will terminate the account on a cPanel & WHM server while preserving the DNS Zone Record. Use this option where you wish to terminate the account but preserve the DNS records. Common use cases for this include scenarios such as account migration where DNS forwarding is being used.

Please Note: You will not be able to re-create a new account on the server using the same domain while a DNS Zone exists for it. Attempting to provision the domain again will result in an error and you must delete the DNS Zone to be able to successfully provision a new account.

Disable 2FA for cPanel API

For the cPanel module to function when 2FA is enabled for your account, you must ensure that the 2FA requirement is disabled for API requests.

To facilitate this:

  1. Log in to WHM as root
  2. Navigate to Security Center > Configure Security Policies
  3. Uncheck API requests and click Save

Add-On Features

In WHMCS 8.2 and later, in addition to WHMCS's existing product addon functionality (now an Independent Product), you can create an Add-On Feature. These addons let you sell module-specific features like WordPress® Toolkit offerings available through both cPanel and Plesk.

For more information and steps to create an addon, see Product Addons.

Common Problems

Access Denied/Permission Denied

An Access Denied error indicates that the cPanel server denied WHMCS access to perform the requested action (eg. create or modify the account). To investigate and resolve, ensure that:

  1. The server settings configured in WHMCS are valid
  2. The API credentials have the required permissions to perform the desired action
  3. The Username and Server assignment under the client's Products/Services tab in WHMCS match exactly with the account records in cPanel
  4. The user specified on the server settings page is has sufficient permissions to manage the cPanel hosting account in question


To check points 1 and 2, begin by navigating to Configuration () > System Settings > Servers. Edit the server in question, and ensure the Username and API Token are valid and match those currently configured in WHM. Refer to #Adding_a_cPanel_.26_WHM_Server above for more detailed instructions

Ensure all the required permissions have been granted to the cPanel API token, these are itemised in the #API_Token_Permissions section above

Tip
Use the Test Connection button to confirm access granted.

You do not have permission to use Selected Package

If you receive this error when trying to create an account then you need to correct the Packages Name setting. To do this, go to Configuration () > System Settings > Products/Services or, prior to WHMCS 8.0, Setup > Products/Services > Edit > Module Settings on the package where you are receiving the error. Where it asks for the WHM Package Name, you must enter this exactly as it appears in WHM - which should be in the format username_packagename.

Package Not Allowed or Exceeded Resource/Account Allocation

This error most likely means you only have reseller access to your server and are trying to create an account without a valid package name. You need to make sure the WHM Package Name in the product configuration of WHMCS matches exactly what is setup in your WHM Package Editor.

Resellers are not permitted to create subdomains of the server's main domain

This means no domain has been selected and is missing. Ensure the product has a domain name entered. You may need to enable Require Domain in Configuration () > System Settings > Products/Services or, prior to WHMCS 8.0, Setup > Product/Services.

Unable to validate setting for language: english

cPanel & WHM have made a number of changes to their API in the latest versions that are not backwards compatible. Therefore it is no longer possible to use an old version of WHMCS with the latest version of cPanel. You will need to upgrade your WHMCS install to version 4.2.1 or above.

Sorry, that username is reserved

cPanel & WHM does not allow usernames to contain the phrase "test" amongst others, so when this error occurs, simply change the username under the client's products/services tab and run the Create Module Command again.

Sorry, a group for that username already exists

An account with this username already exists on the server. This error can occur on shared servers even when you do not have an account with this username under your reseller account another reseller on the same server may be using it already.

To resolve, navigate to the client's Products/Services tab, change the Username, click Save Changes and finally click the "Create" Module Command button.

Login Failed

There are two possible causes for this error:

  1. The login details under Configuration () > System Settings > Servers or, prior to WHMCS 8.0, Setup > Products/Services > Servers > Edit are incorrect. Please ensure you are using either the username and API Key or the username and password combination and that the login details are correct.
  2. The Brute Force Protection settings are preventing WHMCS from creating/suspending/terminating accounts via the cPanel API. Please adjust the BFP settings in WHM.

No user name supplied: "username" is a required argument

This means the username under the client's Products/Services tab is empty.

You should enter a username, save changes and try module creation again. Also ensure that Require Domains is checked in Configuration () > System Settings > Products/Services or, prior to WHMCS 8.0, Setup > Products/Services > Products/Services.

Action Failed Unable to auto-login. Please contact support

This error also means the username under the client's Products/Services tab is empty.

You should enter a username, save changes and try module creation again. Also ensure that Require Domains is checked in Configuration () > System Settings > Products/Services or, prior to WHMCS 8.0, Setup > Products/Services > Products/Services.

WHM Username is missing for the selected server

Seeing this error when attempting to provision a hosting account is caused by a server balancing misconfiguration. Ie. no server is selected upon which the account should be created. For troubleshooting steps for this particular issue, please refer to this article

An Unknown Error Occurred after updating to cPanel 74

After updating to cPanel 74, every module command performed results in a "An unknown error occurred" message. Inspecting the Module Debug Log reveals that a WHM 404 error page is being returned by the server.

This is caused by the deprecation of the cPanel XML API in version 74. To use the newer cPanel JSON API, it is necessary to update to WHMCS 7.3 or above.

WHM Package not shown in Module dropdown list when editing product

The cPanel API only returns packages available to provision under the reseller's WHM account. This often means packages may not show in this list if it would exceed the reseller's allowances on their WHM account.

Confirm this diagnosis by following these steps:

  1. cPanel Package Limits
    Login to WHM and navigate to Account Functions » Create a New Account
  2. Select the desired package from the Choose a Package dropdown
  3. Observe the package name is suffixed by the note "Cannot use due to limits"

There are two ways to resolve this issue:

  1. Ensure the WHM account has sufficient allowances to provision desired WHM package when configuring in WHMCS
  2. Enable overselling on the reseller account (requires WHM root access) - You can learn more about overselling in WHM in the cPanel docs here

Product attribute Package Name "Package Name" not found on server

There are two possible causes of this error:


Server Modules
cPanel/WHM - DirectAdmin - Plesk - Helm 3 - Helm 4 - Ensim - InterWorx - WebsitePanel - Cloudmin
Lxadmin - Virtualmin Pro - XPanel - HyperVM - SolusVM - Cloudmin - WHMSonic - VPS.Net
CentovaCast - SCPanel - MediaCP - GameCP - TCAdmin - Reseller Central - Auto Release - Heart Internet

Registrar Modules
Enom - ResellerClub - Nominet - OpenSRS - ResellOne - OnlineNIC - PlanetDomain - Affordable Domains
TPP Wholesale - TPPInternet - Stargate - Namecheap - NetEarthOne - Bizcn - InternetBS - GMO Internet
12Register - Registercom - DotDNS - WebNIC - Dot.TK - HexoNet - Realtime Register - Registereu
RRPProxy - ResellerCamp - TransIP - Heart Internet - IPMirror - NetRegistry - OVH - VentraIP Wholesale
Email - 101Domain

Fraud Modules
MaxMind - VariLogiX FraudCall - Telesign

Gateway Modules
2CheckOut - AsiaPay - Auth.net Echeck - Authorize.net - Authorize.net CIM - Bank Transfer - BidPay
BluePay - BluePay Echeck - BluePay Remote - Boleto - CashU - CC Avenue - ChronoPay - Direct Debit
EMatters - E-Path - eProcessingNetwork - eWAY Tokens - F2B - Finansbank - GarantiBank - Gate2Shop
Inpay - InternetSecure - IP.Pay - Kuveytturk - Modulo Moip - Mail In Payment - Merchant Partners
Merchant Warrior - IDEALMollie - Moneris - Moneris Vault - Skrill 1-Tap - NaviGate - NETbilling
Netregistry Pay - NoChex - Offline Credit Card - Optimal Payments - PagSeguro - Payflow Pro - Pay Junction
Paymate AU and NZ - Payment Express - PayPal - PayPal Card Payments - PayPal Express Checkout
PayPal Payments - PayPal Payments Pro - PayPoint.net (SecPay) - Payson - Planet Authorize - ProtX VSP Form
PSIGate - Quantum Gateway - Quantum Vault - SagePay - SagePay Tokens v2 - SecurePay
SecurePay AU - Secure Trading - TrustCommerce - USA ePay - WorldPay - WorldPay Invisible


Retrieved from "http://3.17.75.209/index.php?title=CPanel/WHM&oldid=30701"