Writing dnsadmin Plugin Setup Modules

For cPanel & WHM 11.30

Introduction

This module of your dnsadmin plugin controls how a node's configuration file is written and how it appears in the interface.

This module lives in the Cpanel::NameServer::Setup::Remote namespace at /usr/local/cpanel/Cpanel/NameServer/Setup/Remote/.

The setup module must contain 2 subroutines:

• setup() — This subroutine writes out the node configuration file. This file is at /var/cpanel/cluster/$user/config/$node (replace $user and $node with the appropriate values).
• get_config() — The get_config() subroutine returns a hash reference that contains the data used to build the user interface (UI). This UI contains the forms that allow users to input data that is passed to the setup() routine.

How is a setup module triggered?

1. An admin or reseller accesses the Configure Cluster feature in WHM and selects the Type drop-down menu. These types are the dnsadmin modules in /usr/local/cpanel/Cpanel/NameServer/Setup/Remote/.
2. The admin or reseller then clicks the Configure button to access the page generated by the get_config() subroutine.
3. The admin or reseller then enters the appropriate data into the available fields and clicks Submit. The data entered into the available fields is handled by the setup() subroutine.
4. The following page of the UI will then show a message of success or failure.

The get_config() subroutine

The get_config() subroutine will need to return a hash. This hash describes the data used to generate WHM's UI that prompts the user to input authentication and configuration information.

Elements

The options array should contain at least 2 elements:

• options (array of hash references) — This array controls how elements appear in the UI accessed by the user when he or she clicks Configure in the Configure Cluster interface. The following three elements are required:
  • name — The name of the option. This value is used as the key when the data is passed to the setup() subroutine.
  • type — The type of field to display. See the reference material below for more information.
  • locale_text — The locale in which the UI should be displayed.
• The following elements are optional:
  • default — The default value for the field.
  • options — An array of hash references that contain values for radio field types. This array should contain at least 2 value elements and 1 label element:
    • value — The value of the key when the radio button is selected.
    • label — The display text for the field.

Key pair types for the options array reference

You can use the following options when defining the type element in the @options array.

Example

The following code block is an example of a get_config() subroutine.

sub get_config {
    my %config = (
        'options' => [
            {
                'name'        => 'user',
                'type'        => 'text',
                'locale_text' => 'SoftLayer API user',
            },
            {
                'name'        => 'apikey',
                'type'        => 'text',
                'locale_text' => 'SoftLayer API key',
            },
            {
                'name'        => 'ns_config',
                'type'        => 'radio',
                'default'     => 'force',
                'locale_text' => 'Method for handling NS lines',
                'options'     => [
                    { value => 'force',   label => 'Force NS records to SoftLayer servers', },
                    { value => 'ensure',  label => 'Ensure that SoftLayer servers are included', },
                    { value => 'default', label => 'Do not modify', },
                ],
            },
            {   
                'name'        => 'debug',
                'locale_text' => 'Debug mode',
                'type'        => 'binary',
                'default'     => 0,
            },
        ],
        'name'       => 'SoftLayer',
    );
    
    return wantarray ? %config : \%config;
}

The setup() subroutine

The setup() subroutine validates input from the get_config() subroutine and writes the configuration file. We strongly suggest that your setup() subroutine adhere to the following order of operations:

1. Receive parameters from the get_config() function
2. Validate parameters
3. Ensure the parameters will work on the system
4. Create /var/cpanel/cluster/$username/$config, if it does not already exist
5. Write the requested settings to the configuration file

Interface

You will need to create an array of hash references from the parameters passed in the get_config() subroutine. You can do so by using the following boilerplate:

my (undef, %OPTS ) = @_;

The %OPTS hash will contain all of the parameters passed to the setup() subroutine from the get_config() subroutine.

The setup() subroutine is expected to return data in the following format:

return $boolean, $msg, $notices, $nodename;

In the example above:

• $boolean is a value of 1 or 0 that indicates whether the node was successfully set up.
• $msg is a string that contains a message of success or a reason for failure.
• $notices is a string that contains any other important messages. These messages are displayed regardless of success or failure.
• $nodename is the name of the node as it appears in /var/cpanel/cluster/$username/config.

How does the setup() subroutine write configuration files?

The setup module must write out the /var/cpanel/cluster/$username/config/$nodename file. This file can have any name; however, we recommend using the name of your product or the hostname to which it connects as the $nodename value. /var/cpanel/cluster/$username/config/$nodename is a configuration file that contains key pairs.

The values contained within the /var/cpanel/cluster/$username/config/$nodename file are used to instantiate the remote object instance that queries the remote system. The file must contain a value for user and module. Any optional data contained in the file is also passed to the remote module.

The following is an example of a configuration file.

#version 2.0
user=MyUser
ns_config=force
apikey=Y6hq6OG0laf=
module=EasyDNS
debug=0

Important: You must make sure that the subroutine includes #version 2.0 at the top of the configuration file in order for the file to be read properly.

Example

You can find code examples in the /usr/local/cpanel/Cpanel/NameServer/Setup/Remote/ directory of your server.