API question

[DephNet[Paul]]

Hi Guys,

Forgive me for asking a simple question but I am not a cPanel user, and neither have I developed any mods for cPanel.

I am trying to add some cPanel functionality to an application I am developing. In the admin area of the application we want to give the user some information, so that they do not need to load up cPanel.

One of these pieces of information we want to display is how much disk space they are using, against how much their plan allows. I did find this PHP class when I did a google search, but it looks like the developer abandoned it back in 2006. The class semi-works, in so far as it shows what a users disk allocation is, but it shows they are using 0MB of the allocation.

I have now decided that it would be better to use the cPanel API however all of the example scripts that cPanel provide look like they need the WHM root user, obviously for security reasons it is unwise to have the root password in a client facing script so my first question is, does using the API require using the root user, for requestion information from a users cPanel, if not how does one use the API for a users cPanel?

--Paul

[vanessa]

you would need to use the API for this, but you don't have to use the root password - you can either use your reseller password, or the WHM remote access key, which is preferred.

[cPanelDavidN]

Hi Paul,

You do not need root level access to attain cPanel user data, just the cPanel user credentials for the user in question.

You can get statistical info from the API2 Module 'StatsBar', function 'stat', which is documented here, ApiStatsBar < ApiDocs/Api2 < TWiki

here's a sample URI for cPanel user 'dave':

https://10.1.1.1:2083/xml-api/cpanel?cpanel_xmlapi_user=dave&cpanel_xmlapi_module=StatsBar&cpanel_xmlapi_func=stat&display=diskusage|bandwidthusage

This sample URI would produce info related to the diskusage and the bandwidth usage, the http response would be similar to this:

  <cpanelresult>
    <apiversion>2</apiversion>
    <data>
      <name>diskusage</name>
      <_count>0.38</_count>
      <_max>unlimited</_max>
      <_maxed>1</_maxed>
      <count>0.38</count>
      <id>diskusage</id>
      <item>Disk Space Usage</item>
      <langkey>INDXDiskUsage</langkey>
      <max>unlimited MB</max>
      <module>Quota</module>
      <normalized>1</normalized>
      <percent>0</percent>
      <percent10>0</percent10>
      <percent20>0</percent20>
      <percent5>0</percent5>
      <units>MB</units>
      <zeroisunlimited>1</zeroisunlimited>
    </data>
    <data>
      <name>bandwidthusage</name>
      <_count>0</_count>
      <_max>unlimited</_max>
      <_maxed>1</_maxed>
      <count>0</count>
      <feature>bandwidth</feature>
      <id>bandwidthusage</id>
      <item>Monthly Bandwidth Transfer</item>
      <langkey>INDXBandwidth</langkey>
      <max>unlimited MB</max>
      <module>Stats</module>
      <normalized>1</normalized>
      <percent>0</percent>
      <percent10>0</percent10>
      <percent20>0</percent20>
      <percent5>0</percent5>
      <units>MB</units>
      <zeroisunlimited>1</zeroisunlimited>
    </data>
    <event>
      <result>1</result>
    </event>
    <func>stat</func>
    <module>StatsBar</module>
    <postevent>
      <result>1</result>
    </postevent>
    <preevent>
      <result>1</result>
    </preevent>
  </cpanelresult>

You can use whatever authentication, request, parse mechanism that you want. Or, you could use/extend our PHP XML-API client class, http://sdk.cpanel.net/lib/xmlapi/php..._v1.0.6.tar.gz for use in your script:

include("xmlapi.php");

$ip = "10.1.1.1";

$account['username'] = "dave";
$account['password'] = "d4vesS3cr3t!";

$xmlapi = new xmlapi($ip);


// gonna use cPanel creds; need to specify port 2083

$xmlapi->password_auth( $account['username'], $account['password'] );
$xmlapi->set_port('2083');  // default is 2087 for WHM

// uncomment to dump to error_log();
//$xmlapi->set_debug(1);


// stat function takes a pipe, '|', separated list
//   there are many list values, I've just chosen just 2 random ones

$args = array( 'display' => 'diskusage|bandwidth');


$xmlapi->api2_query( $account['username'], 'Statsbar', 'stat' );

You can checkout the API docs at Developer Resources . You should also checkout the Integration Blog, cPanel - cPanel Integration

Post back if you have any more questions.

Best Regards,
-DavidN

[DephNet[Paul]]

Hi Guys,

Thanks for your help David, I have just a few more questions and once again. Sorry if this is a stupid question.

I am trying to get this to display the bandwidth usage, against the bandwidth limit, using your script does not show anything.

How does one show details from the resulting XML?

Also, how would one get a list of the email users, and add a new one?

I would also like to point out that I am trying to do this in an external script.

Paul

[cPanelDavidN]

Paul,

The XML-API PHP client class will, by default, return a SimpleXML object of the response XML when you call 'api2_query', 'api1_query' or 'xmlapi_query'. So, to answer you question simply, you could do something like this:

$response = $xmlapi->api2_query( $account['username'], 'Statsbar', 'stat' );
echo $response->asXML();

By performing the 'asXML' method you're turning the object back into a string. Depending on your implementation (ie, if you letting a browser consume the output directly), you may want to send the header content type before you echo anything:

header('Content-Type: text/xml');

Alternatively, if you're just testing, you can turn on debug mode for the PHP object and it will print the response object and other info to PHP's error_log. On most workstations (desktops, machines without web servers), that's just your terminal screen. On web servers, error_log often points to an Apache error log. On a cPanel box, it usually points to /usr/local/cpanel/logs/error_log. In the sample code if my previous post, you could uncomment line 17 to turn debug mode on.


As far as the email stuff, you can checkout the documentation here:
ApiEmail < ApiDocs/Api2 < TWiki

Those are all API2 calls, so you can use the example code I provided in the previous post as a template.

Regards,
-DavidN

[rsingga]

Dear David,

I've followed your instruction and try with this:

$args = array( 'display' => 'diskusage|mysqldiskusage|hostingpackage');

$response = $xmlapi->api2_query( $account['username'], 'StatsBar', 'stat' );

echo $args;

How to display diskusage, mysqldiskusage and hostingpackage in $args? can I explode $args like:

$value = explode("|", $args);

After that we can display with:

echo $value[0]; and so on...


Thanks for your help

[cPanelDavidN]

$response will contain all the returned data. By default, the PHP Client class's query methods (api2_query(), api1_query(), and xmlapi_query()) return SimpleXML objects.

The $args variable is only for telling the query method which data you need. performing an 'echo' on it will do nothing useful. You script will need to examine the $response variable.

-DavidN

[rsingga]

Dear David,

Thanks for your response, I've tried with this:

$args = array( 'display' => 'diskusage|mysqldiskusage|hostingpackage');

$response = $xmlapi->api2_query( $account['username'], 'StatsBar', 'stat' );

header('Content-Type: text/xml');
echo $response->asXML();

The result on my browser is:

This XML file does not appear to have any style information associated with it. The document tree is shown below.

−
<cpanelresult>
<apiversion>2</apiversion>
−
<event>
<result>1</result>
</event>
<func>stat</func>
<module>StatsBar</module>
</cpanelresult>

Is there anything wrong? I thought that I will get the information about diskusage, mysqldiskusage and hostingpackage, but the result displayed on my browser just only like above.

I also uncommented $xmlapi->set_debug(1); when I saw Error Log from cpanel, there is no log related to xmlapi, only from people access the website, is there any other error log file?

Thanks.

[cPanelDavidN]

Looks like you're missing the last argument to the api2_query() method.

From xmlapi.php, api2_query():

/**
* Call an API2 Function
*
* This function allows you to call an API2 function, this is the modern API for cPanel and should be used in preference over
* API1 when possible
*
* @param string $user The username of the account to perform API2 actions on
* @param string $module The module of the API2 call to use
* @param string $function The function of the API2 call
* @param array $args An associative array containing the arguments for the API2 call
* @return mixed

So, you should be able to get back the data by simply ensuring that you provide all 4 arguments, namely the last one...which will determine which information to retrieve and send back in the XML response:

// need $args array as last argument
$response = $xmlapi->api2_query( $account['username'], 'StatsBar', 'stat', $args );

And the error log that should capture (server-side) error messages is /usr/local/cpanel/logs/error_log, the standard cPanel error log. There isn't one specifically for the XML-API. If you're executing the xmlapi.php PHP class on a cPanel box, it might put any PHP errors in the Apache error log, or the cPanel error log or simply STDERR (the screen): it all depends on your script and PHP environment.

Regards,
-DavidN

[rsingga]

Dear David,

I've tried what you told me, and it works perfectly, thanks for your help, I really appreciated that. I've tried almost the whole display parameters on StatsBar::stat, and it returned the information what I need.

But I'm still confuse with Fileman::getdiskinfo, because there is no parameter like StatsBar::stat

Fileman::getdiskinfo

API Version: 2 - Click here for documentation
Description: Retrieve disk usage statistics about your account. These values will include your quota and the amount of disk space used by your cPanel account.
Returns:

<data>
<file_upload_max_bytes> The maximum file size, in bytes, you can upload via cPanel's File Manager.</file_upload_max_bytes>
<file_upload_must_leave_bytes> The amount of disk space, in bytes, that must be reserved to avoid quota issues due to file uploads.</file_upload_must_leave_bytes>
<file_upload_max_bytes_humansize> A string value that contains the amount of disk space, in a human recognizable format, that must be reserved to avoid issues due to file uploads. (e.g. 50 MB)</file_upload_max_bytes_humansize>
<file_upload_must_leave_bytes_humansize> The maximum file size you can upload via cPanel's File Manager, in a human readable format.</file_upload_must_leave_bytes_humansize>
<file_upload_remain_humansize> A string value that contains the remaining quota in a human readable format.</file_upload_remain_humansize>
<spaceused> The amount of disk space used in bytes.</spaceused>
<spacelimit> Your account's quota in bytes.</spacelimit>
<file_upload_remain> Your account's remaining file upload space in bytes.</file_upload_remain>
<spacelimit_humansize> A string value that contains your account's quota in a human readable format.</spacelimit_humansize>
<spaceremain_humansize> A string value that contains your account's remaining disk space in a human readable format.</spaceremain_humansize>
<spaceremain> A floating point variable that contains your account's remaining disk space in bytes.</spaceremain>
<spaceused_humansize> A string value that contains your account's remaining disk space in a human readable format.</spaceused_humansize>
</data>

How I can get the data from Fileman::getdiskinfo just like StatsBar::stats?

[cPanelDavidN]

Unfortunately, Fileman::getdiskinfo does not take any parameters; the output can not be modified.

-DavidN

[rsingga]

Dear David,

Thanks for your help, I hope you don't mind if I ask something in the future

[cPanelDavidN]

Glad I could help. Feel free to post question and concerns anytime!

-DavidN