We have a new documentation site for cPanel & WHM! You can find our new documentation site at docs.cpanel.net.
We will continue to maintain our API documentation on this server.
In cPanel & WHM version 86 and later, cPanel, L.L.C. recommends that you develop Perl admin modules as subclasses of the
Cpanel::Admin::Base class. The admin module method improves creating API escalation methods in several ways. This method is:
cpsrvdservice loads admin modules directly and within the initiated process with the admin module method. The previous Call method would run a new command on each admin function call. This resulted in a slower process.
We recommend that you write all admin functions in Perl. If you cannot, use the Standard method to write admin functions in other code languages.
To create a new admin module, perform the following steps:
/var/cpanel/perl/Cpanel/Admin/Modulesdirectory. For example, if you create the
GreatHostingnamespace, then create the
GreatThingsmodule, that module will exist in the
Create a function named
_actions() in the new module.
The following is an example of the admin module's basic usage:
To call your admin module, use the following example:
The called admin function runs in the same context (
list) as the
Cpanel:AdminBin::Call:call() function. For example, if the unprivileged code calls the
GET_INFO function in scalar context, the caller receives the last element of the list.
If an untrapped exception happens within an admin function, an exception gets thrown in the calling process. This exception will contain an error ID, and the error details and the same error ID get written to the
/usr/local/cpanel/logs/error_log file. You can use this log file to review specific errors via the error ID.
To indicate details of an error (for example, validation failures) to a caller, return the details as status codes.
Admin modules let you send a file handle as part of a call to an admin function. This allows you to reduce the overhead of the exchange of large amounts of data between privileged and unprivileged processes. An admin function that accepts a filehandle might look like the following example:
A call to this function might look like the following example:
The admin function can also pass a filehandle back to the caller. To do this, perform the following steps:
stream() function uses blocking I/O, real-time communication between the unprivileged and privileged processes is not currently possible.
Cpanel::Admin::Base methods not documented below are subject to removal or change at any time without prior notice. Do not use any undocumented methods in your code.
cPanel, L.L.C. documents the following methods for use by integrators when writing admin functions:
get_caller_username()— Returns the name of the cPanel user who called the admin function.
get_cpuser_domains()— Returns an array reference of the calling cPanel user's domains, including the cPanel user's primary domain.
get_passed_fh()— Returns the Perl file handle that the caller passed. If the caller did not pass a file handle, this returns the
By default, cPanel demo mode users cannot access any admin functions. To expose an admin function to demo mode users, create a
_demo_actions() function that returns the names of the functions you want to make available to these users.
You do not need to create the
_demo_actions() method for any other reason.