cPanel Integration

Developing with LiveAPI

2012-04-02T08:58:45Z

In earlier versions of cPanel, developers included a script called LivePHP. This technology is essentially an internal window on the server to make API 1 and API 2 calls to the local machine via a socket to cpsrvd. Through LivePHP, you could use API functions through API tags and our Remote XML or JSON API. This is the suggested best practice for accessing cPanel functionality from your Plugins for reasons of simplification and also reducing network overhead.

Where previously the Live environment only included PHP, we have now expanded it to include multiple languages, Ruby, Python, Perl, as well as PHP; and have renamed it LiveAPI.

cPanel ships with example scripts for both PHP and Perl. Both scripts can be found in the x3 directory (/usr/local/cpanel/base/frontend/x3/) of your cPanel installation. The scripts are named test.live.php and test.live.pl.

For reading about specific module usage for LiveAPI, please see our documentation. Or if you have usage questions along the way, please feel free to post in our developer forums where we have dedicated cPanel development staff available to help.

Create Custom cPanel Modules

2012-02-22T12:55:54Z

Nearly all cPanel actions are governed by cPanel API1 and API2 functions.

For your application, instead of creating your own API from scratch, we're created the ability to add your application's logic to the cPanel XML/JSON API. Essentially speaking, your custom cPanel Perl Module can create a remote window of access to your application's functions to be used through the XML/JSON APIs, LiveAPI, or cPanel tags.

The ability to build and use Custom cPanel Modules is available in all current versions of cPanel.

We've updated [our documentation] <- (http://docs.cpanel.net/twiki/bin/view/SoftwareDevelopmentKit/WritingCpanelModules) and have provided a complete, working example of a [custom cPanel Perl module] <- (https://github.com/CpanelInc/Custom-cPanel-Module), available for download on [our Github account] <- (https://github.com/CpanelInc). This example Perl module, it's inline comments and POD documentation, along with prior existing documentation, should provide a great resource for anyone wishing to leverage the cPanel API!

Test it in the User Interface

2012-02-22T12:53:27Z

After spending time in the Developer section of the cPanel Community Forums, we've found a commonly asked question: "Why won't my script work with XYZ function using the XML/JSON-API?"

Rewinding a bit, the purpose of the XML/JSON API is to allow usage of cPanel & WHM functions through applications or scripts. Naturally, the first question we often ask, when trying to figure out why a script isn't working, is if the user is trying to do something that they couldn't normally do through cPanel & WHM.

For example, let's say you're trying to park a domain on top of an existing domain. Parking a domain is like adding an additional domain name for the same content in your hosting account. Given this option is allowed by your hosting provider, the first thing to do would be to attempt to add the parked domain through cPanel. Running through the process of parking the domain through cPanel will give you, the user, a good sense of what's actually happening when parking a domain.

After testing through the interface and finding out more about the function, the next step would be to consult our documentation at sdk.cPanel.net to find more about the module name and function. Following the parking a domain example, <a href="http://docs.cpanel.net/twiki/bin/view/ApiDocs/Api2/ApiPark" target="_blank">we find in the documentation</a> that the name of the module is "Park", with function "park". (On a side note, there are also other functions available within the Park module, including "unpark", "listparkeddomains", and "listaddondomains".)

In this case, we're only interested in using the "domain" parameter, since we're wanting to park the new domain on the primary domain for the account. If the user wanted to park a domain onto a subdomain in the account, the user would also use the parameter, "topdomain". This parameter would contain the name of the subdomain to attach the new parked domain to. Often, the error in the script has to do with incorrect parameters, or the order of parameters (for API1 functions) within the array.

So after testing the function through cPanel, then making sure you have the correct parameters passed in through the XML/JSON-API, you should be well on your way to troubleshooting your script.

Making your script work with security tokens in cPanel & WHM

2012-01-12T13:51:00Z

What is a security token?

“Security token” URLs were added in cPanel & WHM 11.25 as a security measure, and they were enabled by default in version 11.28. They help combat a common type of attack called a Cross-Site Request Forgery (XSRF).

So, what does a “security token” look like? Take, for example, this URL:

https://example.com:2087/i/love/cpanel

With security tokens enabled, this would become:

https://example.com:2087/cpsessYYYYYYY/i/love/cpanel

In that example, cpsessYYYYYYY is the token unique to that logged-in user on that browser.

(You can learn more about security tokens in cPanel & WHM by reading our Security Tokens white paper.)

In order for your custom script to work with cPanel & WHM, every URL involved needs to be compatible with the security token.

Creating security token-compatible URLs

Fortunately, it is very easy to do!

The token is available in the environment variable 'cp_security_token'.

If security tokens are not in use, 'cp_security_token' will be an empty string.

If security tokens are in use, 'cp_security_token' will be, in terms of the above example: /cpsessYYYYYYY

Note the preceding slash! Since the variable has that slash, the examples will work whether cPanel & WHM has security tokens enabled or disabled.

Here's how you'd use it in Perl code that calls one of our API URLS.

Simply change this:

my $APIurl = "http://127.0.0.1:2087/xml-api/$url";

to this:

my $APIurl = "http://127.0.0.1:2087$ENV{'cp_security_token'}/xml-api/$url";
Here's how you might use it in JavaScript for, say, an AJAX call.

First, make it available to your JavaScript. For example:

print <<"END_SECURITY_TOKEN_JAVASCRIPT"; <script type="text/javascript"> if ( !("CPANEL" in window) ) CPANEL = {}; CPANEL.security_token = "$ENV{'cp_security_token'}"; </script> END_SECURITY_TOKEN_JAVASCRIPT

Next, make your URLs compatible by changing this:

var ajaxURL = '/3rdparty/ZZZ/zzz.cgi';

to this:

var ajaxURL = CPANEL.security_token + '/3rdparty/ZZZ/zzz.cgi';

LivePHP

2011-10-05T18:44:11Z

Currently, if you want to write a Plugin for cPanel, you can write it in either LivePHP or cPPHP. Last year, we put some major effort into refactoring LivePHP. We added better debugging information, optimized the socket communication protocol, and added a few other tweaks. After a year of vetting by external developers, I can say with confidence: there is no longer any reason to use cPPHP when developing your application.

cPPHP is a system that requires cPanel to parse cPanel tags and then run the result through the PHP interpreter. Alternately, it can run your code through a PHP interpreter, then parse out cPanel tags, depending on file extension. This system has a few major disadvantages.

Consider the following standard use case:

* Grab information from database
* Perform API call based on information from database
* Update database

While in most ecosystems this is a very simple process, cPPHP does not make this easy because it required two separate pages. Once cPanel switches from one parsing engine to the other (e.g. PHP to cptags) there is no way to switch back. This means that to switch back, you have to grab the information from the database, POST that information to a second page, perform the API call, and then process it. This is not an ideal scenario for any plugin and leads to some ugliness that the end user doesn't need to see.

Another problem with cPPHP is that the templating engine uses a proprietary format. While this format may work for our needs, it simply isn't reasonable to expect a third party developer to write the following code to make & display an API call:

<?cp StatsBar::stat([tr class="row-%"][td class="stats_left"]%[/td][td class="stats_right"] % / %[br /][div class="stats_progress_bar"][div class="cpanel_widget_progress_bar_percent" style="display\{colon}none"]%[/div][/div][/td][/tr],rowtype,item,count,max,percent) display=diskusage|bandwidthusage,infinitylang=true,rowcounter=mainstats >

At least without wanting to tear their hair from their heads.

LiveAPI (aka LivePHP) resolves all of these problems.

LivePHP provides an object for interfacing with LiveAPI. This API is a heavily optimized version of our XML API's cpanel call. LiveAPI works by having an object, abstracted into a class, you can use to access cPanel's API over a socket connection. When a LivePHP process is launched, cPanel forks itself into a special "LiveAPI" mode that acts as the socket server while the PHP script acts as a client sending commands to the server.

This solves both of the aforementioned problems. For the first case, when we wanted to grab information from a database, the interaction becomes simple. We begin by calling the database object, then call the LivePHP object, and finally call the database class again.

When calling API2, LivePHP will return the same data that's returned by the actual API call, wrapped in some metadata. All of this data is in the same format that is used by our XML API cpanel call ). This allows you to format the data using whichever templating engine you prefer. This is a much cleaner method than the old cPPHP system. API1 calls return the same data structure through LiveAPI. The main difference is that the node containing the response data will contain a string rather than an array.

One of the major misconceptions I hear about LivePHP is that it can't be branded. While this was true 2 years ago, before we optimized the system, it isn't an issue now. The problem with branding used to be that calls tended to involve making an API call that had to make an API call. This caused problems with the serialization method we used, resulting in quite a few ugly nested cpanelresult data structures.

These days, it's quite simple to brand LivePHP. For example, the following code will result in a branded LivePHP page that you can work with:

<?php include("/usr/local/cpanel/php/cpanel.php"); $cpanel = new CPANEL(); $res = $cpanel->api1('Branding', 'include', array('stdheader.html') ); print $res['cpanelresult']['data']['result']; ?> <div class="body-content"> Hello World! </div> <?php $res = $cpanel->api1('Branding', 'include', array('stdfooter.html') ); print $res['cpanelresult']['data']['result']; $cpanel->end();

As you can see, LiveAPI is a much more straightforward approach to the cPTags system. We have found LivePHP to be a much more robust system for developing cPanel plugins in PHP.

Why you should use RPMs to distribute your application

2011-09-14T18:02:21Z

As a developer, it is important to understand who you are developing for. When developing an application for cPanel & WHM servers, there are 5 potential customer profiles to be aware of:

Data centers
Developers
Website owners
System administrators
Hosting providers

Understanding these profiles will help you scope and define a project.

In this article, we will focus on Data centers and the various problems you might encounter when working with them.

Data centers make up a nice segment of the cPanel & WHM customer base. They include the likes of SoftLayer, InMotion Hosting, Knownhost, SingleHop, as well as a long list of our worldwide hosting providers. These organizations have spent a considerable amount of time automating server, cloud and VPS deployments. As an application developer, being part of the deployment process is important.

Automated server deployments come in many shapes and sizes, but the important thing to remember is to avoid having a manual installation step as part of the deployment process. Imagine deploying thousands of servers each month and having to log into each in order run a manual installation at the end. This is a real problem for streamlined product delivery. Overcoming this problem can help you, the application developer, gain access to a core distribution channel.

The ideal scenario is getting your application integrated with the deployment, or ordering, process. By this I mean when a potential data center customer is navigating the ordering system, your application becomes a selectable configuration option included with the server purchase, and it is automatically installed and configured. Without automation capability you will have to overcome the challenge of convincing the data center to manually install and configure your application, for each customer who requests it. The closer you can get to achieving automated deployments, the more interested data centers will be in your product.

One way to resolve this problem is to distribute your application as an RPM. An RPM allows the data center to automate installation and configuration at deployment time, without investing resources in working with a variety of third-party applications, each with their own peculiar method of installation and configuration. Decreasing the amount of work involved for a potential customer or client will increase the likelihood of their being willing to distribute your application.

There are other advantages, as well as disadvantages, to using RPMs for your application installation. RPMs are a standardized package format on the Linux platform. This means that Linux-based cPanel & WHM servers come standard with tools to manage RPMs from the command line. Such systems also provide a means of integrating custom RPMs at operating system installation time — for example, using kickstart profiles.

A disadvantage of using RPM is it locks you out of the small part of the cPanel & WHM server base that does not use an RPM package format. While that portion of the server base is expected to diminish over time, excluding yourself from some customers is something to consider.

There is more work involved in packaging your application as an RPM than as a tarball. There are numerous resources available to help you learn and overcome these challenges, such as the book Maximum RPM.

Once in the deployment process, an issue can arise if your application is installed too soon in the process. For example, if your application requires the basic cPanel & WHM setup to first be performed, there may be insufficient data in /etc/wwwacct.conf for your application’s needs. A resolution for this problem is to create a WHM Plugin that handles the configuration of your application. This way, your configuration step can be performed after the WHM Initial Setup Wizard has been run.

Spotlight On: Creating DNS Modules

2011-08-24T15:59:04Z

In cPanel & WHM 11.30, we added the ability to add 3rd party systems to your DNS cluster. With this ability, we added functionality that allows you to create dnsadmin plugins. You can use these plugins to control and configure remote nodes of your DNS cluster. The plugins themselves consist of a few Perl modules. Creating a dnsadmin plugin will require some familiarity with Perl.

To begin building a dnsadmin plugin, please read the documentation.

Enkompass 2.0, now with new integration features...

2011-06-17T20:54:13Z

Announcement:

With the release of Enkompass 2.0 on Tuesday, several exciting new integration features are now available.

XML API for Enkompass - Crafted to be familiar to our existing cPanel XML API users. We provide comparable functionality. Extensions to the API for the Enkompass specific functionally.

XML API Developer Page - Try out the API calls from the developer page access in System Administration Interface (SAI) by logging in with your account and using this link:

http://<your Enkompass server>:2086/API/xml-api/

These developer pages include complete self-documentation for this API as well as test pages for each available function.

Remote Access Keys - A new interface for configuring remote access keys for XML API authentication have been added to the System Administration Interface. To access this tool, type "remote access" in the find box of the System Administration Interface. Remote access keys can be setup for any account in Enkompass. These keys have an added security feature, you can set a start and end date for the key allowing you to provide limited time access to the XML API.

Hooks for the Enkompass API - We designed a framework for intercepting pre and post API calls to the Enkompass Core services. The framework we developed comes with two out of the box solutions: Command Hooks and URL Hooks. If these implementations do not meet your needs, the framework was designed with extensibility in mind. For more information check out the documentation at:

http://go.cPanel.net/enkwcfhooks

Coming Soon:

The Enkompass team is hard at work building the Addin interface for the Enkompass applications. With the Addin system, third party tools designed to work with Enkompass can be added to the System Administration Interface, Web Site Owner Interface, and Mail Owner Interface. I'll have more information on this soon.

BETA Release of PublicAPI PHP, the cPanel PHP Library, and cPanel PEAR

2011-04-08T13:52:19Z

We are pleased to announce that our PublicAPI PHP client is ready! This API query client is the sibling to Cpanel::PublicAPI that was announced last month.

You can download the PublicAPI PHP client at our github repository as well as the new cPanel PEAR channel.

One of the key distinctions of the PublicAPI PHP client class is that it's distributed as part of the cPanel PHP Library. The cPanel PHP library is a collection of PHP classes for interfacing with cPanel systems.

When we began working on the PublicAPI PHP client, we had three goals in mind:

Create a PHP-based API client for developers that adheres to the PublicAPI interface
Provide compatibility with existing scripts that use the XML-API client
Provide support for LivePHP

Because LivePHP and XML-API work on two different query mechanisms (file sockets and HTTP, respectively) it was immediately apparent that the code responsible for transmitting and receiving the server response would need to be abstracted.

We also had to consider that the Public API, XML-API, and LivePHP interfaces defined their own set of query methods. This meant that any instance of the client object would need to be smart enough to know about each interfaces' methods, understand their context, and validate each methods' arguments.

The most direct solution would have been to lump all of the query calls together in one class. However, this solution would have put us back to square one if a new interface or cPanel service were to be introduced. Instead, we made a series of inherited models that would function 'under the hood,' while the 'top' would be a customizable object that could be tailored as necessary.

Long story short, about 2000 lines into it, we realized that this was no longer a client but a full-fledged library — a group of components that are (mostly) decoupled. The result being that any one or more components can be used to build an entirely different client or application. Thus, the cPanel PHP Library was born.

The README.markdown file in the repo (also in the PEAR package) offers a good summarization of what is included in the distribution as well as an introduction to the cPanel PHP Library and PublicAPI. Please take the time to read that file and checkout the Examples/ directory in the distribution.

As an example, here is a little script I wrote while answering a quick forum post related to Analog Stats queries via API1 and API2:

<?php
require_once 'Cpanel/Util/Autoload.php';
$hash = file_get_contents('/root/.accesshash');
$cfg = array(
    'service' => array(
        'whm' => array(
            'host'=>'127.0.0.1',
            'user'=>'root',
            'hash'=>$hash,
        ),
    ),
);

$cp = Cpanel_PublicAPI::getInstance();
// just a quick poll of what cPanel version I'm running
$response = $cp->whm_api('version');
echo "Version: {$response->version}\n";

// Test the output of API2 Stats::listanalog
//   call should produce a list of domains that have stats
$mf = array(
    'module' => 'Stats',
    'function' => 'listanalog',
    'user' => 'cppirum',
);

$api2_list = $cp->cpanel_api2_request('whostmgr', $mf);

echo "List from API2 Stats::listanalog\n";

/**
 * For debugging I could just dump the "array" format
 *  var_dump ($api2_list->getResponse('array'));
 *
 * But I'd rather have a nice loop on the object
 */
foreach ( $api2_list->cpanelresult->data as $stat_holder) {
    echo "\tDomain '{$stat_holder->domain}' has stats.\n";
}
echo "\n";

// Same thing here, only we'll look at API1 Stats::analoglist, which generates HTML

$mf = array(
    'module' => 'Stats',
    'function' => 'analoglist',
    'user'=>'cppirum',
);
// This API call requires a domain
$args = array('pear.cppirum.net');

$api1_list = $cp->cpanel_api1_request('whostmgr', $mf, $args);


echo "list from API1 Stats::analoglist\n";
$html = $api1_list->data->result;
$xml = '<?xml version="1.0"?><root>' . trim($html) . '</root>';
$sxml = simplexml_load_string($xml);
foreach ($sxml->a as $url) {
    $attributes = $url->attributes();
    echo "\tStats for {$url} can be found at 'https://{$args[0]}:2083{$attributes['href']}'.\n";
}
echo "\n";
?>

As you can see, I used the the whm_api(), cpanel_api1_request(), and cpanel_api2_request() query methods of the PublicAPI interface. The arguments for each of those methods are the same as in the Perl PublicAPI client.

Download it and give it whirl. This is BETA software so you may encounter some quirky behavior. If you experience any problems, please let use know by using the github issue tracker. There are several features within the library that we hope to refine, as it matures to a STABLE release over the next several months.

In the coming days, we hope to provide more detailed documentation on sdk.cpanel.net concerning PublicAPI (Perl and PHP) and the cPanel PHP library. In the meantime, you can checkout the POD (Perl) and DocBlock (PHP) documentation that's included in the code.

Regards & Happy Coding!

Introduction to cPanel & WHM APIs

2011-03-25T11:45:00Z

Application Programming Interfaces (APIs) are fundamental to the cPanel & WHM product. APIs allow developers to perform actions (functions) that source and manipulate data related to cPanel accounts and system utilities. Our APIs are used by the cPanel developers when designing new features and interfaces but are also available to 3rd-party developers. In this post, we'll review the various APIs associated with cPanel and WHM and how you can use them in your own development.

There are two APIs that affect the cPanel user space: API1 and API2. These APIs are used throughout the cPanel interface. In fact, every cPanel interface (i.e., all themes, branding, and pages served in a descendant direct of $server/base/frontend/ ) use these APIs alone to present and alter the end-user's environment.

API1 and API2 each have their own set of modules*. Within each module, there is a set functions. For instance, API2's 'Email' module contains a function called 'listpopswithdisk' that will list all the details for all of the pop email accounts associated with a cPanel username. API1 modules are listed here and API2 modules are listed here.

There are two common, false assumptions about API1 and API2 that confuse many newcomers to cPanel development. The first common misconception is that API1 begat API2. API1 and API2 are not ancestrally related. It is true that API1 was the first publicly available API in cPanel;however, development on API2 did not occur after API1. Both versions of the API were concurrently developed for several years. API1 is considered fully matured at this point in time. Active development has stopped, but API1 is maintained for bugs, security, and (as necessary) forward compatibility. The second common misconception is is that all API1 modules (and their functions) are available in API2. Sometimes, I hear the opposite, that all API2 module and functions are available in API1. Neither of these statements are true. Both API1 and API2 have their particular modules (and their functions) due, in large part, to the organic growth of the cPanel & WHM product. It is not uncommon for a module of the same name, present in both API1 and API2, to have different functions. It most cases, if a particular function exists in both API1 and API2, we recommend using API2.

API1 was originally designed to be a front-end-only API for use in cPanel pages. Because of this, API1 calls print their output directly to STDOUT. In various parts of the product, that output is suppressed or redirected due to the context of its usage. However, this is the exception to the rule and wouldn't occur within a cPanel end-user interface. Since API1 was designed for use by a browsable interface, it is not out of the ordinary for an API1 function to generate a snippet of HTML**. API2, on the other hand, always returns a Perl hash structure. While this makes getting raw data much easier, it adds a layer of complexity for front end developers. (But it's so much more flexible! Which is why we prefer API2 functions where possible). Both API1 and API2 calls can be accessed within cPanel pages and their front end usage is described here and here, respectively.

The XML-API can perform actions that are found within the WHM interface. The XML-API was written specifically for remote interactions with cPanel & WHM. That means that a developer must make an HTTP query to invoke the desired function. While the XML-API covers a lot of functionality, the breadth of utility does not cover as much ground as API1 and API2. so the function sets aren't compartmentalized into modules. However, in our documentation, you will find those functions within logical groupings, like "Account functions" and "SSL functions."

The XML-API, like the name suggests, will return XML formatted results. We also offer a JSON version. The interface (aka, HTTP request format) is the same, it's just a different path in the URL. Unconventionally, it is completely commonplace to see both the XML and the JSON response/query types referred to as XML-API, despite the obvious discrepancy in the API's name.

As it was mentioned earlier, the XML-API can source and manipulate data similar to actions found in the WHM interface. Informally, we call these XML-API functions "native" since they are built right into the XML-API query parser. These native functions are performed as the authenticated, privileged WHM user, namely "root" or a reseller account. This is an important distinction since the XML-API can also perform cPanel actions as a privileged user or end-user! The XML-API can be used as a proxy for API1 and API2 functions. This proxy style query parser is available to all users. If a privileged user makes an API1 or API2 call via the XML-API on either the WHM or cPanel ports, the action will be performed as the user they specify, provided they clear any relevant ACL checks. If a cPanel end-user makes an API1 or API2 call, authenticated as themselves, via the XML-API on a cPanel port, it will perform the action as if from a cPanel page. Details about invoking the XML-API are here. Specific information about calling API1 and API2 functions via the XML-API can be found here.

There is one other API currently available to developers that should be mentioned. The Manage2 API provides the utility for managing cPanel licenses. The Manage2 API is primarily for those interested in creating a custom interface for viewing and updating their cPanel licenses. Being an HTTP query, these functions are queried in a similar fashion to the XML-API. The response can be formatted in XML, JSON, or YAML. The Manage2 API is documented here.

In case you missed Matt Dees' post from earlier this month, he announced the official release of cPanel::PublicAPI. It's available for download on CPAN and our Github repository. This is an excellent package for querying these APIs (and some other stuff too) in Perl. For PHP folk, we have the XML-API PHP client class, available on our Github repository.

There is always good information and helpful people in the Developer Discussions forum. Please don't hesitate to ask questions or make comments. We really appreciate the input as we review our previous implementations and design new ones. This year promises to be filled with lots of new integration utilities and functionality, so stay tuned!

* The API1 and API2 modules are called "modules" because of their correlation to the "Cpanel" Perl module namespace. However, these API calls actually pass through a request parser before action is delegated to the end Perl subroutine. So, there wouldn't be a one-to-one relationship with the API module/functions and the Perl module/subroutines.

** If a particular API1 call renders HTML, it is likely to do the same in the body of an XML-API request too. Since HTML is not XML, but the entire response will likely be treated as such by an XML parser, be careful as you might not receive a well-formed response.

cPanel::PublicAPI

2011-03-07T17:42:06Z

Today I posted cPanel::PublicAPI to github.  This is a set of perl modules that allows for easy access into cPanel's APIs from a simple object interface.  This module offers several great features:

* Auto-detection of credentials (when available)

* Support for cPanel's DNS Clustering API

* Support for: cPanel, WHM, webmail and non-cPanel services.

* Minimal dependencies

* BSD Licensed

To get started, you can install cPanel::PublicAPI via CPAN the source is also available on our github repository if you wish to submit patches/changes. I strongly suggest reading the documentation on CPAN to get started.

The following is an example of how to query the XML-API's listaccts() call using PublicAPI (on a cPanel server, running as root, and an accesshash exists):

#!/usr/bin/perl use cPanel::PublicAPI (); use Data::Dumper; my $pubapi = cPanel::PublicAPI->new(); print Dumper $pubapi->whm_api('listaccts');
To query a cpanel account with API2 while authenticated as root, you would do something like the following:

#!/usr/bin/perl use cPanel::PublicAPI (); use Data::Dumper (); my $pubapi = cPanel::PublicAPI->new(); # Create email account print Dumper $pubapi->cpanel_api2_request( 'whostmgr', { 'module' => 'Email', 'func' => 'addpop', 'user' => 'someuser', }, { 'domain' => 'myawesomedomain.com', 'email' => 'localuser', 'password' => 'AS(d0m9d0sad12ea!s', 'quota' => 42, } );

You may have noticed that you have to specify the service as the first parameter. It is important to note that even though you may be calling the cpanel API, if you are root or a reseller querying an account that is not the reseller account itself, you will still need to query the whostmgr service. This is because if you authenticate against the cpanel service, you will be querying your user, no mater which user you specify in the “config” hash.

If you don't want cPanel::PublicAPI to auto-detect credentials, you can pass in the user and pass:

my $pubapi = cPanel::PublicAPI->new( 'user' => 'someuser', 'pass' => 'sdfkklkasf' );
Or you can specify an access hash:

my $pubapi = cPanel::PublicAPI->new( 'user' => 'someuser', 'accesshash' => $contents_of_homedir_slash_dot_acesshash );

There are tons of other features within this module, I suggest starting out with the POD documentation for cPanel::PublicAPI and going from there. If you have any further questions, please post on our dev forums and we will be happy to help you.

cPanel 11.30

2011-02-25T21:48:26Z

The release of cPanel & WHM version 11.30 in EDGE is right around the corner. With this release we have made numerous changes, added a few features and fixed some bugs. Predominantly, these changes can be encompassed in a few bullet points:

Complete rewrite of update system
Addition of Cpanel::PublicAPI
Removal of Legacy Themes
Several new API calls

Though each of these changes may seem small when listed as bullet points, there are a few details that you, as someone who customizes or integrates with cPanel & WHM should be aware of.

Update System

The rewrite of the cPanel & WHM update system (or upcp) has been a major project of ours for quite some time now. There are numerous improvements in this version, including the addition of long term support, better logging and many other benefits for both users and developers.

Some parts of this change will have a major impact on developers. Most importantly, /scripts will be relocated to /usr/local/cpanel/scripts. When this happens, we will attempt to migrate the data in /scripts to /usr/local/cpanel/scripts and then backup /scripts and symlink /usr/local/cpanel/scripts to /scripts. There are a couple of scenarios where this will not happen:

if /scripts contains more than 5,000 files
if the size of /scripts is more than 100mB

In this scenario, an email should be sent to the user asking them to resolve the issue. The user should also be updated to the latest version of 11.28 (rather than 11.30). In a standard cPanel install, or even a heavily customized one, this should not be an issue.

Another major part of this change is the reworking of how RPMs are versioned with the product. Previously, an RPM has been tied to a specific tier. For example, exim may have a different version for EDGE and CURRENT. Now, the RPM version is tied to the version of the product. Thus,if you are running 11.30.3 in the EDGE tier or CURRENT tier, you will have the same version of exim. We will also be offering the ability to source RPMs from a custom repo. This means that, if you wish to provide your customer with your own version of ProFTPd or dovecot, it is now possible in a way that is supported (more on this in a future post).

Also, /etc/cpupdate.conf now uses a different format for determining the prescribed version. This file will break the update tier and update method into separate tiers. A valid cpupdate.conf will now look something like:

CPANEL=release

UPDATES=manual

Valid values for CPANEL are: stable, release, current, edge.

Valid values for UPDATES are: automatic, manual, never.

Addition of Cpanel::PublicAPI

cPanel & WHM 11.30 contains the first version of Cpanel::PublicAPI, a perl module capable of querying APIs from a single interface. This module deprecates the old Cpanel::Accounting module and offers a few new pieces of functionality:

Automatic detection of credentials (when available)
Interfaces for querying API1, API2, xml-api and our DNS clustering system
Full legacy support for Cpanel::Accounting

Eventually, a full set of modules will be available to query all of our APIs via any method available.

Removal of Legacy Themes

In cPanel & WHM 11.28, we dropped support for x, x2, bluelagoon and monsoon. Within the 11.30 release cycle, we will stop distributing them all together. If you develop a theme that is based off of one of these themes, we strongly suggest that you update to a theme using cPanel’s API2. If you require guidance updating your themes, you can always contact us via our ticket system.

New API Calls & Hook

We have added a few new API calls within version 11.30, specifically:

xml-api:

updateconfig - This call allows you to set your preferred release tier.

api2:

MysqlFE::adddb - Add a database

MysqlFE::adduser - Add a Mysql user

MysqlFE::adduserdb - Grant a user permission to access a DB

MysqlFE::addhost - Allow a new host to access Mysql

MysqlFE::deldb - Delete a database

MysqlFE::deluser - Delete a user

MysqlFE::delhost - Delete a host’s access

MysqlFE::deluserdb - Remove a user’s permission to access a database

Email::delforwarder - Allow deletion of Email Forwarders

Email::adddomainforward - Add a domain forwarder

Note: Documentation on these calls will be available once version 11.30 hits CURRENT.

Hook:

We have now added a “modifyacct” hook at /usr/local/cpanel/scripts/postmodifyacct and /usr/local/cpanel/scripts/premodifyacct. It will be passed all the new values for an account.

----

Questions or Comments can be left here

JSON vs. XML in LivePHP

2011-02-11T14:00:00Z

A while back, Matt Dees blogged about our upcoming change to LivePHP in 11.28. Specifically, he mentions the use of JSON. In this article I will illustrate, in brief, why this change was made. The decision process, as you'll see, wasn't exactly straight forward, but a solid compromise.

I'm not going to expound on the benefits or drawbacks of using XML vs. JSON as a format. We've see those debates for a while now in various online (and offline) venues. Instead, I'd like to talk about our choice to use JSON within LivePHP, based on data from a three point comparison we did.

First, let's go over some background information. The LivePHP class was originally written for PHP 4 compatibility. Those were the days when we couldn't depend on having a parser for XML or JSON readily available within a given PHP binary. One of the best options when we initially wrote LivePHP was to 'include' a pure PHP XML parser. But thankfully, PHP 4 has nearly gone the way of the dinosaurs and cPanel's internal build of PHP has been 5.2.x. for awhile now. This allowed us the opportunity to refactor the LivePHP class.

Once we decided to refactor the LivePHP class, we boiled our wish list down to two key points:

Reduce resource consumption.
Maintain backwards compatibility for anyone who relied on an external parser or any legacy code within cPanel that produces a particular output string.

Maintaining backwards compatibility for the cPanel strings was a fairly easy task. We knew that XML strings were always sent in the legacy code, so as long as we could detect a "pure" XML structure, we could use SimpleXML or the pure XML parsing functions that were already being shipped. But which one — SimpleXML or pure PHP? SimpleXML seemed like the obvious answer until we explored the full meaning of this compatibility goal.

Since we not only wanted compatibility on the string level, but also from the utility level, the idea of changing the external parsing functions needed more consideration and, as you'll see, compromise.

The likelihood that someone uses those pure PHP functions directly (in their own, neighboring code) is small. However, if we were to suddenly remove them or rewrite their internals, the potential risk of breaking someone's application seemed too great. And thus, we struck a compromise: we would ship the parsing functions as they had always been and simply create a logic flow within the class that would fallback to the old functions if a legacy-style string happened to come across the wire.

The other goal was to reduce resource consumption. The refactoring process was not only about optimizing the code, but also making it "better. " While evaluating this class, we found a ton of stuff that we wanted to change. In the end, we had to ask ourselves, "How can we cover the most ground while making the fewest changes?" Sure, there were plenty of other changes like more robust logging, conforming to standard PHP 5 class conventions, and a more PEAR-ish coding style that would eventually make it into the final revision of LivePHP. But really, the true gain would ultimately come down to dealing with the overhead of encoding and decoding the data stream. This is where a few simple tests helped us decide that PHP's native JSON functions would work best for us.

For brevity's sake, I won't include the actual code in this article. Fortunately, it's straight forward enough to describe the tests and present the results in a few charts.

We used two datasets, both based on real output from the Email::listpopswithdisk API2 function.. This function's return value is an itemized list of email account details for a cPanel account. The first set is very small; only two email accounts exist for the cPanel user. The second set is large, but not uncommon at 5000 email accounts for the cPanel user.

We'll compare three scenarios that all produce a PHP associative array:

JSON string decoded with "json_decode($str, true)" ["true" produces the array]
XML string decoded with the legacy pure PHP functions
XML string decoded with "simplexml_load_string($str)" [in a recursive callback to get an array]

The first, small dataset yielded mildly interesting results. The data makes it pretty clear that SimpleXML takes less memory at compile and execution time and during the life of the script. It also responds just as fast as the JSON.

However, in the large dataset, the results are a bit more intriguing. The JSON version is using more memory at the start of execution, but once the script is done, it consumes the least memory over time. As one might guess, the pure SimpleXML parsing consumes a noticeably larger amount of memory during its lifetime. The pure PHP XML functions perform well, but as a whole they just aren't as good as the native JSON parsing.

And then there's the execution time on the larger dataset...wow! The pure PHP XML functions are just atrocious in comparison to the other two methods. SimpleXML, while consuming 42% more memory, took twice as long as the JSON.

Ultimately, we decided that PHP's native JSON parsing was the best fit. We had several debates about the various permutations of these scenarios and dataset sizes. That is, with really small datasets, SimpleXML is the obvious tool of choice. We also did some analogous Perl testing to see how the other end of the system would perform. The results were conclusively in favor of JSON (we predominantly use JSON::XS nowadays). So, in the end, we came to the consensus that datasets tend to be larger rather than smaller and that execution time is the hardest resource to compromise. This makes JSON the best all around solution for LivePHP.

Maintaining Application Compatibility

2010-10-22T21:48:54Z

With version 11.28 of cPanel & WHM making it's way into the production update tiers, now is a great time to discuss your application testing strategies. It's every developer's responsibility to test and verify their applications within their actual deployment environments. cPanel & WHM is a constantly evolving product. With each new version we aim to improve not only the end user experience, but also its suitability as a platform for your applications. We work hard to maintain a stable and consistent application platform, but sometimes changes for the better will require an additional effort from developers. We want to ensure that those changes happen before our customers and your end users notice a problem.

Have you heard of a development license? cPanel offers a product license especially for cPanel & WHM application developers. You don't have to sign your life away or give up your trade secrets to qualify. We really just want you to work to extend the functionality of cPanel & WHM to meet your needs. One of the great things about the development license is that it allows you to have multiple environments to test your application. The only cost to you is in the hardware and connectivity. There are limitations of course, but they are very reasonable. You cannot use a development license to host paid accounts. There's also a small banner displaying that the server is running a development license in the cPanel & WHM interfaces. To apply for this license visit the Developer’s License Application page and answer a few simple questions. Once we have ensured the validity of your request, we will gladly provide you with a development license.

When testing your application, you should verify it against both production and development versions of cPanel & WHM. If you are unfamiliar with how the product is published then visit our page describing the cPanel & WHM versions and release process. In short, our EDGE releases represent the "cutting edge" version of the product and STABLE releases are our long-term support releases. If you notice a problem in any version then please contact us through oursupport system. We give developers high priority here at cPanel, and we will try to resolve your issue or answer your question as quickly as possible.

Developing and testing against both development and production releases will help ensure that your application will continue to work as you expect it for all your users.

Upcoming Improvements to LivePHP

2010-10-18T21:07:13Z

This past week, we have been working to improve livePHP. For those of you not familiar with livePHP, it is a PHP class that allows access to the cPanel & WHM API1 and API2 system within an object-oriented PHP environment.

We improved the backend of the livePHP system to use JSON for socket communication, which utilizes PHP’s native JSON internally. Our testing shows that this is a great deal faster (3X) than the previous XML-based serialization with custom PHP parsing functions.

Our intent has been to maintain compatibility with the legacy interface provided by the cpanel.php class. However when changes of this nature are made, there is always a possibility of conflict. If you have an application, either for your internal use or public distribution, then we would love to get feedback on how this change has improved your product. We recommend that you submit a support request directly to us, so that we can help coordinate your testing. Please reference this article so that we can ensure your request gets the priority it deserves.

It should be noted that this is not available in public builds yet, so a ticket will need to be opened in order to coordinate your testing.