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