コマンド解説(コマンドリファレンス)
このページ「コマンド解説」(コマンドリファレンス)では、Certbot クライアント(旧・Let's Encrypt クライアント)のコマンド・サブコマンド・オプションの使い方を説明しています。
※Certbot クライアントは、電子フロンティア財団(EFF)が提供している証明書取得・管理ソフトウェアです。
※このページは、Certbot クライアント Version 0.8.0 のヘルプ出力( certbot-auto --help all
)の全文を和訳(意訳)した上で、解説や補足等を追加したものです(出典とライセンス表示)。
コマンドの使い方
certbot-auto [サブコマンド] [オプション] [-d DOMAIN] [-d DOMAIN] ...
※サブコマンドを省略した場合には、サブコマンド run
が指定されたものとみなされます。
※オプションは、半角スペースで区切って複数指定することができます。
※ドメイン名は、1つだけ指定することも、2つ以上指定することもできます。
Certbot クライアントを使用することで、HTTPS / TLS / SSL の証明書を、取得したりインストールしたりすることができます。
デフォルト(サブコマンド省略時)では、Certbot クライアントは、サーバに導入されているウェブサーバを使用して、証明書の取得とインストール(ウェブサーバの設定)を試みます。
主要なサブコマンド
run
(デフォルト)-
現在動作しているウェブサーバに、SSL/TLS サーバ証明書を取得・インストールします。
デフォルトのサブコマンドであるため、サブコマンドの指定を省略した場合には、このサブコマンド(run)が指定されたものとみなされます。
certonly
-
SSL/TLS サーバ証明書の取得のみを行います。
証明書のインストール(サーバソフトウェアの設定)は行われません。
別名は
auth
です。 install
-
取得済みの SSL/TLS サーバ証明書を、サーバソフトウェアにインストールします。
(サーバソフトウェアの設定ファイル編集を自動的に行います)
renew
-
取得済みの SSL/TLS サーバ証明書のうち、有効期限が近い証明書を自動的に更新します。
revoke
-
取得済みの SSL/TLS サーバ証明書を、失効させます。
register
-
認証局への登録に関連したタスクを実行します。
rollback
-
証明書のインストールによって変更されたサーバソフトウェアの設定ファイルを元に戻します(ロールバック)。
config_changes
-
証明書のインストールを行う際に、サーバソフトウェアの設定ファイルにどのような変更が行われるのかを表示します。
plugins
-
インストールされているプラグインの情報を表示します。
一般オプション
-h
もしくは--help
-
ヘルプを表示(出力)して、終了します。
-c CONFIG_FILE
もしくは--config CONFIG_FILE
-
設定ファイルのパスを指定します。
(デフォルト: None)
-v
もしくは--verbose
-
出力の詳細度を高めます。
このフラグを
-vvv
のように複数回指定することで、出力の詳細度を更に高めることができます。(デフォルト: -3)
-t
もしくは--text
-
カーシス UI の代わりに、テキスト出力を使用します。
(デフォルト: False)
-n
もしくは--non-interactive
もしくは--noninteractive
-
クライアントソフトウェアの実行時に、ユーザーからの入力を一切求めません。
このオプションを指定すると、追加のコマンドラインフラグが必要となる場合があります。その場合には、クライアントソフトウェアは、必要なコマンドラインフラグの説明の表示(出力)を試みます。
(デフォルト: False)
--dialog
-
ダイアログを使用します。
(デフォルト: False)
--dry-run
-
クライアントソフトウェアをテスト実行して、テスト用の SSL/TLS サーバ証明書(信頼されていない無効な証明書)の取得を試みます。取得したテスト用の SSL/TLS サーバ証明書は、ディスク(HDD や SSD など)に保存されません。
このオプションは、今のところ、サブコマンド
certonly
もしくはrenew
と併せて使用する必要があります。注意:
--dry-run
は、システムに対する永続的な変更をなるべく加えないように設計していますが、完全ではありません。もし、ウェブサーバ(Apache や nginx)のオーセンティケータプラグインと一緒に使用した場合、テスト用の SSL/TLS サーバ証明書を取得するために一時的なウェブサーバの設定変更とウェブサーバのリロードが行われた後、ウェブサーバの設定変更がロールバックされます。正確に証明書の更新をシミュレーションするため、--pre-hook や --post-hook コマンドが定義されていた場合には、それらが呼び出されることがあります。
--renew-hook
コマンドは呼び出されません。(デフォルト: False)
--register-unsafely-without-email
-
このフラグを指定した場合、証明書管理のためのアカウントを作成する際に、電子メールアドレスを登録しません。
暗号鍵の紛失やアカウントの盗用が発生した際にアカウントへアクセスする手段が完全に失われることになるため、このフラグを指定しないことを強く推奨します。
電子メールアドレスを登録しない場合、SSL/TLS サーバ証明書の有効期限が近付いた場合や証明書が失効した場合の通知を受け取ることもできなくなります。また、利用規約が変更された場合には、ウェブサイトで告知してから14日間が経過した時点で、新しい利用規約が有効となります。
(デフォルト: False)
--update-registration
-
アカウント情報の登録時に、新規のアカウントを作成するのではなく、既存のアカウントに関連付けられた詳細情報(電子メールアドレスなど)を更新したい場合に指定します。
(デフォルト: False)
-m EMAIL
もしくは--email EMAIL
-
アカウントの登録や回復などに使用する電子メールアドレスを
-m webmaster@example.jp
もしくは--email webmaster@example.jp
のように指定します(一般公開はされません)。証明書を取得するドメイン名のメールアドレスである必要はなく、Gmail (gmail.com) などの電子メールアドレスも使用可能です。
また、同一のメールアドレスで、複数の証明書を管理することができます。
(デフォルト: None)
-d DOMAIN
もしくは--domains DOMAIN
もしくは--domain DOMAIN
-
SSL/TLS サーバ証明書の取得を申請するドメイン名を指定します。
複数のドメイン名を指定する場合、
-d example.jp -d www.example.jp
のように-d
フラグを複数回指定します。また、
-d example.jp,www.example.jp
のようにカンマ(,
)で区切ったリストをパラメータとして指定する方法もあります。(デフォルト: [])
--user-agent USER_AGENT
-
クライアントのユーザーエージェント文字列を変更します。
ユーザーエージェント文字列は、認証局によって、OS やプラグインごとの成功率に関する高精度の統計情報を収集する目的で使用されます。
もし、Let's Encrypt 認証局のサーバに対して OS のバージョン情報を提供したくない場合には、
--user-agent ""
を指定します。(デフォルト: None)
自動化オプション
処理や調整を自動化する際に使用するオプションです。
--keep-until-expiring
もしくは--keep
もしくは--reinstall
-
リクエストされた SSL/TLS サーバ証明書が既に存在している証明書とマッチする場合には、証明書の更新が必要になるまでは、常に既存の証明書を保ちます(新規の証明書を取得しません)。
サブコマンド run と併せて指定した場合、既に導入されている証明書がそのまま再インストールされます(新しい証明書は発行されません)。
(デフォルト: False)
--expand
-
リクエストされたドメイン名の集合の一部が、既に存在している SSL/TLS サーバ証明書に含まれている場合には、常に既存の証明書のサブジェクト代替名(サブジェクトの別名、SANs)を拡張します(ドメイン名の集合の追加した証明書への置き換え)。
(デフォルト: False)
--version
-
クライアントプログラムのバージョン番号を表示(出力)して、終了します。
--force-renewal
もしくは--renew-by-default
-
リクエストされたドメイン名の SSL/TLS サーバ証明書が既に存在する場合には、残りの有効期間にかかわらず、証明書を更新します。
このオプションを有効にすると --expand も有効になります。
多くの場合、このオプションではなく --keep-until-expiring を使うべきです。
(デフォルト: False)
--allow-subset-of-names
-
ドメイン名の認証を行う際に、指定されたドメイン名の集合のうちの一部のドメイン名の認証に失敗した場合にも、認証に成功したドメイン名のみに対応した SSL/TLS サーバ証明書を取得します。
複数のドメイン名のうち、いくつかのドメイン名がサーバをポイントしていない可能性がある場合には、このオプションが有用かもしれません。
このオプションと --csr を同時に有効にすることはできません。
(デフォルト: False)
--agree-tos
-
ACME 利用規約に同意します。
このオプションを有効にした場合、過去に利用規約の同意を行ったことがない場合であっても、利用規約の同意を求める画面が表示されません。
(デフォルト: False)
--account ACCOUNT_ID
-
アカウントの ID を指定します。
(デフォルト: None)
--duplicate
-
既に存在している SSL/TLS サーバ証明書を複製した系統の証明書を作成することを許可します(双方の証明書を平行して更新することが可能)。
(デフォルト: False)
--os-packages-only
-
letsencrypt-auto 専用オプションです。
OS のパッケージの依存関係をインストール・更新のみを行って、プログラムを終了します。
(デフォルト: False)
--no-self-upgrade
-
letsencrypt-auto 専用オプションです。
letsencrypt-auto プログラムの新しいバージョンへの自動更新を阻止します。
(デフォルト: False)
-q
もしくは--quiet
-
エラーを除くすべての出力を行いません(エラーメッセージのみを出力)。
cron
を用いた自動化の際に便利です。このオプションを有効にすると --non-interactive も有効になります。
(デフォルト: False)
テスト用オプション
これらのフラグは、テスト目的のみで使用することを意図しています。
やろうとしていることを本当に理解している場合を除き、これらのフラグを変更しないでください。
--debug
-
エラー発生時に traceback を表示し、letsencrypt-auto を実験的なプラットフォーム上で実行することを許可します。
(デフォルト: False)
--no-verify-ssl
-
SSL/TLS 証明書の検証を無効にします。
(デフォルト: False)
--tls-sni-01-port TLS_SNI_01_PORT
-
HTTPS 接続による認証(tls-sni-01 challenge)を実施する際に使用する TCP ポート番号を指定します。
テストモードにおける Boulder のデフォルトを 5001 にします。
(デフォルト: 443)
--http-01-port HTTP01_PORT
-
シンプルな HTTP 接続による認証(SimpleHttp challenge)を実施する際に使用する TCP ポート番号を指定します。
(デフォルト: 80)
--break-my-certs
-
既存の有効な証明書を、無効な証明書(テスト用・ステージング)に置き換えることを許可します。
(デフォルト: False)
--test-cert
もしくは--staging
-
SSL/TLS サーバ証明書の取得時に、ステージングサーバを使用して、無効な証明書を取得します。
オプション
--server https://acme-staging.api.letsencrypt.org/directory
を指定するのと同じ動作です。(デフォルト: False)
セキュリティ関係のオプション
セキュリティに関係したパラメータやサーバの設定です。
--rsa-key-size N
-
RSA 鍵の鍵長(ビット数)を指定します。
(デフォルト: 2048)
--must-staple
-
SSL/TLS サーバ証明書に、OCSP Must Staple 拡張を追加します。
Apache バージョン 2.3.3 以上において、OCSP Stapling の自動構成がサポートされています。
(デフォルト: False)
--redirect
-
新たに認証されたバーチャルホストにおいて、すべての HTTP トラフィックを HTTPS に自動リダイレクトさせます。
(デフォルト: None)
--no-redirect
-
新たに認証されたバーチャルホストにおいて、すべての HTTP トラフィックを HTTPS に自動リダイレクトしないようにします。
(デフォルト: None)
--hsts
-
すべての HTTP レスポンスにおいて、Strict-Transport-Security ヘッダーを追加します。
これにより、当該ドメインへの接続の際にブラウザに対して SSL/TLS 接続を強制し、SSL Stripping 攻撃を防ぎます。
(デフォルト: False)
--no-hsts
-
すべての HTTP レスポンスにおいて、Strict-Transport-Security ヘッダーが自動的に追加されないようにします。
(デフォルト: False)
--uir
-
すべての HTTP レスポンスにおいて、"Content-Security-Policy: upgrade-insecure-requests" ヘッダーが自動的に追加されるようにします。
これにより、ブラウザがすべての http:// リソースに対して https:// で接続するようにします。
(デフォルト: None)
--no-uir
-
すべての HTTP レスポンスにおいて、"Content-Security-Policy: upgrade-insecure-requests" ヘッダーが自動的に追加されないようにします。
これにより、ブラウザがすべての http:// リソースに対して https:// で接続するようにします。
(デフォルト: None)
--staple-ocsp
-
OCSP Stapling を有効にします。
有効な OCSP レスポンスが、TLS 接続時にサーバから提供される SSL/TLS サーバ証明書に含めて提供されます。
(デフォルト: None)
--no-staple-ocsp
-
自動的に OCSP Stapling を有効にしないようにします。
(デフォルト: None)
--strict-permissions
-
すべての設定ファイルの所有者が現在のユーザーであることを要求します。
設定ファイルが "/tmp/" などの安全でない場所にある場合のみ有効にする必要があるフラグです。
(デフォルト: False)
サブコマンド "renew" のオプション
サブコマンド renew は、過去に取得したことのある SSL/TLS サーバ証明書のうち、有効期限が近いすべての証明書の更新を試み、その結果の概要を出力します。デフォルトでは、それぞれの証明書における、最後に証明書の取得や更新に成功した際に使われたオプション設定が使われます。
まずは、--dry-run オプションを用いてテストしてみることをお勧めします。
より細かなコントロールを行いたい場合には、それぞれの証明書をサブコマンド certonly を用いて更新してください。
証明書の更新の前後にコマンドを実行したい場合には、Hooks が利用可能です。詳しくは、SSL/TLS サーバ証明書の更新 をご覧ください。
--pre-hook PRE_HOOK
-
証明書の取得前にシェルで実行するコマンドを指定します。
主に standalone プラグインを利用する場合に、起動中のウェブサーバを一時的に終了する目的で使用します(standalone プラグインが TCP Port 80 や TCP Port 443 を Listen するため)。
これは、証明書が実際に取得・更新できる場合のみ呼び出されます。
(デフォルト: None)
--post-hook POST_HOOK
-
証明書を取得・更新する試みが終わった後にシェルで実行するコマンドを指定します。
更新された証明書を配備する目的や、--pre-hook で終了したサービスを起動する目的で使用できます。
これは、証明書を取得・更新する試みが行われた場合のみ実行されます。
(デフォルト: None)
--renew-hook RENEW_HOOK
-
それぞれの更新に成功した証明書について、一回ずつシェルで実行されるコマンドを指定します。
このオプションを使用する場合、シェル変数
$RENEWED_LINEAGE
が新しい証明書と暗号鍵を含む live サブディレクトリをポイントし、シェル変数$RENEWED_DOMAINS
が更新されたドメイン名の一覧(半角スペース区切り)をポイントします。(デフォルト: None)
サブコマンド "certonly" のオプション
SSL/TLS サーバ証明書の取得方法を変更するためのオプションです。
--csr CSR
-
証明書署名要求(CSR : Certificate Signing Request)のパスを指定します。
証明書署名要求は、DER フォーマットでエンコードされている必要があります。また、認証を希望する各ドメイン名が .csr ファイルの Subject Alternative Name フィールドに必ず含まれている必要があります。
今のところ、
--csr
オプションは、サブコマンド certonly のみで有効です。(デフォルト: None)
サブコマンド "rollback" のオプション
設定の変更を元に戻す際に使用するオプションです。
--checkpoints N
-
設定の構成を、チェックポイント N 個分だけロールバックします。
(デフォルト: 1)
サブコマンド "config_changes" のオプション
設定の変更の履歴を表示する際に使用するオプションです。
--num NUM
-
何個前のリビジョンを表示するのかを数字で指定します。
(デフォルト: None)
パスやサーバを変更するオプション
実行パスや証明書の取得に使用するサーバを変更する引数です。
--cert-path CERT_PATH
-
証明書の保存場所のパスを指定します。
(デフォルト: None)
--key-path KEY_PATH
-
証明書のインストールや失効(アカウントキー紛失時)に用いる秘密鍵のパスを指定します。
(デフォルト: None)
--fullchain-path FULLCHAIN_PATH
-
完全な証明書チェーン(cert plus chain)付随のパスを指定します。
(デフォルト: None)
--chain-path CHAIN_PATH
-
証明書チェーン付随のパスを指定します。
(デフォルト: None)
--config-dir CONFIG_DIR
-
コンフィギュレーションディレクトリを指定します。
(デフォルト: /etc/letsencrypt)
--work-dir WORK_DIR
-
ワーキングディレクトリを指定します。
(デフォルト: /var/lib/letsencrypt)
--logs-dir LOGS_DIR
-
ログファイルの保存先ディレクトリを指定します。
(デフォルト: /var/log/letsencrypt)
--server SERVER
-
ACME ディレクトリリソースの URI を指定します。
(デフォルト: https://acme-v01.api.letsencrypt.org/directory)
プラグイン関係のオプション
Certbot クライアント(旧・Let's Encrypt クライアント)は、拡張可能なプラグインアーキテクチャをサポートしています。
すべてのインストール済みプラグインとその名称のリストは certbot-auto plugins
を実行すると表示できます(サブコマンド plugins)。
下記のオプションを指定することで、特定のプラグインを強制することが可能です。
また、--help plugin_name
を実行することで、そのプラグイン固有のフラグが一覧表示されます。
--init
-
プラグインの初期化を行います。
(デフォルト: False)
--prepare
-
プラグインの初期化と準備を行います。
(デフォルト: False)
--authenticators
-
使用するプラグインを、Authenticators(オーセンティケータ)のみに限定します。
(デフォルト: None)
--installers
-
使用するプラグインを、Installers(インストーラ)のみに限定します。
(デフォルト: None)
-a AUTHENTICATOR
もしくは--authenticator AUTHENTICATOR
-
Authenticator(オーセンティケータ)プラグインの名前を指定します。
(デフォルト: None)
-i INSTALLER
もしくは--installer INSTALLER
-
Installer(インストーラ)プラグインの名前を指定します。
Installer プラグインは、ドメイン名の検索にも使用します。
(デフォルト: None)
--configurator CONFIGURATOR
-
Authenticator(オーセンティケータ)と Installer(インストーラ)の両方に属しているプラグイン(Authenticator かつ Installer なプラグイン)の名前を指定します。
--authenticator や --installer と同時に使用することはできません。
(デフォルト: None)
--apache
-
SSL/TLS サーバ証明書を取得して Apache にインストールします。ドメイン名の認証の際には Apache を使用します。
(デフォルト: False)
--nginx
-
SSL/TLS サーバ証明書を取得して Nginx にインストールします。ドメイン名の認証の際には Nginx を使用します。
(デフォルト: False)
--standalone
-
Certbot クライアントに内蔵されているウェブサーバを使用して、SSL/TLS サーバ証明書を取得します。
(デフォルト: False)
--manual
-
ドメイン名の認証を手動で行い、SSL/TLS サーバ証明書を取得します。
(デフォルト: False)
--webroot
-
ウェブサーバの DocumentRoot ディレクトリ以下に認証用のファイルを設置することでドメイン使用権者の認証を行って、SSL/TLS サーバ証明書を取得します。
(デフォルト: False)
apache プラグインのオプション
プラグイン "apache" のオプションです。
--apache-enmod APACHE_ENMOD
-
Apache の "a2enmod" バイナリへのパスを指定します。
(デフォルト: None)
--apache-dismod APACHE_DISMOD
-
Apache の "a2dismod" バイナリへのパスを指定します。
(デフォルト: None)
--apache-le-vhost-ext APACHE_LE_VHOST_EXT
-
SSL バーチャルホストの設定拡張のファイル名を指定します。
(デフォルト: -le-ssl.conf)
--apache-server-root APACHE_SERVER_ROOT
-
Apache サーバのルートディレクトリを指定します。
(デフォルト: /etc/httpd)
--apache-vhost-root APACHE_VHOST_ROOT
-
Apache サーバのバーチャルホスト設定ファイルのディレクトリを指定します。
(デフォルト: /etc/httpd/conf.d)
--apache-challenge-location APACHE_CHALLENGE_LOCATION
-
チャレンジ設定のディレクトリパスを指定します。
(デフォルト: /etc/httpd/conf.d)
--apache-handle-modules APACHE_HANDLE_MODULES
-
今のところ、Ubuntu と Debian のみで有効です。
Let installer handle enabling required modules for you.
(デフォルト: False)
--apache-handle-sites APACHE_HANDLE_SITES
-
今のところ、Ubuntu と Debian のみで有効です。
Let installer handle enabling sites for you.
(デフォルト: False)
webroot プラグインのオプション
プラグイン webroot のオプションです。
"webroot" プラグインは、ウェブサーバの DocumentRoot ディレクトリ以下に認証用のファイルを設置することでドメイン使用権者の認証を行って、SSL/TLS サーバ証明書を取得します。
--webroot-path WEBROOT_PATH
もしくは-w WEBROOT_PATH
-
"public_html" や "webroot" のパスを指定します。
複数のドメイン名に対する証明書を一度に取得する場合には、このオプションを複数回指定することができます。その場合、それぞれのドメイン名に対して、最後に指定した WEBROOT_PATH が適用されます。
例えば、
-w /var/www/example -d example.com -d www.example.com -w /var/www/thing -d thing.net -d m.thing.net
のように指定します。(デフォルト: [])
--webroot-map WEBROOT_MAP
-
ドメイン名と WEBROOT_PATH を、JSON 辞書マッピングで指定します。
これには、それぞれのエントリーへの -d が含まれており、シェルにおけるエスケープが必要です。
例えば、
--webroot-map '{"eg1.is,m.eg1.is":"/www/eg1/", "eg2.is":"/www/eg2"}'
のように指定します。このオプションはマージ(結合)されますが、-w と -d エントリーよりも優先されます。
今のところ、WEBROOT_MAP を設定ファイルで指定する場合には、
webroot-map = {"example.com":"/var/www"}
のように1行で記述する必要があります。
(デフォルト: {})
manual プラグインのオプション
プラグイン manual のオプションです。
"manual" プラグインを使用する場合、ドメイン名の認証を手動で行い、SSL/TLS サーバ証明書を取得します。
--manual-test-mode
-
テストモードです。
サブプロセスの手動のコマンドを実行します。
(デフォルト: False)
--manual-public-ip-logging-ok
-
グローバルIPアドレスを認証局でロギングすることに対する確認を表示しません。
このオプションを指定した場合、グローバルIPアドレスのロギングが自動的に許可されます。
(デフォルト: False)
standalone プラグインのオプション
プラグイン standalone のオプションです。
"standalone" プラグインを使用する場合、Certbot クライアントに内蔵されているウェブサーバを使用して、SSL/TLS サーバ証明書を取得します。
--standalone-supported-challenges STANDALONE_SUPPORTED_CHALLENGES
-
ドメイン名使用者の認証に使用するチャレンジを、優先度順で指定します。
(デフォルト: tls-sni-01,http-01)
出典とライセンス表示
このページ「コマンド解説」は、電子フロンティア財団 (Electronic Frontier Foundation) (英文) が提供している Certbot ソフトウェア(Version 0.8.0)に内包されているヘルプデータを抽出して内容の修正を加えたデータを内包している二次的著作物です。
Certbot ソフトウェア と ドキュメント (英文) には、Apache 2.0 ライセンスが適用されています。
©Copyright 2014-2016 - The Certbot software and documentation are licensed under the Apache 2.0 license as described at https://eff.org/cb-license .
- スポンサーリンク