We have a new documentation site for cPanel & WHM! You can find our new documentation site at docs.cpanel.net.

We will continue to maintain our API documentation on this server.

Child pages
  • UAPI Functions - DCV::check_domains_via_http
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 an HTTP request.

Examples


 cPanel or Webmail Session URL
https://hostname.example.com:2083/cpsess##########/execute/DCV/check_domains_via_http?domain=example.com&domain-1=example2.com&domain-2=example3.com&dcv_file_allowed_characters=[0,1,2,3,4,5,6,7,8,9,"A","B","C","D","E","F"]&dcv_file_random_character_count=32&dcv_file_extension=txt&dcv_file_relative_path=.well-known%2Fpki-validation&dcv_user_agent_string=SECTIGO+DCV


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 example.com, example2.com, and example3.com domains can pass Domain Control Validation (DCV) via an HTTP request.
$poll = $cpanel->uapi(
    'DCV', 'check_domains_via_http',
    array(
        'domain' => 'example.com',
        'domain-1' => 'example2.com',
        'domain-2' => 'example3.com',
        'dcv_file_allowed_characters' => '[0,1,2,3,4,5,6,7,8,9,"A","B","C","D","E","F"]',
		'dcv_file_random_character_count' => '32',
		'dcv_file_extension' => 'txt',
		'dcv_file_relative_path' => '.well-known%2Fpki-validation',
		'dcv_user_agent_string' => 'SECTIGO+DCV'
  )
);


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 example.com, example2.com, and example3.com domains can pass Domain Control Validation (DCV) via an HTTP request.
my $poll = $cpliveapi->uapi(
    'DCV', 'check_domains_via_http',
    {
        'domain' => 'example.com',
        'domain-1' => 'example2.com',
        'domain-2' => 'example3.com',
        'dcv_file_allowed_characters' => '[0,1,2,3,4,5,6,7,8,9,"A","B","C","D","E","F"]',
		'dcv_file_random_character_count' => '32',
		'dcv_file_extension' => 'txt',
		'dcv_file_relative_path' => '.well-known%2Fpki-validation',
		'dcv_user_agent_string' => 'SECTIGO+DCV'
  }
);


Note:

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

 Command Line
uapi --user=username DCV check_domains_via_http domain=example.com domain-1=example2.com domain-2=example3.com dcv_file_allowed_characters="[0,1,2,3,4,5,6,7,8,9,\"A\",\"B\",\"C\",\"D\",\"E\",\"F\"]" dcv_file_random_character_count=32 dcv_file_extension="txt" dcv_file_relative_path=.well-known/pki-validation dcv_user_agent_string=SECTIGO+DCV


Notes:

  • You must URI-encode values.
  • username represents your account-level username.
  • For more information and additional output options, read our Guide to UAPI documentation or run the uapi --help command. 
  • If you run CloudLinux™, you must use the full path of the uapi command:

    /usr/local/cpanel/bin/uapi


 Output (JSON)
{
	"metadata": {
		"transformed": 1
	},
	"status": 1,
	"messages": null,
	"data": [{
		"redirects": [],
		"redirects_count": 0,
		"failure_reason": "The system queried for a temporary file at “http://example.com/.well-known/pki-validation/8K4S1AD1U0MFFAOKH64X4Z4MYRSTIGJXFEL1HWB4WOS23F4AP1VCS6SNIOLFGMSLA7ZGLBAI1TPC77VAI4VH2CMJC0ASHXA9UE0Y”, but the web server responded with the following error: 404 (Not Found). A DNS (Domain Name System) or web server misconfiguration may exist. The domain “example.com” resolved to an IP address “2606:2800:0220:0001:0248:1893:25c8:1946” that does not exist on this server."
	}],
	"errors": null,
	"warnings": null
}


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 domains to check.

Note:

Repeat or increment the parameter name to check more than one domain.

  • To check three domains, use the domain parameter multiple times, or use the domain, domain-1, and domain-2 parameters.
A domain name.example.com
dcv_file_allowed_charactersarray

An array of characters that the certificate provider allows in the DCV check file's filename.

This parameter defaults to the following array:

 Click to view...

["A","B","C","D","E","F","G","H","I","J","K","L","M","N","O","P","Q","R","S","T","U","V","W","X","Y","Z","0",1,2,3,4,5,6,7,8,9]

A valid array of characters.
 Click to view...

["A","B","C","D","E","F","G","H","I","J","K","L","M","N","O","P","Q","R","S","T","U","V","W","X","Y","Z",0,1,2,3,4,5,6,7,8,9]

dcv_file_random_character_countinteger
The number of characters that the certificate provider allows in the DCV check file's filename.
This parameter defaults to 100.
A positive integer.32
dcv_file_extensionstring
The DCV check file extension that the certificate provider requires.
This parameter defaults to an empty string.
A valid file extension.txt
dcv_file_relative_pathstring

The DCV check file's filepath.

Note:

In cPanel & WHM version 68 and earlier, this parameter defaults to an empty string.

This parameter defaults to .well-known/pki-validation.

A valid file path, relative to the domain's document root directory..well-known/pki-validation
dcv_user_agent_stringstring

The user agent string that the system uses for the imitated local DCV check.

Important:

The default value can change at any time.

This parameter defaults to Cpanel-HTTP-Client/1.0.

A valid agent string.SECTIGO+DCV
dcv_max_redirectsinteger

The number of domain redirects the system permits the DCV check to follow. The function checks the provider's supported number of redirects. It will then return the redirect array of hashes for the passed value, plus one. This ensures the function will display any redirects causing DCV failures, if any exist.

Note:

  • If you pass a 0 value, this function does not limit the number of redirect returns.
  • Use the Market::get_provider_specific_dcv_constraints UAPI function to list a provider's supported number of redirects.
  • We added this parameter in cPanel & WHM version 80.

This parameter defaults to undef.

A valid integer.2

Returns

ReturnTypeDescriptionPossible valuesExample
dataarray of hashes

An array of hashes that contains results from each domain's DCV check.

Note:

The function returns the domain's results in the same order that you pass them in the domain parameter.

This array of hashes contains the failure_reason and redirects_count returns and the redirects array of hashes.


redirects

array of hashes

An array of hashes that contains DCV check redirect information.

Note:

This array of hashes only contains data if the redirects_count return includes a value greater than zero.

This function returns this value in the data array of hashes.

This array of hashes contains the content, protocol, reason, redirects, status, success, url returns and the headers hash.

content

string

A message that explains why the function failed.

This function returns this value in the redirects array of hashes.

A valid string.
 Click to view...
<!DOCTYPE HTML PUBLIC \"-//IETF//DTD HTML 
2.0//EN\">\n<html><head>\n<title>301 Moved 
Permanently</title>\n
</head><body>\n<h1>Moved 
Permanently</h1>\n
<p>The document has moved <a 
href=\"http://www.example.com/.well-known/pki-validation/770102
17B0CCF0CCF6211602F9A1B2B2.txt\">here</a>.</p>\n</body></html>\n

headers

hash

A hash that contains the HTTP::Tiny CPAN module returns.

The function returns this value in the redirects array of hashes.

A hash of valid header fields.

Note:

This hash's contents vary according to the URL's headers.


protocol

string

The URL's HTTP protocol.

The function returns this value in the redirects array of hashes.

A valid HTTP protocol.HTTP/1.1

reason

string

The HTTP response status message.

The function returns this value in the redirects array of hashes.

A valid string.

Moved Permanently

redirects

array of hashes

An array of hashes of the redirects, if the value exists.

Note:

The function returns this value in the same order that the redirects occur.

The function returns this value in the redirects array of hashes.

An array of hashes or null.

null

status

integer

The HTTP response status code.

The function returns this value in the redirects array of hashes.

A valid status code.301

success

string

Whether the server returns a 2XX HTTP status code.

The function returns this value in the redirects array of hashes.

  • 1 — The server returns a 2XX status code.
  • 0 or an empty string ( "" ) — The server does not return a 2XX status code.
""

url

string

The URL that the function searches for the DCV file.

The function returns this value in the redirects array of hashes.

A valid URL.http://example.com/.well-known/pki-validation/77010217B0CCF0CCF6211602F9A1B2B2.txt

failure_reason

string

The reason that the DCV check failed.

The function returns this value in the data array of hashes.

  • undef — The domain passed the DCV check.
  • A valid string that contains the reason why the DCV check failed.
 Click to view …

"The system queried for a temporary file at “http://example.com/.well-known/pki-validationD01511F4E E535A5442FC378AA946CF41.txt”, but the web server responded with the following error: 404 (Not Found). A DNS (Domain Name System) or web server misconfiguration may exist. The domain “example.com” resolved to an IP address “93.184.216.34” that does not exist on this server."

redirects_count

integer

The number of HTTP redirects that the DCV check follows.

The function returns this value in the data array of hashes.

A valid integer.0