Child pages
  • UAPI Functions - DCV::check_domains_via_dns
Skip to end of metadata
Go to start of metadata

Description

This function checks whether the account's domains can pass Domain Control Validation (DCV) via a DNS request.

Examples


 cPanel or Webmail Session URL
https://hostname.example.com:2083/cpsess##########/execute/DCV/check_domains_via_dns?domain=example.com&domain-1=example2.com


Note:

This example calls the UAPI function via a cPanel session. For more information, read our Guide to UAPI documentation. 

 LiveAPI PHP Class
$cpanel = new CPANEL(); // Connect to cPanel - only do this once.
 
// Check whether the domains can pass Domain Control Validation (DCV) via a DNS request.
$poll = $cpanel->uapi(
    'DCV', 'check_domains_via_dns',
    array(
        'domain' => 'example.com',
		'domain-1' => 'example2.com'
  )
);


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.
 
#  Check whether the domains can pass Domain Control Validation (DCV) via a DNS request.
my $poll = $cpliveapi->uapi(
    'DCV', 'check_domains_via_dns',
    {
        'domain' => 'example.com',
		'domain-1' => 'example2.com'
  }
);


Note:

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

 cPanel Template Toolkit
<!-- Check whether the domains can pass Domain Control Validation (DCV) via a DNS request. -->
[% execute('DCV', 'check_domains_via_dns', { 'domain' => 'example.com','domain-1'=>'example2.com' } ) %]


Note:

For more information, read our Guide to Template Toolkit documentation. 

 Command Line
uapi --user=username DCV check_domains_via_dns domain=example.com domain-1=example2.com
 Output (JSON)
{
  "data": [
    {
      "dcv_string": "_dcv-test-record=wsWRlG9IsG7KNnLdIsx9Oz2oTw8m5q0imRR9L6LnDBz14sZelvDHqrJyJc6LA0DY",
      "domain": "example.org",
      "query_results": [
	    "_dcv-test-record=wsWRlG9IsG7KNnLdIsx9Oz2oTw8m5q0imRR9L6LnDBz14sZelvDHqrJyJc6LA0DY"
      ],
      "succeeded": 1,
      "zone": "example.org"
	},
	{
      "dcv_string": "_dcv-test-record=wRUFPTN1DskKDG8KHfYM_5cQF5QUGWq1_A2ovO8rKsrIYO_HilAjsQABFCrbJkLX",
      "domain": "example2.org",
      "failure_reason": "The DNS query to “_dcv-test-record.example2.org” for the DCV challenge returned no “TXT” record that matches the value “_dcv-test-record=wRUFPTN1DskKDG8KHfYM_5cQF5QUGWq1_A2ovO8rKsrIYO_HilAjsQABFCrbJkLX”."
      "query_results": [
      ],
      "succeeded": 0,
      "zone": "example2.org"
	}
  ],
  "errors": null,
  "messages": null,
  "metadata":{
    "transformed": 1
  },
  "status": 1,
  "warnings": null
}


Note:

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

Parameters

ParameterTypeDescriptionPossible valuesExample
domainstring

Required

The domains to check.

Note:

To check multiple domains, duplicate or increment the parameter name. For example, to check three domains, use the domain parameter multiple times or use the domain, domain-1, and domain-2 parameters.

A valid domain name.

example.com

Returns

ReturnTypeDescriptionPossible valuesExample

hash

This hash contains the results from each domain parameter's DCV check.

Note:

The function returns the results from the domain parameter in the same order in which you called them.

This hash reference contains the dcv_string, domain, query_results, succeeded, and zone returns.


dcv_string

string

The expected value of the queried DNS record.

The function returns this value in the unnamed hash.

A valid DCV string.
_dcv-test-record=wsWRlG9IsG7KNnLdIsx9Oz2oTw8m5q0imRR9L6LnDBz14sZelvDHqrJyJc6LA0DY

domain

string

The domain that the system verified.

The function returns this value in the unnamed hash.

A valid domain.example.com

failure_reason

stringThe reason the DCV check failed.

A valid string that contains the reason why the DCV check failed.

Note:

If the server fails to update the DNS zone, the system returns this value.

The DNS query to “_dcv-test-record.example2.org” for the DCV challenge returned no “TXT” record that matches the value “_dcv-test-record=wRUFPTN1DskKDG8KHfYM_5cQF5QUGWq1_A2ovO8rKsrIYO_HilAjsQABFCrbJkLX”.

query_results

array of strings

The strings that the DNS query returned.

The function returns this value in the unnamed hash.

  • A list of returned values from the DNS query.
  • An empty array.

    Note:

    If the server fails to update the DNS zone, the system returns the failure_reason value.

_dcv-test-record=wsWRlG9IsG7KNnLdIsx9Oz2oTw8m5q0imRR9L6LnDBz14sZelvDHqrJyJc6LA0DY

succeeded

Boolean

Whether the DCV check succeeded.

The function returns this value in the unnamed hash.

  • 1 — At least one of the query_results values equals the dcv_string value.

  • 0 — None of the query_results values equal the dcv_string value.

1

zone

string

The altered and queried DNS zone name.

The function returns this value in the unnamed hash.

A valid DNS zone name.example.com