UAPI Functions - DCV::check_domains_via_http

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.

cPanel Template Toolkit

<!-- Check whether the example.com, example2.com, and example3.com domains can pass Domain Control Validation (DCV) via an HTTP request. -->
[% 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' } ) %]
[% FOREACH q = data.resultname %]
     <p>
         [% q %]
     </p>
[% END %]

Note:

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

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)

{  
   "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.example.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.example.com/.well-known/pki-
				  validation/853FE9D9F40EEEED96D423632186BD89.txt",
                  "server":"Apache"
               },
               "protocol":"HTTP/1.1",
               "reason":"Moved Permanently",
               "redirects":null,
               "status":"301",
               "success":"",
               "url":"http://example.com/.well-known/pki-validation/
				853FE9D9F40EEEED96D423632186BD89.txt"
            }
         ],
         "failure_reason":"The system queried for a temporary file at "http://www.example.com/
		 .well-known/pki-validation/853FE9D9F40EEEED96D423632186BD89.txt", which was redirected
		 from "http://example.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 "example.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,
   "warnings":null,
   "errors":null
}

Note:

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

Parameters

Parameter	Type	Description	Possible values	Example
`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_characters`	array	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_count`	integer	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_extension`	string	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_path`	string	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_string`	string	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`

Returns

Return	Type	Description	Possible values	Example
`data`	array 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`

Function information

Module:

DCV

API Version:

UAPI

Available in:

cPanel 60+

Methods:

GET, POST

Required Parameters:

domain

Return Formats:

JSON, XML

Important:

cPanel & WHM version 66 deprecated XML output.

Legacy Equivalents:

(none)

About this module

The DCV module checks Domain Control Validation (DCV).

About UAPI

UAPI accesses and modifies data for cPanel accounts.

Notes:

These functions may require specific features. To enable or disable features, use WHM's Feature Manager interface.
Unless you call this API via the WHM API, you must use the appropriate cPanel ports (2082 or 2083). You can also call some functions via cPanel's Webmail ports (2095 or 2096).

Find a function

Related functions

Page:

UAPI Modules - DCV — The DCV module checks Domain Control Validation (DCV).
Page:

UAPI Functions - DCV::check_domains_via_http — This function checks whether the account's domains can pass Domain Control Validation (DCV) via an HTTP request.
Page:

UAPI Functions - DCV::ensure_domains_can_pass_dcv — This function indicates whether the account's domains can pass a Domain Control Validation (DCV) check.
Page:

UAPI Modules - DNS — The DNS module checks DNS resolution issues.
Page:

UAPI Functions - DNS::ensure_domains_reside_only_locally — This function indicates whether the account's domains resolve exclusively to this server.

Child pages

UAPI Functions - DCV::check_domains_via_http

Description

Examples

Parameters

Returns

Function information

About this module

About UAPI

Find a function

Related functions