Cara buat sijil wildcard Certbot guna DNS-01

Mengapa sijil wildcard memerlukan DNS-01

Sijil wildcard melindungi setiap sub-domain tahap pertama bagi sesuatu domain: *.example.com sepadan dengan app.example.com, blog.example.com, dan mana-mana nama lain yang mempunyai satu label. Let's Encrypt hanya mengeluarkan sijil wildcard melalui cabaran DNS-01, jadi Certbot mesti membuktikan kawalan ke atas DNS domain tersebut dengan menerbitkan rekod TXT pada _acme-challenge.example.com. Cabaran HTTP-01 tidak boleh digunakan kerana penyediaan fail token hanya membuktikan kawalan ke atas satu nama hos, iaitu nama hos yang digunakan oleh pelayan pengesahan untuk mengambil fail tersebut. Wildcard adalah tuntutan bagi setiap nama yang mungkin di bawah domain tersebut, dan satu-satunya rekod awam yang mewakili keseluruhan ruang nama ialah DNS itu sendiri.

Satu keperluan tersebut menentukan semua perkara lain pada halaman ini. Untuk lulus DNS-01, anda mesti boleh mencipta rekod TXT dalam zon domain tersebut, sama ada secara manual atau melalui API (application programming interface) pembekal DNS anda. Kaedah manual hanya berfungsi sekali dan akan gagal semasa pembaharuan, atas sebab khusus yang dinyatakan di bawah. Kaedah API, melalui plugin DNS Certbot, akan memperbaharui sijil secara automatik, dan ini adalah tetapan yang harus anda gunakan.

Ini adalah bab wildcard dalam panduan Certbot kami. Sijil nama hos tunggal biasa, konfigurasi pelayan web, dan peraturan port 80 dibincangkan dalam Certbot dengan nginx pada Ubuntu 24.04 dan Certbot dengan Apache pada Ubuntu 24.04.

Cara rekod _acme-challenge TXT berfungsi

Apabila Certbot meminta *.example.com, Let's Encrypt akan memberikan token rawak. Certbot menggabungkan token tersebut dengan kunci akaun ACME (automatic certificate management environment) anda, melakukan hash pada hasil tersebut dengan SHA-256, dan menghasilkan nilai teks pendek. Nilai tersebut mesti muncul sebagai rekod TXT pada _acme-challenge.example.com. Let's Encrypt kemudian akan membuat pertanyaan kepada name server autoritatif domain anda daripada infrastruktur mereka sendiri. Jika rekod yang dibaca sepadan dengan nilai yang dijangkakan, anda telah membuktikan bahawa anda mengawal zon tersebut, dan kawalan zon diterima sebagai kawalan bagi setiap nama di bawahnya.

Dua perkara menyebabkan kebanyakan kegagalan:

• Meminta example.com dan *.example.com pada sijil yang sama bermaksud dua cabaran berasingan, dan kedua-dua rekod TXT berada pada nama yang sama, _acme-challenge.example.com. Kedua-duanya mesti wujud pada masa yang sama. Menambah rekod kedua adalah betul; menggantikan rekod pertama dengan rekod kedua akan menyebabkan cabaran pertama gagal.
• Pengesahan membaca pelayan autoritatif anda, tetapi panel kawalan penyedia mungkin mengambil masa satu minit atau lebih untuk menghantar rekod baharu kepada mereka. Semak dari luar sebelum anda menjalankan pengesahan:

dig +short TXT _acme-challenge.example.com @1.1.1.1

Apabila ia memaparkan nilai yang diminta oleh Certbot, pengesahan boleh berjaya. Apabila ia tidak memaparkan apa-apa, tunggu dan jalankan semula.

Lihat ia berfungsi sekali: mod manual

Mod manual memerlukan anda melakukan suntingan DNS sendiri. Ini adalah cara terbaik untuk memahami mekanisme tersebut sebelum anda mengautomasikannya:

sudo certbot certonly --manual --preferred-challenges dns -d example.com -d '*.example.com'

Tanda petikan pada wildcard menghalang shell daripada menganggap * sebagai corak nama fail. Certbot akan berhenti dan memberikan arahan:

Please deploy a DNS TXT record under the name:
_acme-challenge.example.com.
with the following value:
Jx9mQ2wLr8vTn5cKp0aYdG3hB7fZs4eN1oiRuXqMk6E

Cipta rekod TXT tersebut dalam panel penyedia DNS anda, sahkan ia boleh dilihat dengan arahan dig di atas, dan hanya selepas itu tekan Enter. Kerana proses ini meminta domain asas dan wildcard, Certbot akan meminta dua kali; kekalkan kedua-dua rekod tersebut sehingga pengeluaran selesai. Kejayaan akan diakhiri dengan baris yang biasa dilihat:

Successfully received certificate.
Certificate is saved at: /etc/letsencrypt/live/example.com/fullchain.pem

Mengapa mod manual tidak boleh memperbaharui diri sendiri

Setiap pembaharuan adalah cabaran baharu dengan token baharu, jadi nilai TXT berubah setiap kali. Rekod yang anda tampal hari ini tidak lagi berguna dalam masa 60 hari. Pemasa pembaharuan Certbot berjalan secara automatik dua kali sehari, dan tiada sesiapa di papan kekunci untuk menampal nilai baharu, jadi sijil yang dikeluarkan secara manual gagal diperbaharui dengan ralat ini:

Failed to renew certificate example.com with error: The manual plugin is not
working; there may be problems with your existing configuration.
The error was: PluginError('An authentication script must be provided with
--manual-auth-hook when using the manual plugin non-interactively.')

Anda boleh memenuhi keperluan tersebut dengan menulis skrip --manual-auth-hook yang memanggil API pembekal DNS anda, tetapi pada tahap itu anda sedang membina semula plugin DNS secara manual. Gunakan mod manual untuk mempelajari aliran kerja, atau untuk kegunaan sekali sahaja pada domain yang DNS-nya belum boleh diautomasikan, dan tetapkan peringatan jauh sebelum hari ke-90, kerana Let's Encrypt tidak lagi menghantar e-mel tamat tempoh. Untuk perkara lain, gunakan plugin.

Laluan plugin: certbot-dns-cloudflare pada Ubuntu 24.04

Plugin DNS menyimpan kredensial API untuk penyedia DNS anda dan menguruskan keseluruhan proses rekod TXT secara automatik semasa pengeluaran dan setiap pembaharuan. Cloudflare digunakan sebagai contoh di sini kerana ia adalah plugin penyedia yang paling kerap diperlukan dan telah dibungkus dalam Ubuntu.

Panduan Certbot kami menyarankan penggunaan pakej apt pada Ubuntu 24.04, dan saranan ini terpakai untuk Cloudflare:

sudo apt update
sudo apt install certbot python3-certbot-dns-cloudflare

Nota mengenai versi. Arkib 24.04 membekalkan plugin ini pada versi 2.0.0 bersama Certbot 2.9.0; apt policy python3-certbot-dns-cloudflare menunjukkan versi anda. Ketidakpadanan ini tidak berbahaya, dan token API berskema (scoped) berfungsi kerana perpustakaan python3-cloudflare asas dalam 24.04 adalah versi 2.11.1, melebihi versi 2.3.1 yang diperlukan oleh plugin untuk sokongan token. Pada versi Ubuntu yang lebih lama, perpustakaan tersebut terlalu lama untuk menyokong token, yang menjadi punca amaran dalam talian mengenai plugin apt yang memaksa penggunaan Global API Key. Pada 24.04, amaran tersebut tidak lagi terpakai.

Di papan pemuka Cloudflare, cipta token API berskema, bukan Global API Key: My Profile, kemudian API Tokens, kemudian Create Token, dengan satu kebenaran Zone / DNS / Edit, yang dihadkan kepada satu zon yang anda ingin keluarkan. Simpan dalam fail yang hanya boleh dibaca oleh root:

sudo mkdir -p /root/.secrets
sudo tee /root/.secrets/cloudflare.ini > /dev/null <<'EOF'
dns_cloudflare_api_token = paste_your_scoped_token_here
EOF
sudo chmod 600 /root/.secrets/cloudflare.ini

Certbot menyemak mod fail dan memberi amaran tentang Unsafe permissions on credentials configuration file jika fail boleh dibaca oleh pengguna lain. Sekarang jalankan:

sudo certbot certonly \
  --dns-cloudflare \
  --dns-cloudflare-credentials /root/.secrets/cloudflare.ini \
  -d example.com -d '*.example.com'

Plugin ini mencipta rekod TXT melalui API, menunggu tempoh propagasi yang singkat, menjalankan pengesahan, kemudian memadam semula rekod tersebut. Jika pelayan nama (name servers) zon anda lambat mengesan perubahan, panjangkan masa menunggu dengan --dns-cloudflare-propagation-seconds 60. Sijil akan disimpan dalam /etc/letsencrypt/live/example.com/, dan anda perlu mengarahkan nginx atau Apache ke fullchain.pem dan privkey.pem tepat seperti yang ditunjukkan dalam panduan asas, termasuk hook deploy.

Jika plugin pembekal anda tiada dalam apt

Arkib 24.04 hanya membungkus plugin untuk segelintir pembekal, termasuk Cloudflare, Route 53, DigitalOcean dan antara muka generik RFC 2136. Jalankan apt search certbot-dns untuk melihat senarai tersebut. Jika pembekal anda tiada, ini adalah satu-satunya keadaan di mana nasihat utama kami berubah: pasang Certbot dan plugin tersebut menggunakan snap, dan buang Certbot daripada apt terlebih dahulu supaya dua pemasa pembaharuan tidak bertindih pada /etc/letsencrypt:

sudo apt remove certbot python3-certbot-dns-cloudflare
sudo snap install --classic certbot
sudo ln -s /snap/bin/certbot /usr/bin/certbot
sudo snap set certbot trust-plugin-with-root=ok
sudo snap install certbot-dns-yourprovider

Plugin snap hanya bersambung dengan Certbot snap; ia tidak boleh meluaskan fungsi versi apt, sebab itulah kedua-dua pemasangan tersebut tidak boleh wujud bersama. Jika hos DNS anda tidak menawarkan API langsung, pilihan realistik anda adalah memindahkan DNS domain ke pembekal yang mempunyai API, atau menjalankan pelayan nama sendiri dan menghalakan plugin rfc2136 kepadanya.

Pembaharuan: buktikan sekarang, bukan dalam 60 hari

Certbot merekodkan cara setiap sijil dikeluarkan dalam /etc/letsencrypt/renewal/example.com.conf, termasuk authenticator = dns-cloudflare dan laluan kredensial, supaya pemasa standard dua kali sehari boleh memperbaharuinya tanpa bantuan anda. Cuba keseluruhan proses ini menggunakan persekitaran staging:

sudo certbot renew --dry-run

Keputusan lulus bermaksud kredensial berfungsi dan pengesahan selesai sepenuhnya; pembaharuan sebenar dalam 60 hari akan mengikuti laluan yang sama. Dua langkah susulan perlu dilakukan hari ini. Pertama, sijil yang diperbaharui pada cakera tidak mengubah apa-apa sehingga pelayan web memuat semula sijil tersebut, jadi pasangkan deploy hook seperti yang diterangkan dalam panduan nginx dan Apache. Kedua, jaga keselamatan fail kredensial: sesiapa yang boleh membacanya boleh mengubah zon DNS anda, yang memadai untuk mengalih hala e-mel atau melepasi cabaran DNS-01 mereka sendiri. Simpan fail tersebut pada mode 600 di bawah /root, hadkan token kepada satu zon, dan tukar token tersebut jika anda mengesyaki berlaku kebocoran.

Apabila anda tidak memerlukan wildcard

Wildcard adalah alat yang sesuai untuk banyak subdomain, atau untuk subdomain yang tidak dapat anda ramalkan. Ia bukan pilihan lalai yang betul untuk perkara lain.

• Satu subdomain, atau beberapa subdomain yang diketahui: sijil SAN (subject alternative name) biasa adalah lebih ringkas. certbot --nginx -d example.com -d www.example.com -d app.example.com menyokong sehingga 100 nama melalui HTTP-01, dan tiada kredensial DNS API disimpan pada pelayan.
• Wildcard memadankan tepat satu label. *.example.com tidak merangkumi example.com, sebab itulah arahan di atas meminta kedua-duanya, dan ia juga tidak merangkumi a.b.example.com; itu memerlukan *.b.example.com.
• Satu kunci peribadi digunakan untuk setiap subdomain. Jika mesin yang menyimpannya diceroboh, setiap nama yang dilindungi oleh wildcard akan terjejas secara serentak.
• Jika Traefik menguruskan TLS (transport layer security) untuk kontena anda, anda tidak memerlukan Certbot sama sekali: Traefik meminta sijil wildcard sendiri melalui DNS-01, menggunakan jenis token pembekal yang sama.

Kegunaan sebenar wildcard: subdomain bagi setiap pelanggan atau setiap aplikasi yang dicipta lebih pantas daripada kemampuan anda untuk mengeluarkan semula sijil, dan hos dalaman tanpa port 80 awam, seperti perkhidmatan yang hanya boleh dicapai melalui VPN WireGuard. DNS-01 tidak pernah menyambung ke hos yang disahkan, jadi mesin yang benar-benar peribadi pun boleh memegang sijil yang dipercayai secara awam.

FAQ

Bolehkah Certbot mengeluarkan sijil wildcard dengan HTTP-01?

Tidak. HTTP-01 membuktikan kawalan ke atas satu nama hos, kerana pelayan pengesahan mengambil fail token daripada nama tepat tersebut. Wildcard merangkumi setiap nama di bawah domain, maka Let's Encrypt memerlukan cabaran DNS-01 untuknya, manakala pengesah --nginx, --apache, --webroot dan --standalone semuanya berasaskan HTTP. Satu-satunya cara adalah rekod TXT pada _acme-challenge.example.com, yang diletakkan secara manual atau melalui plugin DNS.

Adakah sijil wildcard merangkumi domain akar?

Tidak. Wildcard hanya sepadan dengan satu label, jadi *.example.com merangkumi www.example.com tetapi bukan example.com yang kosong, dan bukan juga a.b.example.com. Mohon kedua-dua nama pada satu sijil dengan -d example.com -d '*.example.com'. Ini akan mencipta dua cabaran, dan kedua-dua rekod TXT berada pada nama _acme-challenge.example.com yang sama, jadi tambah rekod kedua tanpa memadam rekod pertama.

Mengapa sijil wildcard saya tidak diperbaharui secara automatik?

Kerana ia dikeluarkan dengan --manual. Setiap pembaharuan memerlukan nilai TXT yang baharu, dan pemasa automatik tidak mempunyai cara untuk menampal nilai tersebut, maka pembaharuan terhenti dengan ralat An authentication script must be provided with --manual-auth-hook when using the manual plugin non-interactively. Keluarkan semula sijil dengan plugin DNS seperti certbot-dns-cloudflare, atau sediakan skrip --manual-auth-hook dan --manual-cleanup-hook yang mengedit rekod melalui API pembekal anda.

Berapa lamakah rekod TXT _acme-challenge mengambil masa untuk muncul?

Ia bergantung pada pembekal DNS anda: antara beberapa saat hingga beberapa minit. Pengesahan membaca pelayan berautoriti zon anda, jadi semak dengan dig +short TXT _acme-challenge.example.com @1.1.1.1 dan tunggu sehingga nilai yang dijangka muncul sebelum meneruskan proses manual. Dengan plugin, tingkatkan masa menunggu terbina melalui pilihan penyebaran plugin, contohnya --dns-cloudflare-propagation-seconds 60, jika pengesahan melaporkan bahawa rekod tidak ditemui.

Adakah sijil wildcard kurang selamat berbanding sijil biasa?

Kriptografinya adalah sama. Perbezaannya adalah dari segi operasi: satu kunci peribadi merangkumi setiap subdomain, jadi pencerobohan akan memberi kesan yang lebih luas, dan kredensial API DNS yang diperlukan oleh automasi itu sendiri adalah rahsia sensitif yang disimpan pada pelayan. Jika anda hanya menjalankan beberapa subdomain yang diketahui, sijil SAN mengelakkan kedua-dua kebimbangan ini, iaitu keadaan di mana panduan ini menyarankan agar anda tidak menggunakan wildcard.