From 545aaa19239da4eff9367ec69824a20cb66d40c6 Mon Sep 17 00:00:00 2001 From: Michael Graff Date: Thu, 18 Mar 2010 19:17:52 +0000 Subject: [PATCH] reorder sections; make all installation instructons including quickstart a child of the installation chapter. Put requirements and supported OS versions first in the installation section. More work to be done git-svn-id: svn://bind10.isc.org/svn/bind10/trunk@1528 e5f2f494-b856-4b98-b285-d166d9295462 --- doc/userguide/userguide.xml | 693 ++++++++++++++++++------------------ 1 file changed, 353 insertions(+), 340 deletions(-) diff --git a/doc/userguide/userguide.xml b/doc/userguide/userguide.xml index 45e3d4e3bf..b9588181e8 100644 --- a/doc/userguide/userguide.xml +++ b/doc/userguide/userguide.xml @@ -4,6 +4,8 @@ ]> + + BIND 10 User Guide Administrator Reference for BIND 10 @@ -105,25 +107,29 @@ - - Once BIND 10 is running, two commands are used to interact directly with - the system: - - - - bindctl — - interactive administration interface - - - - - b10-loadzone — - tool to load standard master zone files - - - - - +
+ Managing BIND 10 + + + Once BIND 10 is running, two commands are used to interact directly with + the system: + + + + bindctl — + interactive administration interface + + + + + b10-loadzone — + tool to load standard master zone files + + + + + +
The tools and modules are covered in full detail in this users guide. @@ -163,166 +169,17 @@ var/ - - Quick start - - This quickly covers the standard steps for installing - and deploying BIND 10 as an authoritative nameserver using - its defaults. For troubleshooting, full customizations and further - details, see the respective chapters in the BIND 10 user guide. - + + Installation - - - - Install required dependencies: Python 3.1, SQLite3 - library, and Boost development headers. - - - - Download the BIND 10 source tarball. - - - - - Extract the tar file: - $ gzcat bind10-VERSION.tar.gz | tar -xvf - - - - - - Go into the source and run configure: - $ cd bind10-VERSION -$ ./configure - - - - - Build it: - $ make - - - - - Install it (to default /usr/local): - $ make install - - - - - Start the server: - $ /usr/local/sbin/bind10 - - - - - - The Y1 prototype of the b10-auth server listens on - 0.0.0.0 (all interfaces) port 5300. (This is not the standard - domain service port.) - - Test it; for example: - $ dig @127.0.0.1 -p 5300 -c CH -t TXT authors.bind - - - - - - Load desired zone file(s), for example: - $ b10-loadzone your.zone.example.org - - - - - Test the new zone. - - - - - - - - - Installation from source - - BIND 10 is open source software written in C++ and Python. - It is freely available in source code form from ISC via - the Subversion code revision control system or as a downloadable - tar file. It may also be available in pre-compiled ready-to-use - packages from operating system vendors. - - - - Download Tar File - The BIND 10 development snapshots and releases - are available as tarball downloads. - - - - - - Retrieve from Subversion - - The latest development code, including temporary experiments - and un-reviewed code, is available via the BIND 10 code revision - control system. This is powered by Subversion and all the BIND 10 - development is public. - The leading development is done in the trunk - and the first year prototype containing reviewed code is in - branches/Y1. - - - The code can be checked out from svn://bind10.isc.org/svn/bind10; for example to check out the trunk: - - $ svn co svn://bind10.isc.org/svn/bind10/trunk - - - - You do not need to retrieve the source code from subversion - unless you are testing latest code which is not provided in the - source tarball or you are a developer. - Most users will just use the source tar file. - - - - Generate configuration files - - When checking out the code from - the code version control system, it doesn't include the - generated configure script, Makefile.in files, nor the - related configure files. - They can be created by running autoreconf - with the switch. - This will run autoconf, aclocal, - libtoolize, autoheader, - automake, and related commands — - and provide needed build files. - - - This requires autoconf version 2.59 or newer - and automake version 1.10 or better. - (For working Python 3.1 tests, automake - version 1.11 or better is needed or use the - configure option described - below). - - - - Some operating systems do not provide these in their - default installation nor standard packages collections. - You may need to install them separately. - - - - - +
Required Software BIND 10 requires Python 3.1. - Building from the source tarball requires the Boost + Building from source code requires the Boost build-time headers. At least Boost version 1.34 is required. @@ -364,9 +221,9 @@ $ ./configure 4.2.1, 4.3.2, and 4.4.1. - +
- +
Supported Platforms BIND 10 builds have been tested on Debian GNU/Linux 5, @@ -379,168 +236,324 @@ $ ./configure It is planned for BIND 10 to build, install and run on Windows and standard Unix-type platforms. - - - - Configure before the build +
+ +
+ Quick start - BIND 10 uses the GNU Build System to discover build environment - details. - To generate the makefiles using the defaults, simply run: - $ ./configure - - - Run ./configure with the - switch to view the different options. The commonly-used options are: - - - - - --with-boostlib - - Define the path to find the Boost system library. - - - - - - --without-boostlib or - --with-boostlib=no - - Disable the Boost ASIO support. - - - - - --with-pythonpath - - Define the path to Python 3.1 if it is not in the - standard execution path. - - - - - - --with-boost-include - - Define the path to find the Boost headers. - - - - - - --prefix - - Define the the installation location (the - default is /usr/local/). - - - - - - - - - - - For example, the following configures it to build - with BOOST ASIO support, find the Boost headers, find the - Python interpreter, and sets the installation location: - - $ ./configure --with-boostlib=/usr/pkg/lib \ - --with-boost-include=/usr/pkg/include \ - --with-pythonpath=/usr/pkg/bin/python3.1 \ - --prefix=/opt/bind10 + This quickly covers the standard steps for installing + and deploying BIND 10 as an authoritative nameserver using + its defaults. For troubleshooting, full customizations and further + details, see the respective chapters in the BIND 10 user guide. - - If the configure fails, it may be due to missing or old - dependencies. - + + + The Y1 prototype of the b10-auth server listens on + 0.0.0.0 (all interfaces) port 5300. (This is not the standard + domain service port.) + + - - - - Build - - After the configure step is complete, to build the executables - from the C++ code and prepare the Python scripts, run: - - $ make - - - - - Install - - To install the BIND 10 executables, support files, - and documentation, run: - $ make install - - The install step may require superuser - privileges. - - - - - - - Install Hierarchy - - The following is the layout of the complete BIND 10 installation: - - bin/ — general tools and - diagnostic clients. - - - etc/bind10/ — configuration files. - - - - - lib/ — libraries and - python modules. - - - libexec/bind10/ — executables that - a user wouldn't normally run directly. Nor would they be used - independently. These are the BIND 10 modules which are daemons - started by the bind10 tool. - - - - sbin/ — commands used by - the system administrator. - - - - share/bind10/ — configuration - specifications. - - - - share/man/ — manual pages (online - documentation). - - - - var/bind10/ — data source and - configuration databases. - - - - - - + + + Install required dependencies: Python 3.1, SQLite3 + library, and Boost development headers. + - + + + + + Extract the tar file: + $ gzcat bind10-VERSION.tar.gz | tar -xvf - + + + + + Go into the source and run configure: + $ cd bind10-VERSION + $ ./configure + + + + + Build it: + $ make + + + + + Install it (to default /usr/local): + $ make install + + + + + Start the server: + $ /usr/local/sbin/bind10 + + + + + + Test it; for example: + $ dig @127.0.0.1 -p 5300 -c CH -t TXT authors.bind + + + + + Load desired zone file(s), for example: + $ b10-loadzone your.zone.example.org + + + + + Test the new zone. + + + + + +
+ +
+ Installation from source + BIND 10 is open source software written in C++ and Python. + It is freely available in source code form from ISC via + the Subversion code revision control system or as a downloadable + tar file. It may also be available in pre-compiled ready-to-use + packages from operating system vendors. - ---> + +
+ Download Tar File + The BIND 10 development snapshots and releases + are available as tarball downloads. + + +
+ +
+ Retrieve from Subversion + + The latest development code, including temporary experiments + and un-reviewed code, is available via the BIND 10 code revision + control system. This is powered by Subversion and all the BIND 10 + development is public. + The leading development is done in the trunk + and the first year prototype containing reviewed code is in + branches/Y1. + + + The code can be checked out from svn://bind10.isc.org/svn/bind10; for example to check out the trunk: + + $ svn co svn://bind10.isc.org/svn/bind10/trunk + + + + You do not need to retrieve the source code from subversion + unless you are testing latest code which is not provided in the + source tarball or you are a developer. + Most users will just use the source tar file. + + +
+ Generate configuration files + + When checking out the code from + the code version control system, it doesn't include the + generated configure script, Makefile.in files, nor the + related configure files. + They can be created by running autoreconf + with the switch. + This will run autoconf, aclocal, + libtoolize, autoheader, + automake, and related commands — + and provide needed build files. + + + This requires autoconf version 2.59 or newer + and automake version 1.10 or better. + (For working Python 3.1 tests, automake + version 1.11 or better is needed or use the + configure option described + below). + + + Some operating systems do not provide these in their + default installation nor standard packages collections. + You may need to install them separately. + +
+
+ + +
+ Configure before the build + + BIND 10 uses the GNU Build System to discover build environment + details. + To generate the makefiles using the defaults, simply run: + $ ./configure + + + Run ./configure with the + switch to view the different options. The commonly-used options are: + + + + + --with-boostlib + + Define the path to find the Boost system library. + + + + + + --without-boostlib or + --with-boostlib=no + + Disable the Boost ASIO support. + + + + + --with-pythonpath + + Define the path to Python 3.1 if it is not in the + standard execution path. + + + + + + --with-boost-include + + Define the path to find the Boost headers. + + + + + + --prefix + + Define the the installation location (the + default is /usr/local/). + + + + + + + + + + + For example, the following configures it to build + with BOOST ASIO support, find the Boost headers, find the + Python interpreter, and sets the installation location: + + $ ./configure --with-boostlib=/usr/pkg/lib \ + --with-boost-include=/usr/pkg/include \ + --with-pythonpath=/usr/pkg/bin/python3.1 \ + --prefix=/opt/bind10 + + + + If the configure fails, it may be due to missing or old + dependencies. + + +
+ +
+ Build + + After the configure step is complete, to build the executables + from the C++ code and prepare the Python scripts, run: + + $ make + +
+ +
+ Install + + To install the BIND 10 executables, support files, + and documentation, run: + $ make install + + The install step may require superuser + privileges. + +
+ + + +
+ Install Hierarchy + + The following is the layout of the complete BIND 10 installation: + + + bin/ — general tools and + diagnostic clients. + + + etc/bind10/ — configuration files. + + + + + lib/ — libraries and + python modules. + + + libexec/bind10/ — executables that + a user wouldn't normally run directly. Nor would they be used + independently. These are the BIND 10 modules which are daemons + started by the bind10 tool. + + + + sbin/ — commands used by + the system administrator. + + + + share/bind10/ — configuration + specifications. + + + + share/man/ — manual pages (online + documentation). + + + + var/bind10/ — data source and + configuration databases. + + + + + +
+
+ + @@ -577,7 +590,7 @@ $ ./configure (These are covered in upcoming chapters.) - +
Starting BIND 10 To start the BIND 10 service, simply run bind10. @@ -585,7 +598,7 @@ $ ./configure get additional debugging or diagnostic output. - +
@@ -840,7 +853,7 @@ or accounts database --> redefined by using the command line argument. - +
Configuration specification for b10-cmdctl The configuration items for b10-cmdctl are: @@ -856,7 +869,7 @@ print_settings shutdown - +
- + - +
Data Source Backends @@ -994,9 +1007,9 @@ This may be a temporary setting until then. database_file configuration. - +
- +
Loading Master Zones Files @@ -1064,15 +1077,15 @@ This may be a temporary setting until then. - +