The LiveAPI Perl Module

For cPanel & WHM 11.32

Introduction

The LiveAPI Perl module is a Perl environment you can utilize within cPanel. This Perl environment provides Perl scripts with a local socket to the cPanel binary, cpsrvd. This allows your script to make API 1 and API 2 calls to the local machine via the socket.

This method prevents you from having to:

• Embed cPanel tags.
• Use cpphp or phpcp tags.
• Make remote API calls via XML or JSON APIs, as these calls require greater network overhead.

/usr/local/cpanel/Cpanel/LiveAPI.pm is an out-of-the-box Perl module that provides common elements for this integration. API calls are executed by the system's user and may fail if asked to perform a task for which the user has insufficient permissions. The same rules apply to this method as when using API tags or cPanel API calls made via our XML or JSON API.

To begin, you must ensure that you meet the following 3 criteria:

1. You must include /usr/local/cpanel/Cpanel/LiveAPI.pm and instantiate the Cpanel::LiveAPI object.
2. Your Perl scripts' file names must end in either .livepl or .live.pl
3. You must place your Perl script in /usr/local/cpanel/base/frontend/$THEME. You may also use a symlink.
   • Note: You will need to replace $THEME in the example above with your theme (x3 in most cases).

This document is a transcription of the Perl POD documentation within the LiveAPI.pm module. Perl developers will find more exact information within that POD.

Synopsis

use Cpanel::LiveAPI ();
my $cpliveapi = Cpanel::LiveAPI->new();  # connect to cpanel
my $live_api_result = $cpliveapi->api2('module', 'func', { 'key1' => 'value1', 'key2' => 'value2', ...} );

Module Variable Summary

• There are two environment variables that can affect the behavior of this module at object instantiation:
  • LIVEAPI_DEBUG_LEVEL — Enable or disable debugging. Debugging can be overridden by accessor method set_debug().
  • LIVEAPI_DEBUG_LOG — The absolute path and filename for a debug log. By default, a random log will be created in user's home directory (e.g., ~/.cpanel/LiveAPI.log.$rand ).

Module Methods

This section contains information about the methods you can use to interact with LiveAPI in Perl.

Public Method Summary

• object new ()
• integer set_debug (integer $debug_level)
• boolean debug_log (integer $level string $log_msg, boolean $stderr)
• boolean debug_log_json (integer $level, string $str)
• string get_debug_log ()
• integer get_debug_level ()
• hashref fetch (string $var)
• hashref api1 (string $module, string $func, arrayref $arg_ref)
• hashref api2 (string $module, string $func, hashref $arg_ref)
• boolean cpanelif (string $code)
• boolean cpanelfeature (string $feature)
• string cpanelprint (string $var)
• string cpanellangprint (string $key)
• hashref exec (string $code, [ boolean $skip_return ])
• hashref api ( string $reqtype, string $version, string $module, string $func, mixed $arg_ref)
• void end ()

Note: Private methods are not itemized here. See /usr/local/cpanel/Cpanel/LiveAPI.pm.

Module Method Details

new()

Description	Instantiates the LiveAPI object.
Return	object — The LiveAPI object.
Example	new ()

set_debug()

Description	The amount of debugging information you wish to include in the log file. Passing a non-zero value will enable socket logging. You should only use debugging when attempting to debug the transactions that happen over the socket. All transmitted data will be logged.
Return	boolean — True on success; otherwise failure.
Example	set_debug ($debug_level)

Parameters:

• $debug_level (integer) — The level of information to include in the log file. You may enter 0 for no information, 1 to include socket transactions.

debug_log()

Description	Writes to the debugging log, ~/.cpanel/LiveAPI.log.$randomstring.
Return	boolean — True on success; otherwise failure.
Example	debug_log($level, $log_msg, $stderr)

Parameters:

• $level (integer) — The log level to set set_debug().
• $log_msg (string) — The message to log.
• $stderr (boolean) — Whether to write the error to STDERR in addition to the log file, either true or false.

debug_log_json()

Description	Writes JSON data to the debugging log. This method is invoked internally by exec() when debugging is enabled.
Return	boolean — True on success; otherwise failure.
Example	debug_log_json ($level, $str)

Parameters:

• $str (string) — The JSON string to parse and log.

get_debug_log()

Description	Retrieves the name of the debugging log file.
Return	string — The debugging log file's path and filename.
Example	get_debug_log ()

get_debug_level()

Description	Retrieves the debugging level.
Return	integer — The debugging level.
Example	get_debug_level ()

fetch()

Description	A wrapper for the cpanelprint() function that retrieves a cPvar. This method returns the entire response as a hashref. If you only want the data result, use cpanelprint().
Return	hashref — A hash reference of the response containing the value of the evaluated $var.
Example	fetch ($var)

Parameters:

• $var (string) — A feature name or logical expression related to a cPanel feature. For more information visit our documentation about using cPanel feature tags.

api1()

Description	Executes an API 1 function.
Return	hashref — Returned response from the API1 function.
Example	api1 ($module, $func, $arg_ref)

Parameters:

• $module (string) — The API module's namespace, e.g. SSL.
• $func (string) — The API function, e.g. showcrt.
• $arg_ref (array reference) — The arguments you wish to pass to the API1 function (e.g., ['foo.tld', 0] ).
  • Note: API 1 arguments are ordered, so pass an array reference. (e.g., ['funcArg1', 'funcArg2']).

api2()

Description	Executes an API 2 function.
Return	hashref — Returned response from the API 2 function.
Example	api2 ($module, $func, $arg_ref)

Parameters:

• $module (string) — The API module's namespace, e.g. SSL.
• $func (string) — The API function, e.g. listsslitems.
• $arg_ref (hash reference) — The arguments you wish to pass to the API1 function (e.g., {'domains'=>'foo.tld|bar.tld', 'items'=>'key|crt'} ).
  • Note: API 2 arguments are key/value pairs, so pass in a hash reference.

cpanelif()

Description	A wrapper for the cpanelif tag.
Return	boolean — Evaluation of the logic expression contained in $code.
Example	cpanelif ($code)

Parameters:

• $code (string) — A cPvar or logical test condition. For more information, please visit our documentation about conditionals.

cpanelfeature()

Description	This method checks to see whether a particular feature is available to a cPanel user. It is a wrapper for cPanel feature tags.
Return	boolean — Indicates whether or not the cPanel account has access to the $feature.
Example	cpanelfeature ($feature)

Parameters:

• $feature (string) — A feature name or logical expression related to a cPanel feature. For more information visit our documentation about Using cPanel feature tags.

cpanelprint()

Description	Retrieves the value of an ExpVar or text. This method functions as a wrapper for the cPanel print function.
Return	string — The value of the queried ExpVar or text.
Example	cpanelprint ($var)

Parameters:

• $var (string) — An expression that may contain an ExpVar or text. For more information, please visit our ExpVar reference document.

cpanellangprint()

Warning: The cpanellangprint tag is no longer supported. You must use API 1 Locale::maketext.

Description	This method functions as a wrapper for the cPanel langprint function.
Return	string — Translated version of the requested language key.
Example	cpanellangprint ($key)

Parameters:

• $key (string) — The language key to process.

exec()

Note: Calling exec directly is discouraged. Use api1(), api2(), or a cpanel method.

Description	Executes a cPanel tag.
Return	hashref — Returned response as a hash reference.
Example	exec ($code [, $skip_return ])

Parameters:

• $code (string) — The cPanel tag to execute.
• $skip_return (boolean) — (optional) If set to true, this method will return nothing.

api()

Note: The api1(), api2(), and cpanel*() methods are preferred, as they call this method internally.

Description	Executes a cPanel API call.
Return	hashref — Returned response in a hash reference data structure.
Example	api ($reqtype, $version, $module, $func, $arg_ref)

Parameters:

• $reqtype (string) — The request type, usually exec.
• $version (integer) — The API version, either 1 or 2.
• $module (string) — The API module's namespace, e.g. Ftp.
• $func (string) — The API function, e.g., ftpquota.
• $arg_ref (mixed) — The arguments to pass to the API function. This should be an array reference for API 1, a hash reference for API 2, or a string for a non-exec $reqtype.

end()

Description	Deconstructs the object and closes the connection.
Return	void — Not Applicable.
Example	end ()

Licensing Information

Version	0.2
Copyright	cPanel, Inc.
License	Modified BSD