Getting Started With The cPanel® API

cPanel & WHM’s web interfaces offer a comprehensive server and web hosting management solution, but hosts and developers often want to automate tasks or integrate cPanel’s tools with other software. To make that easier, we provide extensive APIs that can be accessed both locally and remotely. 

In this article, we’ll explore the cPanel & WHM APIs and show you how to get started with cPanel’s command-line API utilities and the HTTP API. We have recently updated our API documentation as well at https://api.docs.cpanel.net/

What Is The cPanel API?

The cPanel & WHM APIs (Application Programming Interfaces) allow users to access the software’s built-in functionality without going through the web interface. To use the APIs, you send a command, and cPanel responds by carrying out an action, which could be to change a setting, perform a server administration task, or tell you some information. 

There are several benefits to using the APIs.

  1. They allow users to automate tasks rather than do them manually. For example, as we’ll see in the next section, you can trigger a backup from a script using the API. That script could run on the same server as cPanel or a different server that sends commands over the internet. 
  2. They allow cPanel to integrate with other tools. A web host might use the API to collect data to display in a dashboard. 
  3. You can use the APIs to extend cPanel’s functionality. Many cPanel extensions build on the APIs.

In short, our APIs help users and developers to leverage cPanel’s sophisticated server and hosting administration technologies to solve problems, save time, and build flexible tools for their users.

Accessing the cPanel API From Your Server

We provide a pair of command-line utilities for scripting and running commands on your server or hosting account, one for the WHM API (whmapi) and the cPanel API (uapi). Functionality is split between them in the same way it’s split between the WHM and cPanel web interfaces, so you would use whmapi for server-related tasks and uapi for hosting-related tasks. 

To use them, you need to be logged in to your server with SSH.

First, let’s see how to query the WHM API for information about a server’s user accounts. 

whmapi list_users

We’re using the “whmapi” command to call the “list_users” function. It does precisely what you’d expect, returning a list of users who have accounts on the server, along with some metadata about the command. 

data: users: - root - user1 - user2 - example1 metadata: command: list_users reason: OK result: 1 version: 1

Now we know which users have accounts on the server, we want to take a deeper look at one account in particular. 

whmapi1 accountsummary user=user1

Here we’re using the “accountsummary” function, and providing the parameter “user” with the value “user1”.  A truncated set of results looks like this:

data: acct: - backup: 1 disklimit: unlimited diskused: 367M domain: example.com email: user1@example.com ip: 198.51.100.13

We see that the account has a domain associated with it, so let’s use the cPanel API to find more information.

One common unknown when starting with our API is understanding how masquerading works. Although the cPanel API is designed to be run as the cPanel user, a root user can masquerade as the cPanel user by specifying `–user=<username>` in the UAPI command.

uapi – user=user1 DomainInfo list_domains

The username is given as an option rather than a parameter. Many functions are gathered into modules that provide related functionality. In this case, we’re accessing the “DomainInfo” module and its “list_domains” function. It returns information about all the domains associated with the account.

data: addon_domains: - example3.com main_domain: example.com parked_domains: [] sub_domains: - files.example.com

So far we’ve only queried the APIs for information, but they can also be used to instruct cPanel to carry out tasks. For example, let’s say we want to trigger a full backup of this user’s account. To do that, we’d use the “Backup” module with the “fullbackup_to_homedir” function:

uapi – user=user1 Backup fullbackup_to_homedir

Each API includes many modules and dozens of functions capable of automating much of the functionality provided by cPanel & WHM. You will find a full list of modules and more information about using the command-line API utilities in the documentation. 

Accessing the cPanel API Remotely 

In addition to their command-line utilities, you can query both APIs remotely with HTTP requests. Any programming language or tool capable of sending HTTP requests can access API functions, but we’re going to use the “curl” command-line tool for our demonstration; to follow along make sure you have curl installed on your system. It’s available on Linux from your package manager, on macOS via brew, and on Windows via the Chocolatey package manager. 

It wouldn’t be safe to allow just anyone to interact with cPanel’s API, so every request needs to be authenticated and linked to a user with the right permissions. There are various authentication mechanisms, but we’re going to use authentication tokens.

cPanel and WHM Authentication Tokens

An authentication token is a long string of letters and numbers that grants access to the API. Both WHM and cPanel include an interface for generating tokens called Manage API Tokens. They’re similar, so we’ll just walk you through the process of creating a token in WHM. 

Navigate to the Manage API Tokens page, which you’ll find in the sidebar menu under Development. Click the Generate Token button, which opens a page for you to select the specific privileges you’d like to give the token holder. 

cPanel API Token Privileges

You should give authentication tokens only necessary privileges; if a bad actor gets their hands on one with a broad range of privileges, they may gain access to the entire system. 

Give it a meaningful name and choose an optional expiration date before clicking Save at the bottom of the page. WHM generates the token and displays it for you to copy. Once you leave this page, you can’t access it again, so be sure to save it somewhere safe. 

cPanel API Authentication Token

Making API Calls with Curl

We can remotely access all of the same API functions we previously used when logged in to the server. To try it out, we’ll list the server’s users as we did before with the command-line utility.

curl -H'Authorization: whm root:XXXXXXXXXXXXXXXXXXX' ‘https://example.com:2087/json-api/list_users?api.version=1’ 

This looks complicated, so let’s break it down:

  • curlthe command-line HTTP client we’re using to send the request to our cPanel server.
  • -H’Authorization: whm root:XXXXXXXXXXXXXXXXXXX’ — the -H option tells curl to send an HTTP header with authentication information; in this case, the API we’re accessing, the root user or the name of the reseller account associated with the token, and the token itself. You should replace XXXX with your token.
  • https://example.com:2087/ — the domain and port of our server. The port will be different depending on the API we are contacting. For a secure SSL connection to WHM, we use 2087.
  • json-api — JSON is a data format, and we’re telling the API to send JSON data in response to our request. 
  • list_users?api.version=1 — the API function to call and the API version we’re using. 

You can find more information about the structure of API calls in the documentation.

When you send the request, curl prints out the JSON data it gets back from WHM. 

{ "metadata" : { "command" : "list_users", "result" : 1, "reason" : "OK", "version" : 1 }, "data" : { "users" : [ "root", "user1", "user2", "example1" ] }

As you can see, it’s the same information we got from the command-line app in a more programmer-friendly format.

In our final example, we’ll use the cPanel API to retrieve domain information for user1, just as we did with the uapi app in the previous section.

curl -H'Authorization: cpanel user1:XXXXXXXXXXXXXX' 'https://example.com:2083/execute/DomainInfo/list_domains'

The format of the request is the same, but some details have changed. We’re using the secure cPanel port (2083), and the module (DomainInfo) and function (list_domains) are preceded by “execute”, which tells cPanel to expect a command. Additionally, we’re accessing the API using a token associated with a cPanel user, so we have to provide their username in the authentication header. 

Each module and function has a page in the documentation. For example, the list_domains function. If you’re unsure which format to use for a function or which modules and functions are available, the documentation should be your first port of call. The cPanel & WHM APIs empower server administrators and hosting clients to take advantage of the software’s rich functionality to build their scripts, automations, and integrations. As always, if you have any feedback or comments, please let us know. We are here to help in the best ways we can. You’ll find us on Discord, the cPanel forums, and Reddit. Be sure to also follow us on Facebook, Instagram, and Twitter.

How to Deploy a WordPress® Staging Site With cPanel

Editing a production WordPress site is like detailing your car while it’s driving down the freeway. You might arrive at your destination on time and looking good. Then again, it could all go horribly wrong—and if you do it often enough,  your luck will run out eventually. 

If a business depends on its WordPress site or WooCommerce store, editing the live production installation is simply not worth the risk. WordPress staging sites, also called development sites or testing sites, are the safe alternative. 

In this article, we explain what you need to know about WordPress staging sites, why you should use them, and how cPanel’s WP Toolkit (WPT) makes it easy to deploy a staging site and synchronize changes back to the production site. 

What Is a WordPress Staging Site?

A staging site is a cloned copy of a production site. It has the same data and files, but it isn’t accessible to the public, and it’s usually hosted on a different subdomain. Any changes you make to a staging site are not transferred to the production site unless you want them to be. Because it’s a clone hosted in the same environment, it behaves just like the production site, making it the ideal testing ground.

In the past, creating a staging or development site was complicated and time-consuming. You had to export data from the production database, create a new database, import the data, copy the files, reconfigure the site, and set up a staging subdomain. Then you’d have to reverse the process to deploy the changes to production. 

That complexity is why many WordPress users don’t use staging sites, instead opting for the risky high-wire act of editing a busy live site. However, if you host WordPress sites on a server managed by cPanel & WHM, the whole process takes just a few clicks. 

Why Do You Need a Staging Site?

There are many situations where it’s a good idea to deploy a WordPress staging site to test changes before committing to them. Ideally, any change more complicated than publishing a post gets thoroughly tested before it goes live.

Use cases for staging sites include:

  • Testing new landing pages to ensure every component works as expected before potential customers visit. 
  • Testing updates for compatibility issues, although WP Toolkit can automate that for you with Smart Update.
  • Creating a new theme or editing your current theme.
  • Editing the site’s code to add new functionality. 

Staging sites are also useful when you want to let developers and designers work on your site but don’t want to give them access to the production installation. 

How to Setup a WordPress Staging Site

We’re going to walk you through the process of creating a staging site and deploying changes back to production. We’ll be using the clone and staging features in WordPress Toolkit Deluxe.

Select WordPress Toolkit from cPanel’s main page menu and expand the detailed view of the site you want to work with. 

cPanel WordPress Toolkit Staging Site

Click the Clone tool in the dashboard view. In the Clone interface, you can choose the staging site’s subdomain and path. The subdomain can be a pre-existing domain, or the Toolkit can create a new one. If necessary, you can also change the database name. 

cPanel Clone WordPress Site

That’s it! The Toolkit will now create the staging site and subdomain. You can access the new site in the main WPT interface alongside your other sites. 

To make staging sites easier to tell apart from live sites, use WPT’s labels. Click Add Label and choose an appropriate option from the dropdown menu. 

cPanel Label WordPress Staging Site

After sites are labeled, you can sort and filter them using the Sort and Filter dropdowns at the top right of the interface. 

Commit Staging Site Changes to Production

Once you have developed and tested a new feature or design, it’s time to push the changes to the production site. To do that, we have to copy the staging site’s database and files. This would once have been a complicated and error-prone process, but it can be done safely in less than a minute with WP Toolkit. 

Click the Copy Data tool in the staging site’s WPT dashboard. 

cPanel WordPress Copy Data

In the Copy Data interface, select the production site from the Target dropdown menu. You have fine-grained control over which aspects of the site are transferred. You can copy the files, database, and specific database tables. You can also choose whether to overwrite and delete production files if they were edited or removed on the staging site. 

In our example image, we’re copying everything except the database’s post and user tables and their associated metadata tables. That allows us to synchronize the WordPress instances without overwriting or deleting posts and users created after we made the staging site. 

cPanel WordPress Staging Site Copy To Production

Because copying can be a destructive operation, WPT automatically creates a restore point so you can quickly roll back if something goes wrong. 

Together, WordPress Toolkit’s clone and copy features provide quick and simple-to-use staging site deployment. You can create a staging site in seconds and push changes to production just as easily.  For agencies and other businesses that offer WordPress hosting and management services, the WPT means faster, safer, and more reliable WordPress workflows. 

As always, if you have any feedback or comments, please let us know. We are here to help in the best ways we can. You’ll find us on Discord, the cPanel forums, and Reddit. Be sure to also follow us on Facebook, Instagram, and Twitter.

Top 5 Reasons To Choose WordPress® For Your Business

In 2021, consumers will rely even more on the web and social media to solve problems and buy products. If a business isn’t on the web, it’s basically invisible. But what’s the best way to build and manage your business site or store? For hundreds of thousands of people, the answer to that question is WordPress.

WordPress is fundamentally a content management system (CMS), a web application that makes it easy to write and publish content online. WordPress is by far the most widely-used CMS. As of this writing, it is the foundation of 40 percent of all websites and 64 percent of sites that use a CMS, including the cPanel blog.

That’s not to say WordPress is the only option for building a business site or even the best option in every case. There’s a lot of competition from content management systems such as Joomla and Drupal, hosted platforms such as Squarespace® and Wix, and static site generators such as Gatsby and Hugo.

Each one is excellent in some scenarios for some users, but WordPress has risen to immense popularity because it hits the sweet spot for a wide range of business hosting contexts.

Businesses use WordPress to build:

  • Marketing and lead-generation websites
  • Blogs
  • Portfolios
  • Ecommerce stores
  • Knowledgebases
  • Customer support sites
  • Media hosting sites

As we move into the top 5 reasons to choose WordPress for your business, let’s clarify exactly what we’re talking about. There are two main ways to use WordPress, as a self-hosted CMS (WordPress.org) and via a hosted SaaS platform (WordPress.com). We’re focused on self-hosted WordPress: businesses take the WordPress software and host it on a server or WordPress hosting account under their control.

WordPress Business Site

WordPress is Free and Open Source

WordPress is an open-source content management system. It’s developed by a project that anyone can contribute to. The code can be inspected and changed to suit individual users. And it’s free; you can download WordPress and install it on a server without paying a cent.

We’ve got nothing against paying for software. Some of the best software in the world uses a paid licensing model because it’s the best way to provide high-quality tools and support to customers. However, there are advantages to using open-source software in your business.

Because WordPress is open-source, businesses are free to use it in any way they like, which gives them complete control over their site. It can be extended, modified, and customized to suit their use-case. It isn’t tied to a particular vendor, so they are free to host their site wherever they want and move it when they want. You can trust that your WordPress site will be usable for many years to come because you control the code.

WordPress Hosting is Under Your Control

WordPress is simple and inexpensive to host. It needs a server with PHP, a MySQL database, and a connection to the internet. That means you can host WordPress on anything from a low-cost shared hosting account to a virtual private server to a dedicated server or even a cluster of servers for the largest sites.

Because WordPress doesn’t have special requirements and depends only on easily available software and hardware, users are free to choose any WordPress hosting provider and move between providers at will. That’s not true of many SaaS alternatives where close integration between the software and hardware makes it challenging and expensive to migrate.

WordPress is Adaptable and Extensible

The theme and plugin ecosystem is one of WordPress’s biggest strengths. Plugins empower users to customize and add features to their site, from small conveniences to transformative add-ons like the WooCommerce plugin, which turns WordPress into a powerful ecommerce platform. Developers have created tens of thousands of plugins, both free and premium.

Themes determine WordPress’s appearance and influence the user experience. Do you want to build a store, a portfolio, a blog, or a marketing site? Do you like minimalism, bold colors and typography, or a design dominated by full-bleed images? Changing a site’s look is as easy as installing a different theme. There are thousands of free themes and an enormous variety of premium themes to choose from. If you want something unique, you can make your own or hire someone to do it for you.

WordPress’s extensibility goes beyond themes and plugins. It also features a comprehensive REST API to integrate third-party tools and “remote control” the CMS. We wrote about the WordPress REST API in How To Use WordPress as a Headless CMS

WordPress Support and Tooling are Widely Available

Because WordPress is so popular, businesses have no trouble finding documentation, support staff, or developers to help them build and look after their site. The project prioritizes user-friendliness, so day-to-day site operations don’t require in-depth technical knowledge. The official documentation and masses of free online support content may well be all you need.

However, if you would like help from an outside expert, WordPress professionals are easy to find and relatively inexpensive to hire compared to professionals who work with other content management systems.

Widespread integration support is another side effect of WordPress’s ubiquity. Your web management, customer relationship management, marketing, communication, and content production tools almost certainly offer WordPress integration, either natively or via a plugin.

For example, our very own WordPress Toolkit is a comprehensive management interface that simplifies the installation and maintenance of multiple WordPress sites. Learn more in The Evolution of WordPress Management with cPanel.

WordPress Toolkit Overview

WordPress is Accessible

Accessibility and inclusivity should be a top priority for any business site. Sites that don’t prioritize accessibility risk excluding millions of people with vision and mobility impairments. The WordPress project enforces accessibility standards to ensure that it conforms to WCAG 2.1 guidelines at level AA.

In practical terms, that means WordPress is keyboard accessible and navigable, accessible to screen reader users, and maximizes the visibility of on-screen components. Third-party plugins and themes may not be built with the same care, but WordPress itself provides a solid foundation for a business site that meets the needs of all your customers.

Is WordPress the Right Choice for Your Business?

As we said at the beginning of this article, WordPress is far from being the only choice when building a business website. It’s worth taking the time to explore all of the options available to you. However, if you are looking for a flexible, extensible, and accessible content management system that can scale from solopreneur to multinational corporation, you won’t regret choosing WordPress.

As always, if you have any feedback or comments, please let us know. We are here to help in the best ways we can. You’ll find us on Discord, the cPanel forums, and Reddit. Be sure to also follow us on FacebookInstagram, and Twitter.

How To Use A Remote MySQL® Database With cPanel

The MySQL database server is a core component of millions of content management systems and ecommerce apps. It provides the secure and reliable data storage and retrieval that makes dynamic, personalized websites possible. cPanel & WHM is a complete MySQL management solution that automates many common web hosting database tasks while offering fine-grained control to web hosts who need it.

Typically, websites and cPanel’s MySQL instance are installed on the same server. However, it’s sometimes useful to separate them so that sites use a remote MySQL database hosted on a different server.

You might use a remote MySQL server to:

  • Offload database workloads from the webserver to improve the performance of busy sites and the database.
  • Use a server specifically configured for database hosting.
  • Centralize database management for multiple servers.
  • Isolate the database from servers accessible via a public IP address.

The wrong way to achieve remote database access is to expose the MySQL server to the internet and allow it to accept connections from untrusted IPs. As you may appreciate, this method creates a critical security vulnerability that is often exploited to steal sensitive data.

In this article, we’ll show you how to do it the right way, using cPanel to securely configure MySQL to accept connections from web applications hosted on different servers.

Using a Remote Database to Host Your Site’s Data

To follow this tutorial, you will need:

  • A server with cPanel & WHM installed. This will be the remote database server.
  • The database server’s IP address or domain name, cPanel authentication credentials, and MySQL username and password.
  • A server on which to install web applications. The method we’re about to describe will work if you install and configure sites manually, but it is faster and more convenient with cPanel.

First, we’ll explain how cPanel users can configure a remote MySQL database before looking at WHM’s MySQL Profile management tools.

Configuring a Remote MySQL Database with cPanel

Log in to cPanel on the server with the MySQL instance you would like to grant access to. Select the Remote MySQL® tool from the main page menu.

cPanel Menu Remote MySQL

In the Add Access Host form, enter the domain name or IP address of the server that hosts the web application. You can add a wildcard (%) to allow multiple IP addresses to access the database; for example, 192.68.0%. When using a wildcard, be sure to limit the scope to addresses under your control or that you are confident pose no security risk.

cPanel Remote MySQL Manager

Click the Add Host button, and cPanel configures the MySQL database to accept requests from the remote site.

Next, you should configure the site to use the remote database. The process differs depending on the application. For example, on a newly installed WordPress site, you would first create the database in cPanel’s MySQL® Database Wizard

Then, edit the WordPress site’s wpconfig.php to include the database name and authentication credentials, as well as the server’s domain name or IP address.

define( 'DB_NAME', 'wp_database' );
define( 'DB_USER', 'user' );
define( 'DB_PASSWORD', 'a-secure-password' );
define( 'DB_HOST', '203.0.113.0' );

Adding MySQL Access Hosts in WHM

System administrators can also configure MySQL to accept incoming connections from sites hosted elsewhere. There are some differences between cPanel and WHM where remote database access is concerned:

  • Hosts added in WHM are applied to all cPanel user accounts and the MySQL users associated with those accounts.
  • cPanel users cannot permanently remove hosts added by system administrators in WHM.

To allow remote hosts to access MySQL databases, navigate to Additional MySQL Access Hosts in the SQL Services section of the sidebar menu.

cPanel Additional Access Hosts

Enter the domain names or IP addresses of remote hosts that should be allowed to connect to the server’s databases and click save. To begin to use databases on the server, you should configure your sites with the relevant IP address and authentication credentials, as described in the previous section.

To learn more about database access hosts, take a look at the feature’s documentation page.

Managing MySQL Profiles in WHM

In addition to configuring remote databases in cPanel & WHM, server administrators can create MySQL profiles in WHM to connect with remote database servers. A MySQL Profile allows administrators to define the remote database used throughout cPanel & WHM; in fact, the local machine’s default database is configured via a profile.

Profiles can be used to configure several types of remote databases, including those running on other cPanel & WHM servers, dedicated MySQL servers, and databases running on Amazon’s Relational Database™ Service.

Before you create and activate a new profile, you should be aware that only one MySQL profile can be active at any time. To add a new profile, log in to WHM and navigate to Manage MySQL® Profiles under SQL Services in the sidebar menu.

cPanel WHM MySQL Profiles

WHM can log in to the server, create a new MySQL superuser to manage databases, and configure MySQL. If you have already configured the MySQL installation with a superuser, you can add those details instead.

cPanel New MySQL Profile

Once you have activated the profile, new databases are created on the remote server. However, existing databases are not automatically migrated, and you will need to transfer data manually.

cPanel & WHM gives web hosts and their clients incredible flexibility when configuring and managing MySQL databases. They can take advantage of:

  • Outstanding out-of-the-box defaults for hosting MySQL databases on the local server.
  • Easy database configuration for sites and stores hosted on remote servers.
  • System administrator tools that give admins complete control over MySQL and where their databases are hosted.

As always, if you have any feedback or comments, please let us know. We are here to help in the best ways we can. You’ll find us on Discord, the cPanel forums, and Reddit. Be sure to also follow us on FacebookInstagram, and Twitter.

Adding cPanel University Certifications To LinkedIn

LinkedIn is the social network for, well, professionals. Whether you’re looking to secure your next job or establish yourself as a thought leader within your current position or industry, LinkedIn is the place where you want to put your best professional foot forward.

For anyone unfamiliar, cPanel University is a one-stop shop for training and certification on all things cPanel & WHM, including technical issues and sales courses.

Becoming a cPanel Certified Partner not only earns you the esteem of your colleagues and industry, but includes other benefits like having your support requests automatically escalated to our Ultra Priority Technical Support queue.

Your cPanel University Certificates

Accessing your existing cPanel University certificates is quite simple. Literally all you need to do is type your name into the search box located in the upper right-hand corner of https://university.cpanel.net.

Click on the results for your name, and you’ll then be shown any/all certificates that you have earned, both Active and Expired:

cPanel University Certificate Search Results

You can then copy and paste the CERTIFICATE ID into the same search bar to be shown the details and verify validity of any individual certificate.

How To Add Certificates To LinkedIn

Now that we know how to locate our cPanel University certifications, it’s time to share these credentials with the rest of the world. The first step is to ensure you have the “Licenses & certifications” section enabled on your LinkedIn page. If you do not, just click the “Add profile section” dropdown just below and to the right of your profile picture, then click “Licenses & certifications”:

LinkedIn Licenses and Certifications

You’ll now be able to scroll down to the Licenses & certifications section of your LinkedIn page and click the + symbol. Here is where you’ll provide the information the we located above for your cPanel certification(s).

And once you’ve entered the necessary information, and clicked “Save,” your certification will now be proudly displayed on your LinkedIn profile for all to see.

LinkedIn Certification

You can repeat this process for any other certificates you may have. A robust LinkedIn profile will only benefit you in your pursuit of any professional goals.

As always, if you have any feedback or comments, please let us know. We are here to help in the best ways we can. You’ll find us on Discord, the cPanel forums, and Reddit. Be sure to also follow us on Facebook, Instagram, and Twitter.

https://www.linkedin.com/help/linkedin/answer/44644/add-edit-or-remove-certifications-on-your-profile