Certbot is most useful when run with root privileges, because it is then able to automatically configure TLS/SSL for Apache and nginx.

Certbot is meant to be run directly on a web server, normally by a system administrator. In most cases, running Certbot on your personal computer is not a useful option. The instructions below relate to installing and running Certbot on a server.

sudo docker run -it --rm --name certbot \


            -v "/etc/letsencrypt:/etc/letsencrypt" \


            -v "/var/lib/letsencrypt:/var/lib/letsencrypt" \


            certbot/certbot certonly

• Apache
• Webroot
• Nginx
• Standalone
• DNS Plugins
• Manual
• Combining plugins
• Third-party plugins

• Re-creating and Updating Existing Certificates
• Changing a Certificate's Domains
• RSA and ECDSA keys

•

Revoking certificates

•

Deleting certificates

• Renewing certificates
• Modifying the Renewal Configuration of Existing Certificates

•

Automated Renewals

# Obtain and install a certificate:
certbot
# Obtain a certificate but don't install it:
certbot certonly
# You may specify multiple domains with -d and obtain and
# install different certificates by running Certbot multiple times:
certbot certonly -d example.com -d www.example.com
certbot certonly -d app.example.com -d api.example.com

certbot certonly --webroot -w /var/www/example -d www.example.com -d example.com -w /var/www/other -d other.example.net -d another.other.example.net

66.133.109.36 - - [05/Jan/2016:20:11:24 -0500] "GET /.well-known/acme-challenge/HGr8U1IeTW4kY_Z6UIyaakzOkyQgPr_7ArlLgtZE8SX HTTP/1.1" 200 87 "-" "Mozilla/5.0 (compatible; Let's Encrypt validation server; +https://www.letsencrypt.org)"

certbot --nginx

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

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

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

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

certbot certonly --cert-name example.com

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

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

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

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

If you obtain certificates using ECDSA keys, you should be careful not to downgrade to a Certbot version earlier than 1.10.0 where ECDSA keys were not supported. Downgrades like this are possible if you switch from something like the snaps or pip to packages provided by your operating system which often lag behind.

certbot renew --key-type ecdsa --cert-name example.com --force-renewal

key-type = ecdsa

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

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.

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

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

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

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

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

Most Certbot installations come with automatic renewal out of the box. See Automated Renewals for more details.

Users of the Manual plugin should note that --manual certificates will not renew automatically, unless combined with authentication hook scripts. See Renewal with the manual plugin.

certbot renew --pre-hook "service nginx stop" --post-hook "service nginx start"

certbot renew exit status will only be 1 if a renewal attempt failed. This means certbot renew exit status will be 0 if no certificate needs to be updated. If you write a custom script and expect to run a command only after a certificate was actually renewed you will need to use the --deploy-hook since the exit status will be 0 both on successful renewal and when renewal is not necessary.

certbot reconfigure --cert-name example.com --webroot-path /path/to/new/location

Rate limits from the certificate authority may prevent you from performing multiple renewals in a short period of time. It is strongly recommended to perform the second step only once, when you have decided on what options should change.

Manually modifying files under /etc/letsencrypt/renewal/ can damage them if done improperly and we do not recommend doing so.

If you're using Windows, these instructions are not neccessary as Certbot on Windows comes with a scheduled task for automated renewal pre-installed.

If you are using macOS and installed Certbot using Homebrew, follow the instructions at https://certbot.eff.org/instructions to set up automated renewal. The instructions below are not applicable on macOS.

SLEEPTIME=$(awk 'BEGIN{srand(); print int(rand()*(3600+1))}'); echo "0 0,12 * * * root sleep $SLEEPTIME && certbot renew -q" | sudo tee -a /etc/crontab > /dev/null

sudo sh -c 'printf "#!/bin/sh\nservice haproxy stop\n" > /etc/letsencrypt/renewal-hooks/pre/haproxy.sh'
sudo sh -c 'printf "#!/bin/sh\nservice haproxy start\n" > /etc/letsencrypt/renewal-hooks/post/haproxy.sh'
sudo chmod 755 /etc/letsencrypt/renewal-hooks/pre/haproxy.sh
sudo chmod 755 /etc/letsencrypt/renewal-hooks/post/haproxy.sh

The certificate name $domain used in the path /etc/letsencrypt/live/$domain follows this convention:

All files are PEM-encoded. If you need other format, such as DER or PFX, then you could convert using openssl. You can automate that with --deploy-hook if you're using automatic renewal.

certbot certonly --manual --manual-auth-hook /path/to/http/authenticator.sh --manual-cleanup-hook /path/to/http/cleanup.sh -d secure.example.com

certbot certonly --manual --preferred-challenges=http --manual-auth-hook /path/to/http/authenticator.sh --manual-cleanup-hook /path/to/http/cleanup.sh -d secure.example.com

#!/bin/bash
echo $CERTBOT_VALIDATION > /var/www/htdocs/.well-known/acme-challenge/$CERTBOT_TOKEN

#!/bin/bash
rm -f /var/www/htdocs/.well-known/acme-challenge/$CERTBOT_TOKEN

certbot certonly --manual --preferred-challenges=dns --manual-auth-hook /path/to/dns/authenticator.sh --manual-cleanup-hook /path/to/dns/cleanup.sh -d secure.example.com

#!/bin/bash
# Get your API key from https://www.cloudflare.com/a/account/my-account
API_KEY="your-api-key"
EMAIL="your.email@example.com"
# Strip only the top domain to get the zone id
DOMAIN=$(expr match "$CERTBOT_DOMAIN" '.*\.\(.*\..*\)')
# Get the Cloudflare zone id
ZONE_EXTRA_PARAMS="status=active&page=1&per_page=20&order=status&direction=desc&match=all"
ZONE_ID=$(curl -s -X GET "https://api.cloudflare.com/client/v4/zones?name=$DOMAIN&$ZONE_EXTRA_PARAMS" \


     -H     "X-Auth-Email: $EMAIL" \


     -H     "X-Auth-Key: $API_KEY" \


     -H     "Content-Type: application/json" | python -c "import sys,json;print(json.load(sys.stdin)['result'][0]['id'])")
# Create TXT record
CREATE_DOMAIN="_acme-challenge.$CERTBOT_DOMAIN"
RECORD_ID=$(curl -s -X POST "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/dns_records" \


     -H     "X-Auth-Email: $EMAIL" \


     -H     "X-Auth-Key: $API_KEY" \


     -H     "Content-Type: application/json" \


     --data '{"type":"TXT","name":"'"$CREATE_DOMAIN"'","content":"'"$CERTBOT_VALIDATION"'","ttl":120}' \


             | python -c "import sys,json;print(json.load(sys.stdin)['result']['id'])")
# Save info for cleanup
if [ ! -d /tmp/CERTBOT_$CERTBOT_DOMAIN ];then


        mkdir -m 0700 /tmp/CERTBOT_$CERTBOT_DOMAIN
fi
echo $ZONE_ID > /tmp/CERTBOT_$CERTBOT_DOMAIN/ZONE_ID
echo $RECORD_ID > /tmp/CERTBOT_$CERTBOT_DOMAIN/RECORD_ID
# Sleep to make sure the change has time to propagate over to DNS
sleep 25

#!/bin/bash
# Get your API key from https://www.cloudflare.com/a/account/my-account
API_KEY="your-api-key"
EMAIL="your.email@example.com"
if [ -f /tmp/CERTBOT_$CERTBOT_DOMAIN/ZONE_ID ]; then


        ZONE_ID=$(cat /tmp/CERTBOT_$CERTBOT_DOMAIN/ZONE_ID)


        rm -f /tmp/CERTBOT_$CERTBOT_DOMAIN/ZONE_ID
fi
if [ -f /tmp/CERTBOT_$CERTBOT_DOMAIN/RECORD_ID ]; then


        RECORD_ID=$(cat /tmp/CERTBOT_$CERTBOT_DOMAIN/RECORD_ID)


        rm -f /tmp/CERTBOT_$CERTBOT_DOMAIN/RECORD_ID
fi
# Remove the challenge TXT record from the zone
if [ -n "${ZONE_ID}" ]; then


    if [ -n "${RECORD_ID}" ]; then


        curl -s -X DELETE "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/dns_records/$RECORD_ID" \


                -H "X-Auth-Email: $EMAIL" \


                -H "X-Auth-Key: $API_KEY" \


                -H "Content-Type: application/json"


    fi
fi

--dry-run uses the Let's Encrypt staging server, unless --server is specified on the CLI or in the cli.ini configuration file. Take caution when using --dry-run with a custom server, as it may cause real certificates to be issued and discarded.

# This is an example of the kind of things you can do in a configuration file.
# All flags used by the client can be configured here. Run Certbot with
# "--help" to learn more about the available options.
#
# Note that these options apply automatically to all use of Certbot for
# obtaining or renewing certificates, so options specific to a single
# certificate on a system with several certificates should not be placed
# here.
# Use ECC for the private key
key-type = ecdsa
elliptic-curve = secp384r1
# Use a 4096 bit RSA key instead of 2048
rsa-key-size = 4096
# Uncomment and update to register with the specified e-mail address
# email = foo@example.com
# Uncomment to use the standalone authenticator on port 80
# authenticator = standalone
# Uncomment to use the webroot authenticator. Replace webroot-path with the
# path to the public_html / webroot folder being served by your web server.
# authenticator = webroot
# webroot-path = /usr/share/nginx/html
# Uncomment to automatically agree to the terms of service of the ACME server
# agree-tos = true
# An example of using an alternate ACME server that uses EAB credentials
# server = https://acme.sectigo.com/v2/InCommonRSAOV
# eab-kid = somestringofstuffwithoutquotes
# eab-hmac-key = yaddayaddahexhexnotquoted

Some distributions, including Debian and Ubuntu, disable certbot's internal log rotation in favor of a more traditional logrotate script. If you are using a distribution's packages and want to alter the log rotation, check /etc/logrotate.d/ for a certbot rotation script.

usage: 


  certbot [SUBCOMMAND] [options] [-d DOMAIN] [-d DOMAIN] ...
Certbot can obtain and install HTTPS/TLS/SSL certificates.  By default,
it will attempt to use a webserver both for obtaining and installing the
certificate. The most common SUBCOMMANDS and flags are:
obtain, install, and renew certificates:


    (default) run   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
optional arguments:


  -h, --help            show this help message and exit


  -c CONFIG_FILE, --config CONFIG_FILE


                        path to config file (default: /etc/letsencrypt/cli.ini


                        and ~/.config/letsencrypt/cli.ini)


  -v, --verbose         This flag can be used 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,


                        causing Certbot to always append to the same log file.


                        (default: 1000)


  -n, --non-interactive, --noninteractive


                        Run without ever asking for user input. This may


                        require additional command line flags; the client will


                        try to explain which ones are required if it finds one


                        missing (default: False)


  --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 DOMAIN, --domains DOMAIN, --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)


  --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)


  --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)


  --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)


  --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)


  --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: [])


  --issuance-timeout ISSUANCE_TIMEOUT


                        This option specifies how long (in seconds) Certbot


                        will wait for the server to issue a certificate.


                        (default: 90)


  --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/3.3.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)
automation:


  Flags for automating execution & other tweaks


  --keep-until-expiring, --keep, --reinstall


                        If the requested certificate matches an existing


                        certificate, always keep the existing one until it is


                        due for renewal (for the 'run' subcommand this means


                        reinstall the existing certificate). (default: Ask)


  --expand              If an existing certificate is a strict subset of the


                        requested names, always expand and replace it with the


                        additional names. (default: Ask)


  --version             show program's version number and exit


  --force-renewal, --renew-by-default


                        If a certificate already exists for the requested


                        domains, renew it now, regardless of whether it is


                        near expiry. (Often --keep-until-expiring is more


                        appropriate). Also implies --expand. (default: False)


  --renew-with-new-domains


                        If a certificate already exists for the requested


                        certificate name but does not match the requested


                        domains, renew it now, regardless of whether it is


                        near expiry. (default: False)


  --reuse-key           When renewing, use the same private key as the


                        existing certificate. (default: False)


  --no-reuse-key        When renewing, do not use the same private key as the


                        existing certificate. Not reusing private keys is the


                        default behavior of Certbot. This option may be used


                        to unset --reuse-key on an existing certificate.


                        (default: False)


  --new-key             When renewing or replacing a certificate, generate a


                        new private key, even if --reuse-key is set on the


                        existing certificate. Combining --new-key and --reuse-


                        key will result in the private key being replaced and


                        then reused in future renewals. (default: False)


  --allow-subset-of-names


                        When performing domain validation, do not consider it


                        a failure if authorizations can not be obtained for a


                        strict subset of the requested domains. This may be


                        useful for allowing renewals for multiple domains to


                        succeed even if some domains no longer point at this


                        system. This option cannot be used with --csr.


                        (default: False)


  --agree-tos           Agree to the ACME Subscriber Agreement (default: Ask)


  --duplicate           Allow making a certificate lineage that duplicates an


                        existing one (both can be renewed in parallel)


                        (default: False)


  -q, --quiet           Silence all output except errors. Useful 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. (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                Add the Strict-Transport-Security header to every HTTP


                        response. Forcing browser to always use SSL for the


                        domain. Defends against SSL Stripping. (default:


                        False)


  --uir                 Add 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 is


                        stapled to the certificate that the server offers


                        during TLS. (default: False)


  --strict-permissions  Require 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 HTTP Strict


                        Transport Security security header (default: False)
testing:


  The following flags are meant for testing and integration purposes only.


  --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               Show tracebacks in case of errors (default: False)


  --no-verify-ssl       Disable verification of the ACME server's certificate.


                        The root certificates trusted by Certbot can be


                        overriden 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 http-01


                        challenge. (default: )


  --https-port HTTPS_PORT


                        Port used to serve HTTPS. This affects which port


                        Nginx will listen on after a LE certificate is


                        installed. (default: 443)


  --break-my-certs      Be willing to replace or renew valid certificates with


                        invalid (testing/staging) certificates (default:


                        False)
paths:


  Flags for changing execution paths & servers


  --cert-path CERT_PATH


                        Path to where 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:


  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


  --csr CSR             Path to a Certificate Signing Request (CSR) in DER or


                        PEM format. Currently --csr only works with the


                        'certonly' subcommand. (default: None)
renew:


  The 'renew' subcommand will attempt to renew any certificates previously


  obtained if they are close to expiry, and print a summary of the results.


  By default, 'renew' will reuse the plugins and options used to obtain or


  most recently renew each certificate. You can test whether future renewals


  will succeed with `--dry-run`. Individual certificates can be renewed with


  the `--cert-name` option. Hooks are available to run commands before and


  after renewal; see https://certbot.eff.org/docs/using.html#renewal for


  more information on these.


  --pre-hook PRE_HOOK   Command to be run in a shell before obtaining any


                        certificates. Unless --disable-hook-validation is


                        used, the command’s first word must be the absolute


                        pathname of an executable or one found via the PATH


                        environment variable. Intended primarily for renewal,


                        where it can be used to temporarily shut down a


                        webserver that might conflict with the standalone


                        plugin. This will only be called if a certificate is


                        actually to be obtained/renewed. When renewing several


                        certificates that have identical pre-hooks, only the


                        first will be executed. (default: None)


  --post-hook POST_HOOK


                        Command to be run in a shell after attempting to


                        obtain/renew certificates. Unless --disable-hook-


                        validation is used, the command’s first word must be


                        the absolute pathname of an executable or one found


                        via the PATH environment variable. Can be used to


                        deploy renewed certificates, or to restart any servers


                        that were stopped by --pre-hook. This is only run if


                        an attempt was made to obtain/renew a certificate. If


                        multiple renewed certificates have identical post-


                        hooks, only one will be run. (default: None)


  --deploy-hook DEPLOY_HOOK


                        Command to be run in a shell once for each


                        successfully issued certificate. Unless --disable-


                        hook-validation is used, the command’s first word must


                        be the absolute pathname of an executable or one found


                        via the PATH environment variable. For this command,


                        the shell variable $RENEWED_LINEAGE will point to the


                        config live subdirectory (for example,


                        "/etc/letsencrypt/live/example.com") containing the


                        new certificates and keys; the shell variable


                        $RENEWED_DOMAINS will contain a space-delimited list


                        of renewed certificate domains (for example,


                        "example.com www.example.com") (default: None)


  --disable-hook-validation


                        Ordinarily the commands specified for --pre-


                        hook/--post-hook/--deploy-hook will be checked for


                        validity, to see if the programs being run are in the


                        $PATH, so that mistakes can be caught early, even when


                        the hooks aren't being run just yet. The validation is


                        rather simplistic and fails if you use more advanced


                        shell constructs, so you can use this switch to


                        disable it. (default: False)


  --no-directory-hooks  Disable running executables found in Certbot's hook


                        directories. (default: False)


  --disable-renew-updates


                        Disable automatic updates to your server configuration


                        that would otherwise be done by the selected installer


                        plugin, and triggered when the user executes "certbot


                        renew", regardless of if the certificate is renewed.


                        This setting does not apply to important TLS


                        configuration updates. (default: False)


  --no-autorenew        Disable 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}


                        Specify reason for revoking certificate. (default:


                        unspecified)


  --delete-after-revoke


                        Delete certificates after revoking them, along with


                        all previous and later versions of those certificates.


                        (default: Ask)


  --no-delete-after-revoke


                        Do not delete certificates after revoking them. This


                        option should be used with caution because the 'renew'


                        subcommand will attempt to renew undeleted revoked


                        certificates. (default: Ask)
register:


  Options for account registration


  -m EMAIL, --email EMAIL


                        Email used for registration and recovery contact. Use


                        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.
show_account:


  Options useful for the "show_account" subcommand:
reconfigure:


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


  Plugin Selection: 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 options


  provided below. Running --help <plugin_name> will list flags specific to


  that plugin.


  --configurator CONFIGURATOR


                        Name of the plugin that is both an authenticator and


                        an installer. Should not be used together with


                        --authenticator or --installer. (default: Ask)


  -a AUTHENTICATOR, --authenticator AUTHENTICATOR


                        Authenticator plugin name. (default: None)


  -i INSTALLER, --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 are


                        using Cloudflare for DNS). (default: False)


  --dns-digitalocean    Obtain certificates using a DNS TXT record (if you are


                        using DigitalOcean for DNS). (default: False)


  --dns-dnsimple        Obtain certificates using a DNS TXT record (if you are


                        using DNSimple for DNS). (default: False)


  --dns-dnsmadeeasy     Obtain certificates using a DNS TXT record (if you are


                        using DNS Made Easy for DNS). (default: False)


  --dns-gehirn          Obtain certificates using a DNS TXT record (if you are


                        using Gehirn Infrastructure Service for DNS).


                        (default: False)


  --dns-google          Obtain certificates using a DNS TXT record (if you are


                        using Google Cloud DNS). (default: False)


  --dns-linode          Obtain certificates using a DNS TXT record (if you are


                        using Linode for DNS). (default: False)


  --dns-luadns          Obtain certificates using a DNS TXT record (if you are


                        using LuaDNS for DNS). (default: False)


  --dns-nsone           Obtain certificates using a DNS TXT record (if you are


                        using NS1 for DNS). (default: False)


  --dns-ovh             Obtain certificates using a DNS TXT record (if you are


                        using OVH for DNS). (default: False)


  --dns-rfc2136         Obtain certificates using a DNS TXT record (if you are


                        using BIND for DNS). (default: False)


  --dns-route53         Obtain certificates using a DNS TXT record (if you are


                        using Route53 for DNS). (default: False)


  --dns-sakuracloud     Obtain certificates using a DNS TXT record (if you are


                        using Sakura Cloud for DNS). (default: False)
apache:


  Apache Web Server plugin (Please note that the default values of the


  Apache plugin options change depending on the operating system Certbot is


  run on.)


  --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 installer handle enabling required modules for you


                        (Only Ubuntu/Debian currently) (default: False)


  --apache-handle-sites APACHE_HANDLE_SITES


                        Let 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).


  --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).


  --dns-google-propagation-seconds DNS_GOOGLE_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-google-credentials DNS_GOOGLE_CREDENTIALS


                        Path to Google Cloud DNS service account JSON file to


                        use instead of relying on Application Default


                        Credentials (ADC). (See https://cloud.google.com/docs/


                        authentication/application-default-credentials for


                        information about ADC, https://developers.google.com/i


                        dentity/protocols/OAuth2ServiceAccount#creatinganaccou


                        nt for information about creating a service account,


                        and https://cloud.google.com/dns/access-


                        control#permissions_and_roles for information about


                        the permissions required to modify Cloud DNS records.)


                        (default: None)


  --dns-google-project DNS_GOOGLE_PROJECT


                        The ID of the Google Cloud project that the Google


                        Cloud DNS managed zone(s) reside in. This will be


                        determined automatically if not specified. (default:


                        None)
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).
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_DOMAIN will always contain the domain 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_DOMAINS


  contains a comma-separated list of all domains 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)
nginx:


  Nginx Web Server plugin


  --nginx-server-root NGINX_SERVER_ROOT


                        Nginx server root directory. (default: /etc/nginx or


                        /usr/local/etc/nginx)


  --nginx-ctl NGINX_CTL


                        Path to the 'nginx' binary, used for 'configtest' and


                        retrieving nginx version number. (default: nginx)


  --nginx-sleep-seconds NGINX_SLEEP_SECONDS


                        Number of seconds to wait for nginx configuration


                        changes to apply when reloading. (default: 1)
null:


  Null Installer
standalone:


  Runs an HTTP server locally which serves the necessary validation files


  under the /.well-known/acme-challenge/ request path. Suitable if there is


  no HTTP server already running. HTTP challenge only (wildcards not


  supported).
webroot:


  Saves the necessary validation files to a .well-known/acme-challenge/


  directory within the nominated webroot path. A separate HTTP server must


  be running and serving files from the webroot path. HTTP challenge only


  (wildcards not supported).


  --webroot-path WEBROOT_PATH, -w WEBROOT_PATH


                        public_html / webroot path. This can be specified


                        multiple times to handle different domains; each


                        domain will have the webroot path that preceded it.


                        For instance: `-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


                        JSON dictionary mapping domains to webroot paths; this


                        implies -d for each entry. You may need to escape this


                        from your shell. E.g.: --webroot-map


                        '{"eg1.is,m.eg1.is":"/www/eg1/", "eg2.is":"/www/eg2"}'


                        This option is merged with, but takes precedence over,


                        -w / -d entries. At present, if you put webroot-map in


                        a config file, it needs to be on a single line, like:


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


                        {})

• Running a local copy of the client
• Find issues to work on
• Testing

• Plugin-architecture
• Authenticators
• Installer
• Installer Development
• Writing your own plugin

• Updating dependency versions
• Choosing dependency versions

git clone https://github.com/certbot/certbot

# For APT-based distributions (e.g. Debian, Ubuntu ...)
sudo apt update
sudo apt install python3-venv libaugeas0
# For RPM-based distributions (e.g. Fedora, CentOS ...)
# NB1: old distributions will use yum instead of dnf
# NB2: RHEL-based distributions use python3X instead of python3 (e.g. python38)
sudo dnf install python3 augeas-libs
# For macOS installations with Homebrew already installed and configured
# NB1: If you also run `brew install python` you don't need the ~/lib
#      directory created below, however, without this directory and symlinks
#      to augeas, Certbot's Apache plugin won't work if you use Python
#      installed from other sources such as pyenv or the version provided by
#      Apple.
# NB2: Some of our developer scripts expect GNU coreutils be first in your
#      PATH. The commands below set this up for bash and zsh, but your
#      instructions may be slightly different if you use an alternate shell.
brew install augeas coreutils gnu-sed
mkdir ~/lib
BREW_PREFIX=$(brew --prefix)
ln -s "$BREW_PREFIX"/lib/libaugeas* ~/lib
RC_LINE="export PATH=\"$BREW_PREFIX/opt/coreutils/libexec/gnubin:"
RC_LINE+="$BREW_PREFIX/opt/gnu-sed/libexec/gnubin:\$PATH\""
echo "$RC_LINE" >> ~/.bashrc  # for bash
echo "$RC_LINE" >> ~/.zshrc  # for zsh

If you have trouble creating the virtual environment below, you may need to install additional dependencies. See the cryptography project's site for more information.

cd certbot
python3 tools/venv.py

You may need to repeat this when Certbot's dependencies change or when a new plugin is introduced.

source venv/bin/activate

tox

pytest acme/acme/_internal/tests/messages_test.py # Use the test file you're working on

pytest acme/acme/_internal/tests/messages_test.py -k test_to_partial_json

The full test suite may attempt to modify your system's Apache config if your user has sudo permissions, so it should not be run on a production Apache server.

tox run -e integration

run_acme_server

Some options are available to tweak the local ACME server. You can execute run_acme_server --help to see the inline help of the run_acme_server tool.

certbot_test [ARGS...]

python3 tools/venv.py
source venv/bin/activate
run_acme_server &
certbot_test certonly --standalone -d test.example.com
# To stop Pebble, launch `fg` to get back the background job, then press CTRL+C

The Certbot team is not currently accepting any new plugins because we want to rethink our approach to the challenge and resolve some issues like #6464, #6503, and #6504 first.

In the meantime, you're welcome to release it as a third-party plugin. See certbot-dns-ispconfig for one example of that.

. venv/bin/activate
pip install -e examples/plugins/
certbot_test plugins

snap install --classic certbot
snap set certbot trust-plugin-with-root=ok
snap install --dangerous your-snap-filename.snap
sudo snap connect certbot:plugin your-snap-name
sudo /snap/bin/certbot plugins

from OpenSSL import crypto
from OpenSSL import SSL

make clean html

mkdir -p ~/.config/git
echo '.DS_Store' >> ~/.config/git/ignore

Parameters

Parameters

mask (int) -- The user file-creation mode mask to apply.

Return type

int

Returns

The previous umask value.

Parameters

mask (int) -- The user file-creation mode mask to apply temporarily

Parameters

Parameters

Parameters

Return type

bool

Returns

True if the POSIX mode matches the file permissions

Parameters

file_path (str) -- File path to check

Return type

bool

Returns

True if given file is owned by current user, False otherwise.

Parameters

Return type

bool

Returns

True if file has correct mode and owner, False otherwise.

Parameters

Returns

the file descriptor to the opened file

Return type

int

Raise

OSError(errno.EEXIST) if the file already exists and os.O_CREAT & os.O_EXCL are set, OSError(errno.EACCES) on Windows if the file already exists and is a directory, and os.O_CREAT is set.

Parameters

Parameters

Parameters

Parameters

file_path (str) -- The path to resolve

Returns

The real path for the given path

Return type

str

Parameters

link_path (str) -- The symlink path to resolve

Returns

The path the symlink points to

Returns

str

Raise

ValueError if a long path (260> characters) is encountered on Windows

Parameters

path (str) -- path to test

Returns

True if path is an executable file

Return type

bool

Parameters

path (str) -- path to test

Returns

True if everybody/world has any right to the file

Return type

bool

Parameters

Returns

the POSIX mode to apply

Return type

int

Parameters

Returns

True if both files have the same ownership, False otherwise

Return type

bool

Parameters

Returns

True if the file matches the minimal permissions expectations, False otherwise

Return type

bool

Raises

.errors.Error -- If the current shell does not have administrative rights on Windows.

Parameters

Returns

The first line entered by the user.

Return type

str

Parameters

folder_type (str) -- The type of folder to retrieve (config, work or logs)

Returns

The relevant default folder.

Return type

str

Run a command:

Parameters

Returns

tuple (int returncode, str stderr, str stdout)

Parameters

invalid (bool) -- True if an invalid address was provided by the user

Returns

e-mail address

Return type

str

Raises

errors.Error -- if the user cancels

Parameters

accounts (list) -- Containing at least one Account

Parameters

Returns

List of selected values

Return type

list

Parameters

Returns

List of selected names

Return type

list of str

Helper method for choose_names that implements basic checks

on domain names

Parameters

domains (list) -- Domain names to validate

Returns

List of valid domains

Return type

list

Parameters

domains (list) -- domain names which were enabled

Parameters

domains (list) -- domain names which were renewed

Parameters

cert_path (list) -- path to certificate which was revoked.

Parameters

Parameters

Returns

as input_text

Return type

tuple

Parameters

Returns

as directory_select

Return type

tuple

Parameters

msg (str) -- message to display

Parameters

Parameters

Returns

tuple of (code, index) where code - str display exit code index - int index of the user's selection

Return type

tuple

Parameters

Returns

tuple of (code, input) where code - str display exit code input - str of the user's input

Return type

tuple

Parameters

Returns

True for "Yes", False for "No"

Return type

bool

Parameters

Returns

tuple of (code, tags) where code - str display exit code tags - list of selected tags

Return type

tuple

Parameters

Returns

tuple of the form (code, string) where code - display exit code string - input entered by the user

Parameters

abstract classmethod add_parser_arguments(add: Callable[[...], None]) -> None

Add plugin arguments to the CLI argument parser.

classmethod inject_parser_options(parser: ArgumentParser, name: str) -> None

Inject parser options.

See inject_parser_options for docs.

property option_namespace: str

ArgumentParser options namespace (prefix of all options).

option_name(name: str) -> str

Option name (include plugin namespace).

property dest_namespace: str

ArgumentParser dest namespace (prefix of all destinations).

dest(var: str) -> str

Find a destination for given variable var.

conf(var: str) -> Any

Find a configuration value for variable var.

auth_hint(failed_achalls: List[AnnotatedChallenge]) -> str

Human-readable string to help the user troubleshoot the authenticator.

Shown to the user if one or more of the attempted challenges were not a success.

Should describe, in simple language, what the authenticator tried to do, what went wrong and what the user should try as their "next steps".

TODO: auth_hint belongs in Authenticator but can't be added until the next major version of Certbot. For now, it lives in .Plugin and auth_handler will only call it on authenticators that subclass .Plugin. For now, inherit from Plugin to implement and/or override the method.

add_to_checkpoint(save_files: Set[str], save_notes: str, temporary: bool = False) -> None

Add files to a checkpoint.

finalize_checkpoint(title: str) -> None

Timestamp and save changes made through the reverter.

recovery_routine() -> None

Revert all previously modified files.

Reverts all modified files that have not been saved as a checkpoint

revert_temporary_config() -> None

Rollback temporary checkpoint.

rollback_checkpoints(rollback: int = 1) -> None

Rollback saved checkpoints.

property ssl_dhparams: str

Full absolute path to ssl_dhparams file.

property updated_ssl_dhparams_digest: str

Full absolute path to digest of updated ssl_dhparams file.

install_ssl_dhparams() -> None

Copy Certbot's ssl_dhparams file into the system's config dir if required.

Parameters

classmethod fromstring(str_addr: str) -> GenericAddr

Initialize Addr from string.

normalized_tuple() -> Tuple[str, str]

Normalized representation of addr/port tuple

get_addr() -> str

Return addr part of Addr object.

get_port() -> str

Return port.

get_addr_obj(port: str) -> GenericAddr

Return new address object with same addr and new port.

get_ipv6_exploded() -> str

Return IPv6 in normalized form

Variables

add_chall(achall: KeyAuthorizationAnnotatedChallenge, idx: Optional[int] = None) -> None

Store challenge to be performed when perform() is called.

perform() -> List[KeyAuthorizationChallengeResponse]

Perform all added challenges.

Parameters

classmethod add_parser_arguments(add: Callable[[...], None], default_propagation_seconds: int = 10) -> None

Add plugin arguments to the CLI argument parser.

auth_hint(failed_achalls: List[AnnotatedChallenge]) -> str

See certbot.plugins.common.Plugin.auth_hint.

get_chall_pref(unused_domain: str) -> Iterable[Type[Challenge]]

Return collections.Iterable of challenge preferences.

prepare() -> None

Prepare the plugin.

Finish up any additional initialization.

more_info() -> str

Human-readable string to help the user.

Should describe the steps taken and any relevant info to help the user decide which plugin to use.

perform(achalls: List[AnnotatedChallenge]) -> List[ChallengeResponse]

Perform the given challenge.

cleanup(achalls: List[AnnotatedChallenge]) -> None

Revert changes and shutdown after challenges complete.

This method should be able to revert all changes made by perform, even if perform exited abnormally.

require(required_variables: Mapping[str, str]) -> None

Ensures that the supplied set of variables are all present in the file.

conf(var: str) -> Optional[str]

Find a configuration value for variable var, as transformed by mapper.

Example

>>> base_domain_name_guesses('foo.bar.baz.example.com')
['foo.bar.baz.example.com', 'bar.baz.example.com', 'baz.example.com', 'example.com', 'com']

Parameters

domain (str) -- The domain for which to return guesses.

Returns

The a list of less specific domain names.

Return type

list

add_txt_record(domain: str, record_name: str, record_content: str) -> None

Add a TXT record using the supplied information.

del_txt_record(domain: str, record_name: str, record_content: str) -> None

Delete a TXT record using the supplied information.

Parameters

Returns

configuration to apply to the provider

Return type

ConfigurationResolver or dict

Assumes:

achall = KeyAuthorizationAnnotatedChallenge(challb=DNS01(token=b'17817c66b60ce2e4012dfad92657527a'), domain='example.com', account_key=JWKRSA(key=<ComparableRSAKey(<cryptography.hazmat.bindings._rust.openssl.rsa.RSAPrivateKey object>)>))

test_more_info() -> None

test_get_chall_pref() -> None

test_parser_arguments() -> None

Parameters

test_perform(unused_mock_get_utility: Any) -> None

test_cleanup() -> None

DOMAIN_NOT_FOUND = Exception('No domain found')

GENERIC_ERROR

alias of RequestException

LOGIN_ERROR = HTTPError('400 Client Error: ...')

UNKNOWN_LOGIN_ERROR = HTTPError('500 Surprise! Error: ...')

record_prefix = '_acme-challenge'

record_name = '_acme-challenge.example.com'

record_content = 'bar'

test_add_txt_record() -> None

test_add_txt_record_try_twice_to_find_domain() -> None

test_add_txt_record_fail_to_find_domain() -> None

test_add_txt_record_fail_to_authenticate() -> None

test_add_txt_record_fail_to_authenticate_with_unknown_error() -> None

test_add_txt_record_error_finding_domain() -> None

test_add_txt_record_error_adding_record() -> None

test_del_txt_record() -> None

test_del_txt_record_fail_to_find_domain() -> None

test_del_txt_record_fail_to_authenticate() -> None

test_del_txt_record_fail_to_authenticate_with_unknown_error() -> None

test_del_txt_record_error_finding_domain() -> None

test_del_txt_record_error_deleting_record() -> None

DOMAIN_NOT_FOUND = Exception('No domain found')

GENERIC_ERROR

alias of RequestException

LOGIN_ERROR = HTTPError('400 Client Error: ...')

UNKNOWN_LOGIN_ERROR = HTTPError('500 Surprise! Error: ...')

test_perform_succeed() -> None

test_perform_with_one_domain_resolution_failure_succeed() -> None

test_perform_with_two_domain_resolution_failures_raise() -> None

test_perform_with_domain_resolution_general_failure_raise() -> None

test_perform_with_auth_failure_raise() -> None

test_perform_with_unknown_auth_failure_raise() -> None

test_perform_with_create_record_failure_raise() -> None

test_cleanup_success() -> None

test_cleanup_with_auth_failure_ignore() -> None

test_cleanup_with_unknown_auth_failure_ignore() -> None

test_cleanup_with_domain_resolution_failure_ignore() -> None

test_cleanup_with_domain_resolution_general_failure_ignore() -> None

test_cleanup_with_delete_record_failure_ignore() -> None

Parameters

config (certbot.configuration.NamespaceConfig) -- Configuration.

Parameters

config (certbot.configuration.NamespaceConfig) -- Configuration.

Parameters

Returns

If all the requested enhancements are supported by the installer

Return type

bool

Parameters

Parameters

add (func) -- Add function of certbot._internal.cli.HelpfulParser

Methods:

enable_autohsts is called when the header is initially installed using a low max-age value.

update_autohsts is called every time when Certbot is run using 'renew' verb. The max-age value should be increased over time using this method.

deploy_autohsts is called for every lineage that has had its certificate renewed. A long HSTS max-age value should be set here, as we should be confident that the user is able to automatically renew their certificates.

abstract update_autohsts(lineage: RenewableCert, *args: Any, **kwargs: Any) -> None

Gets called for each lineage every time Certbot is run with 'renew' verb. Implementation of this method should increase the max-age value.

NOTE:

abstract deploy_autohsts(lineage: RenewableCert, *args: Any, **kwargs: Any) -> None

Gets called for a lineage when its certificate is successfully renewed. Long max-age value should be set in implementation of this method.

abstract enable_autohsts(lineage: Optional[RenewableCert], domains: Iterable[str], *args: Any, **kwargs: Any) -> None

Enables the AutoHSTS enhancement, installing Strict-Transport-Security header with a low initial value to be increased over the subsequent runs of Certbot renew.

save() -> None

Saves PluginStorage content to disk

put(key: str, value: Any) -> None

Put configuration value to PluginStorage

fetch(key: str) -> Any

Get configuration value from PluginStorage

Parameters

path (str) -- the path to break into prefixes

Returns

all possible path prefixes of given path in descending order

Return type

list of str

Parameters

cmd (str) -- the command that is being searched for in the PATH

Returns

True if the operation succeeded, False otherwise

Parameters

get_all_names() -> Iterable[str]

Returns all names that may be authenticated.

deploy_cert(domain: str, cert_path: str, key_path: str, chain_path: str, fullchain_path: str) -> None

Deploy certificate.

enhance(domain: str, enhancement: str, options: Optional[Union[List[str], str]] = None) -> None

Perform a configuration enhancement.

supported_enhancements() -> List[str]

Returns a collections.Iterable of supported enhancements.

save(title: Optional[str] = None, temporary: bool = False) -> None

Saves all changes to the configuration files.

Both title and temporary are needed because a save may be intended to be permanent, but the save is not ready to be a full checkpoint.

It is assumed that at most one checkpoint is finalized by this method. Additionally, if an exception is raised, it is assumed a new checkpoint was not finalized.

config_test() -> None

Make sure the configuration is valid.

restart() -> None

Restart or refresh the server content.

classmethod add_parser_arguments(add: Callable[[...], None]) -> None

Add plugin arguments to the CLI argument parser.

prepare() -> None

Prepare the plugin.

Finish up any additional initialization.

more_info() -> str

Human-readable string to help the user.

Should describe the steps taken and any relevant info to help the user decide which plugin to use.

Parameters

Returns

path to the renewal conf file for the created lineage

Return type

str

Returns

patch on the function used internally by certbot.display.util to get a display utility instance

Return type

mock.MagicMock

Parameters

stdout (object) -- object to write standard output to; it is expected to have a write method

Returns

patch on the function used internally by certbot.display.util to get a display utility instance

Return type

mock.MagicMock

freeze() -> None

Freeze object preventing further changes.

setUp() -> None

Execute before test

tearDown() -> None

Execute after test

setUp() -> None

Execute before test

from acme import challenges
from acme import messages
from certbot import achallenges
chall = challenges.DNS(token='foo')
challb = messages.ChallengeBody(chall=chall)
achall = achallenges.DNS(chall=challb, domain='example.com')

achall.token == challb.token

Variables

~.challb -- Wrapped ChallengeBody.

challb

response_and_validation(*args: Any, **kwargs: Any) -> Tuple[KeyAuthorizationChallengeResponse, Any]

Generate response and validation.

challb

domain

account_key

acme_type

alias of DNS

challb

domain

acme_type

alias of Challenge

challb

domain

Parameters

Returns

Key

Return type

certbot.util.Key

Raises

ValueError -- If unable to generate the key given key_size.

Parameters

Returns

CSR

Return type

certbot.util.CSR

Parameters

csr (bytes) -- CSR in PEM.

Returns

Validity of CSR.

Return type

bool

Parameters

Returns

Correspondence of private key to CSR subject public key.

Return type

bool

Parameters

Returns

(acme_crypto_util.Format.PEM, util.CSR object representing the CSR, list of domains requested in the CSR)

Return type

tuple

Parameters

Returns

new RSA or ECDSA key in PEM form with specified number of bits or of type ec_curve when key_type ecdsa is used.

Return type

bytes

Parameters

privkey -- Private key file contents in PEM

Returns

Validity of private key.

Return type

bool

Several things are checked:

Parameters

renewable_cert (certbot.interfaces.RenewableCert) -- cert to verify

Raises

errors.Error -- If verification fails.

Parameters

renewable_cert (certbot.interfaces.RenewableCert) -- cert to verify

Raises

errors.Error -- If signature verification fails.

Parameters

Raises

Parameters

Raises

errors.Error -- If they don't match.

Parameters

renewable_cert (certbot.interfaces.RenewableCert) -- cert to verify

Raises

errors.Error -- If cert and chain do not combine to fullchain.

Parameters

Returns

A list of Subject Alternative Names.

Return type

list

Parameters

Returns

A list of domain names.

Return type

list

Parameters

Returns

A list of domain names.

Return type

list

Parameters

cert_path (str) -- path to a cert in PEM format

Returns

the notBefore value from the cert at cert_path

Return type

datetime.datetime

Parameters

cert_path (str) -- path to a cert in PEM format

Returns

the notAfter value from the cert at cert_path

Return type

datetime.datetime

Parameters

filename (str) -- path to the file whose hash will be computed

Returns

sha256 digest of the file in hexadecimal

Return type

str

Parameters

fullchain_pem (str) -- concatenated cert + chain

Returns

tuple of string cert_pem and chain_pem

Return type

tuple

Raises

errors.Error -- If there are less than 2 certificates in the chain.

Parameters

cert_path (str) -- path to a cert in PEM format

Returns

serial number of the certificate

Return type

int

Parameters

Returns

The best-matching fullchain, PEM-encoded, or the first if none match.

Return type

str

Variables

failed_achalls (set) -- Failed AnnotatedChallenge instances.

abstract find_all() -> List[Account]

Find all accounts.

abstract load(account_id: str) -> Account

Load an account by its id.

abstract save(account: Account, client: ClientV2) -> None

Save account.

description: str = NotImplemented

Short plugin description

name: str = NotImplemented

Unique name of the plugin

abstract prepare() -> None

Prepare the plugin.

Finish up any additional initialization.

abstract more_info() -> str

Human-readable string to help the user.

Should describe the steps taken and any relevant info to help the user decide which plugin to use.

abstract classmethod inject_parser_options(parser: ArgumentParser, name: str) -> None

Inject argument parser options (flags).

1. Be nice and prepend all options and destinations with option_namespace and dest_namespace.

2. Inject options (flags) only. Positional arguments are not allowed, as this would break the CLI.

abstract get_chall_pref(domain: str) -> Iterable[Type[Challenge]]

Return collections.Iterable of challenge preferences.

abstract perform(achalls: List[AnnotatedChallenge]) -> List[ChallengeResponse]

Perform the given challenge.

abstract cleanup(achalls: List[AnnotatedChallenge]) -> None

Revert changes and shutdown after challenges complete.

This method should be able to revert all changes made by perform, even if perform exited abnormally.

abstract get_all_names() -> Iterable[str]

Returns all names that may be authenticated.

abstract deploy_cert(domain: str, cert_path: str, key_path: str, chain_path: str, fullchain_path: str) -> None

Deploy certificate.

abstract enhance(domain: str, enhancement: str, options: Optional[Union[List[str], str]] = None) -> None

Perform a configuration enhancement.