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