moonbuggy2000/dnsmasq-updater

Docker Dnsmasq Updater

自动使用Docker容器主机名更新本地或远程hosts文件。

• 基本原理
• 功能说明
• 设置指南
  • Docker容器安装
    • 镜像标签
    • 独立部署
    • 独立DNS服务器部署
    • Swarm部署
  • dnsmasq服务器设置
  • 其他Docker容器设置
  • 与Traefik配合使用
• 已知问题
• 链接

基本原理

如果您的局域网中路由器使用dnsmasq作为本地DNS，可能会频繁更新hosts文件以添加或删除Docker容器。当前可用的自动化方案通常要求将Docker容器放在子域中（如*.docker.local），或者如果要将容器保留在顶级域（如*.local），则需要在路由器上安装完整的名称服务器并与Docker主机上的容器同步。

Docker Dnsmasq Updater无需增加路由器的复杂性或资源需求，即可自动添加或删除主机名。它可以作为独立脚本运行、在容器中运行，只需访问Docker套接字和路由器（或任何提供带有hosts文件的本地DNS的设备）的SSH访问权限。

此脚本专为[AsusWRT-Merlin][]/[Entware][]路由器设计，但应适用于任何运行dnsmasq或使用hosts文件的设备。

功能说明

• 可在Docker主机、容器内或任何位置运行（管理模式）
• 加载时，扫描所有运行中的容器以查找dnsmasq.updater.enable标签
• 可选，加载时扫描指定的Docker网络以查找运行中的容器
• 加载后，监控Docker套接字以检测容器启动/停止，可选监控容器连接/断开指定Docker网络
• 查找符合条件的容器的所有主机名
• 写入hosts文件
• 重启dnsmasq守护进程

设置指南

Docker容器安装

镜像标签

默认latest标签和script标签指向standalone/manager脚本。Agent镜像标签为agent。

server标签提供安装并配置了dnsmasq的standalone/manager脚本容器，可直接提供Docker主机名的DNS服务。

标签可前缀<version>-以获取特定版本，或直接使用版本号获取<version>-script。

[!NOTE] 升级Nuitka版本后，二进制构建目前比未编译镜像大。此外，构建gunicorn（用于manager镜像中的API后端）存在问题，我尚未费心调查。

因此，至少目前，我已停止binary构建。构建系统仍能构建它们，将来可能会再次开始，但不是现在。

架构

主要的latest、<version>、script、agent和server标签应自动提供与amd64、arm/armv7、armhf/armv6、arm64、386、ppc64le和s390x平台兼容的镜像。特定单一架构镜像的标签不再推送到Docker Hub。

[!NOTE] 我只能在amd64、armv7和arm64上测试。这些架构的镜像目前可正常工作。我假设它们也适用于其他架构，但不保证。

独立部署

sh
docker run -d \
  --name dnsmasq-updater \
  -v /var/run/docker.sock:/var/run/docker.sock \
  moonbuggy2000/dnsmasq-updater

如果使用配置文件而非环境变量（见下文），需通过-v <主机路径>:/app/conf/dnsmasq_updater.conf挂载配置文件。如果使用SSH密钥认证，可挂载并使用/app/keys/目录。

独立DNS服务器部署

server标签镜像安装了dnsmasq，并配置Docker Dnsmasq Updater更新其配置。这些镜像提供开箱即用的DNS服务器，自动填充符合Updater配置条件的Docker主机名。

server镜像包含Docker Dnsmasq Updater的standalone/manager版本，并继承其配置选项，同时提供一些dnsmasq的额外选项。最小配置示例如下：

yaml
version: '3.7'

services:
  dmu-server:
    image: moonbuggy2000/dnsmasq-updater:server
    hostname: dmu-dns-server
    environment:
      - DMU_DOMAIN=docker  # 可选，默认值
      - DMU_IP=<frontend_IP>
      - DMU_NETWORK=traefik  # 可选
      - DMU_LABELS_FROM=traefik  # 可选
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    ports:
      - 53:53/tcp
      - 53:53/udp
    networks:  # 可选
      - traefik

networks:  # 可选
  traefik:
    external: true

此compose文件假设存在预先创建的Traefik网络，但可使用任何网络。如果使用容器标签选择要更新主机名的容器，DMU_NETWORK和网络配置可完全省略。

要自定义dnsmasq配置，可挂载/etc/dnsmasq.d/目录并添加额外的*.conf文件。不要直接编辑/etc/dnsmasq.conf，初始化系统会在启动时写入该文件，修改可能被覆盖。

Swarm部署

docker-compose.yml

yaml
version: '3.7'

services:
  dnsmasq-updater:
    image: moonbuggy2000/dnsmasq-updater:script
    hostname: dmu
    deploy:
      mode: replicated
      replicas: 1
      placement:
        constraints:
          # 使用标签选择特定Swarm节点作为管理器
          # 确保/app/keys卷存在
          - node.labels.dnsmasq-updater.manager == true
    environment:
      - DMU_DEBUG=false
      - DMU_MODE=manager
      - DMU_DOMAIN=swarm
      - DMU_IP=<frontend_IP>
      - DMU_KEY=/app/keys/id_rsa
      - DMU_LOGIN=<login>
      - DMU_PREPEND_WWW=true  # 可选
      - DMU_HOSTS_FILE=/opt/etc/hosts.swarm
      - DMU_SERVER=<dnsmasq_server_IP>
      - DMU_API_PORT=8080
      - DMU_API_KEY=<api_key>
    volumes:
      - dnsmasq-updater_keys:/app/keys
    networks:
      - traefik

  dnsmasq-updater-agent:
    image: moonbuggy2000/dnsmasq-updater:agent
    deploy:
      mode: global
    environment:
      - DMU_DEBUG=false  # 可选
      - DMU_NETWORK=traefik  # 可选
      - DMU_API_SERVER=dmu
      - DMU_API_PORT=8080
      - DMU_API_KEY=<api_key>
      - DMU_LABELS_FROM=traefik  # 可选
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    networks:
      - traefik

  # 测试单个在traefik前端后的间接暴露容器
  whoami-frontend:
    image: traefik/whoami:latest
    hostname: whoami-frontend
    deploy:
      mode: replicated
      replicas: 1
      labels:
        - traefik.enable=true
        - traefik.http.routers.whoami-frontend.rule=Host(`whoami-frontend.swarm`)
        - traefik.http.routers.whoami-frontend.entryPoints=http,https
        - traefik.http.services.whoami-frontend.loadbalancer.server.port=80
    labels:
      - dnsmasq.updater.enable=true # 可省略，我们在DMU_NETWORK上
      - dnsmasq.updater.host=whoami-frontend.swarm # 可省略，由'hostname'和traefik设置
      - dnsmasq.updater.ip=<frontend_IP> # 可省略，默认使用DMU_IP
    networks:
      - traefik

  # 假设dnsmasq端无限制，测试全局部署且直接暴露服务的轮询DNS
  whoami-global:
    image: traefik/whoami:latest
    hostname: whoami-global
    deploy:
      mode: global
    ports:
      - 8888:80
    labels:
      - dnsmasq.updater.enable=true
      - dnsmasq.updater.host=whoami-global.swarm # 可省略，由'hostname'设置
      - dnsmasq.updater.ip=host # 覆盖默认值，使用节点IP

volumes:
  dnsmasq-updater_keys:
    name: dnsmasq-updater_keys

networks:
  traefik:
    external: true

此compose文件假设存在预先创建的Traefik服务和网络，但只有whoami-frontend测试服务包含Traefik特定配置。如果在其他前端测试，可根据需要修改该服务。

Docker Dnsmasq Updater本身不依赖Traefik（或任何特定前端）运行，但在Swarm环境中，假设存在某种入口控制器，将默认IP上的流量路由到节点上的间接暴露服务。

在此例中，所有Agent连接到traefik网络以监控活动，因此将管理器也放在该网络上并用于API通信很方便。

管理器的DMU_IP默认IP应指向前端/反向代理（Traefik或其他）。可通过单个服务上的dnsmasq.updater.ip标签覆盖默认IP。

要满足管理器的约束，需将dnsmasq-updater.manager标签应用到所选节点： docker node update --label-add dnsmasq-updater.manager=true <node>

详见环境变量详细说明。

Agent应允许自由重启，因为设计上遇到各种非致命错误时会退出。这是触发重新初始化并确保管理器在重启或通信中断时获取完整信息的简单方法。

Docker环境变量

几乎所有命令行参数（见使用方法）都可通过环境变量设置。

Docker Dnsmasq Updater环境

• DMU_MODE - 操作模式（接受：standalone、manager；默认：standalone）
• DMU_HOSTS_LOCATION - hosts文件位置（接受：local、remote；默认：remote）
• DMU_IP - DNS记录的默认IP
• DMU_DOMAIN - DNS记录的域/区域（默认：docker）
• DMU_DOCKER_SOCKET - Docker套接字路径（默认：unix://var/run/docker.sock）
• DMU_NETWORK - 要监控的Docker网络，默认无/禁用
• DMU_SERVER - dnsmasq服务器地址
• DMU_PORT - dnsmasq服务器SSH端口（默认：22）
• DMU_LOGIN - dnsmasq服务器登录名
• DMU_PASSWORD - 登录名密码，或密钥解密密码（如果指定密钥）
• DMU_KEY - SSH密钥文件完整路径
• DMU_HOSTS_FILE - dnsmasq服务器上要更新的hosts文件完整路径
• DMU_RESTART_CMD - 重启/更新dnsmasq的命令（默认：service restart_dnsmasq）
• DMU_DELAY - 写入远程hosts文件前的延迟（秒，默认：10）
• DMU_API_ADDRESS - API监听地址（默认：0.0.0.0）
• DMU_API_PORT - API监听端口（默认：8080）
• DMU_API_KEY - API访问密钥
• DMU_LABELS_FROM - 从其他服务的标签添加主机名（仅独立模式，接受：traefik、none；默认：traefik）
• DMU_PREPEND_WWW - 为所有主机名添加www子域（默认：False）
• DMU_DEBUG - 设置为_True_启用调试日志输出
• TZ - 设置时区

Docker Dnsmasq Updater Agent环境

• DMU_DOCKER_SOCKET - Docker套接字路径（默认：unix://var/run/docker.sock）
• DMU_NETWORK - 要监控的Docker网络（默认：无）
• DMU_API_SERVER - API服务器地址
• DMU_API_PORT - API监听端口（默认：8080）
• DMU_API_KEY - API访问密钥
• DMU_API_RETRY - 连接失败后重试延迟（秒，默认：10）
• DMU_API_CHECK - API服务器状态检查间隔（秒，默认：60）
• DMU_CLEAN_ON_EXIT - Agent关闭时从API删除设备主机（默认：True）
• DMU_LABELS_FROM - 从其他服务的标签添加主机名（接受：traefik、none；默认：traefik）
• DMU_DEBUG - 设置为_True_启用调试日志输出
• TZ - 设置时区

Docker Dnsmasq Updater DNS Server环境

除继承Standalone/Manager镜像的环境变量（见上文）外，还有dnsmasq的额外变量：

• DNS_SERVERS - 上游DNS服务器空格分隔列表（默认：1.1.1.1 8.8.8.8）
• DNS_LOG_QUERIES - 设置为_True_启用DNS查询日志输出
• DNS_DEBUG - 设置为_True_启用dnsmasq调试日志输出

DNS Server镜像中预配置了一些环境变量，不应设置或修改：DMU_HOSTS_LOCATION、DMU_HOSTS_FILE、DMU_RESTART_CMD

TZ参数仅用于设置日志消息的时间戳。

dnsmasq服务器设置

Docker Dnsmasq Updater不会跟踪其他软件（如dnsmasq）对hosts文件的更改。因此，为避免冲突，最好为Docker Dnsmasq Updater提供自己的hosts文件，并通过-addn-hosts <file>参数（或在dnsmasq.conf中）指定为dnsmasq的附加hosts文件，或通过其他机制合并到主hosts文件中。

如果dnsmasq服务器是连接了外部存储的路由器，将updater生成的hosts文件保存在外部存储上是合理的，以减少对路由器板载存储的写入。

如果使用密钥而非密码，需将相应公钥添加到路由器的~/.ssh/authorized_keys中（可能通过路由器的WebUI而非shell）。

AsusWRT-Merlin/Entware示例

例如，使用AsusWRT-Merlin/Entware，可通过写入/opt/etc/hosts.docker并将以下内容添加到/jffs/scripts/hosts.postconf，轻松配置路由器包含此外部文件：

sh
# 用于远程hosts更新
if [ -f /opt/etc/hosts.docker ]; then
  cat "/opt/etc/hosts.docker" >> "$CONFIG"
fi

这会将hosts.docker中的主机定义添加到/etc/hosts，便于集中查看所有主机定义。

或者，可通过/jffs/configs/dnsmasq.conf.add实现addn-hosts方法：

sh
addn-hosts=/opt/etc/hosts.docker

这会使dnsmasq直接读取hosts.docker文件。

无论哪种方式，由于dnsmasq可能在/opt挂载前启动，需在/jffs/scripts/post-mount中重启dnsmasq，确保路由器重启后容器名称解析正常：

sh
if [ -d "$1/entware" ] ; then
  ln -nsf $1/entware /tmp/opt
  service restart_dnsmasq
fi

此场景下Docker Dnsmasq Updater的相关配置参数为--remote_file /opt/etc/hosts.docker --restart_cmd 'service restart_dnsmasq'。