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

 

Description

This function retrieves a zone file.

Warning:

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

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&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.
 
// Fetch the zone file for  "example.com"
$fetch_zone = $cpanel->api2(
    'ZoneEdit', 'fetchzone',
 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.
 
# Fetch the zone file for  "example.com"
my $fetch_zone= $cpliveapi->api2(
    'ZoneEdit', 'fetchzone',
  { 
        'domain'    => 'example.com',
		'customonly'=> '0',
		'line'		=> '1',
		'ttl' 		=> '14400',
		'name'		=> 'example.com'
		'class'		=> 'IN',
		'address'	=> '10.10.10.10',
		'type'
  }
);

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 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",
    "data": [
      {
        "statusmsg": "Zone Serialized",
        "record": [
          {
            "record": null,
            "Line": 1,
            "ttl": "86400",
            "type": ":RAW",
            "raw": "; cPanel first:11.47.0.9999 (update_time):1413480646 Cpanel::ZoneFile::VERSION:1.3 hostname.hostingcompany.com 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": "2014101606",
            "name": "example.com.",
            "mname": "ns1.hostingcompany.com",
            "retry": "7200",
            "record": null,
            "refresh": "86400",
            "Line": 4,
            "Lines": 6,
            "class": "IN",
            "type": "SOA",
            "rname": "hostname.hostingcompany.com",
            "expire": "3600000",
            "line": 4
          },
          {
            "record": null,
            "Line": 10,
            "ttl": "86400",
            "type": ":RAW",
            "raw": "",
            "line": 10
          },
          {
            "nsdname": "ns1.hostingcompany.com",
            "ttl": "86400",
            "name": "example.com.",
            "record": null,
            "Line": 11,
            "type": "NS",
            "class": "IN",
            "line": 11
          },
          {
            "nsdname": "ns1.hostingcompany.com",
            "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": "webmail.example.com.",
            "record": "10.215.214.95",
            "Line": 33,
            "type": "A",
            "class": "IN",
            "address": "10.215.214.95",
            "line": 33
          },
          {
            "ttl": "14400",
            "name": "www.example.com.",
            "value": "totallyrealca.tld",
			"tag": "issue",
			"flag": "0",
            "Line": 33,
            "type": "CAA",
            "class": "IN",
            "line": 33
          }
        ],
        "status": 1,
        "serialnum": "2014101606"
      }
    ],
    "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 names 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

ReturnTypeDescriptionPossible valuesExample
 array of hashesA hash of zone record information.The returns that each hash includes depend on the type of record that you query. 

domain

string

The record's domain.

The function returns this value in the zone record's hash.

A valid domain name.example.com

line

integer

The line number in the zone file.

The function returns this value in the zone record's hash.

A positive integer.1

ttl

integer

The record's time to live (TTL).

The function returns this value in the zone record's hash.

A positive integer that represents the interval in seconds.14400

name

string

The record's name.

The function returns this value in the zone record's hash.

A valid string.example.com

class

string

The record's class.

The function returns this value in the zone record's hash.

ININ

address

string

The record's IP address.

The function returns this value in the zone record's hash.

A valid IPv4 or IPv6 address.10.10.10.10

type

string

The record's type.

The function returns this value in the zone record's hash.

  • A
  • AAAA
  • CNAME
  • MX
  • NS
  • RAW
  • SOA
  • TXT
A

txtdata

string

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

The function returns this value in the zone record's hash.

A string.v=blahblahblah

preference

string

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

The function returns this value in the zone record's hash.

A positive integer, where smaller integers represent higher priority.10

exchange

string

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

The function returns this value in the zone record's hash.

A valid hostname.mail.example.com

cname

string

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

The function returns this value in the zone record's 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 zone record's hash.

A valid hostname.ns1.example.com

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.

The function returns this value in the zone record's hash.

  • 0 — Non-critical. The CAA Resource Record contains unknown property tags, but 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 66.

The function returns this value in the zone record's 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 zone record's 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