Poor implementations of this system may cause
root-privilege vulnerabilities and compromised servers. Read the Security requirements section of this document before you use this system.
The system manages privilege escalation, and ensures that the user can only run the permitted code.
To run a function with escalated privileges, call a function through the
Call method or use the pluggable wrapper.
- This set of documents applies to cPanel & WHM version 11.38 and later. For information about the legacy method of API privilege escalation (for cPanel & WHM version 11.36 and earlier), read our Legacy API Privilege Escalation documentation.
- cPanel, L.L.C. introduced the
Callmethod for Perl admin modules in cPanel & WHM version 54 in order to simplify construction of modules. We recommend that you write
adminmodules with this method when possible. For earlier versions and other programming languages, use the Standard Method.
To query all of the
SETGIDvalues on a server, run the following command:
cPanel, L.L.C. introduced this functionality in cPanel & WHM version 54 for
admin modules in Perl.
As of cPanel & WHM version 54, cPanel, L.L.C. recommends that you develop
admin modules as subclasses of the cPanel-provided
Cpanel::AdminBin::Script::Call base class. This class, and the
Cpanel::AdminBin::Call module that accompanies it, contain privilege escalation logic so that
admin modules are simpler to write and call.
To make a
TheModule module in the
TheNameSpace namespace, perform the following steps:
- Create the
Run the following command to create the configuration file:
Create your new module in the
Set that file to be executable with the following command:
The following example
admin module uses the
run(OPTS) method runs the script after it checks whether the first element in the value of the
@ARGV array is
--bincheck exists in the
@ARGV array, the system prints the
BinCheck ok message with a trailing newline and the process performs an
exit(). This is normally how Call-type
admin modules invoke themselves when run from a script.
OPTSobject is an optional list of arguments that can include the
alarmargument, an integer that represents a timeout value for the script. This option defaults to 350 seconds.
The following example includes the
run()method with the
new(OPTS) method is identical to the
run() method, but it does not check whether the first element in the value of the
@ARGV array is the
- This method helps you test your module.
For example, the following example includes the
To call the
DO_GOOD function from unprivileged code, your code should resemble the following example:
The above example passes the
first arg and
second arg parameters to the
DO_GOOD method in the
- This example returns one value, but you may also return a list.
- Input parameters and return values may be scalars, array references, or hash references.
- This structure does not support scalar references, references that use the
bless()function, and self-referential data structures as inputs or outputs.
The code calls the
admin function with the same context (void, scalar, or list) as the
Cpanel::AdminBin::Call::call() method itself. The system handles mismatched returns (for example, an array in scalar context as a return value) as Perl handles them. The
admin module traps exceptions and then re-throws them without a stack trace in the code that calls them.
For a full example, read our Guide to API Privilege Escalation - Call Your Application documentation.
$self parameter in the example contains a reference to the instance of your
admin module and class. Your class will inherit several useful methods such as
get_caller_username() from the
For more information, read our Guide to API Privilege Escalation - Object Methods documentation.
To use privilege escalation in your custom code, perform the following steps:
- Create the following files:
- Store these files in a new namespace in the
- The namespace and the directory name must be identical.
- Do not create your
AdminBinapplication in the
Whenever you use this system, do not manipulate files or directories that a user owns as the
root user or execute any actions on unvalidated input.
You must adhere to the following security practices:
- Only use this system to execute code that must run as the
- Thoroughly validate any input that passes through this system.
- Sanitize the
To sanitize the
admin script's environment, set environment variables to limit the paths from which the script loads libraries.
- This action sanitizes the
@INCarray and ensures that users cannot load arbitrary libraries.
The following example adds the
/usr/local/cpanel/directory to the environment, and then removes entries that do not match standard Perl library paths: