libcurl 自定义 DNS 服务器:CURLOPT_DNS_SERVERS 完整指南
libcurl 自定义 DNS 服务器:CURLOPT_DNS_SERVERS 完整指南
导读
当应用需要绕过系统默认 DNS 解析路径、切换特定解析器或排查域名解析故障时,libcurl 提供了 CURLOPT_DNS_SERVERS 选项,允许为单个 easy handle 指定一组自定义 DNS 服务器(可带端口)。本文基于 curl 官方文档 CURLOPT_DNS_SERVERS 展开,结合仓库内 setopt.c、asyn-ares.c 等源码实现,完整讲解该选项的语法、调用方式、底层解析流程、前提条件与常见问题,同时覆盖命令行工具 curl 对应的 --dns-servers 参数,帮助读者在需要精细控制 DNS 解析时正确使用这一能力。
一、选项总览
CURLOPT_DNS_SERVERS 用于替换系统默认 DNS 服务器,将域名解析请求定向到应用指定的 DNS 服务器列表。下表汇总了该选项的关键属性(依据 CURLOPT_DNS_SERVERS.md 头部元信息):
| 属性 | 值 |
|---|---|
| 引入版本 | 7.24.0 |
| 适用协议 | 全部(All,DNS 解析是传输层前置步骤) |
| 默认值 | NULL(即使用系统默认解析配置) |
| 取值类型 | char *(以 NUL 结尾的字符串) |
| 底层要求 | libcurl 须以 c-ares 作为解析后端构建 |
| 重复调用 | 最后一次设置覆盖此前值 |
| 重置方式 | 传入 NULL 关闭该功能 |
该选项在 curl_easy_setopt(3) 家族中归属于字符串指针类网络选项,其设置入口位于 lib/setopt.c 的 setopt_cptr_net() 函数:
#ifdef USE_RESOLV_ARES
case CURLOPT_DNS_SERVERS:
return Curl_setstropt(data, STRING_DNS_SERVERS, ptr);
#endif
两个关键点值得注意:
- 该 case 被
#ifdef USE_RESOLV_ARES包裹,意味着只有在编译期启用了 c-ares 解析后端时,该选项才会被注册;否则curl_easy_setopt会返回CURLE_UNKNOWN_OPTION。 - 字符串通过
Curl_setstropt存入内部STRING_DNS_SERVERS槽位,libcurl 会自行拷贝,因此调用方在设置之后无需再保留该字符串(文档 DESCRIPTION 亦明确说明这一点)。
二、语法与取值格式
选项的值是一个逗号分隔的服务器列表,每项格式为:
host[:port][,host[:port]]...
示例:
192.168.1.100,192.168.1.101,3.4.5.6
说明:
- host:DNS 服务器地址,通常为 IPv4 地址;从实现角度看,该字符串最终交给 c-ares 的
ares_set_servers_ports_csv()解析,因此也支持 IPv6 地址字面量等 c-ares 认可的地址形式。 - port:可选。省略时使用默认 DNS 端口 53;指定时以冒号追加,如
192.168.1.100:53。 - 多个服务器之间用英文逗号分隔,libcurl 与 c-ares 会按列表顺序依次尝试。
命令行工具 curl 侧对应的 --dns-servers 参数(docs/cmdline-opts/dns-servers.md)使用同样的语法:
--dns-servers 192.168.0.1,192.168.0.2 $URL
--dns-servers 10.0.0.1:53 $URL
三、完整示例代码
以下示例来自官方文档 CURLOPT_DNS_SERVERS.md 的 EXAMPLE 小节,展示了在一个 easy handle 上同时设置 URL 与自定义 DNS 服务器:
#include <curl/curl.h>
int main(void)
{
CURL *curl = curl_easy_init();
if(curl) {
CURLcode result;
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin");
curl_easy_setopt(curl, CURLOPT_DNS_SERVERS,
"192.168.1.100:53,192.168.1.101");
result = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
}
代码要点:
CURLOPT_DNS_SERVERS的设置在curl_easy_perform()之前完成即可,无需单独初始化解析器。- 第一个服务器
192.168.1.100显式指定了端口 53,第二个192.168.1.101省略端口,两者写法等价。 - 若设置失败(例如 libcurl 未以 c-ares 构建),
curl_easy_setopt返回非CURLE_OK的错误码,示例中通过result承接以便检查。
--libcurl 选项生成的代码同样会包含该设置,仓库 src/config2setopts.c 中有对应映射:
MY_SETOPT_STR(curl, CURLOPT_DNS_SERVERS, config->dns_servers);
四、底层实现:从选项到 c-ares 通道
4.1 前置条件:必须以 c-ares 构建
官方文档 NOTES 明确:该选项要求 libcurl 使用支持此操作的解析后端,c-ares 是唯一满足条件的内置后端。这一点在源码中体现得十分直接:
- lib/setopt.c 中
CURLOPT_DNS_SERVERS仅在USE_RESOLV_ARES宏开启时注册; - lib/vdns/asyn-ares.c 还硬性要求 c-ares 版本不低于 1.16.0:
#if ARES_VERSION < 0x011000
#error "c-ares 1.16.0 or greater required"
#endif
因此,判断当前 libcurl 是否支持该选项,可以检查构建配置中是否包含 c-ares(如 ./configure --enable-ares 或 CMake 的 -DCARES=ON)。
4.2 设置生效时机与调用链
该选项的值并不会在 curl_easy_setopt 调用时立即下发到 c-ares 通道,而是在解析器初始化阶段统一应用。核心逻辑在 lib/vdns/asyn-ares.c 的 async_ares_init():创建 ares channel 之后,依次调用 async_ares_set_dns_servers()、async_ares_set_dns_interface()、async_ares_set_dns_local_ip4()、async_ares_set_dns_local_ip6() 四个设置函数,将用户配置的 DNS 服务器、出口接口、本地 IP 绑定等偏好一次性写入 channel。
async_ares_set_dns_servers() 的实现位于 lib/vdns/asyn-ares.c,其注释说明了两个调用场景:
- 应用通过
CURLOPT_DNS_SERVERS传入新值(或传入 NULL 取消之前设置)时,若已有 channel,需要重建 channel 以使新值生效; - 惰性初始化 channel 时应用已有偏好,此时 NULL 表示无偏好、不重置现有 channel。
函数核心代码如下:
const char *servers = CURL_EASY_STR(data, STRING_DNS_SERVERS);
#ifdef DEBUGBUILD
if(getenv("CURL_DNS_SERVER"))
servers = getenv("CURL_DNS_SERVER");
#endif
if(!servers)
return CURLE_OK;
/* if channel is not there, this is a parameter check */
if(ares && ares->channel)
ares_result = ares_set_servers_ports_csv(ares->channel, servers);
值得注意的实现细节:
- 调试环境变量:在
DEBUGBUILD编译下,环境变量CURL_DNS_SERVER会覆盖代码中设置的值,便于开发者不修改代码即可切换 DNS 服务器进行调试。 - 参数预校验:注释“if channel is not there, this is a parameter check”表明,即使 channel 尚未创建,该函数也会被调用以提前校验服务器字符串的合法性。
4.3 错误码映射
ares_set_servers_ports_csv() 的返回值被逐一映射为 libcurl 错误码(lib/vdns/asyn-ares.c):
| c-ares 返回值 | 含义 | libcurl 错误码 |
|---|---|---|
ARES_SUCCESS |
解析成功 | CURLE_OK (0) |
ARES_ENOMEM |
内存不足 | CURLE_OUT_OF_MEMORY |
ARES_ENOTINITIALIZED / ARES_ENODATA / ARES_EBADSTR |
未初始化 / 无数据 / 服务器字符串格式非法 | CURLE_BAD_FUNCTION_ARGUMENT |
因此,当传入的服务器列表格式错误(如非法 IP、多余分隔符)时,应用会在解析阶段收到 CURLE_BAD_FUNCTION_ARGUMENT。若设置失败,async_ares_init() 会销毁已创建的 channel 并将错误向上传递。
五、命令行工具用法:--dns-servers
除库 API 外,curl 命令行工具从 7.33.0 起提供 --dns-servers 参数,与 CURLOPT_DNS_SERVERS 一一对应(docs/cmdline-opts/dns-servers.md):
curl --dns-servers 192.168.0.1,192.168.0.2 https://example.com/
curl --dns-servers 10.0.0.1:53 https://example.com/
参数解析逻辑位于 src/tool_getparam.c:
case C_DNS_SERVERS: /* --dns-servers */
if(!curlinfo->ares_num) /* c-ares is needed for this */
err = PARAM_LIBCURL_DOESNT_SUPPORT;
else
/* IP addrs of DNS servers */
err = getstr(&config->dns_servers, nextarg, DENY_BLANK);
break;
同样地,命令行工具在运行时若检测到 libcurl 未编译 c-ares 支持(通过 curlinfo->ares_num 判断),会直接返回 PARAM_LIBCURL_DOESNT_SUPPORT,提示该参数不可用。
六、与其他 DNS 相关选项的配合
CURLOPT_DNS_SERVERS 属于 libcurl DNS 解析控制族,官方文档 See-also 一节指出了可配合使用的相邻选项,它们在 lib/setopt.c 中同属 USE_RESOLV_ARES 代码块:
| 选项 | 引入版本 | 作用 |
|---|---|---|
CURLOPT_DNS_CACHE_TIMEOUT |
7.9.3 | 设置 DNS 缓存条目存活时间(秒),见 CURLOPT_DNS_CACHE_TIMEOUT.md |
CURLOPT_DNS_LOCAL_IP4 |
7.33.0 | 指定 IPv4 解析请求的本地出口 IP,见 CURLOPT_DNS_LOCAL_IP4.md |
CURLOPT_DNS_LOCAL_IP6 |
7.33.0 | 指定 IPv6 解析请求的本地出口 IP,见 CURLOPT_DNS_LOCAL_IP6.md |
CURLOPT_DNS_INTERFACE |
7.33.0 | 指定发起 DNS 查询的网络接口,见 CURLOPT_DNS_INTERFACE.md |
这些选项都在 async_ares_init() 中依次生效(lib/vdns/asyn-ares.c),例如 async_ares_set_dns_interface() 通过 ares_set_local_dev() 绑定出口设备(lib/vdns/asyn-ares.c),async_ares_set_dns_local_ip4() 通过 ares_set_local_ip4() 绑定本地地址。当需要“指定 DNS 服务器 + 指定出口 IP/网卡”组合时,可同时设置多个选项。
另外,若使用 DoH(DNS over HTTPS,CURLOPT_DOH_URL),自定义 DNS 服务器列表会作用于 DoH 服务器本身的域名解析,二者搭配可实现“加密查询上游 + 私有解析下游”的分层解析。
七、测试验证与注意事项
7.1 仓库中的相关测试
仓库 tests/libtest/lib1592.c 给出了一个利用该选项的典型测试场景:
/* Set a DNS server that hopefully does not respond when using c-ares. */
if(curl_easy_setopt(curl, CURLOPT_DNS_SERVERS, "0.0.0.0") == CURLE_OK)
该测试把 DNS 服务器指向 0.0.0.0(一个大概率不响应的地址),并据此推断当前 libcurl 构建使用的是 c-ares 后端——因为只有 c-ares 后端才会接受该选项并返回 CURLE_OK。这既验证了选项的功能,也提供了一种运行时探测 libcurl 是否支持自定义 DNS 服务器的实用手法。
7.2 使用注意事项
- 后端依赖:未以 c-ares 构建的 libcurl 无法使用本选项(API 返回
CURLE_UNKNOWN_OPTION,命令行返回参数不支持)。这是最常见的使用前提。 - 字符串生命周期:
curl_easy_setopt内部已拷贝字符串,调用后可立即释放或复用该内存;但后续若想修改服务器列表,需重新调用该选项。 - 覆盖与重置:多次调用以最后一次为准;传入 NULL 可恢复系统默认解析(在已有 channel 时会触发重建)。
- 格式校验:服务器列表格式错误时,解析阶段会返回
CURLE_BAD_FUNCTION_ARGUMENT,建议在调试模式下结合详细日志定位。 - 多服务器语义:列表按顺序提供多个服务器作为候选,具体故障切换策略由 c-ares 决定,应用层无需自行实现重试。
八、总结
CURLOPT_DNS_SERVERS 是 libcurl 面向应用层暴露的自定义 DNS 解析入口,其核心价值在于:在不影响系统全局 /etc/resolv.conf(或其他平台解析配置)的前提下,为单个 easy handle 指定专属 DNS 服务器列表。从仓库源码可以看出,它的实现深度绑定 c-ares 后端——从 setopt.c 的选项注册,到 asyn-ares.c 中调用 ares_set_servers_ports_csv() 完成下发,整条链路清晰可查。配合 CURLOPT_DNS_INTERFACE、CURLOPT_DNS_LOCAL_IP4/IP6 等选项,开发者可以构建精细的 DNS 分流与绑定策略,是排查域名解析故障、对接私有 DNS 基础设施时的重要工具。