ridgarou/acme-dns

acme-dns

基于 https://hub.docker.com/r/joohoi/acme-dns 镜像构建，适用于 linux/arm/v7 架构。


概述

acme-dns是一个简化的DNS服务器，提供RESTful HTTP API，用于简单地自动化ACME DNS挑战验证过程。

为什么使用acme-dns

许多DNS服务器不提供API来实现ACME DNS挑战的自动化。那些提供API的服务器通常赋予密钥过多权限，而将这些密钥存放在各种设备上是实现有意义的流程自动化的常见要求。

acme-dns提供专门用于TXT记录更新的简单API，应与ACME专用的"_acme-challenge"子域CNAME记录一起使用。这样，即使API密钥不幸泄露，影响也仅限于相关的子域TXT记录。

因此，acme-dns的核心价值在于可访问性和安全性。

有关底层问题和其他解决方案的详细说明，请参阅EFF deeplinks博客上的相关文章：[***]

特性

• 简化的DNS服务器，专门处理ACME DNS挑战(TXT记录)
• 支持自定义记录（可提供所需的A、AAAA、NS等记录）
• HTTP API自动获取和使用Let's Encrypt TLS证书
• 限制/update API端点访问到特定的CIDR掩码（在/register请求中定义）
• 支持SQLite和PostgreSQL作为数据库后端
• 支持两个TXT记录的滚动更新，能够同时应答针对yourdomain.tld和*.yourdomain.tld证书的挑战
• 部署简单（基于Go语言开发）

使用方法

acme-dns的Certbot认证钩子可在以下位置获取：https://github.com/joohoi/acme-dns-certbot%E3%80%82

![asciicast]([***]

使用acme-dns分为三个步骤（假设您已设置好自托管服务器）：

1. 获取凭据和唯一子域（向例如[***]
2. 在现有DNS区域中创建指向注册获得的子域的CNAME记录（例如：_acme-challenge.domainiwantcertfor.tld. CNAME a097455b-52cc-4569-90c8-7a4b97c6eba8.auth.example.org）
3. 使用凭据向acme-dns服务器POST新的DNS挑战值，供CA验证
4. 设置定时任务，之后无需人工干预

API

注册端点

该方法返回新的唯一子域和更新记录所需的凭据。fulldomain是您可以将自己的_acme-challenge子域CNAME记录指向的地址。使用这些凭据，您可以更新服务中的TXT响应以匹配挑战令牌（CA提供的___validation_token_received_from_the_ca___）。

可选：您可以POST JSON数据来限制/update请求到预定义的源网络（使用CIDR表示法）。

POST /register

可选示例输入

json
{
    "allowfrom": [
        "192.168.100.1/24",
        "1.2.3.4/32",
        "2002:c0a8:2a00::0/40"
    ]
}

响应

Status: 201 Created

json
{
    "allowfrom": [
        "192.168.100.1/24",
        "1.2.3.4/32",
        "2002:c0a8:2a00::0/40"
    ],
    "fulldomain": "8e5700ea-a4bf-41c7-8a77-e990661dcc6a.auth.acme-dns.io",
    "password": "htB9mR9DYgcu9bX_afHF62erXaH2TS7bg9KW3F7Z",
    "subdomain": "8e5700ea-a4bf-41c7-8a77-e990661dcc6a",
    "username": "c36f50e8-4632-44f0-83fe-e070fef28a10"
}

更新端点

该方法允许您更新唯一子域的TXT记录内容。通常由自动化ACME客户端执行。

POST /update

必需请求头

示例输入

json
{
    "subdomain": "8e5700ea-a4bf-41c7-8a77-e990661dcc6a",
    "txt": "___validation_token_received_from_the_ca___"
}

响应

Status: 200 OK

json
{
    "txt": "___validation_token_received_from_the_ca___"
}

健康检查端点

该方法可用于检查服务器的就绪状态和/或存活状态。成功时返回状态码200，否则无法访问。

GET /health

自托管

建议运行自己的acme-dns实例，因为您实际上是授权acme-dns服务器代表您提供对CA挑战的应答，使该实例能够请求（并获得）指向它的CNAME域的TLS证书。

有关如何执行此操作的信息，请参见安装部分。

安装

使用Docker

1. 拉取最新的acme-dns Docker镜像：docker pull joohoi/acme-dns

2. 创建目录：config用于配置文件，data用于sqlite3数据库

3. 将https://raw.githubusercontent.com/joohoi/acme-dns/master/config.cfg%E5%A4%8D%E5%88%B6%E5%88%B0%60config/config.cfg%60

4. 修改config.cfg以满足您的需求

5. 运行Docker（假设配置文件中设置了port = "80"）：

bash
docker run --rm --name acmedns                 \
 -p 53:53                                      \
 -p 53:53/udp                                  \
 -p 80:80                                      \
 -v /path/to/your/config:/etc/acme-dns:ro      \
 -v /path/to/your/data:/var/lib/acme-dns       \
 -d joohoi/acme-dns

Docker Compose

1. 创建目录：config用于配置文件，data用于sqlite3数据库

2. 将https://raw.githubusercontent.com/joohoi/acme-dns/master/config.cfg%E5%A4%8D%E5%88%B6%E5%88%B0%60config/config.cfg%60

3. 复制项目的https://raw.githubusercontent.com/joohoi/acme-dns/master/docker-compose.yml%E6%88%96%E5%88%9B%E5%BB%BA%E6%82%A8%E8%87%AA%E5%B7%B1%E7%9A%84

4. 编辑config/config.cfg和docker-compose.yml以满足您的需求，然后运行docker-compose up -d

DNS记录

注意：本文档中：

• auth.example.org是acme-dns服务器的主机名
• acme-dns将提供*.auth.example.org记录
• 198.51.100.1是运行acme-dns的系统的公共IP地址

这些值应根据您的环境进行更改。

您需要在域名的常规DNS服务器上添加一些DNS记录：

• auth.example.org的NS记录指向auth.example.org（这意味着auth.example.org负责所有*.auth.example.org记录）
• auth.example.org的A记录指向198.51.100.1
• 如果使用IPv6，添加指向IPv6地址的AAAA记录
• 每个要认证的域都需要添加_acme-challenge CNAME子域。您使用的客户端将说明如何执行此操作

测试

在用于实际查询之前，您可能需要测试acme-dns是否正常工作。

1. 确认acme-dns子域的DNS查找按预期工作：dig auth.example.org

2. 调用/register API端点注册测试域：

bash
$ curl -X POST http://auth.example.org/register
{"username":"eabcdb41-d89f-4580-826f-3e62e9755ef2","password":"pbAXVjlIOE01xbut7YnAbkhMQIkcwoHO0ek2j4Q0","fulldomain":"d420c923-bbd7-4056-ab64-c3ca54c9b3cf.auth.example.org","subdomain":"d420c923-bbd7-4056-ab64-c3ca54c9b3cf","allowfrom":[]}

3. 调用/update API端点设置测试TXT记录。传递从上面执行的register调用收到的username、password和subdomain：

bash
$ curl -X POST \
  -H "X-Api-User: eabcdb41-d89f-4580-826f-3e62e9755ef2" \
  -H "X-Api-Key: pbAXVjlIOE01xbut7YnAbkhMQIkcwoHO0ek2j4Q0" \
  -d '{"subdomain": "d420c923-bbd7-4056-ab64-c3ca54c9b3cf", "txt": "___validation_token_received_from_the_ca___"}' \
  http://auth.example.org/update

注意：txt字段必须正好43个字符，否则acme-dns将拒绝它

4. 对测试子域执行DNS查找，确认更新的TXT记录正在提供：

bash
$ dig -t txt @auth.example.org d420c923-bbd7-4056-ab64-c3ca54c9b3cf.auth.example.org

配置

bash
[general]
# DNS接口。注意systemd-resolved可能在127.0.0.53上保留端口53
# 在这种情况下，acme-dns将出错，您需要定义监听接口
# 例如：listen = "127.0.0.1:53"
listen = "127.0.0.1:53"
# 协议，"both", "both4", "both6", "udp", "udp4", "udp6" 或 "tcp", "tcp4", "tcp6"
protocol = "both"
# 提供请求的域名
domain = "auth.example.org"
# 区域名称服务器
nsname = "auth.example.org"
# 管理员电子邮件地址，@替换为.
nsadmin = "admin.example.org"
# 除TXT外提供的预定义记录
records = [
    # 指向acme-dns服务器公共IP的域
    "auth.example.org. A 198.51.100.1",
    # 指定auth.example.org将解析任何*.auth.example.org记录
    "auth.example.org. NS auth.example.org.",
]
# CORS等的调试消息
debug = false

[database]
# 使用的数据库引擎，sqlite3或postgres
engine = "sqlite3"
# 连接字符串，sqlite3的文件名为postgres://$username:$password@$host/$db_name
# 请注意，默认Docker镜像使用路径/var/lib/acme-dns/acme-dns.db作为sqlite3
connection = "/var/lib/acme-dns/acme-dns.db"
# connection = "postgres://user:password@localhost/acmedns_db"

[api]
# 监听IP，例如127.0.0.1
ip = "0.0.0.0"
# 禁用注册端点
disable_registration = false
# 监听端口，例如443为默认HTTPS
port = "443"
# 可能的值："letsencrypt", "letsencryptstaging", "cert", "none"
tls = "letsencryptstaging"
# 仅当tls = "cert"时使用
tls_cert_privkey = "/etc/tls/example.org/privkey.pem"
tls_cert_fullchain = "/etc/tls/example.org/fullchain.pem"
# 仅当tls = "letsencrypt"时使用
acme_cache_dir = "api-certs"
# CORS AllowOrigins，可以使用通配符
corsorigins = [
    "*"
]
# 使用HTTP头获取客户端IP
use_header = false
# 用于提取IP地址/ IP地址列表的头名称
header_name = "X-Forwarded-For"

[logconfig]
# 日志级别："error", "warning", "info" 或 "debug"
loglevel = "debug"
# 可能的值：stdout, TODO file & integrations
logtype = "stdout"
# 日志文件路径 TODO
# logfile = "./acme-dns.log"
# 格式，"json"或"text"
logformat = "text"

HTTPS API

RESTful acme-dns API可以通过两种方式通过HTTPS公开：

1. 使用tls = "letsencrypt"并让acme-dns自动使用Let's Encrypt颁发自己的证书
2. 使用tls = "cert"并提供您自己的HTTPS证书链和私钥，通过tls_cert_fullchain和tls_cert_privkey

在可能的情况下，推荐第一种选择。这是让acme-dns通过HTTPS公开其API的最简单和最安全的方式。

警告：如果您选择使用tls = "cert"，则必须注意证书不会过期！如果过期，并且您用于颁发证书的ACME客户端依赖ACME DNS API来更新TXT记录，您将陷入API证书已过期但无法续订的困境，因为ACME客户端将拒绝连接到续订所需的ACME DNS API。

客户端

• acme.sh: https://github.com/Neilpang/acme.sh
• Certify The Web: https://github.com/webprofusion/certify
• cert-manager: https://github.com/jetstack/cert-manager
• Lego: https://github.com/xenolf/lego
• Posh-ACME: https://github.com/rmbolger/Posh-ACME
• Sewer: https://github.com/komuw/sewer
• Traefik: https://github.com/containous/traefik
• Windows ACME Simple (WACS): [***]

认证钩子

• Python编写的Certbot认证钩子: https://github.com/joohoi/acme-dns-certbot-joohoi
• Go编写的Certbot认证钩子: https://github.com/koesie10/acme-dns-certbot-hook

库

• Python通用客户端库 (PyPI): https://github.com/joohoi/pyacmedns
• Go通用客户端库: [https://github.com/cpu/goacmedns%5D(https://github.com/cpu/go