The Community Forums

Interact with an entire community of cPanel & WHM users!
  1. This site uses cookies. By continuing to use this site, you are agreeing to our use of cookies. Learn More.

API question

Discussion in 'cPanel Developers' started by DephNet[Paul], Aug 16, 2010.

  1. DephNet[Paul]

    DephNet[Paul] Registered

    Joined:
    Jun 19, 2007
    Messages:
    4
    Likes Received:
    0
    Trophy Points:
    1
    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
     
  2. vanessa

    vanessa Well-Known Member
    PartnerNOC

    Joined:
    Sep 26, 2006
    Messages:
    817
    Likes Received:
    22
    Trophy Points:
    18
    Location:
    Virginia Beach, VA
    cPanel Access Level:
    DataCenter Provider
    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.
     
  3. cPanelDavidN

    cPanelDavidN Integration Developer
    Staff Member

    Joined:
    Dec 17, 2009
    Messages:
    571
    Likes Received:
    1
    Trophy Points:
    18
    Location:
    Houston, TX
    cPanel Access Level:
    Root Administrator
    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':
    Code:
    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:
    Code:
      <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/cp_xmlapi_php_v1.0.6.tar.gz for use in your script:

    Code:
    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
     
  4. DephNet[Paul]

    DephNet[Paul] Registered

    Joined:
    Jun 19, 2007
    Messages:
    4
    Likes Received:
    0
    Trophy Points:
    1
    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
     
  5. cPanelDavidN

    cPanelDavidN Integration Developer
    Staff Member

    Joined:
    Dec 17, 2009
    Messages:
    571
    Likes Received:
    1
    Trophy Points:
    18
    Location:
    Houston, TX
    cPanel Access Level:
    Root Administrator
    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:
    Code:
    $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:
    Code:
    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
     
  6. rsingga

    rsingga Registered

    Joined:
    Oct 8, 2010
    Messages:
    4
    Likes Received:
    0
    Trophy Points:
    1
    How to display the result?

    Dear David,

    I've followed your instruction and try with this:

    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
     
  7. cPanelDavidN

    cPanelDavidN Integration Developer
    Staff Member

    Joined:
    Dec 17, 2009
    Messages:
    571
    Likes Received:
    1
    Trophy Points:
    18
    Location:
    Houston, TX
    cPanel Access Level:
    Root Administrator
    $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
     
  8. rsingga

    rsingga Registered

    Joined:
    Oct 8, 2010
    Messages:
    4
    Likes Received:
    0
    Trophy Points:
    1
    Dear David,

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

    The result on my browser is:

    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.
     
    #8 rsingga, Oct 8, 2010
    Last edited: Oct 8, 2010
  9. cPanelDavidN

    cPanelDavidN Integration Developer
    Staff Member

    Joined:
    Dec 17, 2009
    Messages:
    571
    Likes Received:
    1
    Trophy Points:
    18
    Location:
    Houston, TX
    cPanel Access Level:
    Root Administrator
    Looks like you're missing the last argument to the api2_query() method.

    From xmlapi.php, api2_query():
    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:
    Code:
    // 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
     
  10. rsingga

    rsingga Registered

    Joined:
    Oct 8, 2010
    Messages:
    4
    Likes Received:
    0
    Trophy Points:
    1
    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

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

    cPanelDavidN Integration Developer
    Staff Member

    Joined:
    Dec 17, 2009
    Messages:
    571
    Likes Received:
    1
    Trophy Points:
    18
    Location:
    Houston, TX
    cPanel Access Level:
    Root Administrator
    Unfortunately, Fileman::getdiskinfo does not take any parameters; the output can not be modified.

    -DavidN
     
  12. rsingga

    rsingga Registered

    Joined:
    Oct 8, 2010
    Messages:
    4
    Likes Received:
    0
    Trophy Points:
    1
    Dear David,

    Thanks for your help, I hope you don't mind if I ask something in the future :)
     
  13. cPanelDavidN

    cPanelDavidN Integration Developer
    Staff Member

    Joined:
    Dec 17, 2009
    Messages:
    571
    Likes Received:
    1
    Trophy Points:
    18
    Location:
    Houston, TX
    cPanel Access Level:
    Root Administrator
    Glad I could help. Feel free to post question and concerns anytime!

    -DavidN
     
Loading...

Share This Page