Certbot
Certbot は Python で書かれた Electronic Frontier Foundation の ACME クライアントです。ウェブサーバの自動設定や HTTP チャレンジのためのビルトインウェブサーバといった便利な機能を持ちます。 Certbot は Let's Encrypt に推奨されています。
インストール
発行された証明書はプラグインを使ってウェブサーバーに自動的に設定・インストールできます:
- Nginx 用のプラグインは certbot-nginx パッケージに入っています。
- Apache HTTP Server 用のプラグインは certbot-apache パッケージで使えます。
設定
証明を作成・インストールする方法は Certbot のドキュメント を参照してください。
プラグイン
Nginx
certbot-nginx プラグインは nginx の server ブロックを自動的に設定します:
# certbot --nginx
証明書を更新するには:
# certbot renew
nginx の設定ファイルに手を加えずに証明書を変更するには:
# certbot --nginx certonly
詳しい情報は Nginx on Arch Linux を見てください。インストールされた証明書の状態を有効に保つ方法は#自動更新を見てください。
サーバーブロックの管理
サーバーブロックを手動で管理する場合、以下のようにサーバーブロックで使うことができます:
/etc/nginx/sites-available/example
server { listen 443 ssl http2; listen [::]:443 ssl http2; # Listen on IPv6 ssl_certificate /etc/letsencrypt/live/domain/fullchain.pem; # managed by Certbot ssl_certificate_key /etc/letsencrypt/live/domain/privkey.pem; # managed by Certbot include /etc/letsencrypt/options-ssl-nginx.conf; ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; .. }
詳しくは nginx#TLS/SSL を見てください。
別の設定ファイルを作成してサーバーブロックから include して使用することも可能です:
/etc/nginx/conf/001-cerbot.conf
ssl_certificate /etc/letsencrypt/live/domain/fullchain.pem; # managed by Certbot ssl_certificate_key /etc/letsencrypt/live/domain/privkey.pem; # managed by Certbot include /etc/letsencrypt/options-ssl-nginx.conf; ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;
/etc/nginx/sites-available/example
server { listen 443 ssl http2; listen [::]:443 ssl http2; # Listen on IPv6 include conf/001-certbot.conf; .. }
Apache
The plugin certbot-apache provides an automatic configuration for the Apache HTTP Server. This plugin will try to detect the configuration setup for each domain. The plugin adds extra configuration recommended for security, settings for certificate use, and paths to Certbot certificates. See #Managing Apache virtual hosts for examples.
First time setup of virtual hosts:
# certbot --apache
To renew certificates:
# certbot renew
To change certificates without modifying apache config files:
# certbot --apache certonly
See Certbot-Apache on Arch Linux for more information and #Automatic renewal to keep installed certificates valid.
Managing Apache virtual hosts
The following example may be used in all virtual hosts when managing these files manually:
/etc/httpd/conf/extra/001-certbot.conf
<IfModule mod_ssl.c> <VirtualHost *:443> Include /etc/letsencrypt/options-ssl-apache.conf SSLCertificateFile /etc/letsencrypt/live/'domain'/fullchain.pem SSLCertificateKeyFile /etc/letsencrypt/live/'domain'/privkey.pem </VirtualHost> </IfModule>
/etc/httpd/conf/httpd.conf
<IfModule mod_ssl.c> Listen 443 </IfModule> Include conf/extra/001-certbot.conf ..
See Apache HTTP Server#TLS for more information.
Webroot
webroot 方式を使う場合、Certbot クライアントは /path/to/domain.tld/html/.well-known/acme-challenge/
の中でチャレンジ・レスポンス認証を行います。
手動でインストールする場合と比べて、自動で証明書を更新したり楽に管理することができます。ただし、#プラグインを使う時のように自動設定・自動インストールはできません。
ACME チャレンジリクエストのマッピング
.well-known/acme-challenge
に対する HTTP リクエストを全てひとつのディレクトリ (例: /var/lib/letsencrypt
) にマッピングすることで管理が簡単になります。
Certbot やウェブサーバー (http ユーザーで動作する nginx や Apache など) が書き込みできるパスを使用してください:
# mkdir -p /var/lib/letsencrypt/.well-known # chgrp http /var/lib/letsencrypt # chmod g+s /var/lib/letsencrypt
nginx
location ブロックを記述したファイルを作成してサーバーブロックから読み込むようにしてください:
/etc/nginx/conf.d/letsencrypt.conf
location ^~ /.well-known/acme-challenge/ { allow all; root /var/lib/letsencrypt/; default_type "text/plain"; try_files $uri =404; }
サーバー設定の例:
/etc/nginx/servers-available/domain.conf
server { server_name domain.tld .. include conf.d/letsencrypt.conf; }
Apache
/etc/httpd/conf/extra/httpd-acme.conf
ファイルを作成してください:
/etc/httpd/conf/extra/httpd-acme.conf
Alias /.well-known/acme-challenge/ "/var/lib/letsencrypt/.well-known/acme-challenge/" <Directory "/var/lib/letsencrypt/"> AllowOverride None Options MultiViews Indexes SymLinksIfOwnerMatch IncludesNoExec Require method GET POST OPTIONS </Directory>
/etc/httpd/conf/httpd.conf
で上記ファイルを読み込んでください:
/etc/httpd/conf/httpd.conf
Include conf/extra/httpd-acme.conf
証明書の取得
公開パスとして /var/lib/letsencrypt/
を使用して domain.tld
の証明書を取得するには:
# certbot certonly --email email@example.com --webroot -w /var/lib/letsencrypt/ -d domain.tld
(サブ)ドメインを追加するときは、登録済みの全てのドメインを一緒に指定します:
# certbot certonly --email email@example.com --webroot -w /var/lib/letsencrypt/ -d domain.tld,sub.domain.tld
登録している証明書を(全て)更新するには:
# certbot renew
証明書の更新方法については#自動更新も参照。
手動
ウェブサーバーのプラグインが存在しない場合、以下のコマンドを使ってください:
# certbot certonly --manual
DNS の TXT レコードを利用して認証したい場合、以下のコマンドを使ってください:
# certbot certonly --manual --preferred-challenges dns
上記のコマンドで自動的にドメインが認証されて秘密鍵と証明書のペアが作成されます。秘密鍵と証明書は /etc/letsencrypt/archive/your.domain/
に保存され、/etc/letsencrypt/live/your.domain/
からリンクが張られます。
証明書が取得できたら手動でウェブサーバーを設定して、シンボリックリンクが存在するディレクトリの秘密鍵・証明書・証明書チェーンを参照してください。
高度な設定
自動更新
systemd
certbot.service
ユニットを作成:
/etc/systemd/system/certbot.service
[Unit] Description=Let's Encrypt renewal [Service] Type=oneshot ExecStart=/usr/bin/certbot renew --quiet --agree-tos
プラグインを使わずにウェブサーバーの設定を自動で管理する場合、ウェブサーバーを手動でリロードして証明書が更新されるたびにリロードが必要です。ExecStart
コマンドに --deploy-hook "systemctl reload nginx.service"
を追加することでリロードさせることができます [1]。適宜 nginx.service
のかわりに httpd.service
を使ってください。
それから、タイマーを追加することで証明書を更新できます (更新の必要がない証明書は自動的にスキップされます)。
/etc/systemd/system/certbot.timer
[Unit] Description=Daily renewal of Let's Encrypt's certificates [Timer] OnCalendar=0/12:00:00 RandomizedDelaySec=1h Persistent=true [Install] WantedBy=timers.target
Automatic renewal for wildcard certificates
The process is fairly simple. To issue a wildcard certificate, you have to do it via a DNS challenge request, using the ACMEv2 protocol.
While issuing a certificate manually is easy, it's not straight forward for automation. The DNS challenge represents a TXT record, given by certbot, which has to be set manually in the domain zone file.
You will need to update the zone file upon every renew. To avoid doing that manually, you may use rfc2136 for which certbot has a plugin packaged in certbot-dns-rfc2136. You will also need to configure your DNS server to allow dynamic updates for TXT records.
Configure BIND for rfc2136
Generate a TSIG secret key:
$ tsig-keygen -a HMAC-SHA512 example-key
and add it in the configuration file:
/etc/named.conf
... zone "domain.ltd" IN { ... // this is for certbot update-policy { grant example-key name _acme-challenge.domain.ltd. txt; }; ... }; key "example-key" { algorithm hmac-sha512; secret "a_secret_key"; }; ...
Restart named.service
.
Configure certbot for rfc2136
Create a configuration file for the rfc2136 plugin.
/etc/letsencrypt/rfc2136.ini
dns_rfc2136_server = IP.ADD.RE.SS dns_rfc2136_name = example-key dns_rfc2136_secret = INSERT_KEY_WITHOUT_QUOTES dns_rfc2136_algorithm = HMAC-SHA512
Since the file contains a copy of the secret key, secure it with chmod by removing the group and others permissions.
Test what we did:
# certbot certonly --dns-rfc2136 --force-renewal --dns-rfc2136-credentials /etc/letsencrypt/rfc2136.ini --server https://acme-v02.api.letsencrypt.org/directory --email example@domain.ltd --agree-tos --no-eff-email -d 'domain.ltd' -d '*.domain.ltd'
If you pass the validation successfully and receive certificates, then you are good to go with automating certbot. Otherwise, something went wrong and you need to debug your setup. It basically boils down to running certbot renew
from now on, see #Automatic renewal.