unbound/pythonmod/doc/modules/struct.rst

   1 Scriptable structures
   2 =====================
   3
   4 module_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`) Informations 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
  59 query_info
  60 ----------------
  61
  62 .. class:: query_info
  63
  64    This class provides these data attributes:
  65
  66    .. attribute:: qname
  67
  68       The original question in the wireformat format (e.g. \\x03www\\x03nic\\x02cz\\x00 for www.nic.cz)
  69
  70    .. attribute:: qname_len
  71
  72       Lenght of question name (number of bytes).
  73
  74    .. attribute:: qname_list[]
  75
  76       The question ``qname`` converted into list of labels (e.g. ['www','nic','cz',''] for www.nic.cz)
  77
  78    .. attribute:: qname_str
  79
  80       The question ``qname`` converted into string (e.g. www.nic.cz. for www.nic.cz)
  81
  82    .. attribute:: qtype
  83
  84       The class type asked for. See RR_TYPE\_ predefined constants.
  85
  86    .. attribute:: qtype_str
  87
  88       The ``qtype`` in display presentation format (string) (e.g 'A' for RR_TYPE_A)
  89
  90    .. attribute:: qclass
  91
  92       The question class. See RR_CLASS\_ predefined constants.
  93
  94    .. attribute:: qclass_str
  95
  96       The ``qclass`` in display presentation format (string).
  97
  98 reply_info
  99 --------------------
 100
 101 .. class:: reply_info
 102
 103    This class provides these data attributes:
 104
 105    .. attribute:: flags
 106
 107       The flags for the answer, host byte order.
 108
 109    .. attribute:: qdcount
 110
 111       Number of RRs in the query section.
 112       If qdcount is not 0, then it is 1, and the data that appears
 113       in the reply is the same as the query_info.
 114       Host byte order.
 115
 116    .. attribute:: ttl
 117
 118       TTL of the entire reply (for negative caching).
 119       only for use when there are 0 RRsets in this message.
 120       if there are RRsets, check those instead.
 121
 122    .. attribute:: security
 123
 124       The security status from DNSSEC validation of this message. See sec_status\_ predefined constants.
 125
 126    .. attribute:: an_numrrsets
 127
 128       Number of RRsets in each section.
 129       The answer section. Add up the RRs in every RRset to calculate
 130       the number of RRs, and the count for the dns packet.
 131       The number of RRs in RRsets can change due to RRset updates.
 132
 133    .. attribute:: ns_numrrsets
 134
 135       Count of authority section RRsets
 136
 137    .. attribute:: ar_numrrsets
 138
 139       Count of additional section RRsets
 140
 141    .. attribute:: rrset_count
 142
 143       Number of RRsets: an_numrrsets + ns_numrrsets + ar_numrrsets
 144
 145    .. attribute:: rrsets[]
 146
 147          (:class:`ub_packed_rrset_key`) List of RR sets in the order in which they appear in the reply message.
 148          Number of elements is ancount + nscount + arcount RRsets.
 149
 150    .. attribute:: ref[]
 151
 152          (:class:`rrset_ref`) Packed array of ids (see counts) and pointers to packed_rrset_key.
 153          The number equals ancount + nscount + arcount RRsets.
 154          These are sorted in ascending pointer, the locking order. So
 155          this list can be locked (and id, ttl checked), to see if
 156          all the data is available and recent enough.
 157
 158
 159 dns_msg
 160 --------------
 161
 162 .. class:: dns_msg
 163
 164    Region allocated message reply
 165
 166    This class provides these data attributes:
 167
 168    .. attribute:: qinfo
 169
 170       (:class:`query_info`) Informations about query.
 171
 172    .. attribute:: rep
 173
 174       (:class:`reply_info`) This attribute points to the packed reply structure.
 175
 176
 177 packed_rrset_key
 178 ----------------------
 179
 180 .. class:: packed_rrset_key
 181
 182    The identifying information for an RRset.
 183
 184    This class provides these data attributes:
 185
 186    .. attribute:: dname
 187
 188       The domain name. If not empty (for ``id = None``) it is allocated, and
 189       contains the wireformat domain name. This dname is not canonicalized.
 190       E.g., the dname contains \\x03www\\x03nic\\x02cz\\x00 for www.nic.cz.
 191
 192    .. attribute:: dname_len
 193
 194       Length of the domain name, including last 0 root octet.
 195
 196    .. attribute:: dname_list[]
 197
 198       The domain name ``dname`` converted into list of labels (see :attr:`query_info.qname_list`).
 199
 200    .. attribute:: dname_str
 201
 202       The domain name ``dname`` converted into string (see :attr:`query_info.qname_str`).
 203
 204    .. attribute:: flags
 205
 206       Flags.
 207
 208    .. attribute:: type
 209
 210       The rrset type in network format.
 211
 212    .. attribute:: type_str
 213
 214       The rrset type in display presentation format.
 215
 216    .. attribute:: rrset_class
 217
 218       The rrset class in network format.
 219
 220    .. attribute:: rrset_class_str
 221
 222       The rrset class in display presentation format.
 223
 224 ub_packed_rrset_key
 225 -------------------------
 226
 227 .. class:: ub_packed_rrset_key
 228
 229    This structure contains an RRset. A set of resource records that
 230    share the same domain name, type and class.
 231    Due to memory management and threading, the key structure cannot be
 232    deleted, although the data can be. The id can be set to 0 to store and the
 233    structure can be recycled with a new id.
 234
 235    The :class:`ub_packed_rrset_key` provides these data attributes:
 236
 237    .. attribute:: entry
 238
 239       (:class:`lruhash_entry`) Entry into hashtable. Note the lock is never destroyed,
 240       even when this key is retired to the cache.
 241       the data pointer (if not None) points to a :class:`packed_rrset`.
 242
 243    .. attribute:: id
 244
 245       The ID of this rrset. unique, based on threadid + sequenceno.
 246       ids are not reused, except after flushing the cache.
 247       zero is an unused entry, and never a valid id.
 248       Check this value after getting entry.lock.
 249       The other values in this struct may only be altered after changing
 250       the id (which needs a writelock on entry.lock).
 251
 252    .. attribute:: rk
 253
 254       (:class:`packed_rrset_key`) RR set data.
 255
 256
 257 lruhash_entry
 258 -------------------------
 259
 260 .. class:: lruhash_entry
 261
 262    The :class:`ub_packed_rrset_key` provides these data attributes:
 263
 264    .. attribute:: lock
 265
 266       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.
 267
 268    .. attribute:: data
 269
 270       (:class:`packed_rrset_data`) entry data stored in wireformat (RRs and RRsigs).
 271
 272 packed_rrset_data
 273 -----------------------
 274
 275 .. class:: packed_rrset_data
 276
 277    Rdata is stored in wireformat. The dname is stored in wireformat.
 278
 279    TTLs are stored as absolute values (and could be expired).
 280
 281    RRSIGs are stored in the arrays after the regular rrs.
 282
 283    You need the packed_rrset_key to know dname, type, class of the
 284    resource records in this RRset. (if signed the rrsig gives the type too).
 285
 286    The :class:`packed_rrset_data` provides these data attributes:
 287
 288    .. attribute:: ttl
 289
 290       TTL (in seconds like time()) of the RRset.
 291       Same for all RRs see rfc2181(5.2).
 292
 293    .. attribute:: count
 294
 295       Number of RRs.
 296
 297    .. attribute:: rrsig_count
 298
 299       Number of rrsigs, if 0 no rrsigs.
 300
 301    .. attribute:: trust
 302
 303       The trustworthiness of the RRset data.
 304
 305    .. attribute:: security
 306
 307       Security status of the RRset data. See sec_status\_ predefined constants.
 308
 309    .. attribute:: rr_len[]
 310
 311       Length of every RR's rdata, rr_len[i] is size of rr_data[i].
 312
 313    .. attribute:: rr_ttl[]
 314
 315       TTL of every rr. rr_ttl[i] ttl of rr i.
 316
 317    .. attribute:: rr_data[]
 318
 319       Array of RR's rdata (list of strings). The rdata is stored in uncompressed wireformat.
 320       The first 16B of rr_data[i] is rdlength in network format.
 321
 322
 323 DNSMessage
 324 ----------------
 325
 326 .. class:: DNSMessage
 327
 328    Abstract representation of DNS message.
 329
 330    **Usage**
 331
 332       This example shows how to create an authoritative answer response
 333
 334       ::
 335
 336          msg = DNSMessage(qstate.qinfo.qname_str, RR_TYPE_A, RR_CLASS_IN, PKT_AA)
 337
 338          #append RR
 339          if (qstate.qinfo.qtype == RR_TYPE_A) or (qstate.qinfo.qtype == RR_TYPE_ANY):
 340              msg.answer.append("%s 10 IN A 127.0.0.1" % qstate.qinfo.qname_str)
 341
 342          #set qstate.return_msg
 343          if not msg.set_return_msg(qstate):
 344              raise Exception("Can't create response")
 345
 346    The :class:`DNSMessage` provides these methods and data attributes:
 347
 348    .. method:: __init__(self, rr_name, rr_type, rr_class = RR_CLASS_IN, query_flags = 0, default_ttl = 0)
 349
 350       Prepares an answer (DNS packet) from qiven information. Query flags are combination of PKT_xx contants.
 351
 352    .. method:: set_return_msg(self, qstate)
 353
 354       This method fills qstate return message according to the given informations.
 355                 It takes lists of RRs in each section of answer, created necessray RRsets in wire format and store the result in :attr:`qstate.return_msg`.
 356                 Returns 1 if OK.
 357
 358    .. attribute:: rr_name
 359
 360       RR name of question.
 361
 362    .. attribute:: rr_type
 363
 364       RR type of question.
 365
 366    .. attribute:: rr_class
 367
 368       RR class of question.
 369
 370    .. attribute:: default_ttl
 371
 372       Default time-to-live.
 373
 374    .. attribute:: query_flags
 375
 376       Query flags. See PKT\_ predefined constants.
 377
 378    .. attribute:: question[]
 379
 380       List of resource records that should appear (in the same order) in question section of answer.
 381
 382    .. attribute:: answer[]
 383
 384       List of resource records that should appear (in the same order) in answer section of answer.
 385
 386    .. attribute:: authority[]
 387
 388       List of resource records that should appear (in the same order) in authority section of answer.
 389
 390    .. attribute:: additional[]
 391
 392       List of resource records that should appear (in the same order) in additional section of answer.
 393
 394 pythonmod_env
 395 -----------------------
 396
 397 .. class:: pythonmod_env
 398
 399    Global state for the module.
 400
 401    This class provides these data attributes:
 402
 403    .. attribute:: data
 404
 405       Here you can keep your own data shared across each thread.
 406
 407    .. attribute:: fname
 408
 409         Python script filename.
 410
 411    .. attribute:: qstate
 412
 413       Module query state.
 414
 415 pythonmod_qstate
 416 -----------------------
 417
 418 .. class:: pythonmod_qstate
 419
 420    Per query state for the iterator module.
 421
 422    This class provides these data attributes:
 423
 424    .. attribute:: data
 425
 426            Here you can keep your own private data (each thread has own data object).
 427