From 8a167a4b304863995a69eab74ded39a8a90ff5dc Mon Sep 17 00:00:00 2001 From: Evan Hunt Date: Fri, 31 Aug 2018 12:55:36 -0700 Subject: [PATCH] restore accidentally erased README and related files --- CONTRIBUTING | 186 ++++++++++++++++++++++++++ OPTIONS | 26 ++++ README | 360 +++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 572 insertions(+) diff --git a/CONTRIBUTING b/CONTRIBUTING index e69de29bb2..003a7c8593 100644 --- a/CONTRIBUTING +++ b/CONTRIBUTING @@ -0,0 +1,186 @@ +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. diff --git a/OPTIONS b/OPTIONS index e69de29bb2..340b53db67 100644 --- a/OPTIONS +++ b/OPTIONS @@ -0,0 +1,26 @@ +Setting the STD_CDEFINES environment variable before running configure can +be used to enable certain compile-time options that are not explicitly +defined in configure. + +Some of these settings are: + +Setting Description + Overwrite memory with tag values when allocating +-DISC_MEM_DEFAULTFILL=1 or freeing it; this impairs performance but + makes debugging of memory problems easier. + Don't track memory allocations by file and line +-DISC_MEM_TRACKLINES=0 number; this improves performance but makes + debugging more difficult. +-DISC_FACILITY=LOG_LOCAL0 Change the default syslog facility for named +-DNS_CLIENT_DROPPORT=0 Disable dropping queries from particular + well-known ports: +-DCHECK_SIBLING=0 Don't check sibling glue in named-checkzone +-DCHECK_LOCAL=0 Don't check out-of-zone addresses in + named-checkzone +-DNS_RUN_PID_DIR=0 Create default PID files in ${localstatedir}/run + rather than ${localstatedir}/run/named/ + Disable the use of inline functions to implement +-DISC_BUFFER_USEINLINE=0 the isc_buffer API: this reduces performance but + may be useful when debugging +-DISC_HEAP_CHECK Test heap consistency after every heap + operation; used when debugging diff --git a/README b/README index e69de29bb2..6a252ca446 100644 --- a/README +++ b/README @@ -0,0 +1,360 @@ +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= 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=, 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)