From 0e10d2264eae5b3067d5dd5d2e5d1a70d2016adf Mon Sep 17 00:00:00 2001 From: "Jeremy C. Reed" Date: Thu, 20 Jan 2011 11:51:51 -0600 Subject: [PATCH] Document more about b10-resolver and introduce b10-stats. Add some bindctl examples for configuring b10-resolver. And also introduce b10-stats and Stats show. --- doc/guide/bind10-guide.html | 95 +++++++++++++++++++++++++++++----- doc/guide/bind10-guide.xml | 100 ++++++++++++++++++++++++++++++++---- 2 files changed, 173 insertions(+), 22 deletions(-) diff --git a/doc/guide/bind10-guide.html b/doc/guide/bind10-guide.html index 114657e929..849cd06b30 100644 --- a/doc/guide/bind10-guide.html +++ b/doc/guide/bind10-guide.html @@ -6,7 +6,7 @@

This is the reference guide for BIND 10 version 20101201. The most up-to-date version of this document, along with - other documents for BIND 10, can be found at http://bind10.isc.org/docs.

Table of Contents

1. Introduction
Supported Platforms
Required Software
Starting and Stopping the Server
Managing BIND 10
2. Installation
Building Requirements
Quick start
Installation from source
Download Tar File
Retrieve from Git
Configure before the build
Build
Install
Install Hierarchy
3. Starting BIND10 with bind10
Starting BIND 10
4. Command channel
5. Configuration manager
6. Remote control daemon
Configuration specification for b10-cmdctl
7. Control and configure user interface
8. Authoritative Server
Server Configurations
Data Source Backends
Loading Master Zones Files
9. Incoming Zone Transfers
10. Outbound Zone Transfers
11. Secondary Manager
12. Recursive Name Server

Chapter 1. Introduction

Table of Contents

Supported Platforms
Required Software
Starting and Stopping the Server
Managing BIND 10

+ other documents for BIND 10, can be found at http://bind10.isc.org/docs.

Table of Contents

1. Introduction
Supported Platforms
Required Software
Starting and Stopping the Server
Managing BIND 10
2. Installation
Building Requirements
Quick start
Installation from source
Download Tar File
Retrieve from Git
Configure before the build
Build
Install
Install Hierarchy
3. Starting BIND10 with bind10
Starting BIND 10
4. Command channel
5. Configuration manager
6. Remote control daemon
Configuration specification for b10-cmdctl
7. Control and configure user interface
8. Authoritative Server
Server Configurations
Data Source Backends
Loading Master Zones Files
9. Incoming Zone Transfers
10. Outbound Zone Transfers
11. Secondary Manager
12. Recursive Name Server
13. Statistics

Chapter 1. Introduction

Table of Contents

Supported Platforms
Required Software
Starting and Stopping the Server
Managing BIND 10

BIND is the popular implementation of a DNS server, developer interfaces, and DNS tools. BIND 10 is a rewrite of BIND 9. BIND 10 is written in C++ and Python @@ -80,6 +80,10 @@ Recursive name server. This process handles incoming queries. +

  • + b10-stats — + Statistics collection daemon. + This process collects and reports statistics data.
  • b10-xfrin — Incoming zone transfer service. @@ -129,7 +133,7 @@ and, of course, DNS. These include detailed developer documentation and code examples. -

    • Chapter 2. Installation

    Table of Contents

    Building Requirements
    Quick start
    Installation from source
    Download Tar File
    Retrieve from Git
    Configure before the build
    Build
    Install
    Install Hierarchy

    Building Requirements

    Note

    +

    Chapter 2. Installation

    Table of Contents

    Building Requirements
    Quick start
    Installation from source
    Download Tar File
    Retrieve from Git
    Configure before the build
    Build
    Install
    Install Hierarchy

    Building Requirements

    Note

    Some operating systems have split their distribution packages into a run-time and a development package. You will need to install the development package versions, which include header files and @@ -189,14 +193,14 @@ the Git 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

    +

    Download Tar File

    Downloading a release tar file is the recommended method to obtain the source code.

    The BIND 10 releases are available as tar file downloads from ftp://ftp.isc.org/isc/bind10/. Periodic development snapshots may also be available. -

    Retrieve from Git

    +

    Retrieve from Git

    Downloading this "bleeding edge" code is recommended only for developers or advanced users. Using development code in a production environment is not recommended. @@ -230,7 +234,7 @@ autoheader, automake, and related commands. -

    Configure before the build

    +

    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: @@ -261,16 +265,16 @@

    If the configure fails, it may be due to missing or old dependencies. -

    Build

    +

    Build

    After the configure step is complete, to build the executables from the C++ code and prepare the Python scripts, run: 

    $ make

    -

    Install

    +

    Install

    To install the BIND 10 executables, support files, and documentation, run: 

    $ make install

    -

    Note

    The install step may require superuser privileges.

    Install Hierarchy

    +

    Note

    The install step may require superuser privileges.

    Install Hierarchy

    The following is the layout of the complete BIND 10 installation:

    • bin/ — @@ -323,6 +327,7 @@ b10-cmdctl for admins to communicate with the system, b10-auth for authoritative DNS service or b10-resolver for recursive name service, + b10-stats for statistics collection, b10-xfrin for inbound DNS zone transfers, b10-xfrout for outbound DNS zone transfers, and b10-zonemgr for secondary service. @@ -484,7 +489,7 @@ shutdown the details and relays (over a b10-msgq command channel) the configuration on to the specified module.

      -

    Chapter 8. Authoritative Server

    Table of Contents

    Server Configurations
    Data Source Backends
    Loading Master Zones Files

    +

    Chapter 8. Authoritative Server

    Table of Contents

    Server Configurations
    Data Source Backends
    Loading Master Zones Files

    The b10-auth is the authoritative DNS server. It supports EDNS0 and DNSSEC. It supports IPv6. Normally it is started by the bind10 master @@ -492,7 +497,7 @@ shutdown

    Note

    This development prototype release listens on all interfaces and the non-standard port 5300. -

    Server Configurations

    +

    Server Configurations

    b10-auth is configured via the b10-cfgmgr configuration manager. The module name is “Auth”. @@ -512,7 +517,7 @@ This may be a temporary setting until then.

    shutdown
    Stop the authoritative DNS server.

    -

    Data Source Backends

    Note

    +

    Data Source Backends

    Note

    For the development prototype release, b10-auth only supports the SQLite3 data source backend. Upcoming versions will be able to use multiple different @@ -525,7 +530,7 @@ This may be a temporary setting until then. The default is /usr/local/var/.) This data file location may be changed by defining the “database_file” configuration. -

    Loading Master Zones Files

    +

    Loading Master Zones Files

    RFC 1035 style DNS master zone files may imported into a BIND 10 data source by using the b10-loadzone utility. @@ -609,4 +614,68 @@ This may be a temporary setting until then. The current version only provides a forwarding DNS server. It does not cache and does not iterate to find answers. It simply forwards the query on to another full resolver. -

    +

    + The main bind10 process can be configured + to select to run either the authoritative or resolver. + By default, it starts the authoritative service. + + + You may change this using bindctl, for example: + + 

    +> config set Boss/start_auth false
+> config set Boss/start_resolver true
+> config commit
+

    + +

    Note

    + In the current version, the master bind10 + process must be stopped and restarted to start up the resolver. +

    + Then the upstream address and port must be configured to + forward queries to, such as: + + 

    +> config set Resolver/forward_addresses [{ "address": "192.168.1.1", "port": 53 }]
+> config commit
+

    + + (Replace 192.168.1.1 to point to your + full resolver.) +

    + The resolver also needs to be configured to listen on an address + and port: + + 

    +> config set Resolver/listen_on [{ "address": "127.0.0.1", "port": 53 }]
+> config commit
+

    +

    Chapter 13. Statistics

    + The b10-stats process is started by + bind10. + It periodically collects statistics data from various modules + and aggregates it. + +

    + + This stats daemon provides commands to identify if it is running, + show specified or all statistics data, set values, remove data, + and reset data. + + For example, using bindctl: + + 

    +> Stats show
+{
+    "auth.queries.tcp": 1749,
+    "auth.queries.udp": 867868,
+    "bind10.boot_time": "2011-01-20T16:59:03Z",
+    "report_time": "2011-01-20T17:04:06Z",
+    "stats.boot_time": "2011-01-20T16:59:05Z",
+    "stats.last_update_time": "2011-01-20T17:04:05Z",
+    "stats.lname": "4d3869d9_a@jreed.example.net",
+    "stats.start_time": "2011-01-20T16:59:05Z",
+    "stats.timestamp": 1295543046.823504
+}
+

    +

    diff --git a/doc/guide/bind10-guide.xml b/doc/guide/bind10-guide.xml index 0935f3acd7..70f6a30af9 100644 --- a/doc/guide/bind10-guide.xml +++ b/doc/guide/bind10-guide.xml @@ -167,6 +167,14 @@ + + + b10-stats — + Statistics collection daemon. + This process collects and reports statistics data. + + + b10-xfrin — @@ -683,6 +691,7 @@ var/ b10-cmdctl for admins to communicate with the system, b10-auth for authoritative DNS service or b10-resolver for recursive name service, + b10-stats for statistics collection, b10-xfrin for inbound DNS zone transfers, b10-xfrout for outbound DNS zone transfers, and b10-zonemgr for secondary service. @@ -1304,27 +1313,100 @@ what is XfroutClient xfr_client?? It simply forwards the query on to another full resolver. - -By default, bind10 starts the authoritative service. + You may change this using bindctl, for example: -> config set Boss/start_auth false -> config set Boss/start_resolver true + +> config set Boss/start_auth false +> config set Boss/start_resolver true +> config commit + -config commit -Boss shutdown + -restart Boss + + + In the current version, the master bind10 + process must be stopped and restarted to start up the resolver. + -then next set forward_addresses as needed + + Then the upstream address and port must be configured to + forward queries to, such as: -{"version": 2, "Resolver": {"forward_addresses": [{"port": 5302, "address": "127.0.0.1"}], "listen_on": [{"port": 53, "address": "192.168.1.2"}, {"port": 53, "address": "127.0.0.1"}]}, "Boss": {"start_auth": false, "start_resolver": true}} + +> config set Resolver/forward_addresses [{ "address": "192.168.1.1", "port": 53 }] +> config commit + + (Replace 192.168.1.1 to point to your + full resolver.) + + + The resolver also needs to be configured to listen on an address + and port: + + +> config set Resolver/listen_on [{ "address": "127.0.0.1", "port": 53 }] +> config commit + + + + + + + + Statistics + + + The b10-stats process is started by + bind10. + It periodically collects statistics data from various modules + and aggregates it. + + + + + + This stats daemon provides commands to identify if it is running, + show specified or all statistics data, set values, remove data, + and reset data. + + For example, using bindctl: + + +> Stats show +{ + "auth.queries.tcp": 1749, + "auth.queries.udp": 867868, + "bind10.boot_time": "2011-01-20T16:59:03Z", + "report_time": "2011-01-20T17:04:06Z", + "stats.boot_time": "2011-01-20T16:59:05Z", + "stats.last_update_time": "2011-01-20T17:04:05Z", + "stats.lname": "4d3869d9_a@jreed.example.net", + "stats.start_time": "2011-01-20T16:59:05Z", + "stats.timestamp": 1295543046.823504 +} + + + + +