+BIND Source Access and Contributor Guidelines
+
+Feb 22, 2018
+
+Contents
+
+ 1. Access to source code
+ 2. Reporting bugs
+ 3. Contributing code
+
+Introduction
+
+Thank you for using BIND!
+
+BIND is open source software that implements the Domain Name System (DNS)
+protocols for the Internet. It is a reference implementation of those
+protocols, but it is also production-grade software, suitable for use in
+high-volume and high-reliability applications. It is by far the most
+widely used DNS software, providing a robust and stable platform on top of
+which organizations can build distributed computing systems with the
+knowledge that those systems are fully compliant with published DNS
+standards.
+
+BIND is and will always remain free and openly available. It can be used
+and modified in any way by anyone.
+
+BIND is maintained by the Internet Systems Consortium, a public-benefit
+501(c)(3) nonprofit, using a "managed open source" approach: anyone can
+see the source, but only ISC employees have commit access. Until recently,
+the source could only be seen once ISC had published a release: read
+access to the source repository was restricted just as commit access was.
+That's now changing, with the opening of a public git mirror to the BIND
+source tree (see below).
+
+Access to source code
+
+Public BIND releases are always available from the ISC FTP site.
+
+A public-access GIT repository is also available at https://gitlab.isc.org
+. This repository is a mirror, updated several times per day, of the
+source repository maintained by ISC. It contains all the public release
+branches; upcoming releases can be viewed in their current state at any
+time. It does not contain development branches or unreviewed work in
+progress. Commits which address security vulnerablilities are withheld
+until after public disclosure.
+
+You can browse the source online via https://gitlab.isc.org/isc-projects/
+bind9
+
+To clone the repository, use:
+
+ $ git clone https://gitlab.isc.org/isc-projects/bind9.git
+
+Release branch names are of the form v9_X, where X represents the second
+number in the BIND 9 version number. So, to check out the BIND 9.12
+branch, use:
+
+ $ git checkout v9_12
+
+Whenever a branch is ready for publication, a tag will be placed of the
+form v9_X_Y. The 9.12.0 release, for instance, is tagged as v9_12_0.
+
+The branch in which the next major release is being developed is called
+master.
+
+Reporting bugs
+
+Reports of flaws in the BIND package, including software bugs, errors in
+the documentation, missing files in the tarball, suggested changes or
+requests for new features, etc, can be filed using https://gitlab.isc.org/
+isc-projects/bind9/issues.
+
+Due to a large ticket backlog, we are sometimes slow to respond,
+especially if a bug is cosmetic or if a feature request is vague or low in
+priority, but we will try at least to acknowledge legitimate bug reports
+within a week.
+
+ISC's ticketing system is publicly readable; however, you must have an
+account to file a new issue. You can either register locally or use
+credentials from an existing account at GitHub, GitLab, Google, Twitter,
+or Facebook.
+
+Reporting possible security issues
+
+If you think you may be seeing a potential security vulnerability in BIND
+(for example, a crash with REQUIRE, INSIST, or ASSERT failure), please
+report it immediately by emailing to security-officer@isc.org. Plain-text
+e-mail is not a secure choice for communications concerning undisclosed
+security issues so please encrypt your communications to us if possible,
+using the ISC Security Officer public key.
+
+Do not discuss undisclosed security vulnerabilites on any public mailing
+list. ISC has a long history of handling reported vulnerabilities promptly
+and effectively and we respect and acknowledge responsible reporters.
+
+ISC's Security Vulnerability Disclosure Policy is documented at https://
+kb.isc.org/article/AA-00861/0.
+
+If you have a crash, you may want to consult ?What to do if your BIND or
+DHCP server has crashed.?
+
+Contributing code
+
+BIND is licensed under the Mozilla Public License 2.0. Earier versions
+(BIND 9.10 and earlier) were licensed under the ISC License
+
+ISC does not require an explicit copyright assignment for patch
+contributions. However, by submitting a patch to ISC, you implicitly
+certify that you are the author of the code, that you intend to reliquish
+exclusive copyright, and that you grant permission to publish your work
+under the open source license used for the BIND version(s) to which your
+patch will be applied.
+
+BIND code
+
+Patches for BIND may be submitted directly via merge requests in ISC's
+Gitlab source repository for BIND.
+
+Patches can also be submitted as diffs against a specific version of BIND
+-- preferably the current top of the master branch. Diffs may be generated
+using either git format-patch or git diff.
+
+Those wanting to write code for BIND may be interested in the developer
+information page, which includes information about BIND design and coding
+practices, including discussion of internal APIs and overall system
+architecture. (This is a work in progress, and still quite preliminary.)
+
+Every patch submitted will be reviewed by ISC engineers following our code
+review process before it is merged.
+
+It may take considerable time to review patch submissions, especially if
+they don't meet ISC style and quality guidelines. If a patch is a good
+idea, we can and will do additional work to bring it up to par, but if
+we're busy with other work, it may take us a long time to get to it.
+
+To ensure your patch is acted on as promptly as possible, please:
+
+ * Try to adhere to the BIND 9 coding style.
+ * Run make check to ensure your change hasn't caused any functional
+ regressions.
+ * Document your work, both in the patch itself and in the accompanying
+ email.
+ * In patches that make non-trivial functional changes, include system
+ tests if possible; when introducing or substantially altering a
+ library API, include unit tests. See Testing for more information.
+
+Changes to configure
+
+If you need to make changes to configure, you should not edit it directly;
+instead, edit configure.in, then run autoconf. Similarly, instead of
+editing config.h.in directly, edit configure.in and run autoheader.
+
+When submitting a patch as a diff, it's fine to omit the configure diffs
+to save space. Just send the configure.in diffs and we'll generate the new
+configure during the review process.
+
+Documentation
+
+All functional changes should be documented. There are three types of
+documentation in the BIND source tree:
+
+ * Man pages are kept alongside the source code for the commands they
+ document, in files ending in .docbook; for example, the named man page
+ is bin/named/named.docbook.
+ * The BIND 9 Administrator Reference Manual is mostly in doc/arm/
+ Bv9ARM-book.xml, plus a few other XML files that are included in it.
+ * API documentation is in the header file describing the API, in
+ Doxygen-formatted comments.
+
+It is not necessary to edit any documentation files other than these; all
+PDF, HTML, and nroff-format man page files will be updated automatically
+from the docbook and XML files after merging.
+
+Patches to improve existing documentation are also very welcome!
+
+Tests
+
+BIND is a large and complex project. We rely heavily on continuous
+automated testing and cannot merge new code without adequate test
+coverage. Please see the 'Testing' section of doc/dev/dev.md for more
+information.
+
+Thanks
+
+Thank you for your interest in contributing to the ongoing development of
+BIND.
+BIND 9
+
+Contents
+
+ 1. Introduction
+ 2. Reporting bugs and getting help
+ 3. Contributing to BIND
+ 4. BIND 9.13 features
+ 5. Building BIND
+ 6. macOS
+ 7. Compile-time options
+ 8. Automated testing
+ 9. Documentation
+10. Change log
+11. Acknowledgments
+
+Introduction
+
+BIND (Berkeley Internet Name Domain) is a complete, highly portable
+implementation of the DNS (Domain Name System) protocol.
+
+The BIND name server, named, is able to serve as an authoritative name
+server, recursive resolver, DNS forwarder, or all three simultaneously. It
+implements views for split-horizon DNS, automatic DNSSEC zone signing and
+key management, catalog zones to facilitate provisioning of zone data
+throughout a name server constellation, response policy zones (RPZ) to
+protect clients from malicious data, response rate limiting (RRL) and
+recursive query limits to reduce distributed denial of service attacks,
+and many other advanced DNS features. BIND also includes a suite of
+administrative tools, including the dig and delv DNS lookup tools,
+nsupdate for dynamic DNS zone updates, rndc for remote name server
+administration, and more.
+
+BIND 9 began as a complete re-write of the BIND architecture that was used
+in versions 4 and 8. Internet Systems Consortium (https://www.isc.org), a
+501(c)(3) public benefit corporation dedicated to providing software and
+services in support of the Internet infrastructure, developed BIND 9 and
+is responsible for its ongoing maintenance and improvement. BIND is open
+source software licenced under the terms of the Mozilla Public License,
+version 2.0.
+
+For a summary of features introduced in past major releases of BIND, see
+the file HISTORY.
+
+For a detailed list of changes made throughout the history of BIND 9, see
+the file CHANGES. See below for details on the CHANGES file format.
+
+For up-to-date release notes and errata, see http://www.isc.org/software/
+bind9/releasenotes
+
+For information about supported platforms, see PLATFORMS.
+
+Reporting bugs and getting help
+
+To report non-security-sensitive bugs or request new features, you may
+open an Issue in the BIND 9 project on the ISC GitLab server at https://
+gitlab.isc.org/isc-projects/bind9.
+
+Please note that, unless you explicitly mark the newly created Issue as
+"confidential", it will be publicly readable. Please do not include any
+information in bug reports that you consider to be confidential unless the
+issue has been marked as such. In particular, if submitting the contents
+of your configuration file in a non-confidential Issue, it is advisable to
+obscure key secrets: this can be done automatically by using
+named-checkconf -px.
+
+If the bug you are reporting is a potential security issue, such as an
+assertion failure or other crash in named, please do NOT use GitLab to
+report it. Instead, please send mail to security-officer@isc.org.
+
+Professional support and training for BIND are available from ISC at
+https://www.isc.org/support.
+
+To join the BIND Users mailing list, or view the archives, visit https://
+lists.isc.org/mailman/listinfo/bind-users.
+
+If you're planning on making changes to the BIND 9 source code, you may
+also want to join the BIND Workers mailing list, at https://lists.isc.org/
+mailman/listinfo/bind-workers.
+
+Contributing to BIND
+
+ISC maintains a public git repository for BIND; details can be found at
+http://www.isc.org/git/.
+
+Information for BIND contributors can be found in the following files: -
+General information: CONTRIBUTING.md - BIND 9 code style: doc/dev/style.md
+- BIND architecture and developer guide: doc/dev/dev.md
+
+Patches for BIND may be submitted as Merge Requests in the ISC GitLab
+server at at https://gitlab.isc.org/isc-projects/bind9/merge_requests.
+
+By default, external contributors don't have ability to fork BIND in the
+GitLab server, but if you wish to contribute code to BIND, you may request
+permission to do so. Thereafter, you can create git branches and directly
+submit requests that they be reviewed and merged.
+
+If you prefer, you may also submit code by opening a GitLab Issue and
+including your patch as an attachment, preferably generated by git
+format-patch.
+
+BIND 9.13 features
+
+BIND 9.13 is the newest development branch of BIND 9. It includes a number
+of changes from BIND 9.12 and earlier releases. New features include:
+
+ * The default value of "dnssec-validation" is now "auto".
+ * Support for IDNA2008 when linking with libidn2.
+ * "Root key sentinel" support, enabling validating resolvers to indicate
+ via a special query which trust anchors are configured for the root
+ zone.
+ * Secondary zones can now be configured as "mirror" zones; their
+ contents are transferred in as with traditional slave zones, but are
+ subject to DNSSEC validation and are not treated as authoritative data
+ when answering. This makes it easier to configure a local copy of the
+ root zone as described in RFC 7706.
+ * QNAME minimization is now supported
+ * The "validate-except" option allows configuration of domains below
+ which DNSSEC validation should not be performed.
+
+In addition, cryptographic support has been modernized. BIND now uses the
+best available pseudo-random number generator for the platform on which
+it's built. Very old versions of OpenSSL are no longer supported.
+Cryptography is now mandatory; building BIND without DNSSEC is now longer
+supported.
+
+Building BIND
+
+Minimally, BIND requires a UNIX or Linux system with an ANSI C compiler,
+basic POSIX support, and a 64-bit integer type. Successful builds have
+been observed on many versions of Linux and UNIX, including RedHat,
+Fedora, Debian, Ubuntu, SuSE, Slackware, FreeBSD, NetBSD, OpenBSD, Mac OS
+X, Solaris, HP-UX, and OpenWRT.
+
+BIND requires a cryptography provider library such as OpenSSL or a
+hardware service module supporting PKCS#11. On Linux, BIND requires the
+libcap library to set process privileges, though this requirement can be
+overridden by disabling capability support at compile time. See
+Compile-time options below for details on other libraries that may be
+required to support optional features.
+
+BIND is also available for Windows 2008 and higher. See win32utils/
+readme1st.txt for details on building for Windows systems.
+
+To build on a UNIX or Linux system, use:
+
+ $ ./configure
+ $ make
+
+If you're planning on making changes to the BIND 9 source, you should run
+make depend. If you're using Emacs, you might find make tags helpful.
+
+Several environment variables that can be set before running configure
+will affect compilation:
+
+Variable Description
+CC The C compiler to use. configure tries to figure out the
+ right one for supported systems.
+ C compiler flags. Defaults to include -g and/or -O2 as
+CFLAGS supported by the compiler. Please include '-g' if you need
+ to set CFLAGS.
+ System header file directories. Can be used to specify
+STD_CINCLUDES where add-on thread or IPv6 support is, for example.
+ Defaults to empty string.
+ Any additional preprocessor symbols you want defined.
+STD_CDEFINES Defaults to empty string. For a list of possible settings,
+ see the file OPTIONS.
+LDFLAGS Linker flags. Defaults to empty string.
+BUILD_CC Needed when cross-compiling: the native C compiler to use
+ when building for the target system.
+BUILD_CFLAGS Optional, used for cross-compiling
+BUILD_CPPFLAGS
+BUILD_LDFLAGS
+BUILD_LIBS
+
+macOS
+
+Building on macOS assumes that the "Command Tools for Xcode" is installed.
+This can be downloaded from https://developer.apple.com/download/more/ or
+if you have Xcode already installed you can run "xcode-select --install".
+This will add /usr/include to the system and install the compiler and
+other tools so that they can be easily found.
+
+Compile-time options
+
+To see a full list of configuration options, run configure --help.
+
+On most platforms, BIND 9 is built with multithreading support, allowing
+it to take advantage of multiple CPUs. You can configure this by
+specifying --enable-threads or --disable-threads on the configure command
+line. The default is to enable threads, except on some older operating
+systems on which threads are known to have had problems in the past.
+(Note: Prior to BIND 9.10, the default was to disable threads on Linux
+systems; this has now been reversed. On Linux systems, the threaded build
+is known to change BIND's behavior with respect to file permissions; it
+may be necessary to specify a user with the -u option when running named.)
+
+To build shared libraries, specify --with-libtool on the configure command
+line.
+
+Certain compiled-in constants and default settings can be increased to
+values better suited to large servers with abundant memory resources (e.g,
+64-bit servers with 12G or more of memory) by specifying --with-tuning=
+large on the configure command line. This can improve performance on big
+servers, but will consume more memory and may degrade performance on
+smaller systems.
+
+For the server to support DNSSEC, you need to build it with crypto
+support. To use OpenSSL, you should have OpenSSL 1.0.2e or newer
+installed. If the OpenSSL library is installed in a nonstandard location,
+specify the prefix using --with-openssl=<PREFIX> on the configure command
+line. To use a PKCS#11 hardware service module for cryptographic
+operations, specify the path to the PKCS#11 provider library using
+--with-pkcs11=<PREFIX>, and configure BIND with --enable-native-pkcs11.
+
+To support the HTTP statistics channel, the server must be linked with at
+least one of the following: libxml2 http://xmlsoft.org or json-c https://
+github.com/json-c. If these are installed at a nonstandard location,
+specify the prefix using --with-libxml2=/prefix or --with-libjson=/prefix.
+
+To support compression on the HTTP statistics channel, the server must be
+linked against libzlib. If this is installed in a nonstandard location,
+specify the prefix using --with-zlib=/prefix.
+
+To support storing configuration data for runtime-added zones in an LMDB
+database, the server must be linked with liblmdb. If this is installed in
+a nonstandard location, specify the prefix using with-lmdb=/prefix.
+
+To support GeoIP location-based ACLs, the server must be linked with
+libGeoIP. This is not turned on by default; BIND must be configured with
+--with-geoip. If the library is installed in a nonstandard location,
+specify the prefix using --with-geoip=/prefix.
+
+For DNSTAP packet logging, you must have installed libfstrm https://
+github.com/farsightsec/fstrm and libprotobuf-c https://
+developers.google.com/protocol-buffers, and BIND must be configured with
+--enable-dnstap.
+
+On Linux, process capabilities are managed in user space using the libcap
+library, which can be installed on most Linux systems via the libcap-dev
+or libcap-devel module. Process capability support can also be disabled by
+configuring with --disable-linux-caps.
+
+Portions of BIND that are written in Python, including dnssec-keymgr,
+dnssec-coverage, dnssec-checkds, and some of the system tests, require the
+'argparse' and 'ply' modules to be available. 'argparse' is a standard
+module as of Python 2.7 and Python 3.2. 'ply' is available from https://
+pypi.python.org/pypi/ply.
+
+On some platforms it is necessary to explicitly request large file support
+to handle files bigger than 2GB. This can be done by using
+--enable-largefile on the configure command line.
+
+Support for the "fixed" rrset-order option can be enabled or disabled by
+specifying --enable-fixed-rrset or --disable-fixed-rrset on the configure
+command line. By default, fixed rrset-order is disabled to reduce memory
+footprint.
+
+make install will install named and the various BIND 9 libraries. By
+default, installation is into /usr/local, but this can be changed with the
+--prefix option when running configure.
+
+You may specify the option --sysconfdir to set the directory where
+configuration files like named.conf go by default, and --localstatedir to
+set the default parent directory of run/named.pid. For backwards
+compatibility with BIND 8, --sysconfdir defaults to /etc and
+--localstatedir defaults to /var if no --prefix option is given. If there
+is a --prefix option, sysconfdir defaults to $prefix/etc and localstatedir
+defaults to $prefix/var.
+
+Automated testing
+
+A system test suite can be run with make test. The system tests require
+you to configure a set of virtual IP addresses on your system (this allows
+multiple servers to run locally and communicate with one another). These
+IP addresses can be configured by running the command bin/tests/system/
+ifconfig.sh up as root.
+
+Some tests require Perl and the Net::DNS and/or IO::Socket::INET6 modules,
+and will be skipped if these are not available. Some tests require Python
+and the 'dnspython' module and will be skipped if these are not available.
+See bin/tests/system/README for further details.
+
+Unit tests are implemented using Automated Testing Framework (ATF). To run
+them, use configure --with-atf, then run make test or make unit.
+
+Documentation
+
+The BIND 9 Administrator Reference Manual is included with the source
+distribution, in DocBook XML, HTML and PDF format, in the doc/arm
+directory.
+
+Some of the programs in the BIND 9 distribution have man pages in their
+directories. In particular, the command line options of named are
+documented in bin/named/named.8.
+
+Frequently (and not-so-frequently) asked questions and their answers can
+be found in the ISC Knowledge Base at https://kb.isc.org.
+
+Additional information on various subjects can be found in other README
+files throughout the source tree.
+
+Change log
+
+A detailed list of all changes that have been made throughout the
+development BIND 9 is included in the file CHANGES, with the most recent
+changes listed first. Change notes include tags indicating the category of
+the change that was made; these categories are:
+
+Category Description
+[func] New feature
+[bug] General bug fix
+[security] Fix for a significant security flaw
+[experimental] Used for new features when the syntax or other aspects of
+ the design are still in flux and may change
+[port] Portability enhancement
+[maint] Updates to built-in data such as root server addresses and
+ keys
+[tuning] Changes to built-in configuration defaults and constants to
+ improve performance
+[performance] Other changes to improve server performance
+[protocol] Updates to the DNS protocol such as new RR types
+[test] Changes to the automatic tests, not affecting server
+ functionality
+[cleanup] Minor corrections and refactoring
+[doc] Documentation
+[contrib] Changes to the contributed tools and libraries in the
+ 'contrib' subdirectory
+ Used in the master development branch to reserve change
+[placeholder] numbers for use in other branches, e.g. when fixing a bug
+ that only exists in older releases
+
+In general, [func] and [experimental] tags will only appear in new-feature
+releases (i.e., those with version numbers ending in zero). Some new
+functionality may be backported to older releases on a case-by-case basis.
+All other change types may be applied to all currently-supported releases.
+
+Acknowledgments
+
+ * The original development of BIND 9 was underwritten by the following
+ organizations:
+
+ Sun Microsystems, Inc.
+ Hewlett Packard
+ Compaq Computer Corporation
+ IBM
+ Process Software Corporation
+ Silicon Graphics, Inc.
+ Network Associates, Inc.
+ U.S. Defense Information Systems Agency
+ USENIX Association
+ Stichting NLnet - NLnet Foundation
+ Nominum, Inc.
+
+ * This product includes software developed by the OpenSSL Project for
+ use in the OpenSSL Toolkit. http://www.OpenSSL.org/
+ * This product includes cryptographic software written by Eric Young
+ (eay@cryptsoft.com)
+ * This product includes software written by Tim Hudson
+ (tjh@cryptsoft.com)
projects / thirdparty / bind9.git / commitdiff
