Page tree
Skip to end of metadata
Go to start of metadata

Introduction

You must include command methods in your custom dnsadmin plugin's Remote module. When the dnsadmin system receives a command, it runs the subroutine for that command from 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()

For more information about the Remote module and additional examples, read our The Remote Module documentation.

addzoneconf()


The addzoneconf() method adds a zone to the configuration database (the named.conf file on BIND servers).

Note:

We recommend that you queue this method, in case of non-fatal errors.


Example call

./dnsadmin --action ADDZONECONF --data zone=example.com
Required?
Required input:
Required output:

Input and output

 Click to view...

The addzoneconf() method must include the following input values:

VariableTypeDescriptionPossible valuesExample
zonestringThe zone to add to the configuration database.A valid DNS zone name.example.com.db

The addzoneconf() method does not require output.

Example subroutine

 Click to view...
# Create a method to add a zone to the configuration database.
sub addzoneconf {
    my ( $self, $unique_dns_request_id, $dataref, $rawdata ) = @_;
    chomp( $dataref->{'zone'} );
    $self->output( $self->{'publicapi'}->addzoneconf_local( $dataref->{'zone'}, $unique_dns_request_id ) );
    return $self->_check_action( "add the zone $dataref->{'zone'}", $Cpanel::NameServer::Constants::QUEUE );
}

 

cleandns()


The cleandns() method removes unnecessary DNS zones from the system.

Example call

./dnsadmin --action CLEANDNS
Required?
Required input:
Required output:

Input and output

The cleandns() method does not require input or output.

Example subroutine

 Click to view...
# Create the cleandns method, to remove unnecessary zones.
sub cleandns {
    my ( $self, $unique_dns_request_id, $dataref, $rawdata ) = @_;
    $self->output( $self->{'publicapi'}->cleandns_local($unique_dns_request_id) );
    return $self->_check_action( 'cleanup dns', $Cpanel::NameServer::Constants::DO_NOT_QUEUE );
}

 

getallzones()


The getallzones() method retrieves a complete dump of all of the zone files on the system.

Example call

./dnsadmin --action GETALLZONES --data zones=example1.com,example2.com,example3.com
Required?
Required input:
Required output:

Input and output

 Click to view...

The getallzones() method does not require input.

The getallzones() method must return a URI-encoded, ampersand-delimited (&) list of zone files and their contents.

For example:

cpdnszone-$zone1=$zone1contents&$zone2=$zone2contents

Example subroutine

 Click to view...
# Create the getallzones command method to get a dump of zone files.
sub getallzones {
    my ( $self, $unique_dns_request_id, $dataref, $rawdata ) = @_;
    require Cpanel::Gzip::ungzip;
    my $zdata  = $self->{'publicapi'}->getallzones_local($unique_dns_request_id);
    my $uzdata = Cpanel::Gzip::ungzip::gunzipmem($zdata);
    $self->output( $uzdata ne '' ? $uzdata : $zdata );
    return $self->_check_action( 'get all the zones', $Cpanel::NameServer::Constants::DO_NOT_QUEUE );
}

 

getips()


The getips() method retrieves a list of the IP addresses that the system's nameserver records use.

Example call

./dnsadmin --action GETIPS
Required?
Required input:
Required output:

Input and output

 Click to view...

The getips() method does not require input.

The getips() method must return a line-delimited (&) list of the IP addresses that the remote system uses.

Example subroutine

 Click to view...
# Create a method to list the nameserver records' IP addresses.
sub getips {
    my ( $self, $unique_dns_request_id, $dataref, $rawdata ) = @_;
    $self->output( $self->{'publicapi'}->getips_local($unique_dns_request_id) );
    return $self->_check_action( "receive an ips list", $Cpanel::NameServer::Constants::DO_NOT_QUEUE );
}

getpath()


The getpath() method lists the nodes with which the current node is peered.

Note:

The system uses this method to build the graph in WHM's DNS Cluster interface (WHM >> Home >> Clusters >> DNS Cluster).

Example call

./dnsadmin --action GETPATH
Required?
Required input:
Required output:

Input and output

 Click to view...

The getpath() method does not require input.

The getpath() method must return a space-separated pair of hosts and nameservers in the DNS cluster.

  • The host values must match their entries in the node configuration file.
  • The nameserver values must match their entries in the NS records.

For example:

host.example.com ns1.example.com 
host.example.com ns2.example.com

Example subroutine

 Click to view...
# Create a method that lists the nodes with which the current node is peered.
sub getpath {
    my ( $self, $unique_dns_request_id, $dataref, $rawdata ) = @_;
    $self->output( $self->{'publicapi'}->getpath_local($unique_dns_request_id) . "\n" );
    return $self->_check_action( "getpath", $Cpanel::NameServer::Constants::DO_NOT_QUEUE );
}

getzone()


The getzone() method retrieves the contents of a single zone file.

Example call

./dnsadmin --action GETZONE --data zone=example.com
Required?
Required input:
Required output:

Input and output

 Click to view...

The getzone() method must include the following input values:

VariableTypeDescriptionPossible valuesExample
zonestringThe zone file to retrieve.A valid DNS zone name.example.com.db

The getzone() method must return a BIND-compatible zone file.

Example subroutine

 Click to view...
# Create a method to get the contents of a single zone file.
sub getzone {
    my ( $self, $unique_dns_request_id, $dataref, $rawdata ) = @_;
    chomp( $dataref->{'zone'} );
    $self->output( $self->{'publicapi'}->getzone_local( $dataref->{'zone'}, $unique_dns_request_id ) );
    return $self->_check_action( "get the zone $dataref->{'zone'}", $Cpanel::NameServer::Constants::DO_NOT_QUEUE );
}

getzonelist()


The getzonelist()  method lists all of the available zones on the system.

Example call

./dnsadmin --action GETZONELIST
Required?
Required input:
Required output:


Input and output

 Click to view...

The getzonelist() method does not require input.

The getzonelist() method must return a line-delimited list of the available DNS zones.

Example subroutine

 Click to view...
# Create a method to list all of the zones on the system.
sub getzonelist {
    my ( $self, $unique_dns_request_id, $dataref, $rawdata ) = @_;
    my @ZONES = $self->{'publicapi'}->getzonelist_local($unique_dns_request_id);
    my @check_action_results = $self->_check_action( "get the zone list", $Cpanel::NameServer::Constants::DO_NOT_QUEUE );
    return (@check_action_results) if $check_action_results[$Cpanel::NameServer::Constants::CHECK_ACTION_POSITION_STATUS] != $Cpanel::NameServer::Constants::SUCCESS;
    foreach my $zone (@ZONES) {
        if ( Cpanel::StringFunc::Match::endmatch( $zone, '.db' ) ) {
            my $cleanzone = $zone;
            $cleanzone =~ Cpanel::StringFunc::Trim::endtrim( $cleanzone, '.db' );
            $self->output( $cleanzone . "\n" );
        }
        elsif ( !Cpanel::StringFunc::Match::beginmatch( $zone, '.' ) && $zone !~ /\.\./ ) {
            $self->output( $zone . "\n" );
        }
    }
    return ( $Cpanel::NameServer::Constants::SUCCESS, 'OK' );
}

getzones()


The getzones()  method retrieves the contents of multiple zone files.

Example call

./dnsadmin --action GETZONES --data zones=example1.com,example2.com,example3.com
Required?
Required input:
Required output:

Input and output

 Click to view...

The getzones() method must include the following input values:

VariableTypeDescriptionPossible valuesExample
getzonesstringThe domains for which the method will retrieve zone files.A comma-separated list of domains.example.com,example.net

The getzones() method must return a URI-encoded, ampersand-delimited (&) list of zone files and their contents. For example:

cpdnszone-$zone1=$zone1contents&$zone2=$zone2contents

Example subroutine

 Click to view...
# Create a method to get the contents of multiple zone files.
sub getzones {
    my ( $self, $unique_dns_request_id, $dataref, $rawdata ) = @_;
    chomp( $dataref->{'zone'} );
    chomp( $dataref->{'zones'} );
    require Cpanel::Gzip::ungzip;
    if ( isatleastversion( '11.1.0', $self->{'publicapi'}->cached_version() ) ) {
        my $zdata = $self->{'publicapi'}->getzones_local( ( $dataref->{'zones'} || $dataref->{'zone'} ), $unique_dns_request_id );
        my $uzdata = Cpanel::Gzip::ungzip::gunzipmem($zdata);
        $self->output( $uzdata ne '' ? $uzdata : $zdata );
    }
    else {
        my @NEEDEDZONES = split( /\,/, ( $dataref->{'zones'} || $dataref->{'zone'} ) );
        my $count = 0;
        my $zonedata;
        foreach my $zone (@NEEDEDZONES) {
            $count++;
            $zonedata = $self->{'publicapi'}->getzone_local( $zone, $unique_dns_request_id . '_' . $count );
            $self->output('cpdnszone-' . Cpanel::Encoder::URI::uri_encode_str($zone) . '=' . Cpanel::Encoder::URI::uri_encode_str($zonedata) . '&' );
        }
    }
    return $self->_check_action( "get the zones " . ( $dataref->{'zones'} || $dataref->{'zone'} ), $Cpanel::NameServer::Constants::DO_NOT_QUEUE );
}

quickzoneadd()


The quickzoneadd()  method adds a zone to the system and saves its contents.

Note:

We recommend that you queue this method, in case of non-fatal errors.

Example call

./dnsadmin --action QUICKZONEADD --data zone=example.com\&zonedata=< uri encoded zonefile >
Required?
Required input:
Required output:

Input and output

 Click to view...

The quickzoneadd() method must include the following input values:

VariableTypeDescriptionPossible valuesExample
zonestringThe zone to add to the configuration database.A valid DNS zone name.example.com.db
zonedatastringThe contents to save in the new zone file.A valid string.
< uri encoded zonefile >

The quickzoneadd() method must return a message of success or an error message:

  • An error message — The method failed.
  • Zone $zone has been successfully added — The method succeeded.

Example subroutine

 Click to view...
# Create a method that adds a new zone to the system and saves its contents.
sub quickzoneadd {
    my ( $self, $unique_dns_request_id, $dataref, $rawdata ) = @_;
    if ( isatleastversion( '11.24.4', $self->{'publicapi'}->cached_version() ) ) {
        $self->output( $self->{'publicapi'}->quickzoneadd_local( $dataref->{'zone'}, $dataref->{'zonedata'}, $unique_dns_request_id ) );
    }
    else {
        if ( isatleastversion( '11.24.2', $self->{'publicapi'}->cached_version() ) ) {
            $self->output(
                $self->{'publicapi'}->synczones_local(
                'cpdnszone-' . Cpanel::Encoder::URI::uri_encode_str($dataref->{'zone'}) .
                '=' .
                Cpanel::Encoder::URI::uri_encode_str($dataref->{'zonedata'}) .
                '&',
                $unique_dns_request_id . '_1'
                )
            );
        }
        else {
            $self->output( $self->{'publicapi'}->addzoneconf_local( $dataref->{'zone'}, $unique_dns_request_id . '_1' ) );
            $self->output( $self->{'publicapi'}->savezone_local( $dataref->{'zone'}, $dataref->{'zonedata'}, $unique_dns_request_id . '_2' ) ) unless ( $self->{'publicapi'}->{'error'} ne '' );
        }
        $self->output( $self->{'publicapi'}->reconfigbind_local( $unique_dns_request_id . '_3' ) ) unless ( $self->{'publicapi'}->{'error'} ne '' );
    }
    return $self->_check_action( "quick add the zone $dataref->{'zone'}", $Cpanel::NameServer::Constants::QUEUE );
}

   

reconfigbind()


The reconfigbind()  method forces BIND to reload the configuration file.

Example call

./dnsadmin --action RECONFIGBIND
Required?
Required input:
Required output:

Input and output

The reconfigbind() method does not require input or output.

Example subroutine

 Click to view...
# An optional method.
sub reconfigbind {
    my ( $self, $unique_dns_request_id, $dataref, $rawdata ) = @_;
    $self->output("No reload needed on $self->{'name'}\n");
    return ( $Cpanel::NameServer::Constants::SUCCESS, 'OK' );
}

reloadbind()


The reloadbind()  method forces BIND to reload completely.

Example call

./dnsadmin --action RELOADBIND
Required?
Required input:
Required output:

Input and output

The reloadbind() method does not require input or output.

Example subroutine

 Click to view...
# An optional method.
sub reloadbind {
    my ( $self, $unique_dns_request_id, $dataref, $rawdata ) = @_;
    $self->output("No reload needed on $self->{'name'}\n");
    return ( $Cpanel::NameServer::Constants::SUCCESS, 'OK' );
}

reloadzones()


The reloadzones()  method forces BIND to reload specific zones.

Example call

./dnsadmin --action RELOADZONES --data zones=example1.com,example2.com
Required?
Required input:
Required output:

Input and output

The reloadzones() method does not require input or output.

Example subroutine

 Click to view...
# An optional method.
sub reloadzones {
    my ( $self, $unique_dns_request_id, $dataref, $rawdata ) = @_;
    $self->output("No reload needed on $self->{'name'}\n");
    return ( $Cpanel::NameServer::Constants::SUCCESS, 'OK' );
}

removezone()


The removezone()  method removes a single zone from the system.

Example call

./dnsadmin --action REMOVEZONE --data zone=example.com
Required?
Required input:
Required output:

Input and output

 Click to view...

The removezone() method must include the following input values:

VariableTypeDescriptionPossible valuesExample
zonestringThe zone to remove.A valid DNS zone name.example.com.db

The removezone() method must return one of the following messages:

  • An error message — The method failed.
  • 'zone' => 'deleted from $node' — The method succeeded.

Example subroutine

 Click to view...
# Create a method to remove a single zone.
sub removezone {
    my ( $self, $unique_dns_request_id, $dataref, $rawdata ) = @_;
    chomp( $dataref->{'zone'} );
    $self->output( $self->{'publicapi'}->removezone_local( $dataref->{'zone'}, $unique_dns_request_id ) . "\n" );
    return $self->_check_action( "remove the zone: $dataref->{'zone'}", $Cpanel::NameServer::Constants::QUEUE );
}

removezones()


The removezones() method removes multiple zones from the system.

Example call

./dnsadmin --action REMOVEZONES --data zone=example.com,example.net
Required?
Required input:
Required output:

Input and output

 Click to view...

The removezones() method must include the following values:

VariableTypeDescriptionPossible valuesExample
zonestringThe zones to remove.A comma-separated list of valid DNS zone names.example.com,example.net

The removezones() method must return one of the following messages:

  • An error message — The method failed.
  • 'zone' => 'deleted from $node' — The method succeeded.

Example subroutine

 Click to view...
# Create a method to remove multiple zones.
sub removezones {
    my ( $self, $unique_dns_request_id, $dataref, $rawdata ) = @_;
    chomp( $dataref->{'zone'} );
    chomp( $dataref->{'zones'} );
    if ( isatleastversion( '11.24.2', $self->{'publicapi'}->cached_version() ) ) {
        $self->output( $self->{'publicapi'}->removezones_local( ( $dataref->{'zones'} || $dataref->{'zone'} ), $unique_dns_request_id ) . "\n" );
    }
    else {
        my $count = 0;
        foreach my $zone ( split( /\,/, ( $dataref->{'zones'} || $dataref->{'zone'} ) ) ) {
            $count++;
            $zone =~ s/^\s*|\s*$//g;
            print $self->{'publicapi'}->removezone_local( $zone, $unique_dns_request_id . '_' . $count ) . "\n";
            {
                my @check_action_results = $self->_check_action( "remove the zone(s): " . ( $dataref->{'zones'} || $dataref->{'zone'} ), $Cpanel::NameServer::Constants::QUEUE );
                return (@check_action_results) if $check_action_results[$Cpanel::NameServer::Constants::CHECK_ACTION_POSITION_IS_RECOVERABLE_ERROR];
            }
        }
    }
    return $self->_check_action( "remove the zone(s): " . ( $dataref->{'zones'} || $dataref->{'zone'} ), $Cpanel::NameServer::Constants::QUEUE );
}

savezone()


The savezone() method saves new records to an existing zone file. This method does not add the zone file to the configuration database (for example, the named.conf file on BIND servers).

Note:

We recommend that you queue this method, in case of non-fatal errors.

Example call

./dnsadmin --action SAVEZONE --data zone=example.com\&zonedata=< uri encoded zonefile >
Required?
Required input:
Required output:

Input and output

 Click to view...

The savezone() method must include the following input values:

VariableTypeDescriptionPossible valuesExample
zonestringThe zone to modify.A valid DNS zone name.example.com.db
zonedatastringThe contents to add to the zone file.A valid string.
< uri encoded zonefile >

The savezone() method does not require output.

Example subroutine

 Click to view...
# Create a method to save new records to existing zone files.
sub savezone {
    my ( $self, $unique_dns_request_id, $dataref, $rawdata ) = @_;
    chomp( $dataref->{'zone'} );
    $self->output( $self->{'publicapi'}->savezone_local( $dataref->{'zone'}, $dataref->{'zonedata'}, $unique_dns_request_id ) );
    return $self->_check_action( "save the zone $dataref->{'zone'}", $Cpanel::NameServer::Constants::QUEUE );
}

synczones()


The synczones() method adds multiple zones to a remote system and to the configuration database (the named.conf file on BIND servers).

Note:

We recommend that you queue this method, in case of non-fatal errors.

Example call

./dnsadmin --action SYNCZONES --data cpdnszone-example1.com=< uri encoded zone>\&cpdnszone-example2.com=< uri encoded zone >
Required?
Required input:
Required output:

Input and output

 Click to view...

The synczones() method must include the following input values:

VariableTypeDescriptionPossible valuesExample
cpdnszone-$zonenamestring

A URI-encoded version of the zone file to synchronize.

Note:

Replace $zonename with the name of the zone. For example, cpdnszone-example.com

A URI-encoded zone name.< uri encoded zone >

The synczones() method does not require output.

Example subroutine

 Click to view...
# Create a method to add multiple zones to a remote system and the config database.
sub synczones {
    my ( $self, $unique_dns_request_id, $dataref, $rawdata ) = @_;
    chomp( $dataref->{'zone'} );
    $rawdata =~ s/^dnsuniqid=[^\&]+\&//g;
    $rawdata =~ s/\&dnsuniqid=[^\&]+//g;
    local $self->{'publicapi'}->{'timeout'} = ( ( int( $self->{'local_timeout'} / 2 ) > $self->{'remote_timeout'} ) ? int( $self->{'local_timeout'} / 2 ) : $self->{'remote_timeout'} );
    $self->output( $self->{'publicapi'}->synczones_local( $rawdata, $unique_dns_request_id ) );
    return $self->_check_action( "sync zones: $dataref->{'zone'}", $Cpanel::NameServer::Constants::QUEUE );
}

 

version()


The version() method retrieves the version number of the module on the local or remote system.

Example call

./dnsadmin --action VERSION
Required?
Required input:
Required output:

Input and output

 Click to view...

The version() method does not require input values.

The version() method must return a version number to display.

Example subroutine

 Click to view...
# Create a method that gets a module's version number.
sub version {
    my ( $self, $unique_dns_request_id, $dataref, $rawdata ) = @_;
    my $version = $self->{'publicapi'}->version();
    $self->{'error'} = $self->{'publicapi'}->{'error'} if $self->{'publicapi'}->{'error'};
    return $version;
}

 

zoneexists()


The zoneexists() method checks whether a zone exists.

Example call

./dnsadmin --action ZONEEXISTS --data zone=example.com
Required?
Required input:
Required output:

Input and output

 Click to view...

The zoneexists() method must include the following input values:

VariableTypeDescriptionPossible valuesExample
zonestringThe zone to check.A valid DNS zone name.example.com

The savezone() method must return one of the following boolean values:

  • 1 — The zone exists.
  • 0 — The zone does not exist.

Example subroutine

 Click to view...
# Create a method to check whether a zone exists.
sub zoneexists {
    my ( $self, $unique_dns_request_id, $dataref, $rawdata ) = @_;
    chomp( $dataref->{'zone'} );
    $self->output( $self->{'publicapi'}->zoneexists_local( $dataref->{'zone'}, $unique_dns_request_id ) ? '1' : '0' );
    return $self->_check_action( "determine if the zone $dataref->{'zone'} exists", $Cpanel::NameServer::Constants::DO_NOT_QUEUE );
}