How command certbot --nginx work under hood

Please explain to me or where i can read about what is happening when i run command certbot --nginx. I thought that its should create file token in my web root directory of nginx, but i can't find this file.

The --nginx authenticator first finds a server block for port 80 and/or port 443 that has your domain name as a server_name. It makes a temp change to those matching server blocks. This change replies to the HTTP Challenge request with a return statement and does not create a file.

If your nginx listens on a different port you can use --http-01-port X so that the plug-in matches to a server block with that port number. This only works when you have a router or similar forwarding the original challenge to this non-standard port.

If the --nginx authenticator does not find any matching server block it might create one from a default port 80 server block. This is not a good thing to rely on in general.

You can see what it does in your case by looking at /var/log/letsencrypt/letsencrypt.log

A sample temp change looks like below.

server {rewrite ^(/.well-known/acme-challenge/.*) $1 break; # managed by Certbot

    listen 80;
    listen [::]:80;
    root /var/www/html;

location = /.well-known/acme-challenge/MxkxRxkxzxkxgxHxvxkxOxpxkxVxkx8xkx4xFxExuxg {default_type text/plain;return 200 MxkxRxkxzxkxgxHxvxkxOxpxkxVxkx8xkx4xFxExuxg.AwQwgwgwzwgwJwgw4wew3wrwxwiw-wpwvwqwxwBwswT;} # managed by Certbot

And welcome to the LE community forum @corlovito
I love the avitar! :slight_smile:

Cheers from Miami :beers:


Thank you for the answer ! Did I understand correctly that for the found block, changes will be temporarily made to the nginx config on the fly and after receiving the certificate, these changes will be returned ?


Thank you for the warm welcome :raised_back_of_hand:


Yes. After adding the rewrite/return the nginx server is reloaded to make those effective. The changes are removed and nginx reloaded again when the challenge is complete.

Note though that when using the --nginx plug-in as authenticator and installer (the default) that the plug-in will make permanent changes to your nginx config. These changes vary depending on the state of your config but may include adding a redirect from http->https, setting up a server block for port 443 with the new certs, and similar.

If you don't want Certbot to make permanent changes, you can use certonly command like: certbot certonly --nginx
This means the plug-in will only do authentication and not "installation" (permanent config changes)

Or, use certbot certonly --webroot option which creates the challenge file in the webroot path which you were describing in your first post. Although, I think certonly --nginx is easier than --webroot for most cases (or even just --nginx if that works for you)


Thanks for explaining this to me :pray: