LinuxCommandLibrary

certbot

Obtain and install TLS/SSL certificates automatically

TLDR

Obtain a new certificate via webroot authorization, but do not install it automatically

$ sudo certbot certonly --webroot [[-w|--webroot-path]] [path/to/webroot] [[-d|--domain]] [subdomain.example.com]
copy

Obtain a new certificate via nginx authorization, installing the new certificate automatically
$ sudo certbot --nginx [[-d|--domain]] [subdomain.example.com]
copy

Obtain a new certificate via apache authorization, installing the new certificate automatically
$ sudo certbot --apache [[-d|--domain]] [subdomain.example.com]
copy

Renew all Let's Encrypt certificates that expire in 30 days or less (don't forget to restart any servers that use them afterwards)
$ sudo certbot renew
copy

Simulate the obtaining of a new certificate, but don't actually save any new certificates to disk
$ sudo certbot --webroot [[-w|--webroot-path]] [path/to/webroot] [[-d|--domain]] [subdomain.example.com] --dry-run
copy

Obtain an untrusted test certificate instead
$ sudo certbot --webroot [[-w|--webroot-path]] [path/to/webroot] [[-d|--domain]] [subdomain.example.com] --test-cert
copy

SYNOPSIS

certbot [SUBCOMMAND] [options]

Common Subcommands:
   run
   certonly
   renew
   revoke
   delete
   certificates
   register

PARAMETERS

run
    Obtain and install a new certificate.

certonly
    Obtain a certificate without installing it.

renew
    Renew all installed certificates that are due for renewal.

revoke
    Revoke a previously issued certificate.

delete
    Delete a certificate and its configuration.

certificates
    List all certificates managed by Certbot.

register
    Register a new account with Let's Encrypt.

-d DOMAIN
    Specify a domain name for which to obtain a certificate. Can be specified multiple times.

--webroot -w PATH
    Authenticate using the webroot method, placing files in a specified webroot directory.

--apache
    Use the Apache plugin for authentication and installation.

--nginx
    Use the Nginx plugin for authentication and installation.

--standalone
    Run a standalone web server for authentication. Requires port 80/443 to be free.

--dns-PLUGIN
    Use a specific DNS plugin (e.g., --dns-cloudflare, --dns-route53) for DNS-01 authentication.

--email EMAIL
    Email address for urgent notices and account recovery.

--agree-tos
    Automatically agree to the Let's Encrypt Terms of Service.

--force-renewal
    Force renewal of a certificate even if it's not yet due.

--dry-run
    Perform a test run without making any changes to the system or requesting real certificates.

--non-interactive -n
    Run Certbot non-interactively, suitable for scripting.

DESCRIPTION

Certbot is a free, open-source software tool developed by the Electronic Frontier Foundation (EFF). Its primary purpose is to automate the process of obtaining, installing, and renewing SSL/TLS certificates from Let's Encrypt, a free, automated, and open certificate authority.

Certbot simplifies the traditionally complex task of securing websites with HTTPS. It handles various aspects, including:
Domain Validation: It can automatically prove control of your domain to Let's Encrypt using methods like HTTP-01 (by serving a specific file) or DNS-01 (by creating a specific DNS record).
Certificate Issuance: Once validated, Certbot requests and receives the SSL/TLS certificate.
Installation: For supported web servers like Apache and Nginx, Certbot can automatically configure the server to use the new certificate, enabling HTTPS.
Automated Renewal: Let's Encrypt certificates are short-lived (90 days), requiring frequent renewal. Certbot excels here by automating renewals, often through cron jobs or systemd timers, ensuring continuous HTTPS availability without manual intervention.

By abstracting away much of the complexity, Certbot has played a pivotal role in the widespread adoption of HTTPS, making secure communication accessible to a vast number of websites and users globally.

CAVEATS

Root Privileges: Certbot typically requires root or sudo privileges to perform operations like writing to system directories, configuring web servers, or binding to privileged ports (80/443).
Network Connectivity: The server running Certbot must have outbound network access to Let's Encrypt's API servers. For HTTP-01 challenges, incoming connections on port 80 or 443 must be allowed. For DNS-01, DNS resolution must be functional.
Web Server Configuration: While Certbot's plugins are robust, highly customized web server configurations might sometimes require manual adjustments post-installation.
Wildcard Certificates: Obtaining wildcard certificates (*.example.com) specifically requires the DNS-01 authentication method.

AUTOMATED RENEWAL MECHANISM

Certbot certificates have a 90-day validity period. To ensure continuous HTTPS availability, Certbot is designed to be run periodically (e.g., daily or twice a day) via a cron job or systemd timer. The certbot renew command checks if any certificates are due for renewal (typically when they are within 30 days of expiry) and renews them automatically, reloading the web server if necessary.

PLUGIN ARCHITECTURE

Certbot utilizes a plugin-based architecture to support various web servers and authentication methods. This allows it to interact seamlessly with different environments. Examples include installer plugins like --apache and --nginx that handle both authentication and configuration, and authenticator plugins like --webroot or --standalone for challenge validation, or specific DNS plugins for the DNS-01 challenge.

HISTORY

Certbot's origins trace back to the Let's Encrypt client, an initiative by the Electronic Frontier Foundation (EFF), Mozilla, Cisco, Akamai, and others, launched with the goal of encrypting the entire web. The initial client, released in beta in 2015, was designed to simplify obtaining certificates from the nascent Let's Encrypt certificate authority.

In 2016, the project was officially renamed to Certbot to reflect its capability to manage certificates more broadly, though its primary use remains with Let's Encrypt. This renaming also aimed to distinguish the client from the Let's Encrypt CA itself. Since its inception, Certbot has been instrumental in driving the widespread adoption of HTTPS, making secure communication a standard rather than an exception on the internet. It continues to be actively developed and maintained by the EFF.

SEE ALSO

openssl(1), apachectl(8), nginx(8), systemctl(1), crontab(1)

Copied to clipboard