Using the webroot domain verification method


The following is outdated!

See the comment below for notes updated on 2nd December 2015.

Some notes on using the webroot domain verification process with the test ACME server (don’t do this on a live server yet!) in case anyone else wants to have a play with this — this method will be best suited for use on servers that you don’t want any downtime on when renewing certs.

Checkout and install, initially using the standalone method, (note that the git clone URL will be outdated when the pull request is merged), these are the steps that you need to follow on Debian Jessie servers (haven’t tested on anything else)

# delete existing copies of the code if they exist
rm -rf /your/path/letsencrypt/ /etc/letsencrypt/ /var/lib/letsencrypt/
# install in /usr/local and run using standalone once
cd /usr/local
git clone -b simplefs 
cd letsencrypt/
bash bootstrap/
virtualenv --no-site-packages -p python2 venv
./venv/bin/pip install -r requirements.txt acme/ . letsencrypt-apache/ letsencrypt-nginx/ 
/usr/local/letsencrypt/venv/bin/letsencrypt auth

Set up Apache (or whichever server you are running) create /etc/apache2/conf-available/letsencrypt.conf containing:

<IfModule mod_headers.c>
  <LocationMatch "/.well-known/acme-challenge/*">
    Header set Content-Type "application/jose+json"

And then enable it:

a2enmod headers
a2enconf letsencrypt

Then generate a key and cert using the webroot method, optionally supplying multiple domain names to be used as subjectAltNames (SANs)

/usr/local/letsencrypt/venv/bin/letsencrypt --renew-by-default -a webroot --webroot-path /var/www/ --email --text --agree-eula --agree-tos -d -d auth

For the cert that was created using the standalone method to start with you can switch this to the webroot method for renewals by editing /etc/letsencrypt/renewal/ and editing:

authenticator = standalone
webroot_path = None
domains = None


authenticator = webroot
webroot_path = /var/www/
domains =,

Edit your server config or create symlinks to the cert.pem, privkey.pem and chain.pem in /etc/letsencrypt/live/

Update without server restart and www/non-www certificates
Can you use the automatic (cron) certificate update while using manual mode first time?
Preventing Letsencrypt 3rd party clients going the Android way?
Got signed with Let's Encrypt Authority X1 using letsencrypt-nosudo
Raspberry Pi compatibility
Getting Bad Vibes
Feedback and problems: My experience with LE
Error: unauthorized :: The client lacks sufficient authorization :: Error creating new authz :: Name is not whitelisted
Error: unauthorized :: The client lacks sufficient authorization :: Error creating new authz :: Name is not whitelisted
Error: Let's Encrypt SSL certificate installation failed: Failed letsencrypt execution
Disable creating vhost
Letsencrypt asks for root password? Where to find good client documentaion?
Letsencrypt asks for root password? Where to find good client documentaion?

glad to see some more development on the web root method

fyi missing a space



@eve2000 thanks. typo fixed.

The only thing that the webroot plugin lacks at the moment is support for supplying --webroot-path multiple times, but this isn’t a feature I need — I’m happy with one cert per directory.

I think this method is going to be the simplest for people to script to work with existing servers as it doesn’t touch the web server config when run and also doesn’t require any downtime.


Indeed, web root plugin is only thing I need. I just finished a guide for using Letsencrypt web root authentication for my Centmin Mod LEMP stack’s Nginx integration at for CentOS 6.x/7.x :smile:

Is this nginx use case supported?

The webroot plugin has been merged so the instructions at the start of this thread are now out of date, rather than pulling the simplefs branch the main branch can be used:

git clone


YAY ! finally merged !


Here’s a little trick we’re using with nginx and the webroot validator to automate letsencrypt with software that isn’t a webserver. This allows you to validate any domain pointed at your server regardless of whether there’s a website behind it and without having to have a free port 443 for the standalone authenticator.

Create /etc/letsencrypt/webrootauth/

In /etc/nginx/snippets/letsencryptauth.conf

location /.well-known/acme-challenge {
    alias /etc/letsencrypt/webrootauth/.well-known/acme-challenge;
    location ~ /.well-known/acme-challenge/(.*) {
        add_header Content-Type application/jose+json;

In /etc/nginx/sites-enabled/default (or wherever your default server block is. You DO have one, right?)

server {
    listen 80 default_server;
    root /etc/letsencrypt/webrootauth;
    include snippets/letsencryptauth.conf;

server {
    listen 443 ssl spdy default_server;
    ssl on;
    # This can be any cert on your system, it doesn't matter.
    # I think the letsencrypt DV accepts a self-signed cert.
    ssl_certificate ssl/default/default.crt;
    ssl_certificate_key ssl/default/default.key;

    root /etc/letsencrypt/webrootauth;
    include snippets/letsencryptauth.conf;

Then just use the letsencrypt client + webroot authenticator normally with

--webroot-path /etc/letsencrypt/webrootauth

included in the parameters.

You can also include snippets/letsencryptauth.conf in your other server configs to allow using your “global” webroot for them too, it won’t break anything.

Multi domain (SAN) certificate and webroot auth
Support for ports other than 80 and 443
Letsencrypt Webroot Authentication Tested on Beta invited/whitelisted domain
What is the recommended Way to register for nginx proxy certs
Is the webroot plugin's sub-directory consistent?

Thanks Leliana I have been doing the same kind of thing with Apache, in my case I want to be able to password protect an entire site using a .htaccess file and still have a Let’s Encrypt cert for it, I have been using /var/www/well-known for the Let’s Encrypt generated files. In the Apache config for the VirtualHost you simply need an Alias, for example:

Alias "/.well-known/acme-challenge" "/var/www/well-known/"

Make sure the directory exists:

mkdir -p /var/www/well-known/

And run the client with:

--webroot-path /var/www/well-known/

Raspberry Pi compatibility

looks like latest version changed the path to letsencrypt binary has changed from letsencrypt/venv/bin/letsencrypt to relative .local/share/letsencrypt/bin/letsencrypt and options have been removed for --agree-eula and new option --agree-dev-preview added

changes for me in Centmin Mod Nginx server for letencrypt web root authentication

so @chrisc might need to update your above guide :slight_smile:


BTW here is the official doc:


At first: Can someone just explain the basic facts of this “webroot authentication method”. What makes it different from other authentication methods? What is it advantage/goal and in what cases can/should it be used?

And can it be used in this case - because it looks like it does not require many(/any?) command line usage.

All docs I could found about this only show how to use this method, but not why


I actually outlined webroot authentication at Letsencrypt Webroot Authentication Tested on Beta invited/whitelisted domain

As to why use webroot, I mentioned my thoughts here Preventing Letsencrypt 3rd party clients going the Android way?

unfortunately webroot authentication does require SSH access to run so not suited for shared hosting

My vision for webroot authentication is to make it easier for control panels, or folks who know their web server/OS environments best to pre-create their https vhost configurations prior to running webroot authentication.


Nice. So the information were just spread about several topics…
Good to have them here finally.


yeah bit spread out :slight_smile:

also webroot authentication useful for non-standard nginx/apache or other web server setups where paths to web server config files and structure are unknown to letsencrypt


how does webroot require SSH I read that manual mode + webroot is the perfect way to get a cert from your home PC and push the challenge and later the cert to the server.


webroot still runs letsencrypt client which is run in ssh. see my example at


well the client itself doesnt need SSH but rather terminal access at any server (at least that’s what I read) so you can us4e a VM, raspi or anything that runs linux let it run the auth in manual mode you get the challenge, upload it to your server and get your cert.


well SSH = terminal as you’d still need to point domain dns to ip of the terminal accessed server for webroot


as seen in the quote,manual mode does not need SSH on the target server, just a way to get files (for webroot) and the cert (obviously) on it. so you can use any computer that is compatible with LE to get your cert.


As far as I understood it you can use the LE on your desktop computer e.g., but you (temporarily) have to change the ip associated with the domain you want to generate a cert for, so that it points to your desktop computer.
If it is like this this is not really different than just using any other normal authentication method after you change the DNS entry.