AdGuard Home 内置 DHCP 服务器测试指南VirtualBox 隔离网络与 DHCPTest 快速验证全流程【免费下载链接】AdGuardHomeNetwork-wide ads trackers blocking DNS server项目地址: https://gitcode.com/gh_mirrors/ad/AdGuardHomeAdGuard Home 不仅是网络级 DNS 广告拦截器还内置了支持 IPv4/IPv6 的 DHCP 服务器可在同一台设备上完成地址分配与 DNS 解析的联动。本文以仓库中 internal/dhcpd/README.md 为骨架完整讲解两套经过验证的测试方案——基于 VirtualBox Host-Only 网络的隔离环境测试以及基于 DHCPTest 工具的 DISCOVER-OFFER 报文级快速验证并结合internal/dhcpd包源码逐项剖析AdGuardHome.yaml中 DHCP 配置参数的含义与生效机制。读完本文你将能够独立搭建 DHCP 测试环境、编写可运行的配置并理解 DHCPv4/DHCPv6 消息处理与租约分配的底层实现。DHCP 服务器在 AdGuard Home 中的定位AdGuard Home 的 DHCP 服务器由 internal/dhcpd 包实现它同时管理 DHCPv4 与 DHCPv6 两套服务并对外暴露一组/control/dhcp/*的 HTTP API注册于 http_unix.go。从 dhcpd.go 的Create函数可以看到服务启动时会同时创建 v4 与 v6 两个子服务dhcpd.go若两者均未启用则会报错neither dhcpv4 nor dhcpv6 srv is configured。值得强调的是DHCP 服务与 DNS 功能是深度联动的DHCP 分配的租约含主机名会回写到 DNS 解析层例如通过HostByIP、IPByHost接口实现「主机名 → IP」的反查从而让局域网内设备可以通过myhost.lan这样的本地域名被解析对应配置项local_domain_name见 config.go。这解释了为什么测试时看到dhcpv4: listening日志意味着整套服务链路已经就绪。测试方案一VirtualBox 隔离网络环境在真实局域网中测试 DHCP 会干扰其他设备使用 VirtualBox 的 Host-Only仅主机网络可以构造一个与外部完全隔离、可随意刷新的实验网络。这也是 README 推荐的正式测试路径。前置条件一台运行 Linux 的 AdGuard Home 主机虚拟机亦可已安装 VirtualBox一台客户机虚拟机guest OS 不限Linux/Windows 均可。配置 VirtualBox创建 Host-Only 网络。安装 VirtualBox 后执行VBoxManage hostonlyif create该命令会创建一个名为vboxnet0通常如此的虚拟网卡。可用ip a命令确认其状态与 IP默认网段通常为192.168.56.0/24。也可以在图形界面完成同样的操作File → Host Network Manager中新建 Host-Only 网络。将虚拟机接入该网络在VM Settings → Network → Host-only Adapter中选择刚创建的 Host-Only 适配器。启动虚拟机并安装操作系统将客户机的网络接口配置为「使用 DHCP 自动获取 IP」。客户机启动后便会向网络中的 DHCP 服务器发送请求。查看客户机当前 IPLinux 上执行ip aWindows 上执行ipconfig。强制客户机重新申请地址Linux 上使用dhclient如dhclient -r dhclient或按发行版使用systemctl restart networkingWindows 上使用ipconfig /release后再ipconfig /renew。这一操作可用于反复验证租约分配与续租流程。配置 AdGuard Home 服务器端编辑 AdGuard Home 的配置文件AdGuardHome.yaml写入以下 DHCP 配置块这是 README 给出的完整示例网段与上一步的vboxnet0默认网段对应dhcp: enabled: true interface_name: vboxnet0 local_domain_name: lan dhcpv4: gateway_ip: 192.168.56.1 subnet_mask: 255.255.255.0 range_start: 192.168.56.2 range_end: 192.168.56.2 lease_duration: 86400 icmp_timeout_msec: 1000 options: [] dhcpv6: range_start: 2001::1 lease_duration: 86400 ra_slaac_only: false ra_allow_slaac: false注意示例中range_start与range_end均为192.168.56.2即地址池只有一个地址适合单客户机的最小验证生产环境应给出连续地址段。启动服务器并验证./AdGuardHome -v-v为 verbose 日志模式。当 DHCP 服务成功绑定网卡并开始监听时日志中会出现 README 指定的标志性输出[info] dhcpv4: listening对应日志在源码中位于 v4_unix.golog.Info(dhcpv4: listening)其前提是配置中dhcpv4已启用且配置校验通过指定的interface_name存在于系统中net.InterfaceByName见 v4_unix.go网卡上存在可用的 IPv4 地址aghnet.IfaceDNSIPAddrs见 v4_unix.go该地址随后会被用作返回给客户端的 DNS 服务器地址。随后在客户机上执行ip aLinux或ipconfigWindows应能看到从地址池192.168.56.2分配的 IP以及下发的网关、子网掩码、DNS 等参数。测试方案二DHCPTest 工具快速验证如果只是想在协议报文层面快速确认 DHCP 服务是否工作可以使用社区通用的 DHCPTest 测试工具CyberShadow/dhcptest。该工具可向目标 DHCP 服务器发送模拟的 DHCPDISCOVER 报文并观察是否收到 DHCPOFFER 响应。前置条件获取 DHCPTest 测试工具dhcptest并确保其可执行。执行快速测试README 指出DHCP 服务器可以在交互式interactive模式下测试 DISCOVER-OFFER 报文交换。具体做法是确认 AdGuard Home 的 DHCP 服务已启动参考上文日志验证在另一台与 DHCP 服务器处于同一网段的机器上运行 DHCPTest观察工具输出正常情况下服务器应回以 DHCPOFFER 报文其中携带建议的 IP 地址、租约时长等选项对应源码中handleDiscover里resp.UpdateOption(dhcpv4.OptMessageType(dhcpv4.MessageTypeOffer))的分支见 v4_unix.go。该方案适合在 CI、脚本或无法启动完整虚拟机时做冒烟测试只要 DISCOVER 能拿到 OFFER就说明 UDP 端口 67 监听、租约分配逻辑与配置校验均已正常工作。配置参数深度解析README 给出的 YAML 示例覆盖了 DHCP 的全部核心配置项。结合 config.go 中的结构体定义可以逐项理解其语义与源码级影响。顶层dhcp配置参数类型默认行为说明enabledboolfalse总开关。dhcpd.go的Create中若总开关关闭但任一子服务未启用会直接报错interface_namestring—监听网卡名如vboxnet0、eth0。服务启动时按此名称查找网卡见 v4_unix.golocal_domain_namestring—本地域名后缀。例如客户端主机名myhost配合lan可解析为myhost.lan见 config.godhcpv4配置对应V4ServerConf见 config.go参数类型默认值说明gateway_ipIPv4—网关地址。Validate会以它与subnet_mask计算子网前缀与广播地址aghnet.BroadcastFromPref见 config.gosubnet_maskIPv4—子网掩码如255.255.255.0用于计算分配子网范围range_start/range_endIPv4—动态租约地址池的首末地址。校验规则网关 IP 不得落在地址池内且地址池必须完全位于子网内否则报错见 config.golease_durationuint32秒864001 天租约时长。配置为 0 时使用默认值见 v4_unix.go 与DefaultDHCPLeaseTTLdhcpd.goicmp_timeout_msecuint32毫秒1000IP 冲突检测分配地址前向目标发 ICMP 探测超时内无回包才认为地址可用设为 0 关闭检测。见addrAvailablev4_unix.go与DefaultDHCPTimeoutICMPdhcpd.gooptionsstring 数组[]自定义 DHCPv4 选项。支持两种语法DEC_CODE hex HEX_DATA任意十六进制数据与DEC_CODE ip IP_ADDRIP 数据仅支持单 IP见 config.godhcpv6配置对应V6ServerConf见 config.go参数类型默认值说明range_startIPv6—动态租约起始地址最后一个允许的地址以0xff字节结尾即地址范围从range_start到同前缀末位0xff判定逻辑见ip6InRangev6_unix.golease_durationuint32秒86400租约时长为 0 时使用默认值v6_unix.gora_slaac_onlyboolfalse仅发送无 M/O 标志的 ICMPv6 路由器通告RA强制客户端使用 SLAAC 而非 DHCPv6 分配地址为 true 时 DHCPv6 服务本身不会启动见 v6_unix.gora_allow_slaacboolfalse在 RA 报文中携带 M/O 标志允许 SLAAC 与 DHCPv6 并存此外DHCPv6 服务会通过configureDNSIPAddrs获取网卡上的 IPv6 地址作为下发给客户端的 DNS 服务器v6_unix.go并初始化 RA 模块周期性发送路由器通告ra.packetSendPeriod 1 * time.Second见 v6_unix.go。底层机制租约分配与消息处理理解测试结果的正确性还需要知道 DHCP 服务内部如何工作。DHCPv4 消息流。packetHandler接受 DISCOVER、REQUEST、DECLINE、RELEASE 四类报文v4_unix.go其中 REQUEST 会根据是否携带 server identifier 选项自动区分 SELECTING、INIT-REBOOT、RENEWING/REBINDING 三种客户端状态handleByRequestType见 v4_unix.go。分配地址时先通过位图leasedOffsets在地址池内找空闲地址池满则回收最早过期的动态租约reserveLease见 v4_unix.go随后用 ICMP 冲突检测addrAvailable确认地址确实空闲。DHCPv6 消息流。对应process与packetHandlerv6_unix.go处理 Solicit/Request/Confirm/Renew/Rebind/Release 等消息校验 ClientID、ServerID 策略与 IA 地址并返回含 IA_NA、DNS 服务器与状态码的 Reply支持 Rapid Commit 快速提交。测试时可重点观察这些日志以-v运行时默认开启 debug 级 DHCP 日志。租约持久化与静态租约。租约数据库保存在工作目录下的文件中dbFilePath由DataDir拼接而来见 dhcpd.go服务启动时加载dbLoad租约变更时通过notify回调触发落盘。除动态租约外还支持静态租约MAC 与 IP 绑定相关操作可经由 HTTP API 完成。通过 HTTP API 进一步验证除日志与客户端观察外仓库还提供了一组 REST 端点注册于 http_unix.go用于交互式验证方法与路径用途GET /control/dhcp/status查询 DHCP 服务状态与当前租约GET /control/dhcp/interfaces列出可用网卡及地址便于确认interface_namePOST /control/dhcp/set_config动态修改并重启 DHCP 配置POST /control/dhcp/find_active_dhcp探测指定网卡上是否已存在其他 DHCP 服务器POST /control/dhcp/add_static_lease添加静态租约POST /control/dhcp/remove_static_lease移除静态租约POST /control/dhcp/update_static_lease更新静态租约POST /control/dhcp/reset/reset_leases停止服务 / 重置租约例如测试时若客户机迟迟拿不到地址可先调用find_active_dhcp检查网段内是否已有别的 DHCP 服务抢占再通过status查看当前租约表是否已有分配记录。测试中的常见问题与排查建议日志未出现dhcpv4: listening优先确认interface_name拼写与ip a输出一致检查gateway_ip是否落入地址池源码会直接报错拒绝启动确认 v4/v6 至少启用其一否则Create会返回neither dhcpv4 nor dhcpv6 srv is configured。客户机拿不到地址在客户机上使用dhclientLinux或ipconfig /release后ipconfig /renewWindows强制重新申请确认虚拟网卡确实接入了 Host-Only 网络而非 NAT。地址池只有一个地址README 的最小示例range_start与range_end相同多台客户机同时测试时会被视为地址耗尽源码日志dhcpv4: no more ip addresses见 v4_unix.go请按需扩大范围。IPv6 场景若使用 SLAAC 优先的网络注意ra_slaac_only为 true 时 DHCPv6 不会监听v6_unix.go此时地址由无状态 SLAAC 分配属预期行为。以上两个测试方案与配置示例均来自 internal/dhcpd/README.md其背后的参数校验、地址分配与消息处理逻辑可在 config.go、dhcpd.go、v4_unix.go 与 v6_unix.go 中逐行验证。【免费下载链接】AdGuardHomeNetwork-wide ads trackers blocking DNS server项目地址: https://gitcode.com/gh_mirrors/ad/AdGuardHome创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考