Automatické SSL certifikáty přes acme.sh a BEST-HOSTING DNS API

Automatizace vydávání SSL certifikátů je dnes standardem moderní správy webové infrastruktury. Nástroj acme.sh v kombinaci s BEST-HOSTING DNS API umožňuje plně automatické získávání a obnovu SSL/TLS certifikátů - včetně wildcard certifikátů - bez nutnosti jakéhokoli ručního zásahu.

Co je acme.sh?

acme.sh je open-source shell skript implementující protokol ACME (Automatic Certificate Management Environment), který používají certifikační autority jako ZeroSSL, Let's Encrypt a další k automatickému vydávání důvěryhodných SSL/TLS certifikátů zdarma.

acme.sh patří mezi nejrozšířenější ACME klienty na světě - je oblíbený zejména pro svou přenositelnost (nevyžaduje žádné závislosti kromě shellu), jednoduchý způsob instalace a rozsáhlou podporu DNS providerů prostřednictvím tzv. DNS API pluginů.

Co je DNS-01 challenge a proč je důležitá?

Při vydávání SSL certifikátu musí certifikační autorita ověřit, že žadatel skutečně kontroluje danou doménu. Nejběžnějším způsobem je HTTP ověření přes soubor umístěný na webovém serveru. To ale není vždy možné - například u:

• serverů bez veřejného HTTP přístupu (interní aplikace, VPN, mail servery, databázové servery),
• wildcard certifikátů (*.example.com), kde HTTP ověření ze své podstaty nefunguje,
• plně automatizovaných prostředí, kde není žádná webová vrstva.

V těchto případech nastupuje DNS-01 challenge: certifikační autorita místo HTTP souboru ověří existenci speciálního TXT záznamu v DNS zóně dané domény. Celý proces lze plně automatizovat právě prostřednictvím DNS API - acme.sh TXT záznam přes API sám přidá i odstraní.

BEST-HOSTING DNS API a plugin dns_bh

BEST-HOSTING provozuje vlastní REST API pro správu DNS záznamů, primárně navržené pro potřeby DNS-01 challenge při vydávání SSL certifikátů. API umožňuje programově přidávat a mazat TXT záznamy v DNS zónách spravovaných na naší platformě.

Náš plugin dns_bh byl přijat do oficiální distribuce acme.sh, kde je dostupný jako součást standardní instalace. Není tedy třeba nic stahovat ručně - plugin je připraven k použití ihned po instalaci acme.sh.

Co DNS API podporuje?

• Přidání TXT záznamu pro DNS-01 ověření
• Automatické odstranění TXT záznamu po vydání certifikátu
• HTTP Basic autentizaci s volitelnou správou přístupových klíčů přes klientský portál
• Rate limiting pro ochranu API

Pro koho je toto řešení určeno?

Automatizace SSL přes BEST-HOSTING DNS API je vhodná pro každého, kdo:

• spravuje jednu nebo více domén na platformě BEST-HOSTING,
• potřebuje wildcard certifikát pokrývající doménu i všechny její subdomény,
• provozuje servery nebo služby bez veřejného webového přístupu na lokálních IP adresách (interní aplikace, VPN, mail servery, databázové servery),
• chce mít obnovu certifikátů plně automatickou bez nutnosti pravidelné ruční intervence,
• integruje správu certifikátů do vlastních skriptů, CI/CD pipeline nebo konfiguračního managementu (Ansible, Chef, apod.),
• provozuje chytrou domácnost a potřebuje důvěryhodný SSL certifikát pro lokálně běžící služby jako Home Assistant nebo podobné platformy,
• spravuje IoT zařízení a embedded systémy, které komunikují přes HTTPS a vyžadují platný certifikát bez možnosti HTTP ověření,
• hostuje NAS nebo domácí server (Synology, TrueNAS, Proxmox apod.) přístupný přes vlastní doménu na lokální nebo privátní síti,
• provozuje interní firemní nástroje - wiki, monitoring, Gitea, Nextcloud a podobné aplikace - na privátní infrastruktuře bez vystavení do internetu,
• a další zařízení nebo služby, kde je žádoucí provoz přes HTTPS s platným certifikátem, ale HTTP ověření není možné.

Bezpečnost a správa přístupů

Přístup k DNS API je chráněn unikátním párem přihlašovacích údajů (BH_API_USER a BH_API_KEY), které si každý zákazník generuje samostatně v klientském portálu BEST-HOSTING v sekci Profil / REST API.

Doporučujeme:

• API klíč nikdy nesdílet ani nezveřejňovat,
• pokud API klíč již nevyužíváte, smažte jej nebo deaktivujte
• pro automatizaci ukládat přihlašovací údaje jako systémové proměnné prostředí nebo do zabezpečeného úložiště secrets,
• v případě kompromitace klíč okamžitě smazat a vygenerovat nový v klientském portálu.

Jak na to

• Doména, jejíž DNS zóna je spravována na platformě BEST-HOSTING
• Přístup k příkazové řádce serveru (Linux)
• Vygenerované API přihlašovací údaje (BH_API_USER, BH_API_KEY) z klientského portálu

Krok 1 - Instalace acme.sh

curl https://get.acme.sh | sh -s email=vas@email.cz

Po instalaci restartujte shell - nejjednodušeji odhlášením a opětovným přihlášením - nebo spusťte:

source ~/.bashrc

Krok 2 - Nastavení přihlašovacích údajů

export BH_API_USER="váš_api_user"
export BH_API_KEY="váš_api_klíč"

Acme.sh si přihlašovací údaje po prvním úspěšném použití uloží do svého konfiguračního souboru a při obnově nebo vydání nového certifikátu je použije automaticky. Pro trvalé uložení na úrovni shellu je možné přidat tyto řádky i do ~/.bashrc nebo ~/.profile.

Krok 3 - Vydání certifikátu

Certifikát pro jednu doménu:

acme.sh --issue --dns dns_bh -d example.com --dnssleep 120

Wildcard certifikát (doména + všechny subdomény):

acme.sh --issue --dns dns_bh -d example.com -d '*.example.com' --dnssleep 120

Certifikát pro více různých domén najednou (SAN certifikát):

acme.sh --issue --dns dns_bh \
  -d example.com \
  -d '*.example.com' \
  -d example2.cz \
  --dnssleep 120

Parametr --dnssleep zajistí, že acme.sh před ověřením počká na propagaci TXT záznamu v DNS. Hodnota 120 sekund je doporučený bezpečný interval.

Krok 4 - Instalace certifikátu

Po vydání lze instalovat certifikát do cílové aplikace, například pro nginx:

acme.sh --install-cert -d example.com \
  --cert-file /etc/nginx/ssl/example.com.crt \
  --key-file /etc/nginx/ssl/example.com.key \
  --fullchain-file /etc/nginx/ssl/example.com.fullchain.crt \
  --reloadcmd "systemctl reload nginx"

Automatická obnova

acme.sh si po prvním vydání zapamatuje veškeré parametry a certifikát bude automaticky obnovovat přibližně 30 dní před vypršením. Při instalaci acme.sh je automaticky přidán záznam do cronu - obnova probíhá zcela bez zásahu.

Stav automatické obnovy lze kdykoliv zkontrolovat:

acme.sh --list

Notifikace

acme.sh podporuje odesílání notifikací při vydání nebo obnově certifikátu - i v případě selhání. To se hodí zejména u automatizovaných prostředí, kde chcete mít přehled o tom, zda obnova proběhla v pořádku, aniž byste museli cokoliv ručně kontrolovat.

Podporované platformy zahrnují mimo jiné Telegram, Discord, Slack, Matrix, e-mail přes SMTP nebo Pushover. Notifikace se nastavují jednorázově a platí pro všechny certifikáty spravované danou instalací acme.sh.

Discord:

export DISCORD_WEBHOOK_URL="https://discord.com/api/webhooks/..."
acme.sh --set-notify \
  --notify-hook discord \
  --notify-level 2

Telegram:

export TELEGRAM_BOT_APITOKEN="váš_bot_token"
export TELEGRAM_CHAT_ID="váš_chat_id"
acme.sh --set-notify \
  --notify-hook telegram \
  --notify-level 2

Parametr --notify-level určuje, kdy se notifikace odešle:

• 0 - vypnuto
• 1 - pouze při chybě
• 2 - při úspěšné obnově certifikátu nebo při chybě
• 3 - vždy, i když obnova nebyla potřeba - každý den

Další informace

• BEST-HOSTING DNS API dokumentace
• acme.sh oficiální repozitář
• acme.sh wiki dns_bh
• acme.sh dns_bh issues

Máte dotazy nebo potřebujete s nastavením pomoci? Kontaktujte naši technickou podporu.