This quick guide answers one of the most common questions during Domain Control Validation (DCV): what is the .well-known folder? You will also learn how to create the .well-known folder on your server and why you need it in the first place.
Table of Contents
- What is the .well-known folder?
- What should I put in the .well-known directory?
- How to create the .well-know folder?
- Frequently Asked Questions
What is the .well-known folder?
Inside your ~/public directory on your server, you might find the .well-known folder. Well-known URIs are Uniform Resource Identifiers for well-known services or information available consistently across servers at URLs.
Some servers create the .well-known folder automatically, but sometimes, you may have to add it manually. This directory acts as a web-based protocol to fetch site metadata about a host before making a request.
What is the .well-known folder used for?
When ordering an SSL Certificate, you must prove domain ownership as part of DCV. If you choose the HTTP/HTTPS method, you’ll have to create the .well-known directory, the folder where you must upload a TEXT file for the CA to scan and approve your SSL request.
The file should be accessible via a live website link. After you add the validation file, the CA crawler system will scan your website and look for the file. Once it finds it, you should pass domain validation within minutes.
What should I put in the .well-known directory?
To confirm you are the owner of the domain name using the HTTP method, you’ll have to upload a TXT file to a location on your website and server that looks like this:
As you can see from the URL path, you should place the file in the .well-known folder and the pki-validation subfolder of the document root directory for the domain name.
You can download the validation file after you select the HTTP method when ordering your SSL certificate. The hash file name is a string of random characters. You must upload it as it comes from the CA without changing its name or content.
How to create the .well-know folder?
To create the well-known folder, you’ll need access to your server via an SFTP client, a web hosting control panel, or any other appropriate means.
Here’s how to create the .well-known folder on the most popular platforms:
How to create the .well-known folder on Linux-based servers?
The instructions below are valid for Ubuntu, Debian, and CentOS servers.
- Go to the root directory of your website
- Create a directory called “.well-known“
- Inside it, create another folder called “pki-validation“
- Upload the TXT file inside the “pki-validation” directory
How to create the .well-known folder in cPanel?
- Log into WHM, or skip this step if you don’t have WHM
- Locate and log into the cPanel account for your domain name
- Click on “File Manager”
- Choose the “Web Root (public_html/www)” option and click “Go.”
- Create a new folder called “.well-known”
- Inside that folder create another folder called “pki-validation”
- Upload your TXT file inside the “pki-validation” folder
How to Create the .well-known folder in Plesk?
- Use the “File Manager” option and go to the “Files” section in the right-side menu.
- You should create the “.well-known” folder in the default document root folder for your domain, which in Plesk is “httpdocs”.
- To create the folder, select “New”, then “Create Directory”.
- Inside the “.well-known” folder, create the “pki-validation” subfolder.
- Use the “Upload” button to add the validation TXT file into the “pki-validation” folder.
How to create the .well-known folder in Windows IIS servers?
Windows-based servers do not allow you to place a dot in a folder name, therefore you need to follow these steps:
- Go to the C: drive
- Create a new folder called “well-known”
- Inside the “well-known” folder, create another folder named “pki-validation”
So far, your folders should look like this: C:\well-known\pki-validation
- Upload the TXT file in the “pki-validation folder”
- Open the IIS Manager on your server
- Do right-click on your website and select “Add Virtual Directory”
- In the Alias section write “.well-known”
- In the “Psychical Path” area enter the path to the “well-known” folder. For example:
- Press “OK” to create this alias
How to create a .well-known folder in WordPress?
You can create a .well-known folder in WordPress in three different ways.
- Using a special plugin
- Through your web-hosting panel
- Via an SFTP Client such as FileZilla
We don’t recommend using a plugin as it may cause compatibility and security issues over time. Instead, use our instructions above to create the .well-known folder in cPanel, the most popular hosting panel.
If you don’t have cPanel, use an SFTP client. Connect to your server and inside your ~/public folder look for the “.well-knwon” directory. If it’s not there, right-click on the public folder, choose “Create directory”, and name the new directory “.well-known”.
How to create a .well-known folder in AWS?
- Use the bash command to create the .well-known.folder in the AWS EC2 instance:
mkdir -p .well-known/pki-validation
- Put your validation file in the pki-validation subfolder:
How to Create the .well-known in macOS X Server?
Connect to your server via the built-in FTP client or the Command Line Interface.
- Press Command + K
- In the “Connect to Server” window, enter the address of the FTP server. For example, ftp://ftp.yourdomain.com. Click “Connect”.
- Next, enter your FTP username and password and hit “Connect” again.
- Find the root directory of your domain.
- Create a directory called “.well-known”
- Inside the “.well-known” folder, create another folder called “pki-validation”.
- Upload the TXT file inside the “pki-validation” directory
Command Line Interface
You can use SSH and the Secure Copy protocol to upload the TXT file.
Where “AC3E5D6I8G12935LSJEIK.txt” is the validation file name, “your_username” is the username of your server account, “hostname.tld” is your Mac OSX server hostname, and “/Library/WebServer/Documents/” is the default directory of the document root folder.
For all server types, if you did everything correctly, you should be able open the following URL and see the hash code along with “comodoca.com” in any web browser:
Frequently Asked Questions
What if the .well-known folder already exists for SSL?
If the .well-known folder exists on your server, open it, then create the pki-validation sub-folder and upload the file.
Why is .well-known directory protected?
Since it’s a public directory, the .well-known folder is often protected to prevent hackers from storing and distributing ransomware and phishing pages. You may need to change the file permissions to access it.
How to move the .well-known directory?
The .well-known folder must always remain in your public directory. If you move it to another location, you won’t be able to pass the SSL validation via the HTTP method.
Should I remove the well-known folder?
Yes, it’s needed each time you renew the SSL Certificate. The CA still has to verify if you’re the domain name’s owner.
The HTTP/HTTPS validation process is pretty straightforward. You should get your SSL certificate in no time if you follow the exact steps outlined above. Now that you know what the .well-known folder is and how to create it on different servers, renewing your certificate or getting a new one will be much faster.