More than 3 years have passed since last update.

certbot(Letsecnrypt)コマンド・オプションを真面目に理解する

Last updated at 2020-10-11Posted at 2020-10-11

背景

弊社が提供するWebシステムはのきなみLetsEncryptを活用しています。(寄付もしたことがある)

LetsEncrptがリリースされた当時は情報が少なくEC2(Amazon Linux)と相性が悪かったりで結構大変だった記憶があります。
その後、困るたびに調べて解決して(その中のいくつかは他の人にも有用だと思って記事(末尾に一覧)化)きましたが、一言でいえば「場当たり的な対応」でした。
本日、更新エラーが通知されてきたので、これを機会に全体を俯瞰して学習しておこうと思いました。

そのまとめ(適宜更新)です。

環境

2020年10月11日現在
OSはAmazon Linux2
certbotバージョンは1.9.0
WebサーバはApache

certbot helpの結果

まずはどれくらいの学習量が必要か覚悟するためにcertbot helpを実行した結果が以下。
思ったより少なくて、オプションの名前からなんとなく機能も想像できるのでホッとしました。
(後で気づきましたが、実際はcertbot -h allするとはるかに大量の情報が表示されます。今回はhelpで表示されるものと重要なオプションだけにとどめることにしました。(^_^;))

次の節で、カテゴリごとに表形式で日本語で整理しました。

certbot help

  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  (the certbot nginx plugin is not installed)
  --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)
manage your account:
    register        Create an ACME account
    unregister      Deactivate an ACME account
    update_account  Update an ACME account
  --agree-tos       Agree to the ACME server’s Subscriber Agreement
   -m EMAIL         Email address for important account notifications
More detailed help:
  -h, --help [TOPIC]    print this message, or detailed help on a topic;the available TOPICS are:all, automation, commands, paths, security, testing, or any of the subcommands or plugins (certonly, renew, install, register, nginx, apache, standalone, webroot, etc.)
  -h all                print a detailed help page including all topics
  --version             print the version number

※ハイライトがおかしくなるので、server’s の'(アポストロフィー)を半角から全角に変えています。

オプションの意味、用途、指定例

obtain, install, and renew certificates/証明書の取得、インストールおよび更新

サブコマンド/オプション等	概要(日本語訳)	備考
(default) run	現在のウェブサーバーで証明書を取得してインストール(注1)
certonly	証明書を取得または更新。インストールはしない
renew	有効期限が近づいている全ての取得済証明書を更新
enhance	既存の構成にセキュリティ拡張機能を追加
-d DOMAINS	証明書を取得するためのドメインのコンマ区切りリスト
--apache	認証とインストールにApacheプラグインを使用する
--standalone	認証のためにスタンドアロンのWebサーバーを実行します
--webroot	認証のためにサーバーのwebrootフォルダーにファイルを配置します	処理中に指定されたディレクトリに動的にランダムな名前のファイル(例えばKmwIkoQpTi7m8ZK43... とか)を配置。https://<ドメイン名>/.well-known/acme-challenge/<ファイル名>のリクエストを創出してレスポンスが戻ってくることを確認することで認証します。リバースプロキシ使ってると面倒
--manual	インタラクティブに、またはシェルスクリプトフックを使用して証明書を取得します
-n	非対話的に実行
★--test-cert★	ステージングサーバーからテスト証明書を取得します	certbotコマンドは1時間に5回までしか失敗できないのでコマンドの指定に不安がある場合やエラーが出た場合はこのオプションを付与します。ステージング環境ではもっとたくさん失敗できるようです。(注2)
--dry-run	「更新」または「証明書のみ」をテスト実行。証明書をディスクに保存しない

(注1)インストールは、Webサーバ(Apacheはnginx)の設定ファイルを作成するという意味です。
(注2)詳しくはレート制限 - Let's Encrypt - フリーな SSL/TLS 証明書を参照

manage certificates/証明書の管理

サブコマンド/オプション等	概要(日本語訳)	備考
certificates	Certbotから取得した証明書に関する情報を表示	当該サーバで取得した全て証明書情報を表示できます。・名称・シリアル番号・ドメイン・失効日時/有効無効状態/有効の場合は残日数も・証明書の格納先・秘密鍵の格納先さらにログ格納先(eg./var/log/letsencrypt)も表示してくれます
revoke	証明書を失効させます（--cert-nameまたは--cert-pathを指定）	`certificates`で確認した名前もしくは格納先を指定します。
delete	証明書を削除します（--cert-nameを指定）	同上

manage your account/アカウントの管理

サブコマンド/オプション等	概要(日本語訳)	備考
register	ACMEアカウントを作成
unregister	ACMEアカウントを無効化
update_account	ACMEアカウントを更新
--agree-tos	ACMEサーバーのサブスクライバー契約に同意
-m EMAIL	重要なアカウント通知のメールアドレス	指定したメールアドレスに失効期限が近いことなどを通知してくれます。

ACMEについて

Automated Certificate Management Environment - Wikipedia

Automated Certificate Management Environment (ACME) プロトコルは、
Webサーバと認証局との間の相互作用を自動化するための通信プロトコル で、
利用者のWebサーバにおいて非常に低コストでPKIX (X.509)形式の公開鍵証明書の自動展開を可能とする[1][2]。
Let's Encryptサービスに対して、Internet Security Research Group（英語版）によって設計された[1]。

【参考/公式サイト】ACME クライアント実装 - Let's Encrypt - フリーな SSL/TLS 証明書

Let’s Encrypt は、与えられたドメインを制御する権限があなたにあることを検証し、
証明書を発行するために、ACME プロトコルを使用しています。
Let’s Encrypt の証明書を取得するためには、使用する ACME クライアントを1つ選ぶ必要があります。

その他/重要なオプション

オプション	概要(日本語訳)	備考(用途など)
--force-renewal	強制的に証明書を更新	`certbot renew`処理は既定では失効日まで残り30日以内でないと更新対象から除外されるが、このオプションを使うことで更新できる。あまり頻度が多いとレート制限 - Let's Encrypt - フリーな SSL/TLS 証明書にひっかかるので注意
--pre-hook	証明書の取得/更新前にシェルで任意の処理を実行できる	主に更新を目的としており、Webサーバーを一時的にシャットダウンするために使用できます。実行されるのは更新/取得する証明書が存在する場合のみ。複数の証明書が更新される場合は最初のフックのみが実行される。
--post-hook	証明書の取得/更新後にシェルで任意の処理を実行できる	更新された証明書を展開したり、サーバーを再起動したりするために使用できる。例えばApache再開したければ `--post-hook "systemctl start httpd.service"`
-v(--verbose)	コマンド実行時の詳細なログを表示	エラーが発生している時に詳細を把握するために有用です。複数回指定することで出力の詳細レベルを変更できます。例.`-vvv`
--version	Certbotのバージョンを表示
help all	全てのサブコマンド・オプションを表示

これまで書いたLetencrypt関連記事

こうしてみるとLet's Encryptには本当にお世話になってるなぁ。LetsEncrypt財団への寄付はこちらです

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up