1Scriptable structures 2===================== 3 4module_qstate 5----------------------- 6 7.. class:: module_qstate 8 9 Module state, per query. 10 11 This class provides these data attributes: 12 13 .. attribute:: qinfo 14 15 (:class:`query_info`) Information about query being answered. Name, RR type, RR class. 16 17 .. attribute:: query_flags 18 19 (uint16) Flags for query. See QF_BIT\_ predefined constants. 20 21 .. attribute:: is_priming 22 23 If this is a (stub or root) priming query (with hints). 24 25 .. attribute:: reply 26 27 comm_reply contains server replies. 28 29 .. attribute:: return_msg 30 31 (:class:`dns_msg`) The reply message, with message for client and calling module (read-only attribute). 32 Note that if you want to create of modify return_msg you should use :class:`DNSMessage`. 33 34 .. attribute:: return_rcode 35 36 The rcode, in case of error, instead of a reply message. Determines whether the return_msg contains reply. 37 38 .. attribute:: region 39 40 Region for this query. Cleared when query process finishes. 41 42 .. attribute:: curmod 43 44 Which module is executing. 45 46 .. attribute:: ext_state[] 47 48 Module states. 49 50 .. attribute:: env 51 52 Environment for this query. 53 54 .. attribute:: mesh_info 55 56 Mesh related information for this query. 57 58 .. attribute:: edns_opts_front_in 59 60 Incoming EDNS options from the front end. 61 62 .. attribute:: edns_opts_front_in_iter 63 64 Iterator for `edns_opts_front_in`. 65 66 .. attribute:: edns_opts_back_out 67 68 Outgoing EDNS options to the back end. 69 70 .. attribute:: edns_opts_back_out_iter 71 72 Iterator for `edns_opts_back_out`. 73 74 .. attribute:: edns_opts_back_in 75 76 Incoming EDNS options from the back end. 77 78 .. attribute:: edns_opts_back_in_iter 79 80 Iterator for `edns_opts_back_in`. 81 82 .. attribute:: edns_opts_front_out 83 84 Outgoing EDNS options to the front end. 85 86 .. attribute:: edns_opts_front_out_iter 87 88 Iterator for `edns_opts_front_out`. 89 90 .. attribute:: no_cache_lookup 91 92 Flag to indicate whether modules should answer from the cache. 93 94 .. attribute:: no_cache_store 95 96 Flag to indicate whether modules should store answer in the cache. 97 98query_info 99---------------- 100 101.. class:: query_info 102 103 This class provides these data attributes: 104 105 .. attribute:: qname 106 107 The original question in the wireformat format (e.g. \\x03www\\x03nic\\x02cz\\x00 for www.nic.cz) 108 109 .. attribute:: qname_len 110 111 Length of question name (number of bytes). 112 113 .. attribute:: qname_list[] 114 115 The question ``qname`` converted into list of labels (e.g. ['www','nic','cz',''] for www.nic.cz) 116 117 .. attribute:: qname_str 118 119 The question ``qname`` converted into string (e.g. www.nic.cz. for www.nic.cz) 120 121 .. attribute:: qtype 122 123 The class type asked for. See RR_TYPE\_ predefined constants. 124 125 .. attribute:: qtype_str 126 127 The ``qtype`` in display presentation format (string) (e.g 'A' for RR_TYPE_A) 128 129 .. attribute:: qclass 130 131 The question class. See RR_CLASS\_ predefined constants. 132 133 .. attribute:: qclass_str 134 135 The ``qclass`` in display presentation format (string). 136 137edns_data 138--------- 139 140.. class:: edns_data 141 142 This class represents the EDNS information parsed/encoded from/to a packet. It provides these data attributes: 143 144 .. attribute:: edns_present 145 146 If EDNS OPT record is present. 147 148 .. attribute:: ext_rcode 149 150 Extended RCODE. 151 152 .. attribute:: edns_version 153 154 The EDNS version number. 155 156 .. attribute:: bits 157 158 The EDNS bits field from ttl (host order): Z. 159 160 .. attribute:: udp_size 161 162 UDP reassembly size. 163 164 .. attribute:: opt_list 165 166 The EDNS option list. 167 168 .. attribute:: opt_list_iter 169 170 Iterator for `opt_list`. 171 172edns_option 173----------- 174 175.. class:: edns_option 176 177 This class represents an EDNS option (code, data) found in EDNS option lists. It provides these data attributes: 178 179 .. attribute:: code 180 181 The EDNS option code. 182 183 .. attribute:: data 184 185 The EDNS option data. 186 187reply_info 188-------------------- 189 190.. class:: reply_info 191 192 This class provides these data attributes: 193 194 .. attribute:: flags 195 196 The flags for the answer, host byte order. 197 198 .. attribute:: qdcount 199 200 Number of RRs in the query section. 201 If qdcount is not 0, then it is 1, and the data that appears 202 in the reply is the same as the query_info. 203 Host byte order. 204 205 .. attribute:: ttl 206 207 TTL of the entire reply (for negative caching). 208 only for use when there are 0 RRsets in this message. 209 if there are RRsets, check those instead. 210 211 .. attribute:: security 212 213 The security status from DNSSEC validation of this message. See sec_status\_ predefined constants. 214 215 .. attribute:: an_numrrsets 216 217 Number of RRsets in each section. 218 The answer section. Add up the RRs in every RRset to calculate 219 the number of RRs, and the count for the dns packet. 220 The number of RRs in RRsets can change due to RRset updates. 221 222 .. attribute:: ns_numrrsets 223 224 Count of authority section RRsets 225 226 .. attribute:: ar_numrrsets 227 228 Count of additional section RRsets 229 230 .. attribute:: rrset_count 231 232 Number of RRsets: an_numrrsets + ns_numrrsets + ar_numrrsets 233 234 .. attribute:: rrsets[] 235 236 (:class:`ub_packed_rrset_key`) List of RR sets in the order in which they appear in the reply message. 237 Number of elements is ancount + nscount + arcount RRsets. 238 239 .. attribute:: ref[] 240 241 (:class:`rrset_ref`) Packed array of ids (see counts) and pointers to packed_rrset_key. 242 The number equals ancount + nscount + arcount RRsets. 243 These are sorted in ascending pointer, the locking order. So 244 this list can be locked (and id, ttl checked), to see if 245 all the data is available and recent enough. 246 247 248dns_msg 249-------------- 250 251.. class:: dns_msg 252 253 Region allocated message reply 254 255 This class provides these data attributes: 256 257 .. attribute:: qinfo 258 259 (:class:`query_info`) Information about query. 260 261 .. attribute:: rep 262 263 (:class:`reply_info`) This attribute points to the packed reply structure. 264 265 266packed_rrset_key 267---------------------- 268 269.. class:: packed_rrset_key 270 271 The identifying information for an RRset. 272 273 This class provides these data attributes: 274 275 .. attribute:: dname 276 277 The domain name. If not empty (for ``id = None``) it is allocated, and 278 contains the wireformat domain name. This dname is not canonicalized. 279 E.g., the dname contains \\x03www\\x03nic\\x02cz\\x00 for www.nic.cz. 280 281 .. attribute:: dname_len 282 283 Length of the domain name, including last 0 root octet. 284 285 .. attribute:: dname_list[] 286 287 The domain name ``dname`` converted into list of labels (see :attr:`query_info.qname_list`). 288 289 .. attribute:: dname_str 290 291 The domain name ``dname`` converted into string (see :attr:`query_info.qname_str`). 292 293 .. attribute:: flags 294 295 Flags. 296 297 .. attribute:: type 298 299 The rrset type in network format. 300 301 .. attribute:: type_str 302 303 The rrset type in display presentation format. 304 305 .. attribute:: rrset_class 306 307 The rrset class in network format. 308 309 .. attribute:: rrset_class_str 310 311 The rrset class in display presentation format. 312 313ub_packed_rrset_key 314------------------------- 315 316.. class:: ub_packed_rrset_key 317 318 This structure contains an RRset. A set of resource records that 319 share the same domain name, type and class. 320 Due to memory management and threading, the key structure cannot be 321 deleted, although the data can be. The id can be set to 0 to store and the 322 structure can be recycled with a new id. 323 324 The :class:`ub_packed_rrset_key` provides these data attributes: 325 326 .. attribute:: entry 327 328 (:class:`lruhash_entry`) Entry into hashtable. Note the lock is never destroyed, 329 even when this key is retired to the cache. 330 the data pointer (if not None) points to a :class:`packed_rrset`. 331 332 .. attribute:: id 333 334 The ID of this rrset. unique, based on threadid + sequenceno. 335 ids are not reused, except after flushing the cache. 336 zero is an unused entry, and never a valid id. 337 Check this value after getting entry.lock. 338 The other values in this struct may only be altered after changing 339 the id (which needs a writelock on entry.lock). 340 341 .. attribute:: rk 342 343 (:class:`packed_rrset_key`) RR set data. 344 345 346lruhash_entry 347------------------------- 348 349.. class:: lruhash_entry 350 351 The :class:`ub_packed_rrset_key` provides these data attributes: 352 353 .. attribute:: lock 354 355 rwlock for access to the contents of the entry. Note that you cannot change hash and key, if so, you have to delete it to change hash or key. 356 357 .. attribute:: data 358 359 (:class:`packed_rrset_data`) entry data stored in wireformat (RRs and RRsigs). 360 361packed_rrset_data 362----------------------- 363 364.. class:: packed_rrset_data 365 366 Rdata is stored in wireformat. The dname is stored in wireformat. 367 368 TTLs are stored as absolute values (and could be expired). 369 370 RRSIGs are stored in the arrays after the regular rrs. 371 372 You need the packed_rrset_key to know dname, type, class of the 373 resource records in this RRset. (if signed the rrsig gives the type too). 374 375 The :class:`packed_rrset_data` provides these data attributes: 376 377 .. attribute:: ttl 378 379 TTL (in seconds like time()) of the RRset. 380 Same for all RRs see rfc2181(5.2). 381 382 .. attribute:: count 383 384 Number of RRs. 385 386 .. attribute:: rrsig_count 387 388 Number of rrsigs, if 0 no rrsigs. 389 390 .. attribute:: trust 391 392 The trustworthiness of the RRset data. 393 394 .. attribute:: security 395 396 Security status of the RRset data. See sec_status\_ predefined constants. 397 398 .. attribute:: rr_len[] 399 400 Length of every RR's rdata, rr_len[i] is size of rr_data[i]. 401 402 .. attribute:: rr_ttl[] 403 404 TTL of every rr. rr_ttl[i] ttl of rr i. 405 406 .. attribute:: rr_data[] 407 408 Array of RR's rdata (list of strings). The rdata is stored in uncompressed wireformat. 409 The first 16B of rr_data[i] is rdlength in network format. 410 411 412DNSMessage 413---------------- 414 415.. class:: DNSMessage 416 417 Abstract representation of DNS message. 418 419 **Usage** 420 421 This example shows how to create an authoritative answer response 422 423 :: 424 425 msg = DNSMessage(qstate.qinfo.qname_str, RR_TYPE_A, RR_CLASS_IN, PKT_AA) 426 427 #append RR 428 if (qstate.qinfo.qtype == RR_TYPE_A) or (qstate.qinfo.qtype == RR_TYPE_ANY): 429 msg.answer.append("%s 10 IN A 127.0.0.1" % qstate.qinfo.qname_str) 430 431 #set qstate.return_msg 432 if not msg.set_return_msg(qstate): 433 raise Exception("Can't create response") 434 435 The :class:`DNSMessage` provides these methods and data attributes: 436 437 .. method:: __init__(self, rr_name, rr_type, rr_class = RR_CLASS_IN, query_flags = 0, default_ttl = 0) 438 439 Prepares an answer (DNS packet) from given information. Query flags are combination of PKT_xx constants. 440 441 .. method:: set_return_msg(self, qstate) 442 443 This method fills qstate return message according to the given information. 444 It takes lists of RRs in each section of answer, created necessary RRsets in wire format and store the result in :attr:`qstate.return_msg`. 445 Returns 1 if OK. 446 447 .. attribute:: rr_name 448 449 RR name of question. 450 451 .. attribute:: rr_type 452 453 RR type of question. 454 455 .. attribute:: rr_class 456 457 RR class of question. 458 459 .. attribute:: default_ttl 460 461 Default time-to-live. 462 463 .. attribute:: query_flags 464 465 Query flags. See PKT\_ predefined constants. 466 467 .. attribute:: question[] 468 469 List of resource records that should appear (in the same order) in question section of answer. 470 471 .. attribute:: answer[] 472 473 List of resource records that should appear (in the same order) in answer section of answer. 474 475 .. attribute:: authority[] 476 477 List of resource records that should appear (in the same order) in authority section of answer. 478 479 .. attribute:: additional[] 480 481 List of resource records that should appear (in the same order) in additional section of answer. 482 483pythonmod_env 484----------------------- 485 486.. class:: pythonmod_env 487 488 Global state for the module. 489 490 This class provides these data attributes: 491 492 .. attribute:: data 493 494 Here you can keep your own data shared across each thread. 495 496 .. attribute:: fname 497 498 Python script filename. 499 500 .. attribute:: qstate 501 502 Module query state. 503 504pythonmod_qstate 505----------------------- 506 507.. class:: pythonmod_qstate 508 509 Per query state for the iterator module. 510 511 This class provides these data attributes: 512 513 .. attribute:: data 514 515 Here you can keep your own private data (each thread has own data object). 516 517sockaddr_storage 518------------------------- 519 520.. class:: sockaddr_storage 521 522 The :class:`sockaddr_storage` provides these data attributes: 523 524 .. attribute:: family 525 526 Address family name as a string. Possible values are `ip4`, `ip6`, and `unix`. 527 528 .. attribute:: addr 529 530 Address in presentation format. 531 532 .. attribute:: raw_addr 533 534 Address in network wire format. 535 536 .. attribute:: port 537 538 Port number. Invalid for Unix address. 539 540 .. attribute:: flowinfo 541 542 Flow info value. Valid only for IPv6 address. 543 544 .. attribute:: scope_id 545 546 Scope ID value. Valid only for IPv6 address. 547