CERTBOT(1)

📦
version 5.5.0 · 7 versions
, in ubuntu stonking

💖 CERTBOT(1) — the manual page, bestie edition 💖

okay so. This is the CERTBOT(1) manual page, from the Certbot corner of your man pages. Sit down, grab a strawberry 🍓, and let me tell you about the tool that's gonna make HTTPS just... happen for you.

✨ NAME ✨

certbot — Automatically configure HTTPS using Let's Encrypt 🎀

🌈 SYNOPSIS 🌈

The whole point, the entire mission statement, the vibe, is this: Certbot, Let's Encrypt, and the ACME protocol (that's Automated Certificate Management Environment, say it with your chest) exist so that you can set up an HTTPS server and have it automatically obtain a browser-trusted certificate — with zero human intervention. No clicking. No drama. No 2am certificate panic. ✨

The way this works is you run a certificate management agent on your web server. That's the whole trick. 🧚

And this agent is used to:

  • Automatically prove to the Let's Encrypt CA that you control the website 👑
  • Obtain a browser-trusted certificate and set it up on your web server 💅
  • Keep track of when your certificate is going to expire, and renew it ⏰
  • Help you revoke the certificate if that ever becomes necessary 😭

🌸 OPTIONS 🌸

Here's the usage, exactly as it is, no cap:

usage:
  certbot [SUBCOMMAND] [options] [-d DOMAIN] [-d DOMAIN] ...

So like — certbot can obtain and install HTTPS/TLS/SSL certificates. And by default? It will attempt to use a webserver both for obtaining and for installing the certificate. Two jobs, one agent, main character energy. 👑

The most common SUBCOMMANDS and flags are:

💖 obtain, install, and renew certificates

  • run (the default) — Obtain & install a certificate in your current webserver 🫶
  • certonly — Obtain or renew a certificate, but do not install it
  • renew — Renew all previously obtained certificates that are near expiry ⏳
  • enhance — Add security enhancements to your existing configuration ✨
  • -d DOMAINS — Comma-separated list of domains to obtain a certificate for
  • --apache — Use the Apache plugin for authentication & installation
  • --standalone — Run a standalone webserver for authentication
  • --nginx — Use the Nginx plugin for authentication & installation
  • --webroot — Place files in a server's webroot folder for authentication
  • --manual — Obtain certificates interactively, or using shell script hooks
  • -n — Run non-interactively 🤫
  • --test-cert — Obtain a test certificate from a staging server
  • --dry-run — Test "renew" or "certonly" without saving any certificates to disk

💜 manage certificates

  • certificates — Display information about certificates you have from Certbot
  • revoke — Revoke a certificate (supply --cert-name or --cert-path)
  • delete — Delete a certificate (supply --cert-name)
  • reconfigure — Update a certificate's configuration (supply --cert-name)

💙 manage your account

  • register — Create an ACME account
  • unregister — Deactivate an ACME account
  • update_account — Update an ACME account
  • show_account — Display account details
  • --agree-tos — Agree to the ACME server's Subscriber Agreement
  • -m EMAIL — Email address for important account notifications 📧
  • -h, --help — the og. shows this help message and exits. that's it, that's the whole thing 💅
  • -c, --config CONFIG_FILE — the path to your config file. (default: /etc/letsencrypt/cli.ini and ~/.config/letsencrypt/cli.ini) — yes bestie, both, it peeks at both of them.
  • -v, --verbose — stack it like it's a limited edition 🎀 use this flag multiple times to incrementally increase the verbosity of output, e.g. -vvv. (default: 0)
  • --max-log-backups MAX_LOG_BACKUPS — specifies the maximum number of backup logs that should be kept by Certbot's built in log rotation. setting this flag to 0 disables log rotation entirely, which makes Certbot always append to the same log file. (default: 1000) — so zero is a vibe, but it's a chaotic one 🙈
  • -n, --non-interactive, --noninteractive — run without ever asking for user input. this may require additional command line flags, and the client will try to explain which ones are required if it finds one missing. (default: False) — it's giving "no talking, just vibes" ✨
  • --force-interactive — force Certbot to be interactive even if it detects it's not being run in a terminal. this flag cannot be used with the renew subcommand. (default: False)
  • -d, --domains, --domain DOMAIN — domain names to include. for multiple domains you can use multiple -d flags or enter a comma separated list of domains as a parameter. all domains will be included as Subject Alternative Names on the certificate. the first domain will be used as the certificate name, unless otherwise specified or if you already have a certificate with the same name. in the case of a name conflict, a number like -0001 will be appended to the certificate name. (default: Ask) — the first one is basically the main character 👑
  • --ip-address IP_ADDRESSES — IP addresses to include. for multiple IP addresses you can use multiple --ip-address flags. all IP addresses will be included as Subject Alternative Names on the certificate. (default: [])
  • --eab-kid EAB_KID — Key Identifier for External Account Binding. (default: None)
  • --eab-hmac-key EAB_HMAC_KEY — HMAC key for External Account Binding. (default: None)
  • --eab-hmac-alg EAB_HMAC_ALG — HMAC algorithm for External Account Binding. (default: HS256)
  • --cert-name CERTNAME — certificate name to apply. this name is used by Certbot for housekeeping and in file paths; it doesn't affect the content of the certificate itself. certificate name cannot contain filepath separators (i.e. / or \, depending on the platform). to see certificate names, run certbot certificates. when creating a new certificate, specifies the new certificate's name. (default: the first provided domain or the name of an existing certificate on your system for the same domains) — pure backstage-pass energy, fr fr 🫶
  • --dry-run — perform a test run against the Let's Encrypt staging server, obtaining test (invalid) certificates but not saving them to disk. this can only be used with the certonly and renew subcommands. it may trigger webserver reloads to temporarily modify & roll back configuration files. --pre-hook and --post-hook commands run by default. --deploy-hook commands do not run, unless enabled by --run-deploy-hooks. the test server may be overridden with --server. (default: False) — the ultimate dress rehearsal 🧚
  • --debug-challenges — after setting up challenges, wait for user input before submitting to CA. when used in combination with the -v option, the challenge URLs or FQDNs and their expected return values are shown. (default: False)
  • --required-profile REQUIRED_PROFILE — request the given profile name from the ACME server. if the ACME server returns an error, issuance (or renewal) will fail. for long-term reliability, setting preferred_profile instead may be preferable because it allows fallback to a default. use this setting when renewal failure is preferable to fallback. (default: None) — highkey a "no plan b" moment 😭
  • --preferred-profile PREFERRED_PROFILE — request the given profile name from the ACME server, or fallback to default. if the given profile name exists in the ACME directory, use it to request a certificate. otherwise, fall back to requesting a certificate without a profile (which means the CA will use its default profile). this allows renewals to succeed even if the CA deprecates and removes a given profile. (default: None) — the resilient queen we stan 💖
  • --preferred-chain PREFERRED_CHAIN — set the preferred certificate chain. if the CA offers multiple certificate chains, prefer the chain whose topmost certificate was issued from this Subject Common Name. if no match, the default offered chain will be used. (default: None)
  • --preferred-challenges PREF_CHALLS — a sorted, comma delimited list of the preferred challenge to use during authorization, with the most preferred challenge listed first (Eg, "dns" or "http,dns"). not all plugins support all challenges. see https://certbot.eff.org/docs/using.html#plugins for details. ACME Challenges are versioned, but if you pick "http" rather than "http-01", Certbot will select the latest version automatically. (default: []) — first one on the list gets first dibs 🌈
  • --issuance-timeout ISSUANCE_TIMEOUT — this option specifies how long (in seconds) Certbot will wait for the server to issue a certificate. (default: 90) — the patience meter ⏳
  • --user-agent USER_AGENT — set a custom user agent string for the client. user agent strings allow the CA to collect high level statistics about success rates by OS, plugin and use case, and to know when to deprecate support for past Python versions and flags. if you wish to hide this information from the Let's Encrypt server, set this to "". (default: CertbotACMEClient/5.5.0 (certbot; OS_NAME OS_VERSION) Authenticator/XXX Installer/YYY (SUBCOMMAND; flags: FLAGS) Py/major.minor.patchlevel). the flags encoded in the user agent are: --duplicate, --force-renew, --allow-subset-of-names, -n, and whether any hooks are set.
  • --user-agent-comment USER_AGENT_COMMENT — add a comment to the default user agent string. may be used when repackaging Certbot or calling it from another tool to allow additional statistical data to be collected. ignored if --user-agent is set. (Example: Foo-Wrapper/1.0) (default: None) — literally a little signature on your work ✍️

⚙️ automation 🦋

Flags for automating execution & other tweaks

  • --keep-until-expiring, --keep, --reinstall — if the cert you're asking for matches one you've already got, just hold onto the existing one until it's actually due for renewal, no drama. (for the run subcommand this basically means reinstall the existing certificate.) (default: Ask)
  • --expand — if your existing cert is a strict subset of the names you're requesting, go ahead and expand it, replacing it with all the extra names. glow up ✨ (default: Ask)
  • --version — shows the program's version number and dips. classic. (default: none)
  • --force-renewal, --renew-by-default — if a cert already exists for the domains you asked for, renew it right now, no matter how far from expiry it is. (ngl --keep-until-expiring is often the more appropriate move here). also implies --expand. (default: False)
  • --renew-with-new-domains — if a cert already exists for the requested certificate name but it doesn't match the domains you're asking for, renew it right now, regardless of whether it's near expiry. (default: False)
  • --reuse-key — when renewing, keep using the same private key as the existing cert. (default: False)
  • --no-reuse-key — when renewing, do not reuse that private key. heads up bestie: not reusing private keys is already the default behavior of Certbot, so this option exists to unset --reuse-key on a cert that already has it on. (default: False)
  • --new-key — when renewing or replacing a cert, generate a fresh private key, even if --reuse-key is set on the existing one. combining --new-key and --reuse-key means the private key gets replaced now and then reused in future renewals. (default: False)
  • --allow-subset-of-names — during domain validation, don't call it a failure just because authorizations couldn't be obtained for a strict subset of the requested domains. lowkey useful when you want renewals for a bunch of domains to succeed even if some of them don't point at this system anymore. 💀 this option cannot be used with --csr. (default: False)
  • --agree-tos — agree to the ACME Subscriber Agreement. (default: Ask)
  • --duplicate — lets you make a certificate lineage that duplicates an existing one (both can be renewed in parallel, twin vibes 🫶). (default: False)
  • -q, --quiet — silences literally all output except errors. perfect for automation via cron. implies --non-interactive. (default: False)

🔒 security

security parameters & server settings 🔐

  • --rsa-key-size N — size of the RSA key. (default: 2048)
  • --key-type {rsa,ecdsa} — type of generated private key. only ONE per invocation can be provided at this time, so pick your fighter. (default: ecdsa)
  • --elliptic-curve N — the SECG elliptic curve name to use. please see RFC 8446 for supported values. (default: secp256r1)
  • --must-staple — adds the OCSP Must-Staple extension to the certificate. autoconfigures OCSP Stapling for supported setups (Apache version >= 2.3.3). (default: False)
  • --redirect — automatically redirect all HTTP traffic to HTTPS for the newly authenticated vhost. (default: redirect enabled for install and run, disabled for enhance)
  • --no-redirect — do not automatically redirect all HTTP traffic to HTTPS for the newly authenticated vhost. (default: redirect enabled for install and run, disabled for enhance)
  • --hsts — adds the Strict-Transport-Security header to every HTTP response, forcing the browser to always use SSL for the domain. defends against SSL Stripping, periodt. 🛡️ (default: False)
  • --uir — adds the "Content-Security-Policy: upgrade-insecure-requests" header to every HTTP response, forcing the browser to use https:// for every http:// resource. (default: False)
  • --staple-ocsp — enables OCSP Stapling. a valid OCSP response gets stapled to the certificate that the server offers during TLS. (default: False)
  • --strict-permissions — requires that all configuration files are owned by the current user. only needed if your config is somewhere unsafe like /tmp/. (default: False)
  • --auto-hsts — gradually increasing max-age value for the HTTP Strict Transport Security security header. (default: False)

🧪 testing

the following flags are meant for testing and integration purposes only. like, do not be out here using these in prod, bestie. 🙈

  • --run-deploy-hooks — when performing a test run using --dry-run or reconfigure, run any applicable deploy hooks. this includes hooks set on the command line, saved in the certificate's renewal configuration file, or present in the renewal-hooks directory. to exclude directory hooks, use --no-directory-hooks. the hook(s) will only be run if the dry run succeeds, and will use the current active certificate, not the temporary test certificate acquired during the dry run. this flag is recommended when modifying the deploy hook using reconfigure. (default: False)
  • --test-cert, --staging — use the Let's Encrypt staging server to obtain or revoke test (invalid) certificates; equivalent to --server https://acme-staging-v02.api.letsencrypt.org/directory. (default: False)
  • --debug — shows tracebacks in case of errors. (default: False)
  • --no-verify-ssl — disables verification of the ACME server's certificate. the root certificates trusted by Certbot can be overridden by setting the REQUESTS_CA_BUNDLE environment variable. (default: False)
  • --http-01-port HTTP01_PORT — port used in the http-01 challenge. this only affects the port Certbot listens on. a conforming ACME server will still attempt to connect on port 80. (default: 80)
  • --http-01-address HTTP01_ADDRESS — the address the server listens to during the http-01 challenge. (default: )
  • --https-port HTTPS_PORT — port used to serve HTTPS. this affects which port Nginx will listen on after an LE certificate is installed. (default: 443)
  • --break-my-certs — be willing to replace or renew valid certificates with invalid (testing/staging) certificates. yes this is as chaotic as it sounds. ⚠️ (default: False)

📁 paths

flags for changing execution paths & servers

  • --cert-path CERT_PATH — path to where the certificate is saved (with certonly --csr), installed from, or revoked. (default: None)
  • --key-path KEY_PATH — path to private key for certificate installation or revocation (if account key is missing). (default: None)
  • --fullchain-path FULLCHAIN_PATH — accompanying path to a full certificate chain (certificate plus chain). (default: None)
  • --chain-path CHAIN_PATH — accompanying path to a certificate chain. (default: None)
  • --config-dir CONFIG_DIR — configuration directory. (default: /etc/letsencrypt)
  • --work-dir WORK_DIR — working directory. (default: /var/lib/letsencrypt)
  • --logs-dir LOGS_DIR — logs directory. (default: /var/log/letsencrypt)
  • --server SERVER — ACME Directory Resource URI. (default: https://acme-v02.api.letsencrypt.org/directory)

🗂️ manage

various subcommands and flags are available for managing your certificates, so you can be the main character of your own PKI 👑

  • certificates — list certificates managed by Certbot
  • delete — clean up all files related to a certificate
  • renew — renew all certificates (or one specified with --cert-name)
  • revoke — revoke a certificate specified with --cert-path or --cert-name
  • reconfigure — update renewal configuration for a certificate specified by --cert-name

🏃 run

options for obtaining & installing certificates

🎯 certonly

options for modifying how a certificate is obtained

  • --deploy-hook DEPLOY_HOOK — a command that gets run in a shell, once, for every certificate that got issued successfully — and yes, also on all the renewals after that 💖. Unless you're using --disable-hook-validation, the first word of that command has to be the absolute pathname of an executable, or something you can find through the PATH environment variable. For this command, the shell variable $RENEWED_LINEAGE points at the config live subdirectory (like, for example, "/etc/letsencrypt/live/example.com") that's holding the shiny new certs and keys ✨, and the shell variable $RENEWED_DOMAINS is a space-delimited list of renewed cert domains (for example, "example.com www.example.com"). (default: None)
  • --csr CSR — path to a Certificate Signing Request (CSR), in DER or PEM format. Heads up bestie: right now --csr only works with the certonly subcommand. (default: None)

✨ renew ✨

The renew subcommand will attempt to renew any certificates you previously obtained if they're close to expiring, then prints a summary of the results 📋. By default, renew reuses the plugins and options that were used to obtain — or most recently renew — each certificate. You can vibe-check whether future renewals will actually succeed with --dry-run 🧪. Individual certificates can be renewed with the --cert-name option. There are hooks you can run before and after renewal; see https://certbot.eff.org/docs/using.html#renewal for more on these 🎀.

  • --pre-hook PRE_HOOK — a command that runs in a shell before obtaining any certificates. Unless --disable-hook-validation is used, the first word of the command has to be the absolute pathname of an executable, or one found via the PATH environment variable. It's mainly meant for renewal, where you can use it to temporarily shut down a webserver that might beef with the standalone plugin 🛑. It only gets called if a certificate is actually about to be obtained/renewed. When you're renewing several certificates that have identical pre-hooks, only the first one runs. (default: None)
  • --post-hook POST_HOOK — a command that runs in a shell after attempting to obtain/renew certificates. Unless --disable-hook-validation is used, the first word of the command has to be the absolute pathname of an executable, or one found via the PATH environment variable. You can use it to deploy renewed certificates, or to restart any servers that got stopped by --pre-hook 🔄. It only runs if an attempt was made to obtain/renew a certificate. If multiple renewed certificates have identical post-hooks, only one gets run. (default: None)
  • --disable-hook-validation — normally, the commands you specify for --pre-hook/--post-hook/--deploy-hook get checked for validity, so we can see if the programs being run are in the $PATH — that way mistakes get caught early, even when the hooks aren't running yet 👀. The problem is the validation is kinda simplistic and fails if you use more advanced shell constructs, so you can use this switch to turn it off. (default: False)
  • --no-directory-hooks — disables running executables found in Certbot's hook directories. (default: False)
  • --disable-renew-updates — disables the automatic updates to your server configuration that the selected installer plugin would otherwise do, and that get triggered when the user runs "certbot renew", regardless of whether the certificate is renewed. Ngl this setting doesn't apply to important TLS configuration updates. (default: False)
  • --no-autorenew — disables auto renewal of certificates. (default: False)

🌸 certificates 🌸

List certificates managed by Certbot 📜

💅 delete 💅

Options for deleting a certificate

🎀 revoke 🎀

Options for revocation of certificates

  • --reason {unspecified,keycompromise,affiliationchanged,superseded,cessationofoperation} — specifies the reason for revoking a certificate. (default: unspecified)
  • --delete-after-revoke — deletes certificates after revoking them, along with all previous and later versions of those certificates. (default: Ask)
  • --no-delete-after-revoke — does not delete certificates after revoking them. Bestie, use this one with caution 🚨 because the renew subcommand will attempt to renew undeleted revoked certificates. (default: Ask)

🦋 register 🦋

Options for account registration

  • -m, --email EMAIL — email used for registration and recovery contact. Use a comma to register multiple emails, ex: u1@example.com,u2@example.com. (default: Ask).
  • --eff-email — share your e-mail address with EFF. (default: Ask)
  • --no-eff-email — don't share your e-mail address with EFF. (default: Ask)

✨ update_account ✨

Options for account modification

💜 unregister 💜

Options for account deactivation.

  • --account ACCOUNT_ID — account ID to use. (default: None)

🌈 install 🌈

Options for modifying how a certificate is deployed

⭐ rollback ⭐

Options for rolling back server configuration changes

  • --checkpoints N — revert configuration N number of checkpoints. (default: 1)

🧚 plugins 🧚

Options for the "plugins" subcommand

  • --init — initialize plugins. (default: False)
  • --prepare — initialize and prepare plugins. (default: False)
  • --authenticators — limit to authenticator plugins only. (default: None)
  • --installers — limit to installer plugins only. (default: None)

💖 enhance 💖

Helps to harden the TLS configuration by adding security enhancements to already existing configuration. We love a glow-up 🔒✨

🍓 show_account 🍓

Options useful for the "show_account" subcommand:

🫶 reconfigure 🫶

Common options that may be updated with the "reconfigure" subcommand:

👑 plugins 👑

Plugin Selection: the Certbot client supports an extensible plugins architecture 🧩. See 'certbot plugins' for a list of all installed plugins and their names. You can force a particular plugin by setting the options provided below. Running --help <plugin_name> will list flags specific to that plugin.

  • --configurator CONFIGURATOR — name of the plugin that's both an authenticator and an installer. Should not be used together with --authenticator or --installer. (default: Ask)
  • -a, --authenticator AUTHENTICATOR — authenticator plugin name. (default: None)
  • -i, --installer INSTALLER — installer plugin name (also used to find domains). (default: None)
  • --apache — obtain and install certificates using Apache. (default: False)
  • --nginx — obtain and install certificates using Nginx. (default: False)
  • --standalone — obtain certificates using a "standalone" webserver. (default: False)
  • --manual — provide laborious manual instructions for obtaining a certificate. (default: False)
  • --webroot — obtain certificates by placing files in a webroot directory. (default: False)
  • --dns-cloudflare — obtain certificates using a DNS TXT record (if you're using Cloudflare for DNS). (default: False)
  • --dns-digitalocean — obtain certificates using a DNS TXT record (if you're using DigitalOcean for DNS). (default: False)
  • --dns-dnsimple — obtain certificates using a DNS TXT record (if you're using DNSimple for DNS). (default: False)
  • --dns-dnsmadeeasy — obtain certificates using a DNS TXT record (if you're using DNS Made Easy for DNS). (default: False)
  • --dns-gehirn — obtain certificates using a DNS TXT record (if you're using Gehirn Infrastructure Service for DNS). (default: False)
  • --dns-google — obtain certificates using a DNS TXT record (if you're using Google Cloud DNS). (default: False)
  • --dns-linode — obtain certificates using a DNS TXT record (if you're using Linode for DNS). (default: False)
  • --dns-luadns — obtain certificates using a DNS TXT record (if you're using LuaDNS for DNS). (default: False)
  • --dns-nsone — obtain certificates using a DNS TXT record (if you're using NS1 for DNS). (default: False)
  • --dns-ovh — obtain certificates using a DNS TXT record (if you're using OVH for DNS). (default: False)
  • --dns-rfc2136 — obtain certificates using a DNS TXT record (if you're using BIND for DNS). (default: False)
  • --dns-route53 — obtain certificates using a DNS TXT record (if you're using Route53 for DNS). (default: False)
  • --dns-sakuracloud — obtain certificates using a DNS TXT record (if you're using Sakura Cloud for DNS). (default: False)

🦋 apache:

Apache Web Server plugin — and heads up bestie, the default values of the Apache plugin options change depending on the operating system Certbot is run on. So don't come for me if your defaults look different. 💅

  • --apache-enmod APACHE_ENMOD — path to the Apache a2enmod binary (default: None)
  • --apache-dismod APACHE_DISMOD — path to the Apache a2dismod binary (default: None)
  • --apache-le-vhost-ext APACHE_LE_VHOST_EXT — SSL vhost configuration extension (default: -le-ssl.conf)
  • --apache-server-root APACHE_SERVER_ROOT — Apache server root directory (default: /etc/apache2)
  • --apache-vhost-root APACHE_VHOST_ROOT — Apache server VirtualHost configuration root (default: None)
  • --apache-logs-root APACHE_LOGS_ROOT — Apache server logs directory (default: /var/log/apache2)
  • --apache-challenge-location APACHE_CHALLENGE_LOCATION — directory path for challenge configuration (default: /etc/apache2)
  • --apache-handle-modules APACHE_HANDLE_MODULES — let the installer handle enabling required modules for you (Only Ubuntu/Debian currently) (default: False)
  • --apache-handle-sites APACHE_HANDLE_SITES — let the installer handle enabling sites for you (Only Ubuntu/Debian currently) (default: False)
  • --apache-ctl APACHE_CTL — full path to Apache control script (default: apache2ctl)
  • --apache-bin APACHE_BIN — full path to apache2/httpd binary (default: None)

☁️ dns-cloudflare:

Obtain certificates using a DNS TXT record (if you are using Cloudflare for DNS). Cloudflare girlies, this one's for you 🫶

  • --dns-cloudflare-propagation-seconds DNS_CLOUDFLARE_PROPAGATION_SECONDS — the number of seconds to wait for DNS to propagate before asking the ACME server to verify the DNS record. (default: 10)
  • --dns-cloudflare-credentials DNS_CLOUDFLARE_CREDENTIALS — Cloudflare credentials INI file. (default: None)

🌊 dns-digitalocean:

Obtain certificates using a DNS TXT record (if you are using DigitalOcean for DNS).

  • --dns-digitalocean-propagation-seconds DNS_DIGITALOCEAN_PROPAGATION_SECONDS — the number of seconds to wait for DNS to propagate before asking the ACME server to verify the DNS record. (default: 10)
  • --dns-digitalocean-credentials DNS_DIGITALOCEAN_CREDENTIALS — DigitalOcean credentials INI file. (default: None)

🍓 dns-dnsimple:

Obtain certificates using a DNS TXT record (if you are using DNSimple for DNS).

  • --dns-dnsimple-propagation-seconds DNS_DNSIMPLE_PROPAGATION_SECONDS — the number of seconds to wait for DNS to propagate before asking the ACME server to verify the DNS record. (default: 30)
  • --dns-dnsimple-credentials DNS_DNSIMPLE_CREDENTIALS — DNSimple credentials INI file. (default: None)

💜 dns-dnsmadeeasy:

Obtain certificates using a DNS TXT record (if you are using DNS Made Easy for DNS).

  • --dns-dnsmadeeasy-propagation-seconds DNS_DNSMADEEASY_PROPAGATION_SECONDS — the number of seconds to wait for DNS to propagate before asking the ACME server to verify the DNS record. (default: 60)
  • --dns-dnsmadeeasy-credentials DNS_DNSMADEEASY_CREDENTIALS — DNS Made Easy credentials INI file. (default: None)

🌸 dns-gehirn:

Obtain certificates using a DNS TXT record (if you are using Gehirn Infrastructure Service for DNS).

  • --dns-gehirn-propagation-seconds DNS_GEHIRN_PROPAGATION_SECONDS — the number of seconds to wait for DNS to propagate before asking the ACME server to verify the DNS record. (default: 30)
  • --dns-gehirn-credentials DNS_GEHIRN_CREDENTIALS — Gehirn Infrastructure Service credentials file. (default: None)

🌈 dns-google:

Obtain certificates using a DNS TXT record (if you are using Google Cloud DNS for DNS).

ngl bestie the auto-detect on that project one is so convenient, you literally don't have to lift a finger 💅

🧚 dns-linode:

Obtain certificates using a DNS TXT record (if you are using Linode for DNS).

  • --dns-linode-propagation-seconds DNS_LINODE_PROPAGATION_SECONDS — the number of seconds to wait for DNS to propagate before asking the ACME server to verify the DNS record. (default: 120)
  • --dns-linode-credentials DNS_LINODE_CREDENTIALS — Linode credentials INI file. (default: None)

🌙 dns-luadns:

Obtain certificates using a DNS TXT record (if you are using LuaDNS for DNS).

  • --dns-luadns-propagation-seconds DNS_LUADNS_PROPAGATION_SECONDS — the number of seconds to wait for DNS to propagate before asking the ACME server to verify the DNS record. (default: 30)
  • --dns-luadns-credentials DNS_LUADNS_CREDENTIALS — LuaDNS credentials INI file. (default: None)

⭐ dns-nsone:

Obtain certificates using a DNS TXT record (if you are using NS1 for DNS).

  • --dns-nsone-propagation-seconds DNS_NSONE_PROPAGATION_SECONDS — the number of seconds to wait for DNS to propagate before asking the ACME server to verify the DNS record. (default: 30)
  • --dns-nsone-credentials DNS_NSONE_CREDENTIALS — NS1 credentials file. (default: None)

🦋 dns-ovh:

Obtain certificates using a DNS TXT record (if you are using OVH for DNS).

  • --dns-ovh-propagation-seconds DNS_OVH_PROPAGATION_SECONDS — the number of seconds to wait for DNS to propagate before asking the ACME server to verify the DNS record. (default: 120)
  • --dns-ovh-credentials DNS_OVH_CREDENTIALS — OVH credentials INI file. (default: None)

🔥 dns-rfc2136:

Obtain certificates using a DNS TXT record (if you are using BIND for DNS).

  • --dns-rfc2136-propagation-seconds DNS_RFC2136_PROPAGATION_SECONDS — the number of seconds to wait for DNS to propagate before asking the ACME server to verify the DNS record. (default: 60)
  • --dns-rfc2136-credentials DNS_RFC2136_CREDENTIALS — RFC 2136 credentials INI file. (default: None)

👑 dns-route53:

Obtain certificates using a DNS TXT record (if you are using AWS Route53 for DNS).

not a single option to configure here — Route53 really said "I got this myself" and honestly? iconic. It just picks up your AWS credentials the normal way ✨

🎀 dns-sakuracloud:

Obtain certificates using a DNS TXT record (if you are using Sakura Cloud for DNS).

  • --dns-sakuracloud-propagation-seconds DNS_SAKURACLOUD_PROPAGATION_SECONDS — the number of seconds to wait for DNS to propagate before asking the ACME server to verify the DNS record. (default: 90)
  • --dns-sakuracloud-credentials DNS_SAKURACLOUD_CREDENTIALS — Sakura Cloud credentials file. (default: None)

🫶 manual:

Authenticate through manual configuration or custom shell scripts. When using shell scripts, an authenticator script must be provided. The environment variables available to this script depend on the type of challenge. $CERTBOT_IDENTIFIER will always contain the domain or IP address being authenticated. For HTTP-01 and DNS-01, $CERTBOT_VALIDATION is the validation string, and $CERTBOT_TOKEN is the filename of the resource requested when performing an HTTP-01 challenge. An additional cleanup script can also be provided and can use the additional variable $CERTBOT_AUTH_OUTPUT which contains the stdout output from the auth script. For both authenticator and cleanup script, on HTTP-01 and DNS-01 challenges, $CERTBOT_REMAINING_CHALLENGES will be equal to the number of challenges that remain after the current one, and $CERTBOT_ALL_IDENTIFIERS contains a comma-separated list of all identifiers that are challenged for the current certificate.

  • --manual-auth-hook MANUAL_AUTH_HOOK — path or command to execute for the authentication script (default: None)
  • --manual-cleanup-hook MANUAL_CLEANUP_HOOK — path or command to execute for the cleanup script (default: None)
okay so this is the "you're on your own, bestie, but we'll hand you the env vars" mode 💀 if you're writing custom scripts, read those variables carefully — they're your whole personality here 😭

🌸 nginx:

Nginx Web Server plugin

  • --nginx-server-root NGINX_SERVER_ROOT — where nginx keeps its root directory. (default: /etc/nginx or /usr/local/etc/nginx, depending on your install 💅)
  • --nginx-ctl NGINX_CTL — the path to the nginx binary, and yes bestie we use it for configtest and for peeking at the nginx version number 👀 (default: nginx)
  • --nginx-sleep-seconds NGINX_SLEEP_SECONDS — how many seconds we just sit here patiently waiting for your nginx config changes to actually apply when we reload. (default: 1)

🌫️ null

Null Installer. That's it, that's the whole vibe — it does nothing. Sometimes the move is to not make a move 💅

🧍 standalone

Runs an HTTP server locally that serves up the necessary validation files under the /.well-known/acme-challenge/ request path. Perfect fit if there's no HTTP server already running on the box.

Not me about to say this twice: HTTP challenge only — wildcards are not supported. 😤

📁 webroot

Saves the necessary validation files into a .well-known/acme-challenge/ directory inside the webroot path you nominate. Heads up though: a separate HTTP server has to actually be running and serving files from that webroot path — this plugin is not the one doing the serving, it's just dropping files off 🫶

Again, for the people in the back: HTTP challenge only — wildcards are not supported. 🙈
  • --webroot-path, -w WEBROOT_PATH — the public_html / webroot path. You can pass this multiple times to handle different identifiers, and each identifier gets the webroot path that came right before it. So like:
-w /var/www/example -d example.com -d www.example.com -w /var/www/thing -d thing.net -d m.thing.net

(default: Ask)

  • --webroot-map WEBROOT_MAP — a JSON dictionary mapping identifiers to webroot paths. Sneaky detail: this implies -d or --ip-address for each entry. Your shell may be dramatic about it, so you might need to escape it. For example:
--webroot-map '{"eg1.is,m.eg1.is":"/www/eg1/", "eg2.is":"/www/eg2"}'

This option is merged with, but takes precedence over, your -w / -d entries. And rn, if you put webroot-map in a config file, it has to live on a single line, like:

webroot-map = {"example.com":"/var/www"}

(default: {})

🫶 AUTHOR

Certbot. The whole thing, authored by Certbot. Iconic of them honestly 👑

2014-2018 - The Certbot software and documentation are licensed under the Apache 2.0 license as described at https://eff.org/cb-license.

okay bestie that's a wrap on the whole page 🎀 you made it to the end, I'm so proud of you fr fr ✨ this was version 5.5, dated Jul 25, 2026, and it's giving CERTBOT(1) — periodt 💖 go get those certs, and remember: no cap, your TLS is gonna be so valid 🌈💅

📦 where this page comes from