Software Development Kit

cPanel & WHM's API [+] cPanel & WHM's API [-]


Modules and Plugins [+] Modules and Plugins [-]


cPanel & WHM Hooks [+] cPanel & WHM Hooks [-]


cPAddons (Site Software) [+] cPAddons (Site Software) [-]


System Administration [+] System Administration [-]


Developer Software [+] Developer Software [-]


Back to All Documentation

Edit Zone Record — editzonerecord

This function allows you to edit a DNS zone record on the server.

To use this function most effectively, you should first run the dumpzone function for the domain(s) whose record(s) you wish to edit. The output of that function call will be used as a reference to create the input for this function.

  1. In the output of the dumpzone function, locate the Line variable corresponding to the data you wish to edit.
  2. Next, locate the parameter(s) you wish to edit. Example: ttl
  3. Use the domain name, line, and new parameter value to formulate the editzonerecord function call as detailed below.

note Note: If you wish to change only the IP in a zone record, the swapip script may suit your purposes better.

Calling Functions

Using the XML API

To use the XML API to perform the editzonerecord function from within your custom script:

  • Append the /xml-api/editzonerecord function call name, plus the required variables (see below), to a URL which includes the address of your server.

  • For example, on a server whose hostname is example.com, you would include the following string in your script: https://example.com:2087/xml-api/editzonerecord

  • You need to be logged in with the proper permissions in order to call a function. See our document about Authenticating API Function Calls for more information about authenticating APIs from within a script.

  • You can also perform the function by entering the string in your web browser's address bar. This may be useful for testing the function call and viewing its output.

Using the JSON API

To use the JSON API to perform the editzonerecord function from within your custom script:

  • Append the /json-api/editzonerecord function call name, plus the required variables (see below), to a URL which includes the address of your server.

  • For example, on a server whose hostname is example.com, you would include the following string in your script: https://example.com:2087/json-api/editzonerecord

  • You need to be logged in with the proper permissions in order to call a function. See our document about Authenticating API Function Calls for more information about authenticating APIs from within a script.

  • You can also perform the function by entering the string in your web browser's address bar. This may be useful for testing the function call and viewing its output.

Variables

Input

The folliowing input variables are required:

  • domain (string) — The domain name whose zone record you wish to edit.
  • Line (string) — The number of the zone record line you wish to edit.

The following input variables represent parameters to be edited and are optional:

  • address (string) — IP address. Example: 127.0.0.1
    note Note: If you wish to change only the IP in a zone record, the swapip script may suit your purposes better.
  • class (string) — The class of the record.
    • note Note: This value is typically IN, for "Internet."
  • cname (string) — The canonical name in a CNAME record.
  • exchange (string) — In an MX record, the name of the destination mail server.
  • preference (integer) — In an MX record, the priority of the destination mail server.
    • note Note: 0 is the highest priority.
  • expire (string) — A 32-bit time value that specifies the upper limit on the time interval that can elapse before the zone is no longer authoritative.
  • minimum (integer) — The unsigned 32-bit minimum time to live field that should be exported with any record from this zone.
  • mname (integer) — The domain name of the nameserver serving as the original or primary source of data for this zone. Example: ns1.example.com
  • name (string) — Domain name. Example: example.com
  • nsdname (string) — A domain name which specifies a host which should be authoritative for the specified class and domain. Example: ns1.example.com
  • raw (string) — Raw line data.
  • refresh (integer) — 32-bit time interval which will elapse before the zone will be refreshed.
  • retry (integer) — 32-bit time interval which will elapse before a failed refresh will be retried.
  • rname (string) — A domain name which specifies the mailbox of the person responsible for this zone. Example: user.example.com
    • note Note: Enter this value as user.example.com rather than user@example.com
  • serial (integer) — The unsigned 32-bit version number of the original copy of the zone.
  • ttl (integer) — The record's time to live.
  • type (string) — The DNS record type. Example: NS, SOA, A, etc.
  • txtdata (string) — Text record data.

Common record types and associated input variables

For your reference when assembling the edited zone record, here are 4 common record types and their associated input variables.

Record type Required variables Optional variables
A name, address, type class, ttl
MX name, name, exchange, preference, type class, ttl
CNAME name, cname, type class, ttl
NS name, nsdname, type class, ttl

Output

  • editzonerecord — Root-level XML tag for the output of the editzonerecord function.
    • result — Container for the results of the function.
      • status — Result of the function.
        • 1 — success.
        • 0 — failure.
      • statusmsg — Message about the result of the function.

Examples

XML API

Calling https://example.com:2087/xml-api/editzonerecord?domain=example.com&Line=2&ttl=86400 in WebHost Manager will produce output similar to:

<editzonerecord>
     <result>
            <status>1</status>
            <statusmsg>Wrote zone file.</statusmsg>
      </result>
</editzonerecord>

JSON API

Calling https://example.com:2087/json-api/editzonerecord?domain=example.com&Line=2&ttl=86400 in WebHost Manager will produce output similar to:

{
   "result":[
      {
         "status":1,
         "statusmsg":"Wrote zone file."
      }
   ]
}

Topic revision: r8 - 30 Sep 2011 - 15:28:55 - Main.JustinSchaefer