The Whostmgr::XMLUI::cPanel Perl Module

For cPanel & WHM 11.32

The Whostmgr::XMLUI::cPanel module allows you to execute cPanel API 1 and API 2 functions natively from within your Perl applications, namely WHM Plugins written in Perl.

Valid application of this module

The Whostmgr::XMLUI::cPanel module was designed for use by WHM and is provided for use in Perl processes spawned by WHM. If your Perl application is spawned from a cPanel process, do not use this module. You should use the LiveAPI system instead.

You can use this module in standalone Perl applications and scripts; however, we strongly discourage you from doing so. If you plan to use this module in a standalone application, 3 stipulations apply:

• The application or script must run as root.
• The REMOTE_USER environment variable must be defined and set to either:
  • The cPanel user being affected, or
  • The owner of the cPanel user being affected
• You must enable the Allow other applications to run the cPanel and admin binaries option in Tweak Settings.
  • Warning: We strongly recommend against enabling this option. cPanel & WHM disables it by default in order to mitigate security risks.

Usage

cpanel_exec()

Input Parameters:

• OPTSref (hashref) — The API function to execute and any relevant parameters. This is the only required parameter. This hash must be formatted as though it were wrapped in a JSON or XML API call.
  • A username key/value pair must be passed in the OPTSref hash reference. The username must be a valid cPanel account or root. The username passed here determines under which user the API 1 or API 2 call will run. The username must be passed using one of the following keys:
    • cpanel_jsonapi_user
    • cpanel_xmlapi_user
• socket (string) deprecated — A file handle. This parameter is deprecated; pass undef.
• has_root (boolean) — Whether the user included in the OPTSref hash reference has root access.
  • A value of 1 indicates that the user has root access, allowing access checks to be skipped.
  • If the has_root parameter is set to 0 (false), security checks are performed. This requires the REMOTE_USER environment variable to contain either:
    • The username passed in the OPTSref hash reference, or
    • The account owner's username in the OPTSref hash reference
• cfg (hashref) — Output configuration. Accepted values:
  • json (boolean) — When enabled, the response will be returned in JSON instead of XML.

More about the $has_root input argument

The $has_root parameter governs how access control is performed in cpanel_exec() prior to invoking the API call. This compares the authenticated user, referenced by the REMOTE_USER environment variable, and the cPanel user being affected (i.e., the value set in cpanel_jsonapi_user or cpanel_xmlapi_user).

• Specifying 1 to $has_root grants the authenticated user access to modify the affected cPanel accounts, without performing any validation.
• When you specify 0, validation is performed to verify that the authenticated user owns the affected cPanel account or is the account in question.
  • Note: In this check, the root user is not considered to inherently have dominion over all other users. If the application is authenticated as root, 1 or undef should be specified to $has_root.
• Specifying undef causes the Whostmgr::ACLS module to load. The $has_root parameter is then assigned the appropriate value based on the all ACL for REMOTE_USER.

Warning: In most cases, you are expected to perform your own ACL checks to populate $has_root with the appropriate level of trust, or simply pass undef. Hardcoding a value of 1 could grant an unreasonably high level of trust to an authenticated user.

Example

#!/usr/bin/perl
# cpanel - example/Whostmgr-XMLUI-cPanel.pl              Copyright(c) 2012 cPanel, Inc.
#                                                           All rights Reserved.
# copyright@cpanel.net                                         http://cpanel.net
# This code is subject to the cPanel license. Unauthorized copying is prohibited

use Test::More tests => 8;

use strict;
use warnings;

use Whostmgr::XMLUI::cPanel ();
use Cpanel::JSON            ();
use XML::Simple             ();

#The following block executes the API 1 function Cgi::phpmyadminlink and produces XML output.

{
    my $form_ref = {
        'cpanel_xmlapi_module'     => 'Cgi',
        'cpanel_xmlapi_func'       => 'phpmyadminlink',
        'cpanel_xmlapi_apiversion' => 1,
        'cpanel_xmlapi_user'       => 'cpanel',
    };
    my ( $serialized_results_length, $serialized_results_ref ) = Whostmgr::XMLUI::cPanel::cpanel_exec( $form_ref, undef, 1 );

    ok( $serialized_results_length, "Whostmgr::XMLUI::cPanel::cpanel_exec returns a result" );

    my $ref = XML::Simple::XMLin($serialized_results_ref);

    is( $ref->{'data'}->{'result'}, '/3rdparty/phpMyAdmin/index.php', "Fast XML API 1 returns a phpmyadmin link" );
}

#The following block executes the API 1 function Cgi::phpmyadminlink and produces JSON output.

{
    my $form_ref = {
        'cpanel_jsonapi_module'     => 'Cgi',
        'cpanel_jsonapi_func'       => 'phpmyadminlink',
        'cpanel_jsonapi_apiversion' => 1,
        'cpanel_jsonapi_user'       => 'cpanel',
    };
    my ( $serialized_results_length, $serialized_results_ref ) = Whostmgr::XMLUI::cPanel::cpanel_exec( $form_ref, undef, 1, { 'json' => 1 } );

    ok( $serialized_results_length, "Whostmgr::XMLUI::cPanel::cpanel_exec returns a result" );

    my $ref = Cpanel::JSON::Load($$serialized_results_ref);

    is( $ref->{'data'}->{'result'}, 'cpanel', "Fast JSON API1 returns a phpmyadmin link" );
}

#The following block executes the API 2 function Statsbar::stat and produces XML output.

{
    my $form_ref = {
        'cpanel_xmlapi_module'     => 'StatsBar',
        'cpanel_xmlapi_func'       => 'stat',
        'display' => 'perlversion',
        'cpanel_xmlapi_apiversion' => 2,
        'cpanel_xmlapi_user'       => 'cpanel',

    };
	my ( $serialized_results_length, $serialized_results_ref ) = Whostmgr::XMLUI::cPanel::cpanel_exec( $form_ref, undef, 1 );

	ok( $serialized_results_length, "Whostmgr::XMLUI::cPanel::cpanel_exec returns a result" );

	my $ref = XML::Simple::XMLin($serialized_results_ref);

	is ($ref->{'data'}->{'id'}, 'perlversion', 'XML response contains proper "id" node');
	like( $ref->{'data'}->{'value'}, qr/5[\.\d]*/, 'XML response for "value" node contains the expected Perl version string');
}

#The following block executes the API 2 function Statsbar::stat and produces JSON output.

{
    my $form_ref = {
        'cpanel_xmlapi_module'     => 'StatsBar',
        'cpanel_jsonapi_func'       => 'stat',
        'display' => 'perlversion',
        'cpanel_jsonapi_apiversion' => 2,
        'cpanel_jsonapi_user'       => 'cpanel',

    };
    my ( $serialized_results_length, $serialized_results_ref ) = Whostmgr::XMLUI::cPanel::cpanel_exec( $form_ref, undef, 1, { 'json' => 1 } );

    ok( $serialized_results_length, "Whostmgr::XMLUI::cPanel::cpanel_exec returns a result" );

    my $ref = Cpanel::JSON::Load($$serialized_results_ref);

	is ($ref->{'data'}->{'id'}, 'perlversion', 'JSON response contains proper "id" node');
	like( $ref->{'data'}->{'value'}, qr/5[\.\d]*/, 'JSON response for "value" node contains the expected Perl version string');

}