modules/ims_qos: added patch for flow-description bug when request originates from...
[sip-router] / dns_cache.h
1 /*
2  * resolver/dns related functions, dns cache and failover
3  *
4  * Copyright (C) 2006 iptelorg GmbH
5  *
6  * This file is part of Kamailio, a free SIP server.
7  *
8  * Kamailio is free software; you can redistribute it and/or modify
9  * it under the terms of the GNU General Public License as published by
10  * the Free Software Foundation; either version 2 of the License, or
11  * (at your option) any later version
12  *
13  * Kamailio is distributed in the hope that it will be useful,
14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
16  * GNU General Public License for more details.
17  *
18  * You should have received a copy of the GNU General Public License
19  * along with this program; if not, write to the Free Software
20  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
21  */
22
23
24 /**
25  * @file
26  * @brief Kamailio core :: resolver/dns related functions, dns cache and failover
27  * @author andrei
28  * @ingroup core
29  * Module: @ref core
30  */
31
32
33
34 #ifndef __dns_cache_h
35 #define __dns_cache_h
36
37 #include "str.h"
38 #include "config.h" /* MAX_BRANCHES */
39 #include "timer.h"
40 #include "ip_addr.h"
41 #include "atomic_ops.h"
42 #include "resolve.h"
43
44
45 #if defined(USE_DNS_FAILOVER) && !defined(USE_DNS_CACHE)
46 #error "DNS FAILOVER requires DNS CACHE support (define USE_DNS_CACHE)"
47 #endif
48
49 #if defined(DNS_WATCHDOG_SUPPORT) && !defined(USE_DNS_CACHE)
50 #error "DNS WATCHDOG requires DNS CACHE support (define USE_DNS_CACHE)"
51 #endif
52
53 #define DEFAULT_DNS_NEG_CACHE_TTL 60 /* 1 min. */
54 #define DEFAULT_DNS_CACHE_MIN_TTL 0 /* (disabled) */
55 #define DEFAULT_DNS_CACHE_MAX_TTL ((unsigned int)(-1)) /* (maxint) */
56 #define DEFAULT_DNS_MAX_MEM 500 /* 500 Kb */
57
58 /** @brief uncomment the define below for SRV weight based load balancing */
59 #define DNS_SRV_LB
60
61 #define DNS_LU_LST
62
63 /** @brief dns functions return them as negative values (e.g. return -E_DNS_NO_IP)
64  *
65  * listed in the order of importance ( if more errors, only the most important
66  * is returned)
67  */
68 enum dns_errors{
69                                         E_DNS_OK=0,
70                                         E_DNS_EOR, /**< no more records (not an error)
71                                                       -- returned only by the dns_resolve*
72                                                                   functions when called iteratively,; it
73                                                                   signals the end of the ip/records list */
74                                         E_DNS_UNKNOWN /**< unkown error */,
75                                         E_DNS_INTERNAL_ERR /**< internal error */,
76                                         E_DNS_BAD_SRV_ENTRY,
77                                         E_DNS_NO_SRV /**< unresolvable srv record */,
78                                         E_DNS_BAD_IP_ENTRY,
79                                         E_DNS_NO_IP /**< unresolvable a or aaaa records*/,
80                                         E_DNS_BAD_IP /**< the ip is invalid */,
81                                         E_DNS_BLACKLIST_IP /**< the ip is blacklisted */,
82                                         E_DNS_NAME_TOO_LONG /**< try again with a shorter name */,
83                                         E_DNS_AF_MISMATCH /**< ipv4 or ipv6 only requested, but
84                                                                                  name contains an ip addr. of the
85                                                                                  opossite type */ ,
86                                         E_DNS_NO_NAPTR /**< unresolvable naptr record */,
87                                         E_DNS_CRITICAL /**< critical error, marks the end
88                                                                           of the error table (always last) */
89 };
90
91
92
93 /** @brief return a short string, printable error description (err <=0) */
94 const char* dns_strerror(int err);
95
96 /** @brief dns entry flags,
97  * shall be on the power of 2 */
98 /*@{ */
99 #define DNS_FLAG_BAD_NAME       1 /**< error flag: unresolvable */
100 #define DNS_FLAG_PERMANENT      2 /**< permanent record, never times out,
101                                         never deleted, never overwritten
102                                         unless explicitely requested */
103 /*@} */
104
105 /** @name dns requests flags */
106 /*@{ */
107 #define DNS_NO_FLAGS    0
108 #define DNS_IPV4_ONLY   1
109 #define DNS_IPV6_ONLY   2
110 #define DNS_IPV6_FIRST  4
111 #define DNS_SRV_RR_LB   8  /**< SRV RR weight based load balancing */
112 #define DNS_TRY_NAPTR   16 /**< enable naptr lookup */
113 /*@} */
114
115
116 /** @name ip blacklist error flags */
117 /*@{ */
118 #define IP_ERR_BAD_DST      2 /* destination is marked as bad (e.g. bad ip) */
119 #define IP_ERR_SND          3 /* send error while using this as destination */
120 #define IP_ERR_TIMEOUT      4 /* timeout waiting for a response */
121 #define IP_ERR_TCP_CON      5 /* could not establish tcp connection */
122 /*@} */
123
124
125 /** @brief stripped down dns rr 
126         @note name, type and class are not needed, contained in struct dns_query */
127 struct dns_rr{
128         struct dns_rr* next;
129         void* rdata; /**< depends on the type */
130         ticks_t expire; /**< = ttl + crt_time */
131 };
132
133
134
135 #ifdef DNS_LU_LST
136 struct dns_lu_lst{  /* last used ordered list */
137         struct dns_lu_lst* next;
138         struct dns_lu_lst* prev;
139 };
140 #endif
141
142 struct dns_hash_entry{
143         /* hash table links */
144         struct dns_hash_entry* next;
145         struct dns_hash_entry* prev;
146 #ifdef DNS_LU_LST
147         struct dns_lu_lst last_used_lst;
148 #endif
149         struct dns_rr* rr_lst;
150         atomic_t refcnt;
151         ticks_t last_used;
152         ticks_t expire; /* when the whole entry will expire */
153         int total_size;
154         unsigned short type;
155         unsigned char ent_flags; /* entry flags: unresolvable/permanent */
156         unsigned char name_len; /* can be maximum 255 bytes */
157         char name[1]; /* variable length, name, null terminated
158                          (actual lenght = name_len +1)*/
159 };
160
161
162 /* to fit in the limit of MAX_BRANCHES */
163 #if MAX_BRANCHES_LIMIT < 32
164 typedef unsigned int srv_flags_t;
165 #else
166 typedef unsigned long long srv_flags_t;
167 #endif
168
169 struct dns_srv_handle{
170         struct dns_hash_entry* srv; /**< srv entry */
171         struct dns_hash_entry* a;   /**< a or aaaa current entry */
172 #ifdef DNS_SRV_LB
173         srv_flags_t srv_tried_rrs;
174 #endif
175         unsigned short port; /**< current port */
176         unsigned char srv_no; /**< current record no. in the srv entry */
177         unsigned char ip_no;  /**< current record no. in the a/aaaa entry */
178         unsigned char proto;  /**< protocol number */
179 };
180
181
182
183 const char* dns_strerror(int err);
184
185 void fix_dns_flags(str *gname, str *name);
186 int use_dns_failover_fixup(void *handle, str *gname, str *name, void **val);
187 int use_dns_cache_fixup(void *handle, str *gname, str *name, void **val);
188 int dns_cache_max_mem_fixup(void *handle, str *gname, str *name, void **val);
189 int init_dns_cache(void);
190 #ifdef USE_DNS_CACHE_STATS
191 int init_dns_cache_stats(int iproc_num);
192 #define DNS_CACHE_ALL_STATS "dc_all_stats"
193 #endif
194 void destroy_dns_cache(void);
195
196
197 void dns_hash_put(struct dns_hash_entry* e);
198 void dns_hash_put_shm_unsafe(struct dns_hash_entry* e);
199
200 inline static void dns_srv_handle_put(struct dns_srv_handle* h)
201 {
202         if (h){
203                 if (h->srv){
204                         dns_hash_put(h->srv);
205                         h->srv=0;
206                 }
207                 if (h->a){
208                         dns_hash_put(h->a);
209                         h->a=0;
210                 }
211         }
212 }
213
214
215
216 /** @brief use it when copying, it manually increases the ref cound */
217 inline static void dns_srv_handle_ref(struct dns_srv_handle *h)
218 {
219         if (h){
220                 if (h->srv)
221                         atomic_inc(&h->srv->refcnt);
222                 if (h->a)
223                         atomic_inc(&h->a->refcnt);
224         }
225 }
226
227
228
229 /** @brief safe copy increases the refcnt, src must not change while in this function
230  * WARNING: the copy must be dns_srv_handle_put ! */
231 inline static void dns_srv_handle_cpy(struct dns_srv_handle* dst,
232                                                                                 struct dns_srv_handle* src)
233 {
234         dns_srv_handle_ref(src);
235         *dst=*src;
236 }
237
238
239
240 /** @brief same as above but assume shm_lock held (for internal tm use only) */
241 inline static void dns_srv_handle_put_shm_unsafe(struct dns_srv_handle* h)
242 {
243         if (h){
244                 if (h->srv){
245                         dns_hash_put_shm_unsafe(h->srv);
246                         h->srv=0;
247                 }
248                 if (h->a){
249                         dns_hash_put_shm_unsafe(h->a);
250                         h->a=0;
251                 }
252         }
253 }
254
255
256
257 /** @brief get "next" ip next time a dns_srv_handle function is called
258  * params: h   - struct dns_srv_handler
259  *         err - return code of the last dns_*_resolve* call
260  * returns: 0 if it doesn't make sense to try another record,
261  * 1 otherwise
262  */
263 inline static int dns_srv_handle_next(struct dns_srv_handle* h, int err)
264 {
265         if (err<0) return 0;
266         h->ip_no++;
267         return (h->srv || h->a);
268 }
269
270
271
272 inline static void dns_srv_handle_init(struct dns_srv_handle* h)
273 {
274         h->srv=h->a=0;
275         h->srv_no=h->ip_no=0;
276         h->port=0;
277         h->proto=0;
278 #ifdef DNS_SRV_LB
279         h->srv_tried_rrs=0;
280 #endif
281 }
282
283
284
285 /** @brief performes a srv query on name
286  * Params:  name  - srv query target (e.g. _sip._udp.foo.bar)
287  *          ip    - result: first good ip found
288  *          port  - result: corresponding port number
289  *          flags - resolve options (like ipv4 only, ipv6 prefered a.s.o)
290  * Returns: < 0 on error (can be passed to dns_strerror(), 0 on success
291  */
292 int dns_srv_get_ip(str* name, struct ip_addr* ip, unsigned short* port,
293                                         int flags);
294
295 /** @brief performs an A, AAAA (or both) query/queries
296  * Params:  name  - query target (e.g. foo.bar)
297  *          ip    - result: first good ip found
298  *          flags - resolve options (like ipv4 only, ipv6 prefered a.s.o)
299  * Returns: < 0 on error (can be passed to dns_strerror(), 0 on success
300  */
301 int dns_get_ip(str* name, struct ip_addr* ip, int flags);
302
303 struct hostent* dns_srv_get_he(str* name, unsigned short* port, int flags);
304 struct hostent* dns_get_he(str* name, int flags);
305
306
307 /** @brief resolve name to an ip, using srv record. Can be called multiple times
308  * to iterate on all the possible ips, e.g :
309  * dns_srv_handle_init(h);
310  * ret_code=dns_sip_resolve(h,...);
311  *  while( dns_srv_handle_next(h, ret_code){ ret_code=dns_sip_resolve(h...); }
312  * dns_srv_handle_put(h);
313  * WARNING: dns_srv_handle_init() must be called to initialize h and
314  *  dns_srv_handle_put(h) must be called when h is no longer needed
315  */
316 int dns_sip_resolve(struct dns_srv_handle* h,  str* name, struct ip_addr* ip,
317                                         unsigned short* port, char* proto, int flags);
318
319 /** @brief same as above, but fills su intead of changing port and filling an ip */
320 inline static int dns_sip_resolve2su(struct dns_srv_handle* h,
321                                                                          union sockaddr_union* su,
322                                                                          str* name, unsigned short port,
323                                                                          char* proto, int flags)
324 {
325         struct ip_addr ip;
326         int ret;
327
328         ret=dns_sip_resolve(h, name, &ip, &port, proto, flags);
329         if (ret>=0)
330                 init_su(su, &ip, port);
331         return ret;
332 }
333
334 /** @brief Delete all the entries from the cache.
335  * If del_permanent is 0, then only the
336  * non-permanent entries are deleted.
337  */
338 void dns_cache_flush(int del_permanent);
339
340 #ifdef DNS_WATCHDOG_SUPPORT
341 /** @brief sets the state of the DNS servers:
342  * 1: at least one server is up
343  * 0: all the servers are down
344  */
345 void dns_set_server_state(int state);
346
347 /** @brief returns the state of the DNS servers */
348 int dns_get_server_state(void);
349 #endif /* DNS_WATCHDOG_SUPPORT */
350
351 /** @brief Adds a new record to the cache.
352  * If there is an existing record with the same name and value
353  * (ip address in case of A/AAAA record, name in case of SRV record)
354  * only the remaining fields are updated.
355  *
356  * Note that permanent records cannot be overwritten unless
357  * the new record is also permanent. A permanent record
358  * completely replaces a non-permanent one.
359  *
360  * Currently only A, AAAA, and SRV records are supported.
361  */
362 int dns_cache_add_record(unsigned short type,
363                         str *name,
364                         int ttl,
365                         str *value,
366                         int priority,
367                         int weight,
368                         int port,
369                         int flags);
370
371 /** @brief Delete a single record from the cache,
372  * i.e. the record with the same name and value
373  * (ip address in case of A/AAAA record, name in case of SRV record).
374  *
375  * Currently only A, AAAA, and SRV records are supported.
376  */
377 int dns_cache_delete_single_record(unsigned short type,
378                         str *name,
379                         str *value,
380                         int flags);
381
382
383 #endif