Steps For Troubleshooting AutoSSL
This guide is meant to address some common issues with AutoSSL's domain validation process and hopefully help add understanding of issues when they occur.
*Please note that all testing here was done using the cPanel provider for AutoSSL
Contents
Step 1. Running AutoSSL
Step 2. Using the Logs
Step 3. Determine which error you're receiving and common causes
Step 4. Re-run AutoSSL check
Step 5. Pending Queue
Step 1. Run AutoSSL - this will happen automatically on systems with AutoSSL enabled.
- You can check to see if you have AutoSSL enabled by going to WHM>>SSL/TLS>>Manage AutoSSL → Providers
- An AutoSSL check can also be initialized on the command line with the following:
Code:
/usr/local/cpanel/bin/autossl_check ( --user=<username> | --all | --help )- You can also use the WHMAPI1 SSL functions to make a number of modifications to the AutoSSL configuration. These can be found here: WHM API 1 Sections - SSL - Developer Documentation - cPanel Documentation
Step 2. Use the logs UI to determine which domains were checked/which passed/etc. You can see the AutoSSL logs at WHM>>SSL/TLS>>Manage AutoSSL → Logs
Step 3. Determine which error you're receiving and check the common causes also listed if a domain is failing validation. This will be listed in the logs with the errors being some variation of the ones listed below. Please also note that some of the errors have changed as far as formatting in v70, I've listed the error in both v68 and v70 of cPanel formats for the ones I had available.
- v68 or before: "The domain “example.com” failed domain control validation: “example.com” does not resolve to any IPv4 addresses on the internet."
- v70+: WARN Local DCV error (example.com): “example.com” does not resolve to any IPv4 addresses on the internet.
- This is one of the most common issues we see. Typically, this is due to a DNS issue - i.e., a misconfiguration of the authoritative nameservers. Some common ways to troubleshoot this are:
- Using the dig command with the +trace option information on dig can be found by typing man dig or here: dig(1): DNS lookup utility - Linux man page
Code:dig +trace domain.com - If you're not familiar with dig or the CLI you might want to use a site such as intoDNS or LeafDNS which will explain where the failure occurs.
- Using the dig command with the +trace option information on dig can be found by typing man dig or here: dig(1): DNS lookup utility - Linux man page
- This is also sometimes due to being unaware that the domain has expired - always check with your registrar to ensure that the domain is valid.
- You can see the validity of the domain by running a whois check on it
Code:# whois cpanel.net [Querying whois.verisign-grs.com] [whois.verisign-grs.com] Domain Name: CPANEL.NET Registry Domain ID: 41945574_DOMAIN_NET-VRSN Registrar WHOIS Server: whois.tucows.com Registrar URL: http://www.tucowsdomains.com Updated Date: 2018-01-05T03:29:59Z Creation Date: 2000-11-12T01:12:26Z Registry Expiry Date: 2026-11-12T01:12:26Z Registrar: Tucows Domains Inc. Registrar IANA ID: 69 Registrar Abuse Contact Email: Registrar Abuse Contact Phone: Domain Status: clientTransferProhibited https://icann.org/epp#clientTransferProhibited Domain Status: clientUpdateProhibited https://icann.org/epp#clientUpdateProhibited Domain Status: serverDeleteProhibited https://icann.org/epp#serverDeleteProhibited Domain Status: serverTransferProhibited https://icann.org/epp#serverTransferProhibited Name Server: C.CPANEL.NET Name Server: HG.CPANEL.NET Name Server: MN.CPANEL.NET DNSSEC: unsigned URL of the ICANN Whois Inaccuracy Complaint Form: https://www.icann.org/wicf/
- sites like who.is will show you this information as well.
- You can see the validity of the domain by running a whois check on it
- This is one of the most common issues we see. Typically, this is due to a DNS issue - i.e., a misconfiguration of the authoritative nameservers. Some common ways to troubleshoot this are:
- v68 or before: "The domain “example.com” failed domain control validation: The system failed to fetch the DCV (Domain Control Validation) file at “http://example.com/.well-known/pki-validation/hash.txt” because of an error: Due to an error, the system was unable to send a Hypertext Transfer Protocol (HTTP) request "GET" to "http://example.com/.well-known/pki-validation/hash.txt": Size of response body exceeds the maximum allowed of 16384 "
- mod_evasive - EA-7330 - we have a case open at the time of writing this where sometimes mod_evasive can add the server's own IP to the blacklist which can cause issues with AutoSSL as one of the checks done internally originates from the domain's primary IP
- nginx - caching - to test if this is the case switch back to Apache and attempt to provision the certificate once more
- varnish - caching - to test if this is the case switch back to Apache and attempt to provision the certificate once more
- DNS Caching - If you just pointed your domain you may need to wait for propagation to complete before attempting to provision an AutoSSL certificate.
- Forced redirection to https - there are a few ways this can be done, through an .htaccess file and through the CMS if this is occurring both need to be checked.
- mod_cache - an exception should be added for the DCV check
- mod_evasive - EA-7330 - we have a case open at the time of writing this where sometimes mod_evasive can add the server's own IP to the blacklist which can cause issues with AutoSSL as one of the checks done internally originates from the domain's primary IP
- v68 or before: "The system failed to fetch the DCV (Domain Control Validation) file at “http://example.com/.well-known/pki-validation/hash.txt” because of an error: The system failed to send an HTTP (Hypertext Transfer Protocol) “GET” request to “http://example.com/.well-known/pki-validation/hash.txt” because of an error: Timed out while waiting for socket to become ready for reading . The domain “example.com” resolved to an IP address “1.2.3.4” that does not exist on this server.”
- v70 +: WARN Local DCV error (example.com): The system failed to fetch the DCV (Domain Control Validation) file at “http://example.com/.well-known/pki-validation/hash.txt” because of an error: The system failed to send an HTTP (Hypertext Transfer Protocol) “GET” request to “http://example.com/.well-known/pki-validation/hash.txt” because of an error: Could not connect to 'example.com:80': Connection timed out . The domain “example.com” resolved to an IP address “1.2.3.4” that does not exist on this server.
- The domain doesn't resolve to the server
- To find where it resolves to use the dig command mentioned above
- This can sometimes be caused by the domain status for instance if the domain is expired or if it's awaiting validation from the registrar.
- v68 or before: " WARN The domain “example.com” failed domain control validation: The system queried for a temporary file at “http://example.com/.well-known/pki-validation/hash.txt”, but the web server responded with the following error: 403 (Forbidden). A DNS (Domain Name System) or web server misconfiguration may exist.
- Most commonly this issue is caused by an .htaccess redirect
- an .htaccess file can be anywhere on the server but most commonly it's in /home/$user/ or /home/$user/public_html
- You can test whether or not the .htaccess is at fault by renaming it temporarily and running the AutoSSL check once more.
- A lot of times just running a curl request (after renaming the .htaccess file) setting the user agent string to COMDO DCV will be useful to determine what's going on when checking for the DCV file and if it's going to be successful. In a lot of cases I'll do the following:
Code:$ curl -k --user-agent "COMODO DCV" http://domain.tld/.well-known/pki-validation/hash.txt hash comodoca.com
- This issue can also be caused by 'deny from' declarations in .htaccess - these can be added manually, there are also some CMS plugins that add these automatically
- This can also be cause by a FilesMatch directive that denies .txt files
Step 4. Once you've identified which error it is and you've used the error list with common causes to fix the issue re-run the AutoSSL check.
Step 5. Once you've run the AutoSSL check and can confirm that the domain passed, you can see the pending orders in WHM>>SSL/TLS>>Manage AutoSSL → Pending Queue . The domain is removed from the pending queue once it's issued and installed.
Contributed By: @cPanelLauren
