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

 

Description

This function retrieves the domain's zone record modifications.

Warning:

We strongly recommend that you use UAPI instead of cPanel API 2. However, no equivalent UAPI function exists.

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 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)

Warning:

In cPanel & WHM version 11.30 and later, cPanel tags are deprecated. We strongly recommend that you only use the LiveAPI system to call the cPanel APIs.

cPanel API 2 calls that use cPanel tags vary widely in code syntax and in their output. For more information, read our Deprecated cPanel Tag Usage documentation. Examples are only present in order to help developers move from the old cPanel tag system to our LiveAPI.

 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.
  • For more information and additional output options, read our Guide to cPanel API 2 documentation or run the cpapi2 --help command. 
  • We introduced this functionality in cPanel & WHM version 56.

 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 

ParameterTypeDescriptionPossible valuesExample

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.

ININ

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
  • 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 TypeDescriptionPossible valuesExample
resulthashA 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 addresscnametxtdata, 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 (.) thatreplaces 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.
  • 0Not 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.

ININ

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

 

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
reasonstring

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.
resultBoolean

Whether the function succeeded.

  • 1 — The function succeeded.
  • 0 — The function failed.
1