This guide explains various ways to obtain a new certificate.
Open a terminal, and execute the following command (insert your own email address and domain):
lego --email="firstname.lastname@example.org" --domains="example.com" --http run
You will find your certificate in the
.lego folder of the current working directory:
$ ls -1 ./.lego/certificates example.com.crt example.com.issuer.crt example.com.json example.com.key [maybe more files for different domains...]
example.com.crtis the server certificate (including the CA certificate),
example.com.keyis the private key needed for the server certificate,
example.com.issuer.crtis the CA certificate, and
example.com.jsoncontains some JSON encoded meta information.
For each domain, you will have a set of these four files.
For wildcard certificates (
*.example.com), the filenames will look like
.key files are PEM-encoded x509 certificates and private keys.
If you’re looking for a
privkey.pem, you can just use
If you can’t or don’t want to start a web server, you need to use a DNS provider. lego comes with support for many providers, and you need to pick the one where your domain’s DNS settings are set up. Typically, this is the registrar where you bought the domain, but in some cases this can be another third-party provider.
For this example, let’s assume you have set up CloudFlare for your domain.
Execute this command:
CLOUDFLARE_EMAIL="email@example.com" \ CLOUDFLARE_API_KEY="yourprivatecloudflareapikey" \ lego --email "firstname.lastname@example.org" --dns cloudflare --domains "example.org" run
The first step in the process of obtaining certificates involves creating a signing request. This CSR bundles various information, including the domain name(s) and a public key. By default, lego will hide this step from you, but if you already have a CSR, you can easily reuse it:
lego --email="email@example.com" --http --csr="/path/to/csr.pem" run
lego will infer the domains to be validated based on the contents of the CSR, so make sure the CSR’s Common Name and optional SubjectAltNames are set correctly.
If you have an existing server running on port 80, the
--http option also requires the
This just writes the http-01 challenge token to the given directory in the folder
.well-known/acme-challenge and does not start a server.
The given directory should be publicly served as
/ on the domain(s) for the validation to complete.
If the given directory is not publicly served you will have to support rewriting the request to the directory;
You could also implement a rewrite to rewrite
.well-known/acme-challenge to the given directory
You should be able to run an existing webserver on port 80 and have lego write the token file with the HTTP-01 challenge key authorization to
<webroot dir>/.well-known/acme-challenge/ by running something like:
lego --accept-tos --email firstname.lastname@example.org --http --http.webroot /path/to/webroot --domains example.com run
You can easily hook into the certificate-obtaining process by providing the path to a script:
lego --email="email@example.com" --domains="example.com" --http run --run-hook="./myscript.sh"
Some information is provided through environment variables:
LEGO_ACCOUNT_EMAIL: the email of the account.
LEGO_CERT_DOMAIN: the main domain of the certificate.
LEGO_CERT_PATH: the path of the certificate.
LEGO_CERT_KEY_PATH: the path of the certificate key.
A typical use case is distribute the certificate for other services and reload them if necessary. Since PEM-formatted TLS certificates are understood by many programs, it is relatively simple to use certificates for more than a web server.
This example script installs the new certificate for a mail server, and reloads it. Beware: this is just a starting point, error checking is omitted for brevity.
#!/bin/bash # copy certificates to a directory controlled by Postfix postfix_cert_dir="/etc/postfix/certificates" # our Postfix server only handles mail for @example.com domain if [ "$LEGO_CERT_DOMAIN" = "example.com" ]; then install -u postfix -g postfix -m 0644 "$LEGO_CERT_PATH" "$postfix_cert_dir" install -u postfix -g postfix -m 0640 "$LEGO_CERT_KEY_PATH" "$postfix_cert_dir" systemctl reload postfix@-service fi