Guide to Custom dnsadmin Plugins - The Remote Module - Knowledgebase

Introduction

The Remote module communicates with other servers in the DNS cluster. Store the Remote module as a file with the .pm extension in the /usr/local/cpanel/Cpanel/NameServer/Remote/ directory, which corresponds to the Cpanel::NameServer::Remote namespace.

Notes:

Remote modules require that you use the cPanel::PublicAPI (cPanel & WHM version 54 and later) or Cpanel::PublicAPI(cPanel & WHM version 11.52 and earlier) clients.
When you create a Remote module, you must use the PublicAPI new() method.
You may call one command method within another command method.
- Whenever this occurs, the command method that called another method must modify the dnsuniqid value.
- We recommend that you append Perl's _$int function to the dnsuniqid value.

You can find additional example modules in the /usr/local/cpanel/Cpanel/NameServer/Remote/ directory on your cPanel & WHM server.

Parameters

When you write a Remote module, you can use the following variables in your code:

Variable	Description
accesshash	The password in the DNS configuration file in the /var/cpanel/cluster/username/config/ directory, whereusername is the authenticated WHM account's username.
dnsrole	The remote server's DNS role.
host	The host to which the module connects.
local_timeout	The amount of time to wait to send an HTTP request before the system times out, in seconds.
logger	Required The Cpanel::Logger instance to use. Note: You must use the bless function to pass this value in the module's final hash. For more information, read the Perl documentation on the bless function.
original_request_time	The time at which the user called the DNS command, in Unix time format.
output_callback	Required A subroutine reference that handles display data. Note: You must use the bless function to pass this value in the module's final hash. For more information, read the Perl documentation on the bless function.
queue_callback	Required A subroutine reference to the subroutine that manages queue requests. Note: You must use the bless function to pass this value in the module's final hash. For more information, read the Perl documentation on the bless function.
remote_timeout	The amount of time to wait to receive an HTTP request before the system times out, in seconds.
timeout	The timeout to use.
update_type	The type of update.
user	The username in the DNS configuration file in the /var/cpanel/cluster/username/config/ directory, whereusername is the authenticated WHM account's username.

Parameters

Each command method must use the following parameters:

Parameter	Description
dnsuniqid	The command's unique identifier, which the method should use to ensure that the same system does not receive a command twice.
dataref	A hash reference that contains a serialized version of arguments that the method passed to the command.
rawdata	A hash reference that contains a raw URL version of the arguments that the method passed to the system.

For this reason, we recommend that you begin each method with the following line of code:

my ( $self, $dnsuniqid, $dataref, $rawdata ) = @_;

Returns

The dnsadmin system returns data as output and parameters, because the system executes processes through output data. The base class implements this output as the output() subroutine. This subroutine relies on the output_callback value that your module passes with the bless function into the new() subroutine.

Command methods return a hash that contains two values:

Return	Type	Description	Possible values	Example
status	string	A constant that theCpanel::NameServers::Constantsnamespace defines.	This value must be$Cpanel::NameServer::Constants::, where is one of the following constants: ERROR_INVALID_RESPONSE_LOGGED ERROR_GENERIC ERROR_TIMEOUT ERROR_GENERIC_LOGGED ERROR_TIMEOUT_LOGGED SUCCESS QUEUE DO_NOT_QUEUE
message	string	A message of success, or a reason for failure.	OK An error message.	OK

Return

Type

Description

Possible values

Example

status

string

A constant that theCpanel::NameServers::Constantsnamespace defines.

This value must be$Cpanel::NameServer::Constants::*, where * is one of the following constants:

ERROR_INVALID_RESPONSE_LOGGED
ERROR_GENERIC
ERROR_TIMEOUT
ERROR_GENERIC_LOGGED
ERROR_TIMEOUT_LOGGED
SUCCESS
QUEUE
DO_NOT_QUEUE

message

string

A message of success, or a reason for failure.

OK
An error message.

The `_check_action()` subroutine

The _check_action() subroutine returns proper data constants when the dnsadmin system sends or receives information. This subroutine checks remote systems' HTTP statuses, and determines whether the system can recover from errors.

Calls to this subroutine resemble the following examples:

_check_action($msg, $Cpanel::NameServer::Constants::QUEUE);
_check_action($msg, $Cpanel::NameServer::Constants::DO_NOT_QUEUE);

In these examples, the QUEUE and DO_NOT_QUEUE constants determine whether the system queues an action if it fails.

The QUEUE constant retries a failed action if the system determines that the action is recoverable.
The DO_NOT_QUEUE constant returns an error message for a failed action, and does not attempt to retry the action.

Note:

Use the $msg variable to pass in a message about the action that failed.

Command methods

You must implement each command that you pass to the dnsadmin system as a subroutine in your Remote module.

Warning:

You must include the following required methods in your module:

addzoneconf()
getallzones()
getips()
getpath()
getzone()
getzonelist()
getzones()
quickzoneadd()
removezone()
removezones()
savezone()
synczones()
version()
zoneexists()

Knowledgebase

Categories

Categories