At this point, cPanel’s APIs are not 100% documented. We are working on it and hope to have complete API docs up in a few months. I’ve written a CustomEventHandler that will print every API call made into cpanel’s error_log (/usr/local/cpanel/logs/error_log).
To use the API Tracer, you will need to download it, then place the Dumper.pm file at /usr/local/cpanel/perl/Dumper and the CustomEventHandler.pm file at /usr/local/cpanel/Cpanel.
Once this has been put into the proper location, cPanel will automatically start logging API calls to the error_log. To view each call, you simply need to run tail -f /usr/local/cpanel/logs/error_log and login to a cPanel interface to start seeing data. Continue reading
We have had a flurry of integration tickets over the past week, which is awesome to see. Most of these tickets have come down to a couple of basic problems. The first of which is due to some confusion about how to utilize HTTP to call an API function.The second problem appears to stem from a lack of information API troubleshooting tools that come with cPanel/WHM.
The first of our common problems stem from some basic confusion about how to utilize HTTP to call our API functions. The second of problem seems to come from a lack of information about how to use the tools that are available within cPanel and WHM for troubleshooting these API calls. Continue reading
This past week we have been working on documenting how to add icons and groups to cPanel without using our plugin generator. Writing DynamicUI files is a direct and flexible approach to adding custom groups, icons and extra logic not available through the plugin generator (boolean ExpVar checks, etc). During the course of documenting this, we realized that we also needed to document the variables available within the cPanel interface. These are referred to as ExpVar variables. These variable expressions internally parse the given reference and return the appropriate module output or dataset value. Example returns from ExpVar variables include information like configuration information, account limits and language tags. Very handy for creating your own cPanel interface.
Adding Icons and Groups to the cPanel Interface – This document is used for learning how to customize icons & groups within cPanel. Icons and Groups can be customized on a per-reseller or per-branding package basis.
DynamicUI Reference – This table explains all of the variables available within the DynamicUI system in a handy small reference-chart format.
ExpVar Reference – This table explains all of the variables available within the cPanel interface. These can be used in DynamicUI keys, inside of >cpanelif< tags and inside of <cpanel print=””> tags.
Some of the reasons why there hasn’t been many updates lately include our cPanel conference, the cPanel/WHM 11.25.0 release, and the release of the XML-API PHP class 1.0. If you are not familiar with the XML-API PHP class, it makes interacting with the XML-API much more simple by implementing functions that allow you to call your remote cPanel server without ever having to touch cURL or simplexml. This works by implementing a function for every XML-API call. For example:
$xmlapi = new xmlapi($ip, “root”, $root_pass);
$zones = $xmlapi->listzones();
The code above will make $zones a simplexml object that contains all of the zones on the server. This combined with proper data handling (encoding), the ability to return associative arrays, simplexml objects, raw JSON or raw XML makes developing PHP applications for the XML-API rather simple.
The biggest change in this version is the fact that the class is full documented, allowing you to access a quick reference for looking up these functions and how they work.
This version is a complete re-write from the previous version. The (partial) change log is below:
- Added in 11.25 functions
- Changed the constructor to allow for either the “DEFINE” config setting method or using parameters
- Removed used of the gui setting
- Added fopen support
- Added auto detection for fopen or curl (uses curl by default)
- Added ability to return in multiple formats: associative array, simplexml, xml, json
- Added PHP Documentor documentation for all necessary functions
- Changed submission from GET to POST
- Change api1 and api2 query to use XML-API fast mode
- added authentication failure detection for 11.24
- add array checking where array parameters are taken in
If you are interested in working with the XML-API PHP Class, you can download it here. If you want to provide feedback, bugs, or comments you can do so from the developer’s discussion forum
It should be noted that this is not an supported class, but rather released as reference code. If you need assistance with the class, the forum is the proper place to ask for help.
If you haven’t noticed, we’ve been working on overhauling our development documentation pretty heavily. We have a ton of great ways to integrate with cPanel but until recently, no information on how to use them. Starting this week, every week I will be posting about what new articles we’ve added to this documentation along with why you should know about these features.
Past couple of weeks I personally have been trying to focus on how to extend the cPanel interface. How to add new interfaces to it and different ways of creating these interfaces. Specifically I have added two sections; WHM Plugins and cPanel PHP.
WHM Plugins – These are extension to the cPanel interface and probably about the most straight-forward integration that cPanel provides. These are just regular CGI scripts with a couple of comments to control how they work
cPanel PHP – In this document we talk about how to use PHP in the cPanel interface along with how PHP and cpanel’s APIs can live together in a single file. This is also another “simple” form of integration that is worth a read for anyone looking to develop custom applications for their users to use.
One of the most flexible ways of working within cPanel is by creating CGI applications. Of course, this isn’t the most efficient method, however sometimes efficiency isn’t your best bet when you’re in a rush. You can use a standard CGI script within cPanel, you are limited by our APIs, such as what perl version to use.
First thing to note, is that these CGI scripts have to be placed in /usr/local/cpanel/base/3rdparty/ with normal CGI permissions (have to be executable by the user, cannot be globally writable, etc). Once placed here it can be accessed via $IP:2083/3rdparty/scriptnamed.cgi. If you place them anywhere else within the cPanel document root, they will be offered up for download rather than executable.
When these CGI scripts are executed, they are executed as the user, so limited permissions apply.
my $xml = Cpanel::XML::cpanel_exec_fast(
'cpanel_xmlapi_module' => 'Email',
'cpanel_xmlapi_func' => 'listpopswithdisk',
$xml = XMLin($xml);
Now $xml is a hash reference containing all the information returned by the call.
To download the example of this in use, click here.
We really have no information available on how to write WHM Plugins. I have had 3 people ask me in the past 48 hours on how to write them, so I thought I might want to consolidate and post this knowledge. A WHM plugin is merely a simple CGI application that has a couple of special comments in it to handle how it is displayed. Any CGI language can be used here, however only perl will allow you access to some special functions that make permission handling much easier.
All WHM plugins must be placed at /usr/local/cpanel/whostmgr/docroot/cgi and must be prefixed with addon_ and end with .cgi. These must be owned by root:root and be globally readable/executable (755), so don’t store any access credentials in these scripts – have them load from other files that are root-readable only. Continue reading
I have been noticing several people challenged with calling cPanel functions via our various ways of hooking into our APIs. Unfortunately, this isn’t as cut and dry as just calling a function within a programming language. Various factors, such as whether the call is being made from within cPanel or from a remote system, affect how this needs to be done.
To help you understand this, I will begin covering these topics in a series of posts on cPanel’s various functions and how they work. In this first post of the series, I will discuss the basics of cPanel’s APIs, and how to call API1 functions. Continue reading
Inside of cPanel 11.25, there are numerous new security features being implemented. These changes can break both cPanel plugins and remote management applications (like billing systems) that integrate with cPanel. Luckily, the changes are all optional; however, I would hate to see addons preventing people from enabling new features — like session tokens, which help prevent XSRF attacks. So, stripped from an email I sent out to third-party developers earlier this week, here are some details regarding these changes.
The first of these changes is the inclusion of security tokens.With this optional feature of 11.25, URLs will now contain <em>cpsess</em>, which has been put in place to help mitigate XSRF attacks. Continue reading