Page tree
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-1=example1.com&domain-2=example2.com&domain-3=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=COMODO+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 example1.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-1' => 'example1.com',
        'domain-2' => 'example2.com',
        'domain-3' => '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' => 'COMODO+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 example1.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-1' => 'example1.com',
        'domain-2' => 'example2.com',
        'domain-3' => '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' => 'COMODO+DCV'
  }
);

Note:

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

 cPanel Template Toolkit
<!-- Check whether the example1.com, example2.com, and example3.com domains can pass Domain Control Validation (DCV) via an HTTP request. -->
[% execute('DCV', 'check_domains_via_http', { 'domain-1' => 'example1.com','domain-2'=>'example2.com','domain-3'=>'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' => 'COMODO+DCV' } ) %]

Note:

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

 Command Line
uapi --user=username DCV check_domains_via_http domain-1=example1.com domain-2=example2.com domain-3=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=COMODO+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. 
  • We introduced this functionality in cPanel & WHM version 56.

 Output (JSON)
{  
   "data":[  
      {  
         "redirects":[  
            {  
               "content":"<!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.example1.com/.well-known/pki-
				validation/853FE9D9F40EEEED96D423632186BD89.txt\">here</a>.</p>\n</body></html>\n",
               "headers":{  
                  "content-length":"295",
                  "content-type":"text/html; charset=iso-8859-1",
                  "date":"Mon, 07 Aug 2017 13:14:58 GMT",
                  "location":"http://www.example1.com/.well-known/pki-
				  validation/853FE9D9F40EEEED96D423632186BD89.txt",
                  "server":"Apache"
               },
               "protocol":"HTTP/1.1",
               "reason":"Moved Permanently",
               "redirects":null,
               "status":"301",
               "success":"",
               "url":"http://example1.com/.well-known/pki-validation/
				853FE9D9F40EEEED96D423632186BD89.txt"
            }
         ],
         "failure_reason":"The system queried for a temporary file at “http://www.example1.com/
		 .well-known/pki-validation/853FE9D9F40EEEED96D423632186BD89.txt”, which was redirected
		 from “http://example1.com/.well-known/pki-validation/853FE9D9F40EEEED96D423632186BD89.txt”.
		 The web server responded with the following error: 404 (Not Found). A DNS (Domain Name System)
		 or web server misconfiguration may exist. The domain “example1.com” resolved to an IP 
		 address “69.94.109.156” that does not exist on this server.",
         "redirects_count":1
      },
      {  
         "redirects":[  

         ],
         "failure_reason":"The content “<!DOCTYPE HTML PUBLIC \"-//W3C//DTD HTML 4.01//EN\" 
		 \"http://www.w3.org/TR/html4/strict.dtd\"><html><head><meta http-equiv=\"Content-” of the DCV
		 (Domain Control Validation) file, as accessed at “http://example2.com/.well-known/pki-
		 validation/3D766176B827BA418F074E5CF2454F34.txt”, did not match the expected value.
		 The domain “example2.com” resolved to an IP address “69.172.201.153” that does not 
		 exist on this server.",
         "redirects_count":0 
	  },
      {  
         "redirects":[  
            {  
               "content":"<head><title>Object moved</title></head>
			   <body><h1>Object Moved</h1>This object may be found 
			   <a HREF=\"https://www.kharkovforum.com/.well-known/pki-validation/
			   B0B40E1B4053050E9B1A2B34299BD208.txt\">here</a>.</body>\r\n",
               "headers":{  
                  "connection":"close",
                  "location":"https://www.kharkovforum.com/.well-known/pki-validation/
				  B0B40E1B4053050E9B1A2B34299BD208.txt",
                  "date":"Mon, 07 Aug 2017 13:15:02 GMT",
                  "content-type":"text/html",
                  "transfer-encoding":"chunked",
                  "cache-control":"private",
                  "server":"Redirector/1.0"
               },
               "protocol":"HTTP/1.1",
               "reason":"Found",
               "redirects":null,
               "status":"302",
               "success":"",
               "url":"http://example3.com/.well-known/pki-validation/
			   B0B40E1B4053050E9B1A2B34299BD208.txt"
            }
         ],
         "failure_reason":"The system failed to fetch the DCV (Domain Control Validation)
		 file at “http://example3.com/.well-known/pki-validation/B0B40E1B4053050E9B1A2B34299BD208.txt”
		 because of an error: The system failed to send an HTTP (Hypertext Transfer Protocol) “GET” 
		 request to “http://example3.com/.well-known/pki-validation/B0B40E1B4053050E9B1A2B34299BD208.txt” 
 	 	 because of an error: Could not connect to 'www.kharkovforum.com:443': Connection refused\n. 
		 The domain “example3.com” resolved to an IP address “98.124.199.39” that does not 
	     exist on this server.",
         "redirects_count":1
      }
   ],
   "status":1,
   "metadata":{  
      "transformed":1
   },
   "messages":null,
   "errors":null
}

Note:

Use cPanel's API Shell interface (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-1, domain-2, and domain-3 parameters.

A valid domain name.example1.com
dcv_file_allowed_charactersarray

Required

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

A valid character or characters.
 Click to view...

[0,1,2,3,4,5,6,7,8,9,\"A\",\"B\",\"C\",\"D\",\"E\",\"F\"]

dcv_file_random_character_countinteger
Required
The number of characters that the certificate provider allows in the DCV check file's filename.
A valid positive integer.32
dcv_file_extensionstring
Required
The DCV check file extension that the certificate provider requires.
A valid file extension.txt
dcv_file_relative_pathstring
Required
The path to the DCV check file.
A valid file path, relative to the domain's document root directory..well-known/pki-validation
dcv_user_agent_stringstring
Required

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

A valid agent string.COMODO+DCV

Returns

Note:

When successful, this function returns null for the failure_reason return.

ReturnTypeDescriptionPossible valuesExample
dataarray of hashes

This array of hashes contains results from each domain parameter's DCV check.

Note:

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

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


redirects

array of hashes

This array of hashes contains information about the

Note:

This function only returns data in the redirects array of hashes if the value of the redirects_count return is 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 summarizes why the function did not pass.

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

A valid message.
 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.example1.com/.well-known/pki-validation/770102
17B0CCF0CCF6211602F9A1B2B2.txt\">here</a>.</p>\n</body></html>\n

headers

hash

This hash contains information that the HTTP::Tiny CPAN module returns.

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

This hash contains the content-length, content-type, date, location, and server returns. 

content-length

string

The number of characters in the header that the HTTP::Tiny CPAN module returns.

The function returns this value in the headers hash.

A valid or empty string.295

content-type

string

The media type and character set of the header.

The function returns this value in the headers hash.

A valid or empty string.text/html; charset=iso-8859-1

date

string

The header generation date and time.

The function returns this value in the headers hash.

A date and time in ddd, DD MMM yyyy HH:mm:ss zzz format where:

  • ddd represents the day.
  • DD represents the date.
  • MMM represents the month.
  • YYYY represents the year.
  • HH represents the hour.
  • mm represents the minute.
  • ss represents the second.
  • zzz represents the timezone.
Mon, 31 Jul 2017 17:32:34 GMT

location

string

The URL to which the header redirects.

The function returns this value in the headers hash.

A valid file path. http://www.example1.com/.well-known/pki-validation/77010217B0CCF0CCF6211602F9A1B2B2.txt

server

string

The type of web server software that the server runs.

The function returns this value in the headers hash.

A valid web server software name.Apache

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 code that the server provides.

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 (in the same order in which the redirections occur), if the value exists.

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

0 — The server does not return a 2XX code.

An empty string ("") — The server does not return a 2XX 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://example1.com/.well-known/pki-validation/77010217B0CCF0CCF6211602F9A1B2B2.txt

failure_reason

string

The reason that the DCV check fails.

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

  • null — The domain passes 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.1