Commit | Line | Data |
---|---|---|
1a4240f4 WL |
1 | =================== |
2 | DNS Resolver Module | |
3 | =================== | |
4 | ||
5 | Contents: | |
6 | ||
7 | - Overview. | |
8 | - Compilation. | |
9 | - Setting up. | |
10 | - Usage. | |
11 | - Mechanism. | |
12 | - Debugging. | |
13 | ||
14 | ||
15 | ======== | |
16 | OVERVIEW | |
17 | ======== | |
18 | ||
19 | The DNS resolver module provides a way for kernel services to make DNS queries | |
20 | by way of requesting a key of key type dns_resolver. These queries are | |
21 | upcalled to userspace through /sbin/request-key. | |
22 | ||
23 | These routines must be supported by userspace tools dns.upcall, cifs.upcall and | |
24 | request-key. It is under development and does not yet provide the full feature | |
25 | set. The features it does support include: | |
26 | ||
27 | (*) Implements the dns_resolver key_type to contact userspace. | |
28 | ||
29 | It does not yet support the following AFS features: | |
30 | ||
31 | (*) Dns query support for AFSDB resource record. | |
32 | ||
33 | This code is extracted from the CIFS filesystem. | |
34 | ||
35 | ||
36 | =========== | |
37 | COMPILATION | |
38 | =========== | |
39 | ||
40 | The module should be enabled by turning on the kernel configuration options: | |
41 | ||
42 | CONFIG_DNS_RESOLVER - tristate "DNS Resolver support" | |
43 | ||
44 | ||
45 | ========== | |
46 | SETTING UP | |
47 | ========== | |
48 | ||
49 | To set up this facility, the /etc/request-key.conf file must be altered so that | |
50 | /sbin/request-key can appropriately direct the upcalls. For example, to handle | |
51 | basic dname to IPv4/IPv6 address resolution, the following line should be | |
52 | added: | |
53 | ||
54 | #OP TYPE DESC CO-INFO PROGRAM ARG1 ARG2 ARG3 ... | |
55 | #====== ============ ======= ======= ========================== | |
56 | create dns_resolver * * /usr/sbin/cifs.upcall %k | |
57 | ||
58 | To direct a query for query type 'foo', a line of the following should be added | |
59 | before the more general line given above as the first match is the one taken. | |
60 | ||
61 | create dns_resolver foo:* * /usr/sbin/dns.foo %k | |
62 | ||
63 | ||
64 | ||
65 | ===== | |
66 | USAGE | |
67 | ===== | |
68 | ||
69 | To make use of this facility, one of the following functions that are | |
70 | implemented in the module can be called after doing: | |
71 | ||
72 | #include <linux/dns_resolver.h> | |
73 | ||
74 | (1) int dns_query(const char *type, const char *name, size_t namelen, | |
75 | const char *options, char **_result, time_t *_expiry); | |
76 | ||
77 | This is the basic access function. It looks for a cached DNS query and if | |
78 | it doesn't find it, it upcalls to userspace to make a new DNS query, which | |
79 | may then be cached. The key description is constructed as a string of the | |
80 | form: | |
81 | ||
82 | [<type>:]<name> | |
83 | ||
84 | where <type> optionally specifies the particular upcall program to invoke, | |
85 | and thus the type of query to do, and <name> specifies the string to be | |
86 | looked up. The default query type is a straight hostname to IP address | |
87 | set lookup. | |
88 | ||
89 | The name parameter is not required to be a NUL-terminated string, and its | |
90 | length should be given by the namelen argument. | |
91 | ||
92 | The options parameter may be NULL or it may be a set of options | |
93 | appropriate to the query type. | |
94 | ||
95 | The return value is a string appropriate to the query type. For instance, | |
96 | for the default query type it is just a list of comma-separated IPv4 and | |
97 | IPv6 addresses. The caller must free the result. | |
98 | ||
ff9517a6 DH |
99 | The length of the result string is returned on success, and a negative |
100 | error code is returned otherwise. -EKEYREJECTED will be returned if the | |
101 | DNS lookup failed. | |
1a4240f4 WL |
102 | |
103 | If _expiry is non-NULL, the expiry time (TTL) of the result will be | |
104 | returned also. | |
105 | ||
106 | ||
107 | ========= | |
108 | MECHANISM | |
109 | ========= | |
110 | ||
111 | The dnsresolver module registers a key type called "dns_resolver". Keys of | |
112 | this type are used to transport and cache DNS lookup results from userspace. | |
113 | ||
114 | When dns_query() is invoked, it calls request_key() to search the local | |
115 | keyrings for a cached DNS result. If that fails to find one, it upcalls to | |
116 | userspace to get a new result. | |
117 | ||
118 | Upcalls to userspace are made through the request_key() upcall vector, and are | |
119 | directed by means of configuration lines in /etc/request-key.conf that tell | |
120 | /sbin/request-key what program to run to instantiate the key. | |
121 | ||
122 | The upcall handler program is responsible for querying the DNS, processing the | |
123 | result into a form suitable for passing to the keyctl_instantiate_key() | |
124 | routine. This then passes the data to dns_resolver_instantiate() which strips | |
125 | off and processes any options included in the data, and then attaches the | |
126 | remainder of the string to the key as its payload. | |
127 | ||
128 | The upcall handler program should set the expiry time on the key to that of the | |
129 | lowest TTL of all the records it has extracted a result from. This means that | |
130 | the key will be discarded and recreated when the data it holds has expired. | |
131 | ||
132 | dns_query() returns a copy of the value attached to the key, or an error if | |
133 | that is indicated instead. | |
134 | ||
135 | See <file:Documentation/keys-request-key.txt> for further information about | |
136 | request-key function. | |
137 | ||
138 | ||
139 | ========= | |
140 | DEBUGGING | |
141 | ========= | |
142 | ||
143 | Debugging messages can be turned on dynamically by writing a 1 into the | |
144 | following file: | |
145 | ||
146 | /sys/module/dnsresolver/parameters/debug |