certbot
Obtain and install TLS/SSL certificates automatically
TLDR
Obtain a new certificate via webroot authorization, but do not install it automatically
Obtain a new certificate via nginx authorization, installing the new certificate automatically
Obtain a new certificate via apache authorization, installing the new certificate automatically
Renew all Let's Encrypt certificates that expire in 30 days or less (don't forget to restart any servers that use them afterwards)
Simulate the obtaining of a new certificate, but don't actually save any new certificates to disk
Obtain an untrusted test certificate instead
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.