certbot

certbot is an easy-to-use automatic client that fetches and deploys SSL/TLS certificates for your webserver. certbot was developed by EFF and others as a client for Let's Encrypt. certbot will also work with any other CAs that support the ACME protocol.

• Project Homepage [EN]
  • Repository

• certbot [EN] @ Fedora Package
• certbot [EN] @ Homebrew Formula

Documentation

• Documentation [EN]
• FAQ [EN]

Syntax

certbot SUBCOMMAND [PARAMETER ...] [-d DOMAIN]

Subcommands & Parameters

Global parameters

The following parameters can be used with the subcommands below:

--agree-tos

Agree to the ACME Subscriber Agreement (default: Ask)

-c FILE, --config FILE

Path to config FILE (default: /etc/letsencrypt/cli.ini and ~/.config/letsencrypt/cli.ini)

--config-dir DIRECTORY

Configuration DIRECTORY (default: /etc/letsencrypt)

-d NAME, --domain NAME, --domains NAME

Domain NAMEs to apply. For multiple domains you can use multiple -d flags or enter a comma separated list of domains as a parameter. The first domain provided will be the subject CN of the certificate, and all domains will be Subject Alternative Names on the certificate. The first domain will also be used in some software user interfaces and as the file paths for the certificate and related material unless otherwise specified or you already have a certificate with the same name. In the case of a name collision it will append a number like 0001 to the file path name (default: Ask)

--logs-dir DIRECTORY

Logs DIRECTORY (default: /var/log/letsencrypt)

-m EMAIL, --email EMAIL

EMAIL used for registration and recovery contact (default: Ask)

--manual-public-ip-logging-ok

Automatically allows public IP logging (default: Ask)

--max-log-backups NUMBER

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)

--no-eff-email

Don't share your e-mail address with EFF (default: None)

--rsa-key-size SIZE

SIZE of the RSA key (default: 2048)

--staging, --test-cert

Use the staging server to obtain or revoke test (invalid) certificates (default: False)

-v, --verbose

This flag can be used multiple times to incrementally increase the verbosity of output, e.g. -vvv (default: -2)

--work-dir DIRECTORY

Working DIRECTORY (default: /var/lib/letsencrypt)

certonly

Obtain or renew a certificate, but do not install it.

--csr PATH

PATHto a Certificate Signing Request (CSR) in DER or PEM format (default: None)

--dry-run

Perform a test run of the client, obtaining test (invalid) certificates but not saving them to disk (default: False)

NOTE:

Although --dry-run tries to avoid making any persistent changes on a system, it is not completely side-effect free: if used with webserver authenticator plugins like Apache and Nginx, it makes and then reverts temporary config changes in order to obtain test certificates, and reloads webservers to deploy and then roll back those changes. It also calls --pre-hook and --post-hook commands if they are defined because they may be necessary to accurately simulate renewal. --deploy-hook commands are not called.

revoke

Revoke a certificate

--cert-name NAME

Certificate NAME to apply

Examples

Install certbot using pip

pip install 'certbot' 'certbot-dns-nsone'

Create a Let's Encrypt certificate for internal purposes using DNS challenge

NOTE:

The DNS provider NS1, which offers an API to edit the DNS zones, is used to provide the challenges.

Create directories:

mkdir --parents "${HOME}/.config/certbot" "${HOME}/certs/log" "${HOME}/certs/tmp"

Create a certbot configuration file with the following content:

vi "${HOME}/.config/certbot/cli.ini"

# Configuration directory (default: /etc/letsencrypt)
config-dir = /home/alex/certs

# Working directory (default: /var/lib/letsencrypt)
work-dir = /home/alex/certs/tmp

# Logs directory (default: /var/log/letsencrypt)
logs-dir = /home/alex/certs/log

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

# Automatically allows public IP logging (default: Ask)
manual-public-ip-logging-ok

# Email used for registration and recovery contact (default: Ask)
email = alex@raysoft.loc

# Don't share your e-mail address with EFF (default: None)
no-eff-email

# Size of the RSA key (default: 2048)
rsa-key-size = 2048

# Obtain certificates using a DNS TXT record (if you are using NS1 for DNS)
# (default: False)
dns-nsone

# NS1 credentials INI file (Required)
dns-nsone-credentials = /home/alex/.config/certbot/ns1.ini

Create a NS1 configuration file with the following content:

vi "${HOME}/.config/certbot/ns1.ini"

dns_nsone_api_key = **********

Run the certbot command:

certbot certonly --config "${HOME}/.config/certbot/cli.ini" \
  --domain 'argon.raysoft.loc'