third_party/dnspython/README

   1 dnspython
   2
   3 INTRODUCTION
   4
   5 dnspython is a DNS toolkit for Python. It supports almost all record
   6 types. It can be used for queries, zone transfers, and dynamic
   7 updates.  It supports TSIG authenticated messages and EDNS0.
   8
   9 dnspython provides both high and low level access to DNS. The high
  10 level classes perform queries for data of a given name, type, and
  11 class, and return an answer set.  The low level classes allow direct
  12 manipulation of DNS zones, messages, names, and records.
  13
  14 To see a few of the ways dnspython can be used, look in the examples/
  15 directory.
  16
  17 dnspython originated at Nominum where it was developed to facilitate
  18 the testing of DNS software.  Nominum has generously allowed it to be
  19 open sourced under a BSD-style license, and helps support its future
  20 development by continuing to employ the author :).
  21
  22
  23 ABOUT THIS RELEASE
  24
  25 This is dnspython 1.10.0
  26
  27 New since 1.9.4:
  28
  29         XXX TBS.
  30
  31 Bugs fixed since 1.9.4:
  32
  33         XXX TBS.
  34
  35 New since 1.9.3:
  36
  37         Nothing.
  38
  39 Bugs fixed since 1.9.3:
  40
  41         The rdata _wire_cmp() routine now handles relative names.
  42
  43         The SIG RR implementation was missing 'import struct'.
  44
  45 New since 1.9.2:
  46
  47         A boolean parameter, 'raise_on_no_answer', has been added to
  48         the query() methods.  In no-error, no-data situations, this
  49         parameter determines whether NoAnswer should be raised or not.
  50         If True, NoAnswer is raised.  If False, then an Answer()
  51         object with a None rrset will be returned.
  52
  53         Resolver Answer() objects now have a canonical_name field.
  54
  55         Rdata now have a __hash__ method.
  56
  57 Bugs fixed since 1.9.2:
  58
  59         Dnspython was erroneously doing case-insensitive comparisons
  60         of the names in NSEC and RRSIG RRs.
  61
  62         We now use "is" and not "==" when testing what section an RR
  63         is in.
  64
  65         The resolver now disallows metaqueries.
  66
  67 New since 1.9.1:
  68
  69         Nothing.
  70
  71 Bugs fixed since 1.9.1:
  72
  73         The dns.dnssec module didn't work at all due to missing
  74         imports that escaped detection in testing because the test
  75         suite also did the imports.  The third time is the charm!
  76
  77 New since 1.9.0:
  78
  79         Nothing.
  80
  81 Bugs fixed since 1.9.0:
  82
  83         The dns.dnssec module didn't work with DSA due to namespace
  84         contamination from a "from"-style import.
  85
  86 New since 1.8.0:
  87
  88         dnspython now uses poll() instead of select() when available.
  89
  90         Basic DNSSEC validation can be done using dns.dnsec.validate()
  91         and dns.dnssec.validate_rrsig() if you have PyCrypto 2.3 or
  92         later installed.  Complete secure resolution is not yet
  93         available.
  94
  95         Added key_id() to the DNSSEC module, which computes the DNSSEC
  96         key id of a DNSKEY rdata.
  97
  98         Added make_ds() to the DNSSEC module, which returns the DS RR
  99         for a given DNSKEY rdata.
 100
 101         dnspython now raises an exception if HMAC-SHA284 or
 102         HMAC-SHA512 are used with a Python older than 2.5.2.  (Older
 103         Pythons do not compute the correct value.)
 104
 105         Symbolic constants are now available for TSIG algorithm names.
 106
 107 Bugs fixed since 1.8.0
 108
 109         dns.resolver.zone_for_name() didn't handle a query response
 110         with a CNAME or DNAME correctly in some cases.
 111
 112         When specifying rdata types and classes as text, Unicode
 113         strings may now be used.
 114
 115         Hashlib compatibility issues have been fixed.
 116
 117         dns.message now imports dns.edns.
 118
 119         The TSIG algorithm value was passed incorrectly to use_tsig()
 120         in some cases.
 121
 122 New since 1.7.1:
 123
 124         Support for hmac-sha1, hmac-sha224, hmac-sha256, hmac-sha384
 125         and hmac-sha512 has been contributed by Kevin Chen.
 126
 127         The tokenizer's tokens are now Token objects instead of (type,
 128         value) tuples.
 129
 130 Bugs fixed since 1.7.1:
 131
 132         Escapes in masterfiles now work correctly.  Previously they
 133         were only working correctly when the text involved was part of
 134         a domain name.
 135
 136         When constructing a DDNS update, if the present() method was
 137         used with a single rdata, a zero TTL was not added.
 138
 139         The entropy pool needed locking to be thread safe.
 140
 141         The entropy pool's reading of /dev/random could cause
 142         dnspython to block.
 143
 144         The entropy pool did buffered reads, potentially consuming more
 145         randomness than we needed.
 146
 147         The entropy pool did not seed with high quality randomness on
 148         Windows.
 149
 150         SRV records were compared incorrectly.
 151
 152         In the e164 query function, the resolver parameter was not
 153         used.
 154
 155 New since 1.7.0:
 156
 157         Nothing
 158
 159 Bugs fixed since 1.7.0:
 160
 161         The 1.7.0 kitting process inadventently omitted the code for the
 162         DLV RR.
 163
 164         Negative DDNS prerequisites are now handled correctly.
 165
 166 New since 1.6.0:
 167
 168         Rdatas now have a to_digestable() method, which returns the
 169         DNSSEC canonical form of the rdata, suitable for use in
 170         signature computations.
 171
 172         The NSEC3, NSEC3PARAM, DLV, and HIP RR types are now supported.
 173
 174         An entropy module has been added and is used to randomize query ids.
 175
 176         EDNS0 options are now supported.
 177
 178         UDP IXFR is now supported.
 179
 180         The wire format parser now has a 'one_rr_per_rrset' mode, which
 181         suppresses the usual coalescing of all RRs of a given type into a
 182         single RRset.
 183
 184         Various helpful DNSSEC-related constants are now defined.
 185
 186         The resolver's query() method now has an optional 'source' parameter,
 187         allowing the source IP address to be specified.
 188
 189 Bugs fixed since 1.6.0:
 190
 191         On Windows, the resolver set the domain incorrectly.
 192
 193         DS RR parsing only allowed one Base64 chunk.
 194
 195         TSIG validation didn't always use absolute names.
 196
 197         NSEC.to_text() only printed the last window.
 198
 199         We did not canonicalize IPv6 addresses before comparing them; we
 200         would thus treat equivalent but different textual forms, e.g.
 201         "1:00::1" and "1::1" as being non-equivalent.
 202
 203         If the peer set a TSIG error, we didn't raise an exception.
 204
 205         Some EDNS bugs in the message code have been fixed (see the ChangeLog
 206         for details).
 207
 208 New since 1.5.0:
 209         Added dns.inet.is_multicast().
 210
 211 Bugs fixed since 1.5.0:
 212
 213         If select() raises an exception due to EINTR, we should just
 214         select() again.
 215
 216         If the queried address is a multicast address, then don't
 217         check that the address of the response is the same as the
 218         address queried.
 219
 220         NAPTR comparisons didn't compare the preference field due to a
 221         typo.
 222
 223         Testing of whether a Windows NIC is enabled now works on Vista
 224         thanks to code contributed by Paul Marks.
 225
 226 New since 1.4.0:
 227
 228         Answer objects now support more of the python sequence
 229         protocol, forwarding the requests to the answer rrset.
 230         E.g. "for a in answer" is equivalent to "for a in
 231         answer.rrset", "answer[i]" is equivalent to "answer.rrset[i]",
 232         and "answer[i:j]" is equivalent to "answer.rrset[i:j]".
 233
 234         Making requests using EDNS, including indicating DNSSEC awareness,
 235         is now easier.  For example, you can now say:
 236
 237            q = dns.message.make_query('www.dnspython.org', 'MX',
 238                                       want_dnssec=True)
 239
 240         dns.query.xfr() can now be used for IXFR.
 241
 242         Support has been added for the DHCID, IPSECKEY, and SPF RR types.
 243
 244         UDP messages from unexpected sources can now be ignored by
 245         setting ignore_unexpected to True when calling dns.query.udp.
 246
 247 Bugs fixed since 1.4.0:
 248
 249         If /etc/resolv.conf didn't exist, we raised an exception
 250         instead of simply using the default resolver configuration.
 251
 252         In dns.resolver.Resolver._config_win32_fromkey(), we were
 253         passing the wrong variable to self._config_win32_search().
 254
 255 New since 1.3.5:
 256
 257         You can now convert E.164 numbers to/from their ENUM name
 258         forms:
 259
 260               >>> import dns.e164
 261               >>> n = dns.e164.from_e164("+1 555 1212")
 262               >>> n
 263               <DNS name 2.1.2.1.5.5.5.1.e164.arpa.>
 264               >>> dns.e164.to_e164(n)
 265               '+15551212'
 266
 267         You can now convert IPv4 and IPv6 address to/from their
 268         corresponding DNS reverse map names:
 269
 270               >>> import dns.reversename
 271               >>> n = dns.reversename.from_address("127.0.0.1")
 272               >>> n
 273               <DNS name 1.0.0.127.in-addr.arpa.>
 274               >>> dns.reversename.to_address(n)
 275               '127.0.0.1'
 276
 277         You can now convert between Unicode strings and their IDN ACE
 278         form:
 279
 280               >>> n = dns.name.from_text(u'les-\u00e9l\u00e8ves.example.')
 281               >>> n
 282               <DNS name xn--les-lves-50ai.example.>
 283               >>> n.to_unicode()
 284               u'les-\xe9l\xe8ves.example.'
 285
 286         The origin parameter to dns.zone.from_text() and dns.zone.to_text()
 287         is now optional.  If not specified, the origin will be taken from
 288         the first $ORIGIN statement in the master file.
 289
 290         Sanity checking of a zone can be disabled; this is useful when
 291         working with files which are zone fragments.
 292
 293 Bugs fixed since 1.3.5:
 294
 295         The correct delimiter was not used when retrieving the
 296         list of nameservers from the registry in certain versions of
 297         windows.
 298
 299         The floating-point version of latitude and longitude in LOC RRs
 300         (float_latitude and float_longitude) had incorrect signs for
 301         south latitudes and west longitudes.
 302
 303         BIND 8 TTL syntax is now accepted in all TTL-like places (i.e.
 304         SOA fields refresh, retry, expire, and minimum; SIG/RRSIG
 305         field original_ttl).
 306
 307         TTLs are now bounds checked when their text form is parsed,
 308         and their values must be in the closed interval [0, 2^31 - 1].
 309
 310 New since 1.3.4:
 311
 312         In the resolver, if time goes backward a little bit, ignore
 313         it.
 314
 315         zone_for_name() has been added to the resolver module.  It
 316         returns the zone which is authoritative for the specified
 317         name, which is handy for dynamic update.  E.g.
 318
 319               import dns.resolver
 320               print dns.resolver.zone_for_name('www.dnspython.org')
 321
 322         will output "dnspython.org." and
 323
 324               print dns.resolver.zone_for_name('a.b.c.d.e.f.example.')
 325
 326         will output ".".
 327
 328         The default resolver can be fetched with the
 329         get_default_resolver() method.
 330
 331         You can now get the parent (immediate superdomain) of a name
 332         by using the parent() method.
 333
 334         Zone.iterate_rdatasets() and Zone.iterate_rdatas() now have
 335         a default rdtype of dns.rdatatype.ANY like the documentation
 336         says.
 337
 338         A Dynamic DNS example, ddns.py, has been added.
 339
 340 New since 1.3.3:
 341
 342         The source address and port may now be specified when calling
 343         dns.query.{udp,tcp,xfr}.
 344
 345         The resolver now does exponential backoff each time it runs
 346         through all of the nameservers.
 347
 348         Rcodes which indicate a nameserver is likely to be a
 349         "permanent failure" for a query cause the nameserver to be removed
 350         from the mix for that query.
 351
 352 New since 1.3.2:
 353
 354         dns.message.Message.find_rrset() now uses an index, vastly
 355         improving the from_wire() performance of large messages such
 356         as zone transfers.
 357
 358         Added dns.message.make_response(), which creates a skeletal
 359         response for the specified query.
 360
 361         Added opcode() and set_opcode() convenience methods to the
 362         dns.message.Message class.  Added the request_payload
 363         attribute to the Message class.
 364
 365         The 'file' parameter of dns.name.Name.to_wire() is now
 366         optional; if omitted, the wire form will be returned as the
 367         value of the function.
 368
 369         dns.zone.from_xfr() in relativization mode incorrectly set
 370         zone.origin to the empty name.
 371
 372         The masterfile parser incorrectly rejected TXT records where a
 373         value was not quoted.
 374
 375 New since 1.3.1:
 376
 377         The NSEC format doesn't allow specifying types by number, so
 378         we shouldn't either.  (Using the unknown type format is still
 379         OK though.)
 380
 381         The resolver wasn't catching dns.exception.Timeout, so a timeout
 382         erroneously caused the whole resolution to fail instead of just
 383         going on to the next server.
 384
 385         The renderer module didn't import random, causing an exception
 386         to be raised if a query id wasn't provided when a Renderer was
 387         created.
 388
 389         The conversion of LOC milliseconds values from text to binary was
 390         incorrect if the length of the milliseconds string was not 3.
 391
 392 New since 1.3.0:
 393
 394         Added support for the SSHFP type.
 395
 396 New since 1.2.0:
 397
 398         Added support for new DNSSEC types RRSIG, NSEC, and DNSKEY.
 399
 400 This release fixes all known bugs.
 401
 402 See the ChangeLog file for more detailed information on changes since
 403 the prior release.
 404
 405
 406 REQUIREMENTS
 407
 408 Python 2.4 or later.
 409
 410
 411 INSTALLATION
 412
 413 To build and install dnspython, type
 414
 415         python setup.py install
 416
 417
 418 HOME PAGE
 419
 420 For the latest in releases, documentation, and information, visit the
 421 dnspython home page at
 422
 423         http://www.dnspython.org/
 424
 425
 426
 427 DOCUMENTATION
 428
 429 Documentation is sparse at the moment.  Use pydoc, or read the HTML
 430 documentation at the dnspython home page, or download the HTML
 431 documentation.
 432
 433
 434 BUG REPORTS
 435
 436 Bug reports may be sent to bugs@dnspython.org
 437
 438
 439 MAILING LISTS
 440
 441 A number of mailing lists are available.  Visit the dnspython home
 442 page to subscribe or unsubscribe.