Page tree
Skip to end of metadata
Go to start of metadata

Introduction

This guide explains the basics of how to test your custom code. You can avoid many common issues when you test your code regularly throughout the development process.

Warning:

cPanel Technical Support cannot always assist third-party developers with problems that relate to custom code. For this reason, always test your projects thoroughly before you attempt to use them on production servers. 


Basic troubleshooting

While the items below may seem basic, we see many support tickets and forum posts with these issues. As a result, we recommend that, when you troubleshoot custom code, you check the following items first:

Does your code include any typos?

Common mistakes include missing semicolons (;) at the ends of lines, out-of-place comment characters, and misspelled variable names, function names, or filenames.

In Perl code, add the use strict; and use warnings; statements to the beginning of your custom code to find these errors more easily.

Are the user's permissions correct?

Make certain that the user who will execute the code possesses the correct permissions. 

Does the function exist in the API that you called?


cPanel, Inc. produces four current and two deprecated APIs, and they all include separate sets of functions. Make certain that the function and module that you call exist in the API version that your code uses.

Important:

API calls must use the correct port:

  • 2082 — Unsecure calls to cPanel's APIs.
  • 2083 — Secure calls to cPanel's APIs.
  • 2095 — Unsecure calls to cPanel's APIs via a Webmail session.
  • 2096 — Secure calls to cPanel's APIs via a Webmail session.
  • 2086 — Unsecure calls to WHM's APIs, or to cPanel's APIs via the WHM API.
  • 2087 — Secure calls to WHM's APIs, or to cPanel's APIs via the WHM API.

Otherwise-correct calls will return Permission denied or Function not found errors if they use an incorrect port number. 

Select a tab to view examples of calls to the desired API:

 Browser-based call...
https://hostname.example.com:2087/cpsess##########/json-api/accountsummary?api.version=1&user=username

Note:

Browser-based calls to WHM API 1 must include the WHM API version (api.version=1). If you omit the version, the system calls WHM API 0, which may not contain the desired function, or may contain an older version of that function.

 Command-line call...
whmapi1 accountsummary user=username

For more information, read our Guide to Testing Custom Code - WHM API Calls and Guide to WHM API 1 documentation. 

 cPanel or Webmail session URL call...
https://hostname.example.com:2083/cpsess##########/execute/Module/function?parameter=value&parameter=value&parameter=value
  LiveAPI PHP Class call...
$cpanel = new CPANEL(); // Connect to cPanel - only do this once.
  
// Call a UAPI function.
$function_result = $cpanel->uapi(
    'Module', 'function',
    array(
        'parameter'     => 'value',
        'parameter'     => 'value',
        'parameter'     => 'value',
         )
);
  LiveAPI Perl Module call...
my $cpliveapi = Cpanel::LiveAPI->new(); # Connect to cPanel - only do this once.
  
# Call a UAPI function.
my $function_result = $cpliveapi->uapi(
    'Module', 'function',
    {
        'parameter'     => 'value',
        'parameter'     => 'value',
        'parameter'     => 'value',
    }
);
  Template Toolkit call...
<!-- Call a UAPI function. -->
[% 
execute( 
     'Module', 'function', 
     { 
        'parameter' => 'value', 
        'parameter' => 'value', 
        'parameter' => 'value', 
     } 
); 
%]

Note:

For more information, read our Guide to Testing Custom Code - cPanel API and UAPI Calls and Guide to UAPI documentation. 

 Call through the WHM API...
https://hostname.example.com:2087/cpsess##########/json-api/cpanel?cpanel_jsonapi_user=user&cpanel_jsonapi_apiversion=2&cpanel_jsonapi_module=Module&cpanel_jsonapi_func=function&parameter="value"
  Template Toolkit call...
<!-- Call a cPanel API 2 function. -->
[%- 
USE Api2;
SET myvariable = execute( 
     'Module', 'function',
    {
        'parameter'      => 'value',
        'parameter'      => 'value',
        'parameter'      => 'value',
    }
);
%]
  LiveAPI PHP Class call...
$cpanel = new CPANEL(); // Connect to cPanel - only do this once.
   
// Call the function.
$my_variable = $cpanel->api2(
    'Module', 'function',
    array(
        'parameter'      => 'value', 
        'parameter'      => 'value', 
        'parameter'      => 'value',
    )
 );
  LiveAPI Perl Module call...
my $cpliveapi = Cpanel::LiveAPI->new(); # Connect to cPanel - only do this once.
  
# Call the function.
my $my_variable = $cpliveapi->api2(
    'Module', 'function',
    {
        'parameter'      => 'value',
        'parameter'      => 'value',
        'parameter'      => 'value',
    }
);

Note:

For more information, read our Guide to Testing Custom Code - cPanel API and UAPI Calls and Guide to cPanel API 2 documentation. 

Warning:

WHM API 0 is deprecated. We strongly recommend that you only use the equivalent WHM API 1 functions instead. 

 Browser-based call...
https://hostname.example.com:2087/cpsess##########/json-api/accountsummary?user=username

Note:

For more information, read our Guide to Testing Custom Code - WHM API Calls and Guide to WHM API 0 documentation. 

Warning:

cPanel API 1 is deprecated. We strongly recommend that you use cPanel API 2 or UAPI instead. 

 LiveAPI PHP Class call...
$cpanel = new CPANEL(); // Connect to cPanel - only do this once.
$your_variable = $cpanel->api1('Module', 'function', array('parameter', 'parameter', 'parameter') ); // Call the function.
 LiveAPI Perl Module call...
my $cpliveapi = Cpanel::LiveAPI->new(); # Connect to cPanel - only do this once.
my $your_variable = $cpliveapi->api1('Module', 'function', ['parameter', 'parameter', 'parameter'] ); # Call the function.
 Template Toolkit call...
<!-- Call a cPanel API 1 function. -->
[%- 
USE Api1;
SET myvariable = execute( 
     'Module', 'function',
    {
        'parameter'      => 'value',
        'parameter'      => 'value',
        'parameter'      => 'value',
    }
);
%]

Note:

For more information, read our Guide to Testing Custom Code - cPanel API and UAPI Calls and Guide to cPanel API 1 documentation. 

Warning:

Do not attempt to use the URL of a cPanel or WHM interface in order to perform actions in custom code. You must call the appropriate API functions in order to perform the actions of cPanel & WHM's interfaces.

For example, do not pass values to .html pages, as in the following example:

http://example.com:2082/frontend/x3/mail/doaddpop.html/email=name&domain=user.com

While this unsupported method sometimes worked in previous versions of cPanel & WHM, we strongly discourage its use and do not guarantee that it will work in the future. Instead, the correct method to perform this action is to call the appropriate API function.


Are the file permissions correct?

Remember:

API functions run as a specific user. If that user does not posses the correct permissions, errors may occur. 

Often, integrators see errors because of file permission issues with one or more of the files that relate to their custom code.

Note:

Make certain that your custom code does not change the permissions for cPanel & WHM's files. Changes to system file permissions may cause unexpected problems on cPanel & WHM servers. 

The following examples describe two possible scenarios in which incorrect file permissions could cause problems:

  • If you see the following error when you call UAPI's Email::add_pop function, the /home/username/etc/example.com/shadow file possesses incorrect permissions:

    File open for /home/username/etc/example.com/shadow failed with error Permission denied

    If the system cannot write to this file, it cannot create an email address, because it must use this file to store email password hashes during the account creation process.

  • If you see the following error when you call cPanel API 2's Fileman::mkfile function, the user cPanel account's files and directories may posses incorrect permissions:

    Encountered error in Fileman::mkfile: Could not create file "example.txt" in /home/user/public_html/: Permission denied: Permission denied

To check the permissions for a directory's files, run the ls -al command.