Copyright 2010 by Ben Greear <greearb@candelatech.com>
SPDX-License-Identifier: MIT
#include <ares.h> int ares_set_servers_csv(ares_channel_t *channel, const char* servers) int ares_set_servers_ports_csv(ares_channel_t *channel, const char* servers) char *ares_get_servers_csv(const ares_channel_t *channel)
ip[:port][%iface]
The ip may be encapsulated in square brackets ([ ]), and must be if using ipv6 and also specifying a port. The port is optional, and will default to 53 or the value specified in ares_init_options(3). The iface is specific to IPv6 link-local servers (fe80::/10) and should not otherwise be used.
192.168.1.100 192.168.1.101:53 [1:2:3::4]:53 [fe80::1]:53%eth0
The URI format is is made up of these defined schemes:
dns:// - Normal DNS server (UDP + TCP). We need to be careful not to conflict with query params defined in RFC4501 since we'd technically be extending this URI scheme. Port defaults to 53. dns+tls:// - DNS over TLS. Port defaults to 853. dns+https:// - DNS over HTTPS. Port defaults to 443.
Query parameters are defined as below. Additional parameters may be defined in the future.
tcpport - TCP port to use, only for dns:// scheme. The port specified as part of the authority component of the URI will be used for both UDP and TCP by default, this option will override the TCP port. ipaddr - Only for dns+tls:// and dns+https://. If the authority component of the URI contains a hostname, this is used to specify the ip address of the hostname. If not specified, will need to use a non-secure server to perform a DNS lookup to retrieve this information. It is always recommended to have both the ip address and fully qualified domain name specified. hostname - Only for dns+tls:// and dns+https://. If the authority component of the URI contains an ip address, this is used to specify the fully qualified domain name of the server. If not specified, will need to use a non-secure server to perform a DNS reverse lookup to retrieve this information. It is always recommended to have both the ip address and fully qualified domain name specified. domain - If specified, this server is a domain-specific server. Any queries for this domain will be routed to this server. Multiple servers may be tagged with the same domain.
dns://8.8.8.8 dns://[2001:4860:4860::8888] dns://[fe80::b542:84df:1719:65e3%en0] dns://192.168.1.1:55 dns://192.168.1.1?tcpport=1153 dns://10.0.1.1?domain=myvpn.com dns+tls://8.8.8.8?hostname=dns.google dns+tls://one.one.one.one?ipaddr=1.1.1.1NOTE: While we are defining the scheme for things like domain-specific servers, DNS over TLS and DNS over HTTPS, the underlying implementations for those features do not yet exist and therefore will result in errors if they are attempted to be used.
As of c-ares 1.24.0, ares_set_servers_csv and ares_set_servers_ports_csv are identical. Prior versions would simply omit ports in ares_set_servers_csv but due to the addition of link local interface support, this difference was removed.
192.168.1.100,[fe80::1]:53%eth0,dns://192.168.1.1?tcpport=1153
15 ARES_SUCCESS The name servers configuration was successfully initialized.
15 ARES_ENOMEM The process's available memory was exhausted.
15 ARES_ENODATA The channel data identified by channel was invalid.
15 ARES_ENOTINITIALIZED c-ares library initialization not yet performed.
ares_get_servers_csv(3) returns a string representing the servers configured which must be freed with ares_free_string(3). If it returns NULL, this is an out of memory condition.