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