cPanel API 2 Functions - ZoneEdit::fetchzone_records

Warning:

The cPanel API 2 system is deprecated. We strongly recommend that you use UAPI instead of cPanel API 2.


Description

This function retrieves the domain's zone record modifications.

Warnings:
  • We strongly recommend that you use UAPI instead of cPanel API 2. However, no equivalent UAPI function exists.
  • When you disable the DNS role ,the system disables this function.

Note:

On servers that run CentOS 7, you may see a named warning about the absence of SPF resource records on DNS.

  • This warning is not relevant on CentOS 7 servers, because RFC 7208 deprecated SPF records . CentOS 7 servers use TXT records instead of SPF records.
  • Red Hat 7.1 and CentOS 7.1 both contain bind-9.9.4-23.el7 , which is an updated version of BIND that complies with RFC 7208. To resolve this issue, update your operating system to a version that contains the updated version of BIND. For more information, read the Red Hat Bugzilla case about SPF record errors .

Examples

WHM API (JSON)

https://hostname.example.com:2087/cpsess###########/json-api/cpanel?cpanel_jsonapi_user=user&cpanel_jsonapi_apiversion=2&cpanel_jsonapi_module=ZoneEdit&cpanel_jsonapi_func=fetchzone_records&domain=example.com&customonly=0&line=1&ttl=14400&name=example.com&address=10.10.10.10&type=A
Note:

For more information, read our Calls from the WHM API documentation.


LiveAPI PHP Class

$cpanel = new CPANEL(); // Connect to cPanel - only do this once.

// Retrieve the "example.com" domain's zone record modifications.
$fetchzone_record = $cpanel->api2(
    'ZoneEdit', 'fetchzone_records',
 array(
        'domain'    => 'example.com',
        'customonly'=> '0',
        'line'      => '1',
        'ttl'       => '14400',
        'name'      => 'example.com'
        'class'     => 'IN',
        'address'   => '10.10.10.10',
        'type'      => 'A',  
  )
);
Note:

For more information, read our Guide to the LiveAPI System.


LiveAPI Perl Module

my $cpliveapi = Cpanel::LiveAPI->new(); # Connect to cPanel - only do this once.

# Retrieve the "example.com" domain's zone record modifications.
my $fetchzone_record = $cpliveapi->api2(
    'ZoneEdit', 'fetchzone_records',
   {
        'domain'    => 'example.com',
        'customonly'=> '0',
        'line'      => '1',
        'ttl'       => '14400',
        'name'      => 'example.com'
        'class'     => 'IN',
        'address'   => '10.10.10.10',
        'type'      => 'A',  
   }
);
Note:

For more information, read our Guide to the LiveAPI System.


cPanel Tag System (deprecated)

Warnings:
  • cPanel tags are deprecated . We strongly recommend that you only use the LiveAPI system to call the cPanel APIs. Examples are only present in order to help developers move from the old cPanel tag system to our LiveAPI .
  • cPanel API 2 calls that use cPanel tags vary in code syntax and in their output.
  • For more information, read our Deprecated cPanel Tag Usage documentation.

Command Line

cpapi2 --user=username ZoneEdit fetchzone_records domain=example.com customonly=0 line=1 ttl=14400 name=example.com class=IN address=10.10.10.10 type=A
Notes:
  • You must URI-encode values.
  • username represents your account-level username.
  • You must include the --user=username option.
  • For more information and additional output options, read our Guide to cPanel API 2 documentation or run the cpapi2 --help command.
  • If you run CloudLinux™, you must use the full path of the cpapi2 command: 
    /usr/local/cpanel/bin/cpapi2

Output (JSON)

{
    "cpanelresult": {
        "apiversion": 2,
        "func": "fetchzone_records",
        "data": [{
                "record": null,
                "Line": 1,
                "ttl": "86400",
                "type": ":RAW",
                "raw": "; cPanel first:11.47.0.9999 (update_time):1413489769 Cpanel::ZoneFile::VERSION:1.3 hostname:laurence.dev.cpanel.net latest:11.47.0.9999",
                "line": 1
            },
            {
                "record": null,
                "Line": 2,
                "ttl": "86400",
                "type": ":RAW",
                "raw": "; Zone file for example.com",
                "line": 2
            },
            {
                "record": null,
                "Line": 3,
                "ttl": "14400",
                "type": "$TTL",
                "line": 3
            },
            {
                "minimum": "86400",
                "ttl": "86400",
                "serial": "2014101608",
                "name": "example.com.",
                "mname": "ns1.dev.cpanel.net",
                "retry": "7200",
                "record": null,
                "refresh": "86400",
                "Line": 4,
                "Lines": 6,
                "class": "IN",
                "type": "SOA",
                "rname": "username.example.net",
                "expire": "3600000",
                "line": 4
            },
            {
                "record": null,
                "Line": 10,
                "ttl": "86400",
                "type": ":RAW",
                "raw": "",
                "line": 10
            },
            {
                "nsdname": "ns1.dev.cpanel.net",
                "ttl": "86400",
                "name": "example.com.",
                "record": null,
                "Line": 11,
                "type": "NS",
                "class": "IN",
                "line": 11
            },
            {
                "nsdname": "ns2.dev.cpanel.net",
                "ttl": "86400",
                "name": "example.com.",
                "record": null,
                "Line": 12,
                "type": "NS",
                "class": "IN",
                "line": 12
            },
            {
                "record": null,
                "Line": 13,
                "ttl": "86400",
                "type": ":RAW",
                "raw": "",
                "line": 13
            },
            {
                "record": null,
                "Line": 14,
                "ttl": "86400",
                "type": ":RAW",
                "raw": "",
                "line": 14
            },
            {
                "ttl": "14400",
                "name": "example.com.",
                "record": "10.215.214.95",
                "Line": 15,
                "type": "A",
                "class": "IN",
                "address": "10.215.214.95",
                "line": 15
            },
            {
                "ttl": "14400",
                "name": "example.com.",
                "record": "2001:db8:1a34:56cf:0:0:0:0",
                "Line": 16,
                "type": "AAAA",
                "class": "IN",
                "address": "2001:db8:1a34:56cf:0:0:0:0",
                "line": 16
            },
            {
                "ttl": "14400",
                "name": "localhost.example.com.",
                "record": "127.0.0.1",
                "Line": 17,
                "type": "A",
                "class": "IN",
                "address": "127.0.0.1",
                "line": 17
            },
            {
                "ttl": "14400",
                "name": "localhost.example.com.",
                "record": "0:0:0:0:0:0:0:1",
                "Line": 18,
                "type": "AAAA",
                "class": "IN",
                "address": "0:0:0:0:0:0:0:1",
                "line": 18
            },
            {
                "record": null,
                "Line": 19,
                "ttl": "86400",
                "type": ":RAW",
                "raw": "",
                "line": 19
            },
            {
                "ttl": "14400",
                "name": "example.com.",
                "preference": "0",
                "record": null,
                "Line": 20,
                "type": "MX",
                "class": "IN",
                "exchange": "example.com",
                "line": 20
            },
            {
                "record": null,
                "Line": 21,
                "ttl": "86400",
                "type": ":RAW",
                "raw": "",
                "line": 21
            },
            {
                "ttl": "14400",
                "name": "mail.example.com.",
                "cname": "example.com",
                "record": "example.com",
                "Line": 22,
                "type": "CNAME",
                "class": "IN",
                "line": 22
            },
            {
                "ttl": "14400",
                "name": "www.example.com.",
                "cname": "example.com",
                "record": "example.com",
                "Line": 23,
                "type": "CNAME",
                "class": "IN",
                "line": 23
            },
            {
                "ttl": "14400",
                "name": "ftp.example.com.",
                "record": "10.215.214.95",
                "Line": 24,
                "type": "A",
                "class": "IN",
                "address": "10.215.214.95",
                "line": 24
            },
            {
                "ttl": "14400",
                "name": "ftp.example.com.",
                "record": "2001:db8:1a34:56cf:0:0:0:0",
                "Line": 25,
                "type": "AAAA",
                "class": "IN",
                "address": "2001:db8:1a34:56cf:0:0:0:0",
                "line": 25
            },
            {
                "ttl": "14400",
                "name": "fish.example.com.",
                "record": "10.215.214.95",
                "Line": 26,
                "type": "A",
                "class": "IN",
                "address": "10.215.214.95",
                "line": 26
            },
            {
                "ttl": "14400",
                "name": "fish.example.com.",
                "record": "2001:db8:1a34:56cf:0:0:0:0",
                "Line": 27,
                "type": "AAAA",
                "class": "IN",
                "address": "2001:db8:1a34:56cf:0:0:0:0",
                "line": 27
            },
            {
                "ttl": "14400",
                "name": "default._domainkey.fish.example.com.",
                "unencoded": 1,
                "record": "v=DKIM1; k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDw5nw4NP1RsWXlfmiMzByDfOT16QCZO\/xJtrPZKskZF8\/sU0zWGTqKUOErlyJfoJzMDUv3\/zzjGswc2nEmYqxxoQZaBkN4QaS6MvJQxysAr+sK8C248\/r9zMperQdhJedUVejtpFQHJwgqpHy1tQMxY37L7sQjdxmQ5WnQ1acXiwIDAQAB;",
                "Line": 28,
                "txtdata": "v=DKIM1; k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDw5nw4NP1RsWXlfmiMzByDfOT16QCZO\/xJtrPZKskZF8\/sU0zWGTqKUOErlyJfoJzMDUv3\/zzjGswc2nEmYqxxoQZaBkN4QaS6MvJQxysAr+sK8C248\/r9zMperQdhJedUVejtpFQHJwgqpHy1tQMxY37L7sQjdxmQ5WnQ1acXiwIDAQAB;",
                "type": "TXT",
                "class": "IN",
                "line": 28
            },
            {
                "record": null,
                "Line": 29,
                "ttl": "86400",
                "type": ":RAW",
                "raw": "",
                "line": 29
            },
            {
                "ttl": "14400",
                "name": "cpanel.example.com.",
                "record": "10.215.214.95",
                "Line": 30,
                "type": "A",
                "class": "IN",
                "address": "10.215.214.95",
                "line": 30
            },
            {
                "ttl": "14400",
                "name": "webdisk.example.com.",
                "record": "10.215.214.95",
                "Line": 31,
                "type": "A",
                "class": "IN",
                "address": "10.215.214.95",
                "line": 31
            },
            {
                "ttl": "14400",
                "name": "whm.example.com.",
                "record": "10.215.214.95",
                "Line": 32,
                "type": "A",
                "class": "IN",
                "address": "10.215.214.95",
                "line": 32
            },
            {
                "ttl": "14400",
                "name": "whm.example.com.",
                "flag": "0",
                "tag": "issue",
                "value": "totallyrealca.tld",
                "Line": 32,
                "type": "CAA",
                "class": "IN",
                "line": 32
            }
        ],
        "event": {
            "result": 1
        },
        "module": "ZoneEdit"
    }
}
Note:

Use cPanel's API Shell interface (cPanel >> Home >> Advanced >> API Shell) to directly test cPanel API calls.


Parameters

Parameter Type Description Possible values Example

domain

 string

Required

The record's domain.

 A valid domain name. example.com

customonly

 Boolean

Whether to return only non-essential A and CNAME records.

This value defaults to 0.
  • 1 — Return only non-essential records.
  • 0 — Return all records.
 0

line

 integer

Filter results for line numbers that match this value.

This value defaults to 1.

 A positive integer. 1

ttl

 integer

Filter results for time to live (TTL) values that match this value.

This value defaults to 14400.

A positive integer.


 14400

name

 string

Filter results for DNS record name values that match this value.

If you do not use this parameter, the function returns all results for the domain.

 A valid string. example.com

class

 string

Filter results for DNS zone classes that match this value.

This value defaults to IN.

 IN IN

address

 string

Filter results for IP addresses that match this value.

If you do not use this parameter, the function returns all of the domain's record types.

 A valid IPv4 or IPv6 address. 10.10.10.10

type

 string

Filter results for types that match this value.

If you do not use this parameter, the function returns all of the domain's record types.
  • A
  • AAAA
  • CAA
  • CNAME
  • MX
  • NS
  • RAW — This represents a blank line in the zone file.
  • SOA
  • SRV
  • TXT
A

txtdata

 string

Filter results for TXT values that match this value.

Note:

Only use this parameter if you pass TXT as the type parameter's value.


This value defaults to a blank string.

 A valid string. v=blahblahblah

preference

 integer

Filter results for preference values that match this value.

Note:

Only use this parameter if you pass MX as the type parameter's value.


This value defaults to 0. 		An integer value. 0

exchange

 string

Filter results for MX values that match this value.

Note:

Only use this parameter if you pass MX as the type parameter's value.


This value defaults to a blank string.

 A valid hostname. mail.example.com

Returns

Return Type Description Possible values Example
result hash A hash of the zonefile's records. The returns that each hash includes depends on the zone file's record type.

Line

 integer

The record's line in the zonefile.

The function returns this value in the result hash.

 A positive integer. 1

Lines

 integer

The total number of lines within the record.

The function returns this value in the result hash.

 A positive integer. 31

line

 integer

The record's line in the zonefile.

The function returns this value in the result hash.

 A positive integer. 1

record

 string

The address, cname, txtdata, or raw content of the record.

The function returns this value in the result hash.

 A value from the address, cname, txtdata, or raw values. (see address, cname, txtdata, and raw values)

mname

 string

The name server record.

The function returns this value in the result hash.

 A valid domain name. ns1.example.com

rname

 string

A contact address for the name server record.

The function returns this value in the result hash.

 An email address, but a period (.) that replaces the at symbol (@). username.example.com

retry

 integer

The time between retries if the secondary name server fails to contact the master when the refresh period expires.

The function returns this value in the result hash.

 A positive integer that represents the interval in seconds.

refresh

 integer

The interval between tries when the secondary name server refreshes a non-authoritative zone from the master.

The function returns this value in the result hash.

 A positive integer that represents the interval in seconds. 86400

expire

 integer

The period before the secondary name server marks the zone as no longer authoritative and tries to refresh the data.

The function returns this value in the result hash.

 A positive integer that represents the interval in seconds. 3600000

ttl

 integer

The record's time to live.

The function returns this value in the result hash.

 A positive integer that represents the interval in seconds. 14400

txtdata

 string

The record's text data.

The function returns this value in the result hash.

 The contents of a DKIM, SPF, or other TXT-based record. v=blahblahblah

uuencode

 Boolean

Whether the record is uuencoded.

The function returns this value in the result hash.
  • 1 — Uuencoded.
  • 0 — Not uuencoded.
 1

raw

 string

The record's raw output.

The function returns this value in the result hash.

 A valid string. v=blahblahblah

cname

 string

The record's canonical name.

The function returns this value in the result hash.

 A valid hostname. hostname.example.com

address

 string

The record's IP address.

The function returns this value in the result hash.

 A valid IPv4 or IPv6 address. 192.168.0.1

class

 string

The record's class.

The function returns this value in the result hash.

 IN IN

type

 string

The record's type.

The function returns this value in the result hash.

The most common results will be the following:

  • A
  • AAAA
  • CAA
  • CNAME
  • MX
  • NS
  • RAW — This represents a blank line in the zone record.
  • SOA
  • SRV
  • TXT
 A

name

 string

The record's name, which will map to the subdomain.

The function returns this value in the result hash.

 A valid subdomain. hostname.example.com

txtdata

 string

If the type return's value is TXT, the record's text data.

The function returns this value in the result hash.

 A valid string. v=blahblahblah

cname

 string

If the type return's value is CNAME, the record's canonical name.

The function returns this value in the result hash.

 A valid string. hostname.example.com

exchange

 string

If the type return's value is MX, the mail exchange's hostname.

The function returns this value in the result hash.

 A valid hostname. mail.example.com

nsdname

 string

If the type return's value is NS, the authoritative nameserver's hostname.

The function returns this value in the result hash.

 A valid hostname. ns1.example.com

preference

 integer

If the type return's value is MX, the priority of the mail exchanger.

The function returns this value in the result hash.

 A valid integer, where smaller numbers represent higher priority mail exchanges. 1

flag

 integer

If the type return's value is CAA, whether the CA will issue an SSL certificate if the CAA Resource Record contains unknown property tags.

Note:

  • For more information about CAA record flags, read the RFC 6844 documentation.
  • We added this return in cPanel & WHM version 66.
  • 0 — Non-critical. The CAA Resource Record contains unknown property tags, and the CA issued an SSL certificate.
  • 1 — Critical. The CAA Resource Record contains unknown property tags, and the CA did not issue an SSL certificate.
 0

tag

 string

If the type return's value is CAA, the CAA record's property type.

Note:

We added this return in cPanel & WHM version 68.


The function returns this value in the result hash.
  • issue — A CA issued a certificate for the domain.
  • issuewild — A CA issued a wildcard certificate for the domain.

  • iodef — The user specified a URL to which a CA may report policy violations.

 issue

value

 string

If the type return's value is CAA , the CA's domain or URL.

Note:

We added this return in cPanel & WHM version 66.


The function returns this value in the result hash. 		totallyrealca.tld

priority

 integer

If the type return's value is SRV, the service record's priority value.

The function returns this value in the result hash.

 A positive integer that represents the target host's priority order . 1

weight

 integer

If the type return's value is SRV, the value that the system uses to rank entries with the same priority value.

The function returns this value in the result hash.

 A positive integer that represents the target host's weight against other hosts with the same priority value. 1

port

 integer

If the type return's value is SRV, the target host's port.

The function returns this value in the result hash.

 A positive integer that represents a port number. 443

target

 integer

If the type return's value is SRV, the service's target host.

The function returns this value in the result hash.

 A valid hostname. subdomain.example.com
reason string

A reason for failure.

Note:

This function only returns a reason value if it failed.

A string that describes the error.

 This is an error message.
result Boolean

Whether the function succeeded.
  • 1 — The function succeeded.
  • 0 — The function failed.
 1
©2024 WebPros International, LLC All rights reserved.Privacy PolicyTrademarks