ares_set_servers_csv.3 (5344B)
1 .\" 2 .\" Copyright 2010 by Ben Greear <greearb@candelatech.com> 3 .\" SPDX-License-Identifier: MIT 4 .\" 5 .TH ARES_SET_SERVERS_CSV 3 "5 Dec 2023" 6 .SH NAME 7 ares_set_servers_csv, ares_set_servers_ports_csv, ares_get_servers_csv \- Set 8 or Get a list of DNS servers used for queries. 9 .SH SYNOPSIS 10 .nf 11 #include <ares.h> 12 13 int ares_set_servers_csv(ares_channel_t *\fIchannel\fP, const char* \fIservers\fP) 14 15 int ares_set_servers_ports_csv(ares_channel_t *\fIchannel\fP, const char* \fIservers\fP) 16 17 char *ares_get_servers_csv(const ares_channel_t *\fIchannel\fP) 18 .fi 19 .SH DESCRIPTION 20 The \fBares_set_servers_csv\fP and \fBares_set_servers_ports_csv\fP functions set 21 the list of DNS servers that c-ares will query. As of v1.22.0 this function can 22 be called on an active channel with running queries, previously it would return 23 ARES_ENOTIMP. 24 25 Though not recommended, passing NULL for servers will clear all configured 26 servers and make an inoperable channel, this may be advantageous for test 27 simulation but unlikely to be useful in production. 28 29 The \fBares_get_servers_csv\fP retrieves the list of servers in comma delimited 30 format. 31 32 The input and output format is a comma separated list of servers. Two formats 33 are available, the typical \fBresolv.conf(5)\fP \fInameserver\fP format, as 34 well as a \fIURI\fP format. Both formats can be used at the same time in the 35 provided CSV string. 36 37 The \fInameserver\fP format is: 38 .nf 39 40 ip[:port][%iface] 41 42 .fi 43 .RS 4 44 The \fBip\fP may be encapsulated in square brackets ([ ]), and must be if 45 using ipv6 and also specifying a port. 46 47 The \fBport\fP is optional, and will default to 53 or the value specified in 48 \fBares_init_options(3)\fP. 49 50 The \fBiface\fP is specific to IPv6 link-local servers (fe80::/10) and should 51 not otherwise be used. 52 .RE 53 54 \fInameserver\fP format examples: 55 .nf 56 57 192.168.1.100 58 192.168.1.101:53 59 [1:2:3::4]:53 60 [fe80::1]:53%eth0 61 62 .fi 63 .PP 64 65 The \fIURI\fP format is is made up of these defined schemes: 66 .RS 4 67 \fIdns://\fP - Normal DNS server (UDP + TCP). We need to be careful not to 68 conflict with query params defined in RFC4501 since we'd technically be 69 extending this URI scheme. Port defaults to 53. 70 71 \fIdns+tls://\fP - DNS over TLS. Port defaults to 853. 72 73 \fIdns+https://\fP - DNS over HTTPS. Port defaults to 443. 74 .RE 75 76 .PP 77 Query parameters are defined as below. Additional parameters may be defined 78 in the future. 79 80 .RS 4 81 \fItcpport\fP - TCP port to use, only for \fIdns://\fP scheme. The port 82 specified as part of the authority component of the URI will be used for both 83 UDP and TCP by default, this option will override the TCP port. 84 85 \fIipaddr\fP - Only for \fIdns+tls://\fP and \fIdns+https://\fP. If the 86 authority component of the URI contains a hostname, this is used to specify the 87 ip address of the hostname. If not specified, will need to use a non-secure 88 server to perform a DNS lookup to retrieve this information. It is always 89 recommended to have both the ip address and fully qualified domain name 90 specified. 91 92 \fIhostname\fP - Only for \fIdns+tls://\fP and \fIdns+https://\fP. If the 93 authority component of the URI contains an ip address, this is used to specify 94 the fully qualified domain name of the server. If not specified, will need to 95 use a non-secure server to perform a DNS reverse lookup to retrieve this 96 information. It is always recommended to have both the ip address and fully 97 qualified domain name specified. 98 99 \fIdomain\fP - If specified, this server is a domain-specific server. Any 100 queries for this domain will be routed to this server. Multiple servers may be 101 tagged with the same domain. 102 .RE 103 104 \fIURI\fP format Examples: 105 .nf 106 107 dns://8.8.8.8 108 dns://[2001:4860:4860::8888] 109 dns://[fe80::b542:84df:1719:65e3%en0] 110 dns://192.168.1.1:55 111 dns://192.168.1.1?tcpport=1153 112 dns://10.0.1.1?domain=myvpn.com 113 dns+tls://8.8.8.8?hostname=dns.google 114 dns+tls://one.one.one.one?ipaddr=1.1.1.1 115 116 .fi 117 118 \fBNOTE\fP: While we are defining the scheme for things like domain-specific 119 servers, DNS over TLS and DNS over HTTPS, the underlying implementations for 120 those features do not yet exist and therefore will result in errors if they are 121 attempted to be used. 122 123 .PP 124 As of c-ares 1.24.0, \fBares_set_servers_csv\fP and \fBares_set_servers_ports_csv\fP 125 are identical. Prior versions would simply omit ports in \fBares_set_servers_csv\fP 126 but due to the addition of link local interface support, this difference was 127 removed. 128 129 .SH EXAMPLE 130 .nf 131 192.168.1.100,[fe80::1]:53%eth0,dns://192.168.1.1?tcpport=1153 132 .fi 133 134 .SH RETURN VALUES 135 .B ares_set_servers_csv(3) 136 and 137 .B ares_set_servers_ports_csv(3) 138 may return any of the following values: 139 .TP 15 140 .B ARES_SUCCESS 141 The name servers configuration was successfully initialized. 142 .TP 15 143 .B ARES_ENOMEM 144 The process's available memory was exhausted. 145 .TP 15 146 .B ARES_ENODATA 147 The channel data identified by 148 .IR channel 149 was invalid. 150 .TP 15 151 .B ARES_ENOTINITIALIZED 152 c-ares library initialization not yet performed. 153 .PP 154 .B ares_get_servers_csv(3) 155 returns a string representing the servers configured which must be freed with 156 \fBares_free_string(3)\fP. If it returns NULL, this is an out of memory condition. 157 .SH SEE ALSO 158 .BR ares_set_servers (3) 159 .SH AVAILABILITY 160 \fBares_set_servers_csv\fP was added in c-ares 1.7.2 161 \fBares_set_servers_ports_csv\fP was added in c-ares 1.11.0. 162 \fBares_get_servers_csv\fP was added in c-ares 1.24.0. 163 \fIURI\fP support was added in c-ares 1.34.0.