Go to file
Willem Toorop 6c5b23f53a Merge branch 'develop' of github.com:verisign/getdns into develop 2013-12-06 16:29:27 +01:00
doc fix issue #38: install, uninstall, libtool, configureoutsidesrcdir, 2013-11-29 15:41:06 +01:00
m4 This commit adds the configure script to the repo. 2013-12-03 16:29:44 +01:00
project-doc Moved project internal documents into their own directory 2013-11-21 15:49:30 -08:00
spec [API 0.370] getdns_context_set_memory_function*s*! 2013-12-06 16:02:32 +01:00
src Two forgotten _TEXT quotes 2013-12-06 15:57:22 +01:00
.gitignore This commit adds the configure script to the repo. 2013-12-03 16:29:44 +01:00
.indent.pro Ran indent with the indent.pro committed 2013-11-05 15:03:44 -05:00
AUTHORS separated libunbound test in configure.ac to give better diag msg 2013-11-03 16:40:24 -05:00
COPYING another file required by automake. using a symlink to LICENSE 2013-08-08 17:39:45 -08:00
ChangeLog Converted makefile generation to automake 2013-08-08 17:21:05 -08:00
CodingStyle added extension validation to the primary entry point to catch bogus 2013-11-04 18:37:54 -05:00
INSTALL Removed symlink ltmain.sh. Add m4 for lt. 2013-08-09 10:48:22 -04:00
LICENSE Change license from MIT to BSD-new 2013-09-11 18:41:23 -04:00
Makefile.in Portable with event1.x, test succeeds on FreeBSD 2013-11-30 13:53:57 +01:00
NEWS separated libunbound test in configure.ac to give better diag msg 2013-11-03 16:40:24 -05:00
README automake version dep noted 2013-08-30 14:19:03 -04:00
README.md Update README.md 2013-12-06 10:01:37 -05:00
aclocal.m4 This commit adds the configure script to the repo. 2013-12-03 16:29:44 +01:00
config.guess This commit adds the configure script to the repo. 2013-12-03 16:29:44 +01:00
config.sub This commit adds the configure script to the repo. 2013-12-03 16:29:44 +01:00
configure This commit adds the configure script to the repo. 2013-12-03 16:29:44 +01:00
configure.ac Get rid of stdbool.h 2013-12-06 14:10:28 +01:00
install-sh Converted makefile generation to automake 2013-08-08 17:21:05 -08:00
ltmain.sh This commit adds the configure script to the repo. 2013-12-03 16:29:44 +01:00
missing necessary for automake/autoconf 2013-08-08 17:31:42 -08:00

README.md

getdns API

getdns is a modern asynchronous DNS API intended to make all types of DNS information easily available as described by Paul Hoffman. This implementation is licensed under the New BSD License (BSD-new).

The getdns-api mailing list is a good place to engage in discussions regarding the design of the API.

This file captures the goals and direction of the project and the current state of the implementation.

The goals of this implementation of the getdns API are:

  • Provide an open source implementation, in C, of the formally described getdns API by Paul Hoffman at http://www.vpnc.org/getdns-api/
  • Initial support for FreeBSD x.y, MS-Windows Ver. X, OSX 10.x, Linux (CentOS/RHEL R6uX, Ubuntu Ver X) via functional "configure" script
  • Initial support to include the Android platform
  • Include examples and tests as part of the build
  • Document code using doxygen
  • Leverage github as much as possible for project coordination
  • Coding style/standards follow the BSD coding style ftp://ftp.netbsd.org/pub/NetBSD/NetBSD-current/src/share/misc/style
  • Follow the git flow branching model described at http://nvie.com/posts/a-successful-git-branching-model/ ** the master branch is always in a production ready state ** the develop branch contains the latest development changes which are merged from develop into master once they are considered production ready
  • Both synchronous and asynchronous entry points with an early focus on the asynchronous model

Non-goals (things we will not be doing) include:

  • implementation of the traditional DNS related routines (gethostbyname, etc.)

Releases

Release numbering follows the Semantic Versioning approach. We are currently in the early stages of building the API so the code should be considered incomplete.

The 0.1.0 release will be issued when the repository is opened to the public, our goal is to meet the following requirements prior to opening the repository:

  • code compiles cleanly on at least the primary target platforms: RHEL/CentOS 6.3 Linux, FreeBSD 9.2
  • examples must compile and be clean
  • clearly document supported/unsupported elements of the API

Tickets/Bug Reports

Tickets and bug reports from external contacts are received via a mailing list and managed in the git issues list.

TBD: mailing list address

External Dependencies

External dependencies are linked outside the getdns API build tree (we rely on configure to find them). We would like to keep the dependency tree short.

  • libevent version 2.0.21 stable Sometimes called libevent2
  • libldns from NL version 1.6.16 (ldns may require openssl headers and libraries)
  • libunbound from NL svn revision 3012, configure must be run with the --with-libevent option (recommended to also use --with-libunbound-only).
  • libexpat for libunbound.
  • libidn from the FSF version 1.
  • Doxygen is used to generate documentation, while this is not technically necessary for the build it makes things a lot more pleasant.

You have to install the library and also the library-devel (or -dev) for your package management system to install the compile time files. If you checked out our git; the configure script is built with autoreconf --install.

Assuming that the getdns sources are in a diretory named getdns in your home directory, to build libunbound:

# mkdir unbound
# cd unbound
# svn export -r 3023 http://unbound.nlnetlabs.nl/svn/trunk
# cd trunk
# ./configure --with-libevent --with-libunbound-only
### add --disable-gost --disable-ecdsa if elliptic curves are disabled for you.
# make
# make install

Unsupported Features

The following API calls are documented in getDNS but not supported by the implementation at this time:

  • Support for OPT Records in getdns_general and variants via the extensions parameter.
  • getdns_convert_dns_name_to_fqdn and getdns_convert_fqdn_to_dns_name
  • EDNS options
    • getdns_context_set_edns_do_bit
    • getdns_context_set_edns_version
    • getdns_context_set_edns_extended_rcode
  • GETDNS_CONTEXT_TCP_ONLY_KEEP_CONNECTIONS_OPEN with getdns_context_set_dns_transport
  • DNS Search suffixes / local file support
    • getdns_context_set_append_name
    • getdns_context_set_suffix
  • Setting root servers via getdns_context_set_dns_root_servers
  • DNSSEC
    • getdns_context_set_dnssec_trust_anchors
    • getdns_validate_dnssec
  • Detecting changes to resolv.conf and hosts

Spec Differences

This implementation makes a few modifications to the spec by adding the following methods to the public API:

  • getdns_context_set_memory_functions replaces getdns_context_set_memory_allocator, getdns_context_set_memory_deallocator, and getdns_context_set_memory_reallocator
  • getdns_list_create_with_context, getdns_list_create_with_memory_functions, getdns_dict_create_with_context, and getdns_dict_create_with_memory_functions` to create lists and dictionaries with context or user supplied memory management functions.

#Supported Platforms

The primary platforms targeted are Linux and FreeBSD, other platform are supported as we get time. The names listed here are intended to help ensure that we catch platform specific breakage, not to limit the work that folks are doing.

Where at all possible we need to make sure that both 32 and 64 bit implementations work.

  • Android, Neel
  • FreeBSD 9.2, gcc/clang Melinda
  • FreeBSD 10.0 (not yet released), gcc/clang Melinda
  • Linux RHEL/CentOS 6.x, Glen
  • MS-Windows 8, cygwin, Neel
  • NetBSD x.x, Wouter
  • OpenBSD 5.3, Wouter
  • OSX 10.8, Glen
  • OSX 10.9, Allison
  • Ubuntu 12.x, Melinda

The NLNet folks offered to build on a number of legacy platforms as well to help ensure that the code is clean. These include some big endian hardware and a few more obscure operating systems which will not be publicly supported but might work if someone wants to try them.

##Build Reports

TBD

Contributors

  • Neel Goyal, Verisign, Inc.
  • Allison Mankin, Verisign, Inc.
  • Melinda Shore, No Mountain Software LLC
  • Willem Toorop, NLNet Labs
  • Glen Wiley, Verisign, Inc.
  • Wouter Wijngaards, NLNet Labs

-- end README