ares_set_servers_csv(3) Library Functions Manual ares_set_servers_csv(3)
NAME
ares_set_servers_csv, ares_set_servers_ports_csv, ares_get_servers_csv
- Set or Get a list of DNS servers used for queries.
SYNOPSIS
#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)
DESCRIPTION
The ares_set_servers_csv and ares_set_servers_ports_csv functions set
the list of DNS servers that c-ares will query. As of v1.22.0 this
function can be called on an active channel with running queries,
previously it would return ARES_ENOTIMP.
Though not recommended, passing NULL for servers will clear all
configured servers and make an inoperable channel, this may be
advantageous for test simulation but unlikely to be useful in
production.
The ares_get_servers_csv retrieves the list of servers in comma
delimited format.
The input and output format is a comma separated list of servers. Two
formats are available, the typical resolv.conf(5) nameserver format, as
well as a URI format. Both formats can be used at the same time in the
provided CSV string.
The nameserver format is:
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.
nameserver format examples:
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.
URI format Examples:
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.1
NOTE: 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.
EXAMPLE
192.168.1.100,[fe80::1]:53%eth0,dns://192.168.1.1?tcpport=1153
RETURN VALUES
ares_set_servers_csv(3) and ares_set_servers_ports_csv(3) may return
any of the following values:
ARES_SUCCESS The name servers configuration was successfully
initialized.
ARES_ENOMEM The process's available memory was exhausted.
ARES_ENODATA The channel data identified by channel was invalid.
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.
SEE ALSO
ares_set_servers(3)
AVAILABILITY
ares_set_servers_csv was added in c-ares 1.7.2
ares_set_servers_ports_csv was added in c-ares 1.11.0.
ares_get_servers_csv was added in c-ares 1.24.0. URI support was added
in c-ares 1.34.0.
5 Dec 2023 ares_set_servers_csv(3)
c-ares 1.34.1 - Generated Fri Oct 11 15:47:06 CDT 2024