Commit 4e2fdd7e authored by Michal Nowak's avatar Michal Nowak Committed by Michał Kępień

Various README.md and README fixes

Fixing typos, typographical glitches. Added backticks around binaries,
modules, and libraries so it's more consistent. Added a paragraph with
ISC Security Policy.
parent 7a3896ef
Pipeline #21360 passed with stages
in 20 minutes and 6 seconds
......@@ -71,6 +71,9 @@ 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.
For a general overview of ISC security policies, read the Knowledge Base
article at https://kb.isc.org/docs/aa-00861.
Professional support and training for BIND are available from ISC at
https://www.isc.org/support.
......@@ -91,7 +94,7 @@ General information: CONTRIBUTING.md - Code of Conduct: CODE_OF_CONDUCT.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
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
......@@ -116,9 +119,10 @@ 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.
been observed on many versions of Linux and UNIX, including RHEL/CentOS,
Fedora, Debian, Ubuntu, SLES, openSUSE, Slackware, Alpine, FreeBSD,
NetBSD, OpenBSD, macOS, Solaris, OpenIndiana, OmniOS CE, 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
......@@ -127,7 +131,7 @@ 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/
BIND is also available for Windows Server 2008 and higher. See win32utils/
readme1st.txt for details on building for Windows systems.
To build on a UNIX or Linux system, use:
......@@ -156,23 +160,23 @@ STD_CDEFINES Defaults to empty string. For a list of possible settings,
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
BUILD_CFLAGS CFLAGS for the target system during cross-compiling.
BUILD_CPPFLAGS CPPFLAGS for the target system during cross-compiling.
BUILD_LDFLAGS LDFLAGS for the target system during cross-compiling.
BUILD_LIBS LIBS for the target system during cross-compiling.
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".
if you have Xcode already installed you can run xcode-select --install.
Dependencies
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://
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.
Compile-time options
......@@ -191,8 +195,9 @@ 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, then:
least one of the following libraries: libxml2 http://xmlsoft.org or json-c
https://github.com/json-c/json-c. If these are installed at a nonstandard
location, then:
* for libxml2, specify the prefix using --with-libxml2=/prefix,
* for json-c, adjust PKG_CONFIG_PATH.
......@@ -225,8 +230,8 @@ smaller systems.
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.
or libcap-devel package. Process capability support can also be disabled
by configuring with --disable-linux-caps.
On some platforms it is necessary to explicitly request large file support
to handle files bigger than 2GB. This can be done by using
......@@ -260,7 +265,7 @@ 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.
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 the CMocka unit testing framework. To
......@@ -271,7 +276,7 @@ tests can be run via 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
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
......@@ -326,16 +331,16 @@ issue number. Prior to 2018, these were usually of the form [RT #NNN] and
referred to entries in the "bind9-bugs" RT database, which was not open to
the public. More recent entries use the form [GL #NNN] or, less often, [GL
!NNN], which, respectively, refer to issues or merge requests in the
Gitlab database. Most of these are publicly readable, unless they include
information which is confidential or security senstive.
GitLab database. Most of these are publicly readable, unless they include
information which is confidential or security sensitive.
To look up a Gitlab issue by its number, use the URL https://
To look up a GitLab issue by its number, use the URL https://
gitlab.isc.org/isc-projects/bind9/issues/NNN. To look up a merge request,
use https://gitlab.isc.org/isc-projects/bind9/merge_requests/NNN.
In rare cases, an issue or merge request number may be followed with the
letter "P". This indicates that the information is in the private ISC
Gitlab instance, which is not visible to the public.
GitLab instance, which is not visible to the public.
Acknowledgments
......@@ -356,9 +361,7 @@ Acknowledgments
* 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)
......@@ -82,6 +82,9 @@ assertion failure or other crash in `named`, please do *NOT* use GitLab to
report it. Instead, please send mail to
[security-officer@isc.org](mailto:security-officer@isc.org).
For a general overview of ISC security policies, read the Knowledge Base
article at [https://kb.isc.org/docs/aa-00861](https://kb.isc.org/docs/aa-00861).
Professional support and training for BIND are available from
ISC at [https://www.isc.org/support](https://www.isc.org/support).
......@@ -104,7 +107,7 @@ Information for BIND contributors can be found in the following files:
- BIND architecture and developer guide: [doc/dev/dev.md](doc/dev/dev.md)
Patches for BIND may be submitted as
[Merge Requests](https://gitlab.isc.org/isc-projects/bind9/merge_requests)
[merge requests](https://gitlab.isc.org/isc-projects/bind9/merge_requests)
in the [ISC GitLab server](https://gitlab.isc.org) at
at [https://gitlab.isc.org/isc-projects/bind9/merge_requests](https://gitlab.isc.org/isc-projects/bind9/merge_requests).
......@@ -126,15 +129,15 @@ include:
* Support for the new GeoIP2 geolocation API
* Improved DNSSEC key configuration using `dnssec-keys`
* YAML output for dig, mdig, and delv.
* YAML output for `dig`, `mdig`, and `delv`.
### <a name="build"/> 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.
observed on many versions of Linux and UNIX, including RHEL/CentOS, Fedora,
Debian, Ubuntu, SLES, openSUSE, Slackware, Alpine, FreeBSD, NetBSD,
OpenBSD, macOS, Solaris, OpenIndiana, OmniOS CE, 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
......@@ -143,7 +146,7 @@ can be overridden by disabling capability support at compile time.
See [Compile-time options](#opts) below for details on other libraries
that may be required to support optional features.
BIND is also available for Windows 2008 and higher. See
BIND is also available for Windows Server 2008 and higher. See
`win32utils/readme1st.txt` for details on building for Windows
systems.
......@@ -166,24 +169,24 @@ affect compilation:
|`STD_CDEFINES`|Any additional preprocessor symbols you want defined. Defaults to empty string. For a list of possible settings, see the file [OPTIONS](OPTIONS.md).|
|`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`||
|`BUILD_CFLAGS`|`CFLAGS` for the target system during cross-compiling.|
|`BUILD_CPPFLAGS`|`CPPFLAGS` for the target system during cross-compiling.|
|`BUILD_LDFLAGS`|`LDFLAGS` for the target system during cross-compiling.|
|`BUILD_LIBS`|`LIBS` for the target system during cross-compiling.|
#### <a name="macos"> 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 can be downloaded from [https://developer.apple.com/download/more/](https://developer.apple.com/download/more/)
or if you have Xcode already installed you can run `xcode-select --install`.
### <a name="dependencies"/> Dependencies
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](https://pypi.python.org/pypi/ply).
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](https://pypi.python.org/pypi/ply).
#### <a name="opts"/> Compile-time options
......@@ -201,16 +204,16 @@ 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](http://xmlsoft.org) or json-c
[https://github.com/json-c](https://github.com/json-c). If these are
installed at a nonstandard location, then:
least one of the following libraries: `libxml2`
[http://xmlsoft.org](http://xmlsoft.org) or `json-c`
[https://github.com/json-c/json-c](https://github.com/json-c/json-c).
If these are installed at a nonstandard location, then:
* for libxml2, specify the prefix using `--with-libxml2=/prefix`,
* for json-c, adjust `PKG_CONFIG_PATH`.
* for `libxml2`, specify the prefix using `--with-libxml2=/prefix`,
* for `json-c`, adjust `PKG_CONFIG_PATH`.
To support compression on the HTTP statistics channel, the server must be
linked against libzlib. If this is installed in a nonstandard location,
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
......@@ -223,9 +226,9 @@ found; if the library is installed in a nonstandard location,
specify the prefix using `--with-maxminddb=/prefix`. GeoIP2 support
can be switched off with `--disable-geoip`.
For DNSTAP packet logging, you must have installed libfstrm
For DNSTAP packet logging, you must have installed `libfstrm`
[https://github.com/farsightsec/fstrm](https://github.com/farsightsec/fstrm)
and libprotobuf-c
and `libprotobuf-c`
[https://developers.google.com/protocol-buffers](https://developers.google.com/protocol-buffers),
and BIND must be configured with `--enable-dnstap`.
......@@ -238,7 +241,7 @@ performance on smaller systems.
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
the `libcap-dev` or `libcap-devel` package. Process capability support can
also be disabled by configuring with `--disable-linux-caps`.
On some platforms it is necessary to explicitly request large file support
......@@ -271,20 +274,21 @@ 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,
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.
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 the CMocka unit testing framework.
Unit tests are implemented using the [CMocka unit testing framework](https://cmocka.org/).
To build them, use `configure --with-cmocka`. Execution of tests is done
by the Kyua test execution engine; if the `kyua` command is available,
then unit tests can be run via `make test` or `make unit`.
by the [Kyua test execution engine](https://github.com/jmmv/kyua); if the
`kyua` command is available, then unit tests can be run via `make test`
or `make unit`.
### <a name="doc"/> Documentation
The *BIND 9 Administrator Reference Manual* is included with the source
distribution, in DocBook XML, HTML and PDF format, in the `doc/arm`
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
......@@ -334,17 +338,17 @@ issue number. Prior to 2018, these were usually of the form `[RT #NNN]`
and referred to entries in the "bind9-bugs" RT database, which was not open
to the public. More recent entries use the form `[GL #NNN]` or, less often,
`[GL !NNN]`, which, respectively, refer to issues or merge requests in the
Gitlab database. Most of these are publicly readable, unless they include
information which is confidential or security senstive.
GitLab database. Most of these are publicly readable, unless they include
information which is confidential or security sensitive.
To look up a Gitlab issue by its number, use the URL
To look up a GitLab issue by its number, use the URL
[https://gitlab.isc.org/isc-projects/bind9/issues/NNN](https://gitlab.isc.org/isc-projects/bind9/issues).
To look up a merge request, use
[https://gitlab.isc.org/isc-projects/bind9/merge_requests/NNN](https://gitlab.isc.org/isc-projects/bind9/merge_requests).
In rare cases, an issue or merge request number may be followed with the
letter "P". This indicates that the information is in the private ISC
Gitlab instance, which is not visible to the public.
GitLab instance, which is not visible to the public.
### <a name="ack"/> Acknowledgments
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment