Certbot Manual – Let’s Encrypt SSL

https://certbot.eff.org/docs/using.html?highlight=wildcard#dns-plugins

Manual

If you’d like to obtain a certificate running certbot on a machine other than your target webserver or perform the steps for domain validation yourself, you can use the manual plugin. While hidden from the UI, you can use the plugin to obtain a certificate by specifying certonly and --manual on the command line. This requires you to copy and paste commands into another terminal session, which may be on a different computer.

The manual plugin can use either the http or the dns challenge. You can use the --preferred-challenges option to choose the challenge of your preference.

The http challenge will ask you to place a file with a specific name and specific content in the /.well-known/acme-challenge/ directory directly in the top-level directory (“web root”) containing the files served by your webserver. In essence it’s the same as the webroot plugin, but not automated.

When using the dns challenge, certbot will ask you to place a TXT DNS record with specific contents under the domain name consisting of the hostname for which you want a certificate issued, prepended by _acme-challenge.

For example, for the domain example.com, a zone file entry would look like:

_acme-challenge.example.com. 300 IN TXT "gfj9Xq...Rg85nM"

Renewal with the manual plugin

Certificates created using --manual do not support automatic renewal unless combined with an authentication hook script via --manual-auth-hook to automatically set up the required HTTP and/or TXT challenges.

If you can use one of the other plugins which support autorenewal to create your certificate, doing so is highly recommended.

To manually renew a certificate using --manual without hooks, repeat the same certbot --manual command you used to create the certificate originally. As this will require you to copy and paste new HTTP files or DNS TXT records, the command cannot be automated with a cron job.

Combining plugins

Sometimes you may want to specify a combination of distinct authenticator and installer plugins. To do so, specify the authenticator plugin with --authenticator or -a and the installer plugin with --installer or -i.

For instance, you could create a certificate using the webroot plugin for authentication and the apache plugin for installation.

certbot run -a webroot -i apache -w /var/www/html -d example.com

Or you could create a certificate using the manual plugin for authentication and the nginx plugin for installation. (Note that this certificate cannot be renewed automatically.)

certbot run -a manual -i nginx -d example.com

Managing certificates

To view a list of the certificates Certbot knows about, run the certificates subcommand:

certbot certificates

This returns information in the following format:

Found the following certificates:
  Certificate Name: example.com
    Domains: example.com, www.example.com
    Expiry Date: 2017-02-19 19:53:00+00:00 (VALID: 30 days)
    Certificate Path: /etc/letsencrypt/live/example.com/fullchain.pem
    Key Type: RSA
    Private Key Path: /etc/letsencrypt/live/example.com/privkey.pem

Certificate Name shows the name of the certificate. Pass this name using the --cert-name flag to specify a particular certificate for the runcertonlycertificatesrenew, and delete commands. Example:

certbot certonly --cert-name example.com

Re-creating and Updating Existing Certificates

You can use certonly or run subcommands to request the creation of a single new certificate even if you already have an existing certificate with some of the same domain names.

If a certificate is requested with run or certonly specifying a certificate name that already exists, Certbot updates the existing certificate. Otherwise a new certificate is created and assigned the specified name.

The --force-renewal--duplicate, and --expand options control Certbot’s behavior when re-creating a certificate with the same name as an existing certificate. If you don’t specify a requested behavior, Certbot may ask you what you intended.

--force-renewal tells Certbot to request a new certificate with the same domains as an existing certificate. Each domain must be explicitly specified via -d. If successful, this certificate is saved alongside the earlier one and symbolic links (the “live” reference) will be updated to point to the new certificate. This is a valid method of renewing a specific individual certificate.

--duplicate tells Certbot to create a separate, unrelated certificate with the same domains as an existing certificate. This certificate is saved completely separately from the prior one. Most users will not need to issue this command in normal circumstances.

--expand tells Certbot to update an existing certificate with a new certificate that contains all of the old domains and one or more additional new domains. With the --expand option, use the -d option to specify all existing domains and one or more new domains.

Example:

certbot --expand -d existing.com,example.com,newdomain.com

If you prefer, you can specify the domains individually like this:

certbot --expand -d existing.com -d example.com -d newdomain.com

Consider using --cert-name instead of --expand, as it gives more control over which certificate is modified and it lets you remove domains as well as adding them.

--allow-subset-of-names tells Certbot to continue with certificate generation if only some of the specified domain authorizations can be obtained. This may be useful if some domains specified in a certificate no longer point at this system.

Whenever you obtain a new certificate in any of these ways, the new certificate exists alongside any previously obtained certificates, whether or not the previous certificates have expired. The generation of a new certificate counts against several rate limits that are intended to prevent abuse of the ACME protocol, as described here.

Changing a Certificate’s Domains

The --cert-name flag can also be used to modify the domains a certificate contains, by specifying new domains using the -d or --domains flag. If certificate example.com previously contained example.com and www.example.com, it can be modified to only contain example.com by specifying only example.com with the -d or --domains flag. Example:

certbot certonly --cert-name example.com -d example.com

The same format can be used to expand the set of domains a certificate contains, or to replace that set entirely:

certbot certonly --cert-name example.com -d example.org,www.example.org

Revoking certificates

If you need to revoke a certificate, use the revoke subcommand to do so.

A certificate may be revoked by providing its name (see certbot certificates) or by providing its path directly:

certbot revoke --cert-name example.com

certbot revoke --cert-path /etc/letsencrypt/live/example.com/cert.pem

If the certificate being revoked was obtained via the --staging--test-cert or a non-default --server flag, that flag must be passed to the revoke subcommand.

Note

After revocation, Certbot will (by default) ask whether you want to delete the certificate. Unless deleted, Certbot will try to renew revoked certificates the next time certbot renew runs.

You can also specify the reason for revoking your certificate by using the reason flag. Reasons include unspecified which is the default, as well as keycompromiseaffiliationchangedsuperseded, and cessationofoperation:

certbot revoke --cert-name example.com --reason keycompromise

Revoking by account key or certificate private key

By default, Certbot will try revoke the certificate using your ACME account key. If the certificate was created from the same ACME account, the revocation will be successful.

If you instead have the corresponding private key file to the certificate you wish to revoke, use --key-path to perform the revocation from any ACME account:

certbot revoke --cert-path /etc/letsencrypt/live/example.com/cert.pem --key-path /etc/letsencrypt/live/example.com/privkey.pem

Deleting certificates

If you need to delete a certificate, use the delete subcommand.

Note

Read this and the Safely deleting certificates sections carefully. This is an irreversible operation and must be done with care.

Note

Do not manually delete certificate files from inside /etc/letsencrypt/. Always use the delete subcommand.

A certificate may be deleted by providing its name with --cert-name. You may find its name using certbot certificates.

Otherwise, you will be prompted to choose one or more certificates to delete:

certbot delete --cert-name example.com
# or to choose from a list:
certbot delete

Safely deleting certificates

Deleting a certificate without following the proper steps can result in a non-functioning server. To safely delete a certificate, follow all the steps below to make sure that references to a certificate are removed from the configuration of any installed server software (Apache, nginx, Postfix, etc) before deleting the certificate.

To explain further, when installing a certificate, Certbot modifies Apache or nginx’s configuration to load the certificate and its private key from the /etc/letsencrypt/live/ directory. Before deleting a certificate, it is necessary to undo that modification, by removing any references to the certificate from the webserver’s configuration files.

Follow these steps to safely delete a certificate:

  1. Find all references to the certificate (substitute example.com in the command for the name of the certificate you wish to delete):sudo bash -c ‘grep -R live/example.com /etc/{nginx,httpd,apache2}’ If there are no references found, skip directly to Step 4.If some references are found, they will look something like:/etc/apache2/sites-available/000-default-le-ssl.conf:SSLCertificateFile /etc/letsencrypt/live/example.com/fullchain.pem /etc/apache2/sites-available/000-default-le-ssl.conf:SSLCertificateKeyFile /etc/letsencrypt/live/example.com/privkey.pem
  2. You will need a self-signed certificate to replace the certificate you are deleting. The following command will generate one for you, saving the certificate at /etc/letsencrypt/self-signed-cert.pem and its private key at /etc/letsencrypt/self-signed-privkey.pem:sudo openssl req -nodes -batch -x509 -newkey rsa:2048 -keyout /etc/letsencrypt/self-signed-privkey.pem -out /etc/letsencrypt/self-signed-cert.pem -days 356
  3. For each reference found in Step 1, open the file in a text editor and replace the reference to the existing certificate with a reference to the self-signed certificate.Continuing from the previous example, you would open /etc/apache2/sites-available/000-default-le-ssl.conf in a text editor and modify the two matching lines of text to instead say:SSLCertificateFile /etc/letsencrypt/self-signed-cert.pem SSLCertificateKeyFile /etc/letsencrypt/self-signed-privkey.pem
  4. It is now safe to delete the certificate. Do so by running:
    sudo certbot delete --cert-name example.com

Was this helpful?

0 / 0