diff --git a/doc/devel/02-dhcp.dox b/doc/devel/02-dhcp.dox index b6c3093e92e62e8d40bfe97ae93ac43f0a5ab913..5217f73971e37b278158e143027566b38b31fee7 100644 --- a/doc/devel/02-dhcp.dox +++ b/doc/devel/02-dhcp.dox @@ -72,11 +72,13 @@ * DHCPv6 server component does not support relayed traffic yet, as * support for relay decapsulation is not implemented yet. * - * DHCPv6 server component does not listen to BIND10 message queue. - * * DHCPv6 server component does not use BIND10 logging yet. * - * DHCPv6 server component is not integrated with boss yet. + * @section dhcpv6Session BIND10 message queue integration + * + * DHCPv4 server component is now integrated with BIND10 message queue. + * It follows the same principle as DHCPv4. See \ref dhcpv4Session for + * details. * * @page libdhcp libdhcp++ * diff --git a/doc/guide/bind10-guide.html b/doc/guide/bind10-guide.html index 7a1a120a7be43528b5047091b9f04e96a8e3502f..11dcf00957ce368f3566d597aa9a8b76063a48cb 100644 --- a/doc/guide/bind10-guide.html +++ b/doc/guide/bind10-guide.html @@ -1,4 +1,4 @@ -BIND 10 Guide

BIND 10 Guide

Administrator Reference for BIND 10

This is the reference guide for BIND 10 version +BIND 10 Guide

BIND 10 Guide

Administrator Reference for BIND 10

This is the reference guide for BIND 10 version 20120405.

Abstract

BIND 10 is a framework that features Domain Name System (DNS) suite and Dynamic Host Configuration Protocol (DHCP) servers managed by Internet Systems Consortium (ISC). It @@ -10,9 +10,9 @@ The most up-to-date version of this document (in PDF, HTML, and plain text formats), along with other documents for BIND 10, can be found at http://bind10.isc.org/docs. -


Table of Contents

Preface
1. Acknowledgements
1. Introduction
1.1. Supported Platforms
1.2. Required Software
1.3. Starting and Stopping the Server
1.4. Managing BIND 10
2. Installation
2.1. Building Requirements
2.2. Quick start
2.3. Installation from source
2.3.1. Download Tar File
2.3.2. Retrieve from Git
2.3.3. Configure before the build
2.3.4. Build
2.3.5. Install
2.3.6. Install Hierarchy
3. Starting BIND10 with bind10
3.1. Starting BIND 10
3.2. Configuration of started processes
4. Command channel
5. Configuration manager
6. Remote control daemon
6.1. Configuration specification for b10-cmdctl
7. Control and configure user interface
8. Authoritative Server
8.1. Server Configurations
8.2. Data Source Backends
8.2.1. In-memory Data Source
8.2.2. In-memory Data Source With SQLite3 Backend
8.2.3. Reloading an In-memory Data Source
8.2.4. Disabling In-memory Data Sources
8.3. Loading Master Zones Files
9. Incoming Zone Transfers
9.1. Configuration for Incoming Zone Transfers
9.2. Enabling IXFR
9.3. Secondary Manager
9.4. Trigger an Incoming Zone Transfer Manually
9.5. Incoming Transfers with In-memory Datasource
10. Outbound Zone Transfers
11. Dynamic DNS Update
11.1. Enabling Dynamic Update
11.2. Access Control
11.3. Miscellaneous Operational Issues
12. Recursive Name Server
12.1. Access Control
12.2. Forwarding
13. DHCPv4 Server
13.1. DHCPv4 Server Usage
13.2. DHCPv4 Server Configuration
13.3. Supported standards
13.4. DHCPv4 Server Limitations
14. DHCPv6 Server
14.1. DHCPv6 Server Usage
14.2. DHCPv6 Server Configuration
14.3. Supported DHCPv6 Standards
14.4. DHCPv6 Server Limitations
15. libdhcp++ library
15.1. Interface detection
15.2. DHCPv4/DHCPv6 packet handling
16. Statistics
17. Logging
17.1. Logging configuration
17.1.1. Loggers
17.1.2. Output Options
17.1.3. Example session
17.2. Logging Message Format

List of Tables

3.1.

Preface

Table of Contents

1. Acknowledgements

1. Acknowledgements

ISC would like to acknowledge generous support for +


Table of Contents

Preface
1. Acknowledgements
1. Introduction
1.1. Supported Platforms
1.2. Required Software
1.3. Starting and Stopping the Server
1.4. Managing BIND 10
2. Installation
2.1. Building Requirements
2.2. Quick start
2.3. Installation from source
2.3.1. Download Tar File
2.3.2. Retrieve from Git
2.3.3. Configure before the build
2.3.4. Build
2.3.5. Install
2.3.6. Install Hierarchy
3. Starting BIND10 with bind10
3.1. Starting BIND 10
3.2. Configuration of started processes
4. Command channel
5. Configuration manager
6. Remote control daemon
6.1. Configuration specification for b10-cmdctl
7. Control and configure user interface
8. Authoritative Server
8.1. Server Configurations
8.2. Data Source Backends
8.2.1. In-memory Data Source
8.2.2. In-memory Data Source With SQLite3 Backend
8.2.3. Reloading an In-memory Data Source
8.2.4. Disabling In-memory Data Sources
8.3. Loading Master Zones Files
9. Incoming Zone Transfers
9.1. Configuration for Incoming Zone Transfers
9.2. Enabling IXFR
9.3. Secondary Manager
9.4. Trigger an Incoming Zone Transfer Manually
9.5. Incoming Transfers with In-memory Datasource
10. Outbound Zone Transfers
11. Dynamic DNS Update
11.1. Enabling Dynamic Update
11.2. Access Control
11.3. Miscellaneous Operational Issues
12. Recursive Name Server
12.1. Access Control
12.2. Forwarding
13. DHCPv4 Server
13.1. DHCPv4 Server Usage
13.2. DHCPv4 Server Configuration
13.3. Supported standards
13.4. DHCPv4 Server Limitations
14. DHCPv6 Server
14.1. DHCPv6 Server Usage
14.2. DHCPv6 Server Configuration
14.3. Supported DHCPv6 Standards
14.4. DHCPv6 Server Limitations
15. libdhcp++ library
15.1. Interface detection
15.2. DHCPv4/DHCPv6 packet handling
16. Statistics
17. Logging
17.1. Logging configuration
17.1.1. Loggers
17.1.2. Output Options
17.1.3. Example session
17.2. Logging Message Format

List of Tables

3.1.

Preface

Table of Contents

1. Acknowledgements

1. Acknowledgements

ISC would like to acknowledge generous support for BIND 10 development of DHCPv4 and DHCPv6 components provided - by Comcast.

Chapter 1. Introduction

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 @@ -23,7 +23,7 @@

This guide covers the experimental prototype of BIND 10 version 20120405. -

1.1. Supported Platforms

+

1.1. Supported Platforms

BIND 10 builds have been tested on (in no particular order) Debian GNU/Linux 5 and unstable, Ubuntu 9.10, NetBSD 5, Solaris 10 and 11, FreeBSD 7 and 8, CentOS Linux 5.3, @@ -171,7 +171,7 @@ and, of course, DNS. These include detailed developer documentation and code examples. -

Chapter 2. Installation

2.1. Building Requirements

+

Chapter 2. Installation

2.1. Building Requirements

In addition to the run-time requirements, building BIND 10 from source code requires various development include headers.

Note

@@ -233,14 +233,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. -

2.3.1. Download Tar File

+

2.3.1. 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. -

2.3.2. Retrieve from Git

+

2.3.2. 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. @@ -274,7 +274,7 @@ autoheader, automake, and related commands. -

2.3.3. Configure before the build

+

2.3.3. 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: @@ -305,16 +305,16 @@

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

2.3.4. Build

+

2.3.4. Build

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

$ make

-

2.3.5. Install

+

2.3.5. Install

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

$ make install

-

Note

The install step may require superuser privileges.

2.3.6. Install Hierarchy

+

Note

The install step may require superuser privileges.

2.3.6. Install Hierarchy

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

  • bin/ — @@ -406,7 +406,7 @@ during startup or shutdown. Unless specified, the component is started in usual way. This is the list of components that need to be started in a special way, with the value of special used for them: -

    Table 3.1. 

    ComponentSpecialDescription
    b10-authauthAuthoritative server
    b10-resolverresolverThe resolver
    b10-cmdctlcmdctlThe command control (remote control interface)


    +

    Table 3.1. 

    ComponentSpecialDescription
    b10-authauthAuthoritative server
    b10-resolverresolverThe resolver
    b10-cmdctlcmdctlThe command control (remote control interface)


    The kind specifies how a failure of the component should be handled. If it is set to dispensable @@ -634,12 +634,12 @@ shutdown the details and relays (over a b10-msgq command channel) the configuration on to the specified module.

    -

Chapter 8. Authoritative Server

The b10-auth is the authoritative DNS server. It supports EDNS0 and DNSSEC. It supports IPv6. Normally it is started by the bind10 master process. -

8.1. Server Configurations

+

8.1. Server Configurations

b10-auth is configured via the b10-cfgmgr configuration manager. The module name is Auth. @@ -736,7 +736,7 @@ This may be a temporary setting until then. if configured.)

-

8.2. Data Source Backends

Note

+

8.2. Data Source Backends

Note

For the development prototype release, b10-auth supports a SQLite3 data source backend and in-memory data source backend. @@ -815,7 +815,7 @@ This may be a temporary setting until then. and/or zones[0] for the relevant zone as needed.) -

8.3. Loading Master Zones Files

+

8.3. Loading Master Zones Files

RFC 1035 style DNS master zone files may imported into a BIND 10 SQLite3 data source by using the b10-loadzone utility. @@ -844,7 +844,7 @@ This may be a temporary setting until then. If you reload a zone already existing in the database, all records from that prior zone disappear and a whole new set appears. -

Chapter 9. Incoming Zone Transfers

Incoming zones are transferred using the b10-xfrin process which is started by bind10. When received, the zone is stored in the corresponding BIND 10 @@ -858,7 +858,7 @@ This may be a temporary setting until then. IXFR. Due to some implementation limitations of the current development release, however, it only tries AXFR by default, and care should be taken to enable IXFR. -

9.1. Configuration for Incoming Zone Transfers

+

9.1. Configuration for Incoming Zone Transfers

In practice, you need to specify a list of secondary zones to enable incoming zone transfers for these zones (you can still trigger a zone transfer manually, without a prior configuration @@ -874,7 +874,7 @@ This may be a temporary setting until then. > config commit

(We assume there has been no zone configuration before). -

9.2. Enabling IXFR

+

9.2. Enabling IXFR

As noted above, b10-xfrin uses AXFR for zone transfers by default. To enable IXFR for zone transfers for a particular zone, set the use_ixfr @@ -926,13 +926,13 @@ This may be a temporary setting until then. (i.e. no SOA record for it), b10-zonemgr will automatically tell b10-xfrin to transfer the zone in. -

9.4. Trigger an Incoming Zone Transfer Manually

+

9.4. Trigger an Incoming Zone Transfer Manually

To manually trigger a zone transfer to retrieve a remote zone, you may use the bindctl utility. For example, at the bindctl prompt run:

> Xfrin retransfer zone_name="foo.example.org" master=192.0.2.99

-

9.5. Incoming Transfers with In-memory Datasource

+

9.5. Incoming Transfers with In-memory Datasource

In the case of an incoming zone transfer, the received zone is first stored in the corresponding BIND 10 datasource. In case the secondary zone is served by an in-memory datasource @@ -987,7 +987,7 @@ Xfrout/transfer_acl[0] {"action": "ACCEPT"} any (default)

TSIGs in the incoming messages and to sign responses.

Note

The way to specify zone specific configuration (ACLs, etc) is likely to be changed. -

Chapter 11. Dynamic DNS Update

BIND 10 supports the server side of the Dynamic DNS Update (DDNS) protocol as defined in RFC 2136. This service is provided by the b10-ddns @@ -1034,7 +1034,7 @@ Xfrout/transfer_acl[0] {"action": "ACCEPT"} any (default)

this feature.

-

11.1. Enabling Dynamic Update

+

11.1. Enabling Dynamic Update

First off, it must be made sure that a few components on which b10-ddns depends are configured to run, which are b10-auth @@ -1093,7 +1093,7 @@ Xfrout/transfer_acl[0] {"action": "ACCEPT"} any (default)

specifying it. But for it to shutdown gracefully this parameter should also be specified.

-

11.2. Access Control

+

11.2. Access Control

By default b10-ddns rejects any update requests from any clients by returning a response with an RCODE of REFUSED. @@ -1192,7 +1192,7 @@ DDNS/zones[0]/update_acl[1] {"action": "ACCEPT", "from": "::1", "key": "key. arbitrary clients. There have been other troubles that could have been avoided if the ACL could be checked before the prerequisite check. -

11.3. Miscellaneous Operational Issues

+

11.3. Miscellaneous Operational Issues

Unlike BIND 9, BIND 10 currently does not support automatic resigning of DNSSEC-signed zone when it's updated via DDNS. It could be possible to resign the updated zone afterwards @@ -1234,7 +1234,7 @@ DDNS/zones[0]/update_acl[1] {"action": "ACCEPT", "from": "::1", "key": "key. IXFR. This is done automatically; it does not require specific configuration to make this possible. -

Chapter 12. Recursive Name Server

+

Chapter 12. Recursive Name Server

The b10-resolver process is started by bind10. @@ -1268,7 +1268,7 @@ DDNS/zones[0]/update_acl[1] {"action": "ACCEPT", "from": "::1", "key": "key.

(Replace the 2 as needed; run config show - Resolver/listen_on if needed.)

12.1. Access Control

+ Resolver/listen_on” if needed.)

12.1. Access Control

By default, the b10-resolver daemon only accepts DNS queries from the localhost (127.0.0.1 and ::1). The Resolver/query_acl configuration may @@ -1301,7 +1301,7 @@ DDNS/zones[0]/update_acl[1] {"action": "ACCEPT", "from": "::1", "key": "key.

(Replace the 2 as needed; run config show Resolver/query_acl if needed.)

Note

This prototype access control configuration - syntax may be changed.

12.2. Forwarding

+ syntax may be changed.

12.2. Forwarding

To enable forwarding, the upstream address and port must be configured to forward queries to, such as: @@ -1362,7 +1362,7 @@ DDNS/zones[0]/update_acl[1] {"action": "ACCEPT", "from": "::1", "key": "key. or

> config remove Boss/components b10-dhcp4
 > config commit

- At start, the server will detect available network interfaces + During start-up the server will detect available network interfaces and will attempt to open UDP sockets on all interfaces that are up, running, are not loopback, and have IPv4 address assigned. @@ -1372,13 +1372,8 @@ DDNS/zones[0]/update_acl[1] {"action": "ACCEPT", "from": "::1", "key": "key. will respond to them with OFFER and ACK, respectively. Since the DHCPv4 server opens privileged ports, it requires root - access. Make sure you run this daemon as root.

Note

- Integration with bind10 is - planned. Ultimately, b10-dhcp4 will not - be started directly, but rather via - bind10. Please be aware of this planned - change. -

13.2. DHCPv4 Server Configuration

+ access. Make sure you run this daemon as root. +

13.2. DHCPv4 Server Configuration

The DHCPv4 server does not have a lease database implemented yet nor any support for configuration, so every time the same set of configuration options (including the same fixed address) @@ -1458,22 +1453,21 @@ const std::string HARDCODED_SERVER_ID = "192.0.2.1";

significant limitations. See Section 14.4, “DHCPv6 Server Limitations” for details.

- The DHCPv6 server is implemented as b10-dhcp6 - daemon. As it is not configurable yet, it is fully autonomous, - that is it does not interact with b10-cfgmgr. - To start DHCPv6 server, simply input: - -

-#cd src/bin/dhcp6
-#./b10-dhcp6
-

- - Depending on your installation, b10-dhcp6 - binary may reside in src/bin/dhcp6 in your source code - directory, in /usr/local/bin/b10-dhcp6 or other directory - you specified during compilation. - - At start, server will detect available network interfaces + b10-dhcp6 is a BIND10 component and is being + run under BIND10 framework. To add a DHCPv6 process to the set of running + BIND10 services, you can use following commands in bindctl: +

> config add Boss/components b10-dhcp6
+> config set Boss/components/b10-dhcp6/kind dispensable
+> config commit

+

+ To shutdown running b10-dhcp6, please use the + following command: +

> Dhcp6 shutdown

+ or +

> config remove Boss/components b10-dhcp6
+> config commit

+

+ During start-up the server will detect available network interfaces and will attempt to open UDP sockets on all interfaces that are up, running, are not loopback, are multicast-capable, and have IPv6 address assigned. @@ -1484,13 +1478,7 @@ const std::string HARDCODED_SERVER_ID = "192.0.2.1";

Since the DHCPv6 server opens privileged ports, it requires root access. Make sure you run this daemon as root. -

Note

- Integration with bind10 is - planned. Ultimately, b10-dhcp6 will not - be started directly, but rather via - bind10. Please be aware of this planned - change. -

14.2. DHCPv6 Server Configuration

+

14.2. DHCPv6 Server Configuration

The DHCPv6 server does not have lease database implemented yet or any support for configuration, so every time the same set of configuration options (including the same fixed address) @@ -1498,7 +1486,7 @@ const std::string HARDCODED_SERVER_ID = "192.0.2.1";

At this stage of development, the only way to alter server configuration is to tweak its source code. To do so, please - edit src/bin/dhcp6/dhcp6_srv.cc file and modify following + edit src/bin/dhcp6/dhcp6_srv.cc file, modify the following parameters and recompile:

 const std::string HARDCODED_LEASE = "2001:db8:1::1234:abcd";
@@ -1592,7 +1580,7 @@ const std::string HARDCODED_DNS_SERVER = "2001:db8:1::1";

} }

-

Chapter 17. Logging

17.1. Logging configuration

+

Chapter 17. Logging

17.1. Logging configuration

The logging system in BIND 10 is configured through the Logging module. All BIND 10 modules will look at the @@ -1601,7 +1589,7 @@ const std::string HARDCODED_DNS_SERVER = "2001:db8:1::1";

-

17.1.1. Loggers

+

17.1.1. Loggers

Within BIND 10, a message is logged through a component called a "logger". Different parts of BIND 10 log messages @@ -1622,7 +1610,7 @@ const std::string HARDCODED_DNS_SERVER = "2001:db8:1::1";

(what to log), and the output_options (where to log). -

17.1.1.1. name (string)

+

17.1.1.1. name (string)

Each logger in the system has a name, the name being that of the component using it to log messages. For instance, if you want to configure logging for the resolver module, @@ -1695,7 +1683,7 @@ const std::string HARDCODED_DNS_SERVER = "2001:db8:1::1";

Auth.cache logger will appear in the output with a logger name of b10-auth.cache). -

17.1.1.2. severity (string)

+

17.1.1.2. severity (string)

This specifies the category of messages logged. Each message is logged with an associated severity which @@ -1711,7 +1699,7 @@ const std::string HARDCODED_DNS_SERVER = "2001:db8:1::1";

-

17.1.1.3. output_options (list)

+

17.1.1.3. output_options (list)

Each logger can have zero or more output_options. These specify where log @@ -1721,7 +1709,7 @@ const std::string HARDCODED_DNS_SERVER = "2001:db8:1::1";

The other options for a logger are: -

17.1.1.4. debuglevel (integer)

+

17.1.1.4. debuglevel (integer)

When a logger's severity is set to DEBUG, this value specifies what debug messages should be printed. It ranges @@ -1730,7 +1718,7 @@ const std::string HARDCODED_DNS_SERVER = "2001:db8:1::1";

If severity for the logger is not DEBUG, this value is ignored. -

17.1.1.5. additive (true or false)

+

17.1.1.5. additive (true or false)

If this is true, the output_options from the parent will be used. For example, if there are two @@ -1744,18 +1732,18 @@ const std::string HARDCODED_DNS_SERVER = "2001:db8:1::1";

-

17.1.2. Output Options

+

17.1.2. Output Options

The main settings for an output option are the destination and a value called output, the meaning of which depends on the destination that is set. -

17.1.2.1. destination (string)

+

17.1.2.1. destination (string)

The destination is the type of output. It can be one of: -

  • console
  • file
  • syslog

17.1.2.2. output (string)

+

  • console
  • file
  • syslog

17.1.2.2. output (string)

Depending on what is set as the output destination, this value is interpreted as follows: @@ -1785,12 +1773,12 @@ const std::string HARDCODED_DNS_SERVER = "2001:db8:1::1";

The other options for output_options are: -

17.1.2.2.1. flush (true of false)

+

17.1.2.2.1. flush (true of false)

Flush buffers after each log message. Doing this will reduce performance but will ensure that if the program terminates abnormally, all messages up to the point of termination are output. -

17.1.2.2.2. maxsize (integer)

+

17.1.2.2.2. maxsize (integer)

Only relevant when destination is file, this is maximum file size of output files in bytes. When the maximum size is reached, the file is renamed and a new file opened. @@ -1799,11 +1787,11 @@ const std::string HARDCODED_DNS_SERVER = "2001:db8:1::1";

etc.)

If this is 0, no maximum file size is used. -

17.1.2.2.3. maxver (integer)

+

17.1.2.2.3. maxver (integer)

Maximum number of old log files to keep around when rolling the output file. Only relevant when destination is file. -

17.1.3. Example session

+

17.1.3. Example session

In this example we want to set the global logging to write to the file /var/log/my_bind10.log, @@ -1964,7 +1952,7 @@ Logging/loggers[0]/output_options[0]/maxver 8 integer (modified) And every module will now be using the values from the logger named *. -

17.2. Logging Message Format

+

17.2. Logging Message Format

Each message written by BIND 10 to the configured logging destinations comprises a number of components that identify the origin of the message and, if the message indicates diff --git a/doc/guide/bind10-guide.txt b/doc/guide/bind10-guide.txt index e38b43a34be8e703165a8c867d831929ad15fb79..bc015154e18b9c3e7fc94ae4afd8b35a4ca5b8fc 100644 --- a/doc/guide/bind10-guide.txt +++ b/doc/guide/bind10-guide.txt @@ -4,7 +4,7 @@ Administrator Reference for BIND 10 This is the reference guide for BIND 10 version 20120405. - Copyright (c) 2010-2012 Internet Systems Consortium, Inc. + Copyright © 2010-2012 Internet Systems Consortium, Inc. Abstract @@ -168,12 +168,12 @@ Preface 1. Acknowledgements -1. Acknowledgements +1. Acknowledgements ISC would like to acknowledge generous support for BIND 10 development of DHCPv4 and DHCPv6 components provided by Comcast. -Chapter 1. Introduction +Chapter 1. Introduction Table of Contents @@ -193,7 +193,7 @@ Chapter 1. Introduction This guide covers the experimental prototype of BIND 10 version 20120405. -1.1. Supported Platforms +1.1. Supported Platforms BIND 10 builds have been tested on (in no particular order) Debian GNU/Linux 5 and unstable, Ubuntu 9.10, NetBSD 5, Solaris 10 and 11, @@ -202,7 +202,7 @@ Chapter 1. Introduction planned for BIND 10 to build, install and run on Windows and standard Unix-type platforms. -1.2. Required Software +1.2. Required Software BIND 10 requires at least Python 3.1 (http://www.python.org/). It has also been tested with Python 3.2. @@ -229,7 +229,7 @@ Chapter 1. Introduction installation nor standard packages collections. You may need to install them separately. -1.3. Starting and Stopping the Server +1.3. Starting and Stopping the Server BIND 10 is modular. Part of this modularity is accomplished using multiple cooperating processes which, together, provide the server functionality. @@ -242,47 +242,46 @@ Chapter 1. Introduction processes as needed. The processes started by the bind10 command have names starting with "b10-", including: - o b10-auth -- Authoritative DNS server. This process serves DNS - requests. - o b10-cfgmgr -- Configuration manager. This process maintains all of the + o b10-auth — Authoritative DNS server. This process serves DNS requests. + o b10-cfgmgr — Configuration manager. This process maintains all of the configuration for BIND 10. - o b10-cmdctl -- Command and control service. This process allows - external control of the BIND 10 system. - o b10-ddns -- Dynamic DNS update service. This process is used to handle + o b10-cmdctl — Command and control service. This process allows external + control of the BIND 10 system. + o b10-ddns — Dynamic DNS update service. This process is used to handle incoming DNS update requests to allow granted clients to update zones for which BIND 10 is serving as a primary server. - o b10-msgq -- Message bus daemon. This process coordinates communication + o b10-msgq — Message bus daemon. This process coordinates communication between all of the other BIND 10 processes. - o b10-resolver -- Recursive name server. This process handles incoming + o b10-resolver — Recursive name server. This process handles incoming queries. - o b10-sockcreator -- Socket creator daemon. This process creates sockets + o b10-sockcreator — Socket creator daemon. This process creates sockets used by network-listening BIND 10 processes. - o b10-stats -- Statistics collection daemon. This process collects and + o b10-stats — Statistics collection daemon. This process collects and reports statistics data. - o b10-stats-httpd -- HTTP server for statistics reporting. This process + o b10-stats-httpd — HTTP server for statistics reporting. This process reports statistics data in XML format over HTTP. - o b10-xfrin -- Incoming zone transfer service. This process is used to + o b10-xfrin — Incoming zone transfer service. This process is used to transfer a new copy of a zone into BIND 10, when acting as a secondary server. - o b10-xfrout -- Outgoing zone transfer service. This process is used to + o b10-xfrout — Outgoing zone transfer service. This process is used to handle transfer requests to send a local zone to a remote secondary server, when acting as a master server. - o b10-zonemgr -- Secondary manager. This process keeps track of timers + o b10-zonemgr — Secondary manager. This process keeps track of timers and other necessary information for BIND 10 to act as a slave server. These are ran automatically by bind10 and do not need to be run manually. -1.4. Managing BIND 10 +1.4. Managing BIND 10 Once BIND 10 is running, a few commands are used to interact directly with the system: - o bindctl -- interactive administration interface. This is a low-level + o bindctl — interactive administration interface. This is a low-level command-line tool which allows a developer or an experienced administrator to control BIND 10. - o b10-loadzone -- zone file loader. This tool will load standard + o b10-loadzone — zone file loader. This tool will load standard masterfile-format zone files into BIND 10. - o b10-cmdctl-usermgr -- user access control. This tool allows an + o b10-cmdctl-usermgr — user access control. This tool allows an administrator to authorize additional users to manage BIND 10. The tools and modules are covered in full detail in this guide. In @@ -292,7 +291,7 @@ Chapter 1. Introduction Python for the message bus, configuration backend, and, of course, DNS. These include detailed developer documentation and code examples. -Chapter 2. Installation +Chapter 2. Installation Table of Contents @@ -314,7 +313,7 @@ Chapter 2. Installation 2.3.6. Install Hierarchy -2.1. Building Requirements +2.1. Building Requirements In addition to the run-time requirements, building BIND 10 from source code requires various development include headers. @@ -340,7 +339,7 @@ Chapter 2. Installation Visit the wiki at http://bind10.isc.org/wiki/SystemSpecificNotes for system-specific installation tips. -2.2. Quick start +2.2. Quick start Note @@ -351,48 +350,48 @@ Chapter 2. Installation To quickly get started with BIND 10, follow these steps. - 1. Install required run-time and build dependencies. - 2. Download the BIND 10 source tar file from +  1. Install required run-time and build dependencies. +  2. Download the BIND 10 source tar file from ftp://ftp.isc.org/isc/bind10/. - 3. Extract the tar file: +  3. Extract the tar file: $ gzcat bind10-VERSION.tar.gz | tar -xvf - - 4. Go into the source and run configure: +  4. Go into the source and run configure: $ cd bind10-VERSION $ ./configure - 5. Build it: +  5. Build it: $ make - 6. Install it (to default /usr/local): +  6. Install it (to default /usr/local): $ make install - 7. Start the server: +  7. Start the server: $ /usr/local/sbin/bind10 - 8. Test it; for example: +  8. Test it; for example: $ dig @127.0.0.1 -c CH -t TXT authors.bind - 9. Load desired zone file(s), for example: +  9. Load desired zone file(s), for example: $ b10-loadzone your.zone.example.org - 10. Test the new zone. + 10. Test the new zone. -2.3. Installation from source +2.3. 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 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. - 2.3.1. Download Tar File + 2.3.1. Download Tar File Downloading a release tar file is the recommended method to obtain the source code. @@ -401,7 +400,7 @@ Chapter 2. Installation ftp://ftp.isc.org/isc/bind10/. Periodic development snapshots may also be available. - 2.3.2. Retrieve from Git + 2.3.2. Retrieve from Git Downloading this "bleeding edge" code is recommended only for developers or advanced users. Using development code in a production environment is @@ -416,7 +415,7 @@ Chapter 2. Installation 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 Git and all the BIND 10 development is public. - The leading development is done in the "master". + The leading development is done in the “master”. The code can be checked out from git://git.bind10.isc.org/bind10; for example: @@ -429,7 +428,7 @@ Chapter 2. Installation the --install switch. This will run autoconf, aclocal, libtoolize, autoheader, automake, and related commands. - 2.3.3. Configure before the build + 2.3.3. 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: @@ -464,14 +463,14 @@ Chapter 2. Installation If the configure fails, it may be due to missing or old dependencies. - 2.3.4. Build + 2.3.4. Build After the configure step is complete, to build the executables from the C++ code and prepare the Python scripts, run: $ make - 2.3.5. Install + 2.3.5. Install To install the BIND 10 executables, support files, and documentation, run: @@ -481,22 +480,22 @@ Chapter 2. Installation The install step may require superuser privileges. - 2.3.6. Install Hierarchy + 2.3.6. Install Hierarchy The following is the layout of the complete BIND 10 installation: - o bin/ -- general tools and diagnostic clients. - o etc/bind10-devel/ -- configuration files. - o lib/ -- libraries and python modules. - o libexec/bind10-devel/ -- executables that a user wouldn't normally run + o bin/ — general tools and diagnostic clients. + o etc/bind10-devel/ — configuration files. + o lib/ — libraries and python modules. + o libexec/bind10-devel/ — executables that a user wouldn't normally run directly and are not run independently. These are the BIND 10 modules which are daemons started by the bind10 tool. - o sbin/ -- commands used by the system administrator. - o share/bind10-devel/ -- configuration specifications. - o share/man/ -- manual pages (online documentation). - o var/bind10-devel/ -- data source and configuration databases. + o sbin/ — commands used by the system administrator. + o share/bind10-devel/ — configuration specifications. + o share/man/ — manual pages (online documentation). + o var/bind10-devel/ — data source and configuration databases. -Chapter 3. Starting BIND10 with bind10 +Chapter 3. Starting BIND10 with bind10 Table of Contents @@ -523,7 +522,7 @@ Chapter 3. Starting BIND10 with bind10 b10-cmdctl for administration tools to communicate with the system, and b10-stats for statistics collection. -3.1. Starting BIND 10 +3.1. Starting BIND 10 To start the BIND 10 service, simply run bind10. Run it with the --verbose switch to get additional debugging or diagnostic output. @@ -532,9 +531,9 @@ Chapter 3. Starting BIND10 with bind10 If the setproctitle Python module is detected at start up, the process names for the Python-based daemons will be renamed to better identify them - instead of just "python". This is not needed on some operating systems. + instead of just “python”. This is not needed on some operating systems. -3.2. Configuration of started processes +3.2. Configuration of started processes The processes to be started can be configured, with the exception of the b10-sockcreator, b10-msgq and b10-cfgmgr. @@ -561,7 +560,7 @@ Chapter 3. Starting BIND10 with bind10 usual way. This is the list of components that need to be started in a special way, with the value of special used for them: - Table 3.1. + Table 3.1.  +------------------------------------------------------------------------+ | Component | Special | Description | @@ -575,11 +574,11 @@ Chapter 3. Starting BIND10 with bind10 +------------------------------------------------------------------------+ The kind specifies how a failure of the component should be handled. If it - is set to "dispensable" (the default unless you set something else), it - will get started again if it fails. If it is set to "needed" and it fails + is set to “dispensable” (the default unless you set something else), it + will get started again if it fails. If it is set to “needed” and it fails at startup, the whole bind10 shuts down and exits with error exit code. But if it fails some time later, it is just started again. If you set it - to "core", you indicate that the system is not usable without the + to “core”, you indicate that the system is not usable without the component and if such component fails, the system shuts down no matter when the failure happened. This is the behaviour of the core components (the ones you can't turn off), but you can declare any other components as @@ -592,10 +591,10 @@ Chapter 3. Starting BIND10 with bind10 the default is enough. There are other parameters we didn't use in our example. One of them is - "address". It is the address used by the component on the b10-msgq message + “address”. It is the address used by the component on the b10-msgq message bus. The special components already know their address, but the usual ones don't. The address is by convention the thing after b10-, with the first - letter capitalized (eg. b10-stats would have "Stats" as its address). + letter capitalized (eg. b10-stats would have “Stats” as its address). The last one is process. It is the name of the process to be started. It defaults to the name of the component if not set, but you can use this to @@ -636,11 +635,11 @@ Chapter 3. Starting BIND10 with bind10 locking the sqlite database, if used. The configuration might be changed to something more convenient in future. -Chapter 4. Command channel +Chapter 4. Command channel The BIND 10 components use the b10-msgq message routing daemon to communicate with other BIND 10 components. The b10-msgq implements what is - called the "Command Channel". Processes intercommunicate by sending + called the “Command Channel”. Processes intercommunicate by sending messages on the command channel. Example messages include shutdown, get configurations, and set configurations. This Command Channel is not used for DNS message passing. It is used only to control and monitor the BIND @@ -650,7 +649,7 @@ Chapter 4. Command channel default, BIND 10 uses port 9912 for the b10-msgq service. It listens on 127.0.0.1. -Chapter 5. Configuration manager +Chapter 5. Configuration manager The configuration manager, b10-cfgmgr, handles all BIND 10 system configuration. It provides persistent storage for configuration, and @@ -662,7 +661,7 @@ Chapter 5. Configuration manager The administrator doesn't connect to it directly, but uses a user interface to communicate with the configuration manager via b10-cmdctl's - REST-ful interface. b10-cmdctl is covered in Chapter 6, Remote control + REST-ful interface. b10-cmdctl is covered in Chapter 6, Remote control daemon. Note @@ -686,10 +685,10 @@ Chapter 5. Configuration manager The configuration manager does not have any command line arguments. Normally it is not started manually, but is automatically started using - the bind10 master process (as covered in Chapter 3, Starting BIND10 with + the bind10 master process (as covered in Chapter 3, Starting BIND10 with bind10). -Chapter 6. Remote control daemon +Chapter 6. Remote control daemon Table of Contents @@ -702,7 +701,7 @@ Chapter 6. Remote control daemon When b10-cmdctl starts, it firsts asks b10-cfgmgr about what modules are running and what their configuration is (over the b10-msgq channel). Then - it will start listening on HTTPS for clients -- the user interface -- such + it will start listening on HTTPS for clients — the user interface — such as bindctl. b10-cmdctl directly sends commands (received from the user interface) to @@ -729,7 +728,7 @@ Chapter 6. Remote control daemon /usr/local/etc/bind10-devel/cmdctl-accounts.csv. This comma-delimited file lists the accounts with a user name, hashed password, and salt. (A sample file is at /usr/local/share/bind10-devel/cmdctl-accounts.csv. It contains - the user named "root" with the password "bind10".) + the user named “root” with the password “bind10”.) The administrator may create a user account with the b10-cmdctl-usermgr tool. @@ -740,14 +739,14 @@ Chapter 6. Remote control daemon connection is stateless and times out in 1200 seconds by default. This can be redefined by using the --idle-timeout command line argument. -6.1. Configuration specification for b10-cmdctl +6.1. Configuration specification for b10-cmdctl The configuration items for b10-cmdctl are: key_file cert_file accounts_file The control commands are: print_settings shutdown -Chapter 7. Control and configure user interface +Chapter 7. Control and configure user interface Note @@ -767,7 +766,7 @@ Chapter 7. Control and configure user interface b10-cfgmgr which then stores the details and relays (over a b10-msgq command channel) the configuration on to the specified module. -Chapter 8. Authoritative Server +Chapter 8. Authoritative Server Table of Contents @@ -789,10 +788,10 @@ Chapter 8. Authoritative Server DNSSEC. It supports IPv6. Normally it is started by the bind10 master process. -8.1. Server Configurations +8.1. Server Configurations b10-auth is configured via the b10-cfgmgr configuration manager. The - module name is "Auth". The configuration data items are: + module name is “Auth”. The configuration data items are: database_file This is an optional string to define the path to find the SQLite3 @@ -801,8 +800,8 @@ Chapter 8. Authoritative Server datasources datasources configures data sources. The list items include: type - to define the required data source type (such as "memory"); class - to optionally select the class (it defaults to "IN"); and zones to + to define the required data source type (such as “memory”); class + to optionally select the class (it defaults to “IN”); and zones to define the file path name, the filetype (e.g., sqlite3), and the origin (default domain). By default, this is empty. @@ -833,7 +832,7 @@ Chapter 8. Authoritative Server There are plans to solve the problem such that the server handles it by itself. But until it is actually implemented, it is - recommended to alter the configuration -- remove the wildcard + recommended to alter the configuration — remove the wildcard addresses and list all addresses explicitly. Then the server will answer on the same interface the request came on, preserving the correct address. @@ -848,9 +847,9 @@ Chapter 8. Authoritative Server loadzone loadzone tells b10-auth to load or reload a zone file. The arguments include: class which optionally defines the class (it - defaults to "IN"); origin is the domain name of the zone; and + defaults to “IN”); origin is the domain name of the zone; and datasrc optionally defines the type of datasource (it defaults to - "memory"). + “memory”). Note @@ -866,7 +865,7 @@ Chapter 8. Authoritative Server argument to select the process ID to stop. (Note that the BIND 10 boss process may restart this service if configured.) -8.2. Data Source Backends +8.2. Data Source Backends Note @@ -879,13 +878,13 @@ Chapter 8. Authoritative Server /usr/local/var/bind10-devel/zone.sqlite3. (The full path is what was defined at build configure time for --localstatedir. The default is /usr/local/var/.) This data file location may be changed by defining the - "database_file" configuration. + “database_file” configuration. - 8.2.1. In-memory Data Source + 8.2.1. In-memory Data Source The following commands to bindctl provide an example of configuring an - in-memory data source containing the "example.com" zone with the zone file - named "example.com.zone": + in-memory data source containing the “example.com” zone with the zone file + named “example.com.zone”: > config add Auth/datasources > config set Auth/datasources[0]/type "memory" @@ -897,11 +896,11 @@ Chapter 8. Authoritative Server The authoritative server will begin serving it immediately after it is loaded. - 8.2.2. In-memory Data Source With SQLite3 Backend + 8.2.2. In-memory Data Source With SQLite3 Backend The following commands to bindctl provide an example of configuring an - in-memory data source containing the "example.org" zone with a SQLite3 - backend file named "example.org.sqlite3": + in-memory data source containing the “example.org” zone with a SQLite3 + backend file named “example.org.sqlite3”: > config add Auth/datasources > config set Auth/datasources[1]/type "memory" @@ -914,14 +913,14 @@ Chapter 8. Authoritative Server The authoritative server will begin serving it immediately after it is loaded. - 8.2.3. Reloading an In-memory Data Source + 8.2.3. Reloading an In-memory Data Source Use the Auth loadzone command in bindctl to reload a changed master file into memory; for example: > Auth loadzone origin="example.com" - 8.2.4. Disabling In-memory Data Sources + 8.2.4. Disabling In-memory Data Sources By default, the memory data source is disabled; it must be configured explicitly. To disable all the in-memory zones, specify a null list for @@ -938,7 +937,7 @@ Chapter 8. Authoritative Server (Replace the list number(s) in datasources[0] and/or zones[0] for the relevant zone as needed.) -8.3. Loading Master Zones Files +8.3. Loading Master Zones Files RFC 1035 style DNS master zone files may imported into a BIND 10 SQLite3 data source by using the b10-loadzone utility. @@ -969,7 +968,7 @@ Chapter 8. Authoritative Server If you reload a zone already existing in the database, all records from that prior zone disappear and a whole new set appears. -Chapter 9. Incoming Zone Transfers +Chapter 9. Incoming Zone Transfers Table of Contents @@ -987,13 +986,13 @@ Chapter 9. Incoming Zone Transfers started by bind10. When received, the zone is stored in the corresponding BIND 10 data source, and its records can be served by b10-auth. In combination with b10-zonemgr (for automated SOA checks), this allows the - BIND 10 server to provide "secondary" service. + BIND 10 server to provide “secondary” service. The b10-xfrin process supports both AXFR and IXFR. Due to some implementation limitations of the current development release, however, it only tries AXFR by default, and care should be taken to enable IXFR. -9.1. Configuration for Incoming Zone Transfers +9.1. Configuration for Incoming Zone Transfers In practice, you need to specify a list of secondary zones to enable incoming zone transfers for these zones (you can still trigger a zone @@ -1010,7 +1009,7 @@ Chapter 9. Incoming Zone Transfers (We assume there has been no zone configuration before). -9.2. Enabling IXFR +9.2. Enabling IXFR As noted above, b10-xfrin uses AXFR for zone transfers by default. To enable IXFR for zone transfers for a particular zone, set the use_ixfr @@ -1033,7 +1032,7 @@ Chapter 9. Incoming Zone Transfers be implemented in a near future version, at which point we will enable IXFR by default. -9.3. Secondary Manager +9.3. Secondary Manager The b10-zonemgr process is started by bind10. It keeps track of SOA refresh, retry, and expire timers and other details for BIND 10 to perform @@ -1059,14 +1058,14 @@ Chapter 9. Incoming Zone Transfers for it), b10-zonemgr will automatically tell b10-xfrin to transfer the zone in. -9.4. Trigger an Incoming Zone Transfer Manually +9.4. Trigger an Incoming Zone Transfer Manually To manually trigger a zone transfer to retrieve a remote zone, you may use the bindctl utility. For example, at the bindctl prompt run: > Xfrin retransfer zone_name="foo.example.org" master=192.0.2.99 -9.5. Incoming Transfers with In-memory Datasource +9.5. Incoming Transfers with In-memory Datasource In the case of an incoming zone transfer, the received zone is first stored in the corresponding BIND 10 datasource. In case the secondary zone @@ -1076,9 +1075,9 @@ Chapter 9. Incoming Zone Transfers The administrator doesn't have to do anything for b10-auth to serve the new version of the zone, except for the configuration such as the one - described in Section 8.2.2, "In-memory Data Source With SQLite3 Backend". + described in Section 8.2.2, “In-memory Data Source With SQLite3 Backend”. -Chapter 10. Outbound Zone Transfers +Chapter 10. Outbound Zone Transfers The b10-xfrout process is started by bind10. When the b10-auth authoritative DNS server receives an AXFR or IXFR request, b10-auth @@ -1127,7 +1126,7 @@ Chapter 10. Outbound Zone Transfers The way to specify zone specific configuration (ACLs, etc) is likely to be changed. -Chapter 11. Dynamic DNS Update +Chapter 11. Dynamic DNS Update Table of Contents @@ -1149,8 +1148,8 @@ Chapter 11. Dynamic DNS Update etc). If the zone has been changed as a result, it will internally notify b10-xfrout so that other secondary servers will be notified via the DNS notify protocol. In addition, if b10-auth serves the updated zone from its - in-memory cache (as described in Section 8.2.2, "In-memory Data Source - With SQLite3 Backend"), b10-ddns will also notify b10-auth so that + in-memory cache (as described in Section 8.2.2, “In-memory Data Source + With SQLite3 Backend”), b10-ddns will also notify b10-auth so that b10-auth will re-cache the updated zone content. The b10-ddns component supports requests over both UDP and TCP, and both @@ -1172,7 +1171,7 @@ Chapter 11. Dynamic DNS Update But right now it's considered a lower priority task and there is no specific plan of implementing this feature. -11.1. Enabling Dynamic Update +11.1. Enabling Dynamic Update First off, it must be made sure that a few components on which b10-ddns depends are configured to run, which are b10-auth and b10-zonemgr. In @@ -1187,7 +1186,7 @@ Chapter 11. Dynamic DNS Update data source storing the zone data be writable. In the current implementation this means the zone must be stored in an SQLite3-based data source. Also, right now, the b10-ddns component configures itself with the - data source referring to the "database_file" configuration parameter of + data source referring to the “database_file” configuration parameter of b10-auth. So this information must be configured correctly before starting b10-ddns. @@ -1221,13 +1220,13 @@ Chapter 11. Dynamic DNS Update because b10-ddns would start and work without specifying it. But for it to shutdown gracefully this parameter should also be specified. -11.2. Access Control +11.2. Access Control By default b10-ddns rejects any update requests from any clients by returning a response with an RCODE of REFUSED. To allow updates to take effect, an access control rule (called update ACL) with a policy allowing updates must explicitly be configured. Update ACL must be configured per - zone basis in the "zones" configuration parameter of b10-ddns. This is a + zone basis in the “zones” configuration parameter of b10-ddns. This is a list of per-zone configurations regarding DDNS. Each list element consists of the following parameters: @@ -1235,7 +1234,7 @@ Chapter 11. Dynamic DNS Update The zone's origin name class - The RR class of the zone (normally "IN", and in that case can be + The RR class of the zone (normally “IN”, and in that case can be omitted in configuration) update_acl @@ -1246,7 +1245,7 @@ Chapter 11. Dynamic DNS Update In general, an update ACL rule that allows an update request should be configured with a TSIG key. This is an example update ACL that allows - updates to the zone named "example.org" of RR class "IN" from clients that + updates to the zone named “example.org” of RR class “IN” from clients that send requests signed with a TSIG whose key name is "key.example.org" (and refuses all others): @@ -1257,7 +1256,7 @@ Chapter 11. Dynamic DNS Update > config add DDNS/zones[0]/update_acl {"action": "ACCEPT", "key": "key.example.org"} > config commit - The TSIG key must be configured system wide (see Chapter 10, Outbound Zone + The TSIG key must be configured system wide (see Chapter 10, Outbound Zone Transfers.) Multiple rules can be specified in the ACL, and an ACL rule can consist of @@ -1293,7 +1292,7 @@ Chapter 11. Dynamic DNS Update which is rejecting any requests in the case of b10-ddns. Other actions than "ACCEPT", namely "REJECT" and "DROP", can be used, too. - See Chapter 12, Recursive Name Server about their effects. + See Chapter 12, Recursive Name Server about their effects. Currently update ACL can only control updates per zone basis; it's not possible to specify access control with higher granularity such as for @@ -1313,7 +1312,7 @@ Chapter 11. Dynamic DNS Update clients. There have been other troubles that could have been avoided if the ACL could be checked before the prerequisite check. -11.3. Miscellaneous Operational Issues +11.3. Miscellaneous Operational Issues Unlike BIND 9, BIND 10 currently does not support automatic resigning of DNSSEC-signed zone when it's updated via DDNS. It could be possible to @@ -1322,20 +1321,20 @@ Chapter 11. Dynamic DNS Update operation. In general, it's not advisable to allow DDNS for a signed zone at this moment. - Also unlike BIND 9, it's currently not possible to "freeze" a zone + Also unlike BIND 9, it's currently not possible to “freeze” a zone temporarily in order to suspend DDNS while you manually update the zone. If you need to make manual updates to a dynamic zone, you'll need to temporarily reject any updates to the zone via the update ACLs. Dynamic updates are only applicable to primary zones. In order to avoid updating secondary zones via DDNS requests, b10-ddns refers to the - "secondary_zones" configuration of b10-zonemgr. Zones listed in - "secondary_zones" will never be updated via DDNS regardless of the update + “secondary_zones” configuration of b10-zonemgr. Zones listed in + “secondary_zones” will never be updated via DDNS regardless of the update ACL configuration; b10-ddns will return a response with an RCODE of NOTAUTH as specified in RFC 2136. If you have a "conceptual" secondary zone whose content is a copy of some external source but is not updated via the standard zone transfers and therefore not listed in - "secondary_zones", be careful not to allow DDNS for the zone; it would be + “secondary_zones”, be careful not to allow DDNS for the zone; it would be quite likely to lead to inconsistent state between different servers. Normally this should not be a problem because the default update ACL rejects any update requests, but you may want to take an extra care about @@ -1346,7 +1345,7 @@ Chapter 11. Dynamic DNS Update can be retrieved in the form of outbound IXFR. This is done automatically; it does not require specific configuration to make this possible. -Chapter 12. Recursive Name Server +Chapter 12. Recursive Name Server Table of Contents @@ -1377,26 +1376,26 @@ Chapter 12. Recursive Name Server > config set Resolver/listen_on[2]/port 53 > config commit - (Replace the "2" as needed; run "config show Resolver/listen_on" if + (Replace the “2” as needed; run “config show Resolver/listen_on” if needed.) -12.1. Access Control +12.1. Access Control By default, the b10-resolver daemon only accepts DNS queries from the localhost (127.0.0.1 and ::1). The Resolver/query_acl configuration may be used to reject, drop, or allow specific IPs or networks. This configuration list is first match. - The configuration's action item may be set to "ACCEPT" to allow the - incoming query, "REJECT" to respond with a DNS REFUSED return code, or - "DROP" to ignore the query without any response (such as a blackhole). For + The configuration's action item may be set to “ACCEPT” to allow the + incoming query, “REJECT” to respond with a DNS REFUSED return code, or + “DROP” to ignore the query without any response (such as a blackhole). For more information, see the respective debugging messages: RESOLVER_QUERY_ACCEPTED, RESOLVER_QUERY_REJECTED, and RESOLVER_QUERY_DROPPED. The required configuration's from item is set to an IPv4 or IPv6 address, addresses with an network mask, or to the special lowercase keywords - "any6" (for any IPv6 address) or "any4" (for any IPv4 address). + “any6” (for any IPv6 address) or “any4” (for any IPv4 address). For example to allow the 192.168.1.0/24 network to use your recursive name server, at the bindctl prompt run: @@ -1406,14 +1405,14 @@ Chapter 12. Recursive Name Server > config set Resolver/query_acl[2]/from "192.168.1.0/24" > config commit - (Replace the "2" as needed; run "config show Resolver/query_acl" if + (Replace the “2” as needed; run “config show Resolver/query_acl” if needed.) Note This prototype access control configuration syntax may be changed. -12.2. Forwarding +12.2. Forwarding To enable forwarding, the upstream address and port must be configured to forward queries to, such as: @@ -1429,7 +1428,7 @@ Chapter 12. Recursive Name Server > config set Resolver/forward_addresses [] > config commit -Chapter 13. DHCPv4 Server +Chapter 13. DHCPv4 Server Table of Contents @@ -1449,7 +1448,7 @@ Chapter 13. DHCPv4 Server clients. Even though principles of both DHCPv4 and DHCPv6 are somewhat similar, these are two radically different protocols. BIND10 offers server implementations for both DHCPv4 and DHCPv6. This chapter is about DHCP for - IPv4. For a description of the DHCPv6 server, see Chapter 14, DHCPv6 + IPv4. For a description of the DHCPv6 server, see Chapter 14, DHCPv6 Server. The DHCPv4 server component is currently under intense development. You @@ -1457,7 +1456,7 @@ Chapter 13. DHCPv4 Server developers mailing list. The DHCPv4 and DHCPv6 components in BIND10 architecture are internally - code named "Kea". + code named “Kea”. Note @@ -1465,43 +1464,44 @@ Chapter 13. DHCPv4 Server servers. That means that while they are capable of performing DHCP configuration, they are not fully functional yet. In particular, neither has functional lease databases. This means that they will assign the same, - fixed, hardcoded addresses to any client that will ask. See Section 13.4, - "DHCPv4 Server Limitations" and Section 14.4, "DHCPv6 Server Limitations" + fixed, hardcoded addresses to any client that will ask. See Section 13.4, + “DHCPv4 Server Limitations” and Section 14.4, “DHCPv6 Server Limitations” for detailed description. -13.1. DHCPv4 Server Usage +13.1. DHCPv4 Server Usage BIND10 provides the DHCPv4 server component since December 2011. It is a skeleton server and can be described as an early prototype that is not fully functional yet. It is mature enough to conduct first tests in lab - environment, but it has significant limitations. See Section 13.4, "DHCPv4 - Server Limitations" for details. - - The DHCPv4 server is implemented as b10-dhcp4 daemon. As it is not - configurable yet, it is fully autonomous, that is it does not interact - with b10-cfgmgr. To start DHCPv4 server, simply input: - - #cd src/bin/dhcp4 - #./b10-dhcp4 - - Depending on your installation, b10-dhcp4 binary may reside in - src/bin/dhcp4 in your source code directory, in /usr/local/bin/b10-dhcp4 - or other directory you specified during compilation. At start, the server - will detect available network interfaces and will attempt to open UDP - sockets on all interfaces that are up, running, are not loopback, and have - IPv4 address assigned. The server will then listen to incoming traffic. - Currently supported client messages are DISCOVER and REQUEST. The server - will respond to them with OFFER and ACK, respectively. Since the DHCPv4 - server opens privileged ports, it requires root access. Make sure you run - this daemon as root. + environment, but it has significant limitations. See Section 13.4, “DHCPv4 + Server Limitations” for details. - Note + b10-dhcp4 is a BIND10 component and is being run under BIND10 framework. + To add a DHCPv4 process to the set of running BIND10 services, you can use + following commands in bindctl: + + > config add Boss/components b10-dhcp4 + > config set Boss/components/b10-dhcp4/kind dispensable + > config commit + + To shutdown running b10-dhcp4, please use the following command: + + > Dhcp4 shutdown - Integration with bind10 is planned. Ultimately, b10-dhcp4 will not be - started directly, but rather via bind10. Please be aware of this planned - change. + or -13.2. DHCPv4 Server Configuration + > config remove Boss/components b10-dhcp4 + > config commit + + During start-up the server will detect available network interfaces and + will attempt to open UDP sockets on all interfaces that are up, running, + are not loopback, and have IPv4 address assigned. The server will then + listen to incoming traffic. Currently supported client messages are + DISCOVER and REQUEST. The server will respond to them with OFFER and ACK, + respectively. Since the DHCPv4 server opens privileged ports, it requires + root access. Make sure you run this daemon as root. + +13.2. DHCPv4 Server Configuration The DHCPv4 server does not have a lease database implemented yet nor any support for configuration, so every time the same set of configuration @@ -1522,60 +1522,55 @@ Chapter 13. DHCPv4 Server Lease database and configuration support is planned for 2012. -13.3. Supported standards +13.3. Supported standards The following standards and draft standards are currently supported: - o RFC2131: Supported messages are DISCOVER, OFFER, REQUEST, and ACK. - o RFC2132: Supported options are: PAD (0), END(255), Message Type(53), + o RFC2131: Supported messages are DISCOVER, OFFER, REQUEST, and ACK. + o RFC2132: Supported options are: PAD (0), END(255), Message Type(53), DHCP Server Identifier (54), Domain Name (15), DNS Servers (6), IP Address Lease Time (51), Subnet mask (1), and Routers (3). -13.4. DHCPv4 Server Limitations +13.4. DHCPv4 Server Limitations These are the current limitations of the DHCPv4 server software. Most of them are reflections of the early stage of development and should be - treated as "not implemented yet", rather than actual limitations. + treated as “not implemented yet”, rather than actual limitations. - o During initial IPv4 node configuration, the server is expected to send + o During initial IPv4 node configuration, the server is expected to send packets to a node that does not have IPv4 address assigned yet. The server requires certain tricks (or hacks) to transmit such packets. This is not implemented yet, therefore DHCPv4 server supports relayed traffic only (that is, normal point to point communication). - o b10-dhcp4 provides a single, fixed, hardcoded lease to any client that + o b10-dhcp4 provides a single, fixed, hardcoded lease to any client that asks. There is no lease manager implemented. If two clients request addresses, they will both get the same fixed address. - o b10-dhcp4 does not support any configuration mechanisms yet. The whole + o b10-dhcp4 does not support any configuration mechanisms yet. The whole configuration is currently hardcoded. The only way to tweak - configuration is to directly modify source code. See see Section 13.2, - "DHCPv4 Server Configuration" for details. - o Upon start, the server will open sockets on all interfaces that are - not loopback, are up and running and have IPv4 address. Support for - multiple interfaces is not coded in reception routines yet, so if you - are running this code on a machine that has many interfaces and - b10-dhcp4 happens to listen on wrong interface, the easiest way to - work around this problem is to turn down other interfaces. This - limitation will be fixed shortly. - o PRL (Parameter Request List, a list of options requested by a client) + configuration is to directly modify source code. See see Section 13.2, + “DHCPv4 Server Configuration” for details. + o Upon start, the server will open sockets on all interfaces that are + not loopback, are up and running and have IPv4 address. + o PRL (Parameter Request List, a list of options requested by a client) is currently ignored and server assigns DNS SERVER and DOMAIN NAME options. - o b10-dhcp4 does not support BOOTP. That is a design choice. This + o b10-dhcp4 does not support BOOTP. That is a design choice. This limitation is permanent. If you have legacy nodes that can't use DHCP and require BOOTP support, please use latest version of ISC DHCP http://www.isc.org/software/dhcp. - o Interface detection is currently working on Linux only. See - Section 15.1, "Interface detection" for details. - o b10-dhcp4 does not verify that assigned address is unused. According + o Interface detection is currently working on Linux only. See + Section 15.1, “Interface detection” for details. + o b10-dhcp4 does not verify that assigned address is unused. According to RFC2131, the allocating server should verify that address is no used by sending ICMP echo request. - o Address renewal (RENEW), rebinding (REBIND), confirmation (CONFIRM), + o Address renewal (RENEW), rebinding (REBIND), confirmation (CONFIRM), duplication report (DECLINE) and release (RELEASE) are not supported yet. - o DNS Update is not supported yet. - o -v (verbose) command line option is currently the default, and cannot + o DNS Update is not supported yet. + o -v (verbose) command line option is currently the default, and cannot be disabled. -Chapter 14. DHCPv6 Server +Chapter 14. DHCPv6 Server Table of Contents @@ -1590,14 +1585,14 @@ Chapter 14. DHCPv6 Server Dynamic Host Configuration Protocol for IPv6 (DHCPv6) is specified in RFC3315. BIND10 provides DHCPv6 server implementation that is described in this chapter. For a description of the DHCPv4 server implementation, see - Chapter 13, DHCPv4 Server. + Chapter 13, DHCPv4 Server. The DHCPv6 server component is currently under intense development. You may want to check out BIND10 DHCP (Kea) wiki and recent posts on BIND10 developers mailing list. The DHCPv4 and DHCPv6 components in BIND10 architecture are internally - code named "Kea". + code named “Kea”. Note @@ -1605,43 +1600,45 @@ Chapter 14. DHCPv6 Server servers. That means that while they are capable of performing DHCP configuration, they are not fully functional yet. In particular, neither has functional lease databases. This means that they will assign the same, - fixed, hardcoded addresses to any client that will ask. See Section 13.4, - "DHCPv4 Server Limitations" and Section 14.4, "DHCPv6 Server Limitations" + fixed, hardcoded addresses to any client that will ask. See Section 13.4, + “DHCPv4 Server Limitations” and Section 14.4, “DHCPv6 Server Limitations” for detailed description. -14.1. DHCPv6 Server Usage +14.1. DHCPv6 Server Usage BIND10 provides the DHCPv6 server component since September 2011. It is a skeleton server and can be described as an early prototype that is not fully functional yet. It is mature enough to conduct first tests in lab - environment, but it has significant limitations. See Section 14.4, "DHCPv6 - Server Limitations" for details. - - The DHCPv6 server is implemented as b10-dhcp6 daemon. As it is not - configurable yet, it is fully autonomous, that is it does not interact - with b10-cfgmgr. To start DHCPv6 server, simply input: - - #cd src/bin/dhcp6 - #./b10-dhcp6 - - Depending on your installation, b10-dhcp6 binary may reside in - src/bin/dhcp6 in your source code directory, in /usr/local/bin/b10-dhcp6 - or other directory you specified during compilation. At start, server will - detect available network interfaces and will attempt to open UDP sockets - on all interfaces that are up, running, are not loopback, are - multicast-capable, and have IPv6 address assigned. The server will then - listen to incoming traffic. Currently supported client messages are - SOLICIT and REQUEST. The server will respond to them with ADVERTISE and - REPLY, respectively. Since the DHCPv6 server opens privileged ports, it - requires root access. Make sure you run this daemon as root. + environment, but it has significant limitations. See Section 14.4, “DHCPv6 + Server Limitations” for details. - Note + b10-dhcp6 is a BIND10 component and is being run under BIND10 framework. + To add a DHCPv6 process to the set of running BIND10 services, you can use + following commands in bindctl: + + > config add Boss/components b10-dhcp6 + > config set Boss/components/b10-dhcp6/kind dispensable + > config commit + + To shutdown running b10-dhcp6, please use the following command: + + > Dhcp6 shutdown - Integration with bind10 is planned. Ultimately, b10-dhcp6 will not be - started directly, but rather via bind10. Please be aware of this planned - change. + or -14.2. DHCPv6 Server Configuration + > config remove Boss/components b10-dhcp6 + > config commit + + During start-up the server will detect available network interfaces and + will attempt to open UDP sockets on all interfaces that are up, running, + are not loopback, are multicast-capable, and have IPv6 address assigned. + The server will then listen to incoming traffic. Currently supported + client messages are SOLICIT and REQUEST. The server will respond to them + with ADVERTISE and REPLY, respectively. Since the DHCPv6 server opens + privileged ports, it requires root access. Make sure you run this daemon + as root. + +14.2. DHCPv6 Server Configuration The DHCPv6 server does not have lease database implemented yet or any support for configuration, so every time the same set of configuration @@ -1649,7 +1646,7 @@ Chapter 14. DHCPv6 Server At this stage of development, the only way to alter server configuration is to tweak its source code. To do so, please edit - src/bin/dhcp6/dhcp6_srv.cc file and modify following parameters and + src/bin/dhcp6/dhcp6_srv.cc file, modify the following parameters and recompile: const std::string HARDCODED_LEASE = "2001:db8:1::1234:abcd"; @@ -1661,50 +1658,50 @@ Chapter 14. DHCPv6 Server Lease database and configuration support is planned for 2012. -14.3. Supported DHCPv6 Standards +14.3. Supported DHCPv6 Standards The following standards and draft standards are currently supported: - o RFC3315: Supported messages are SOLICIT, ADVERTISE, REQUEST, and + o RFC3315: Supported messages are SOLICIT, ADVERTISE, REQUEST, and REPLY. Supported options are SERVER_ID, CLIENT_ID, IA_NA, and IAADDRESS. - o RFC3646: Supported option is DNS_SERVERS. + o RFC3646: Supported option is DNS_SERVERS. -14.4. DHCPv6 Server Limitations +14.4. DHCPv6 Server Limitations These are the current limitations of the DHCPv6 server software. Most of them are reflections of the early stage of development and should be - treated as "not implemented yet", rather than actual limitations. + treated as “not implemented yet”, rather than actual limitations. - o Relayed traffic is not supported. - o b10-dhcp6 provides a single, fixed, hardcoded lease to any client that + o Relayed traffic is not supported. + o b10-dhcp6 provides a single, fixed, hardcoded lease to any client that asks. There is no lease manager implemented. If two clients request addresses, they will both get the same fixed address. - o b10-dhcp6 does not support any configuration mechanisms yet. The whole + o b10-dhcp6 does not support any configuration mechanisms yet. The whole configuration is currently hardcoded. The only way to tweak - configuration is to directly modify source code. See see Section 14.2, - "DHCPv6 Server Configuration" for details. - o Upon start, the server will open sockets on all interfaces that are + configuration is to directly modify source code. See see Section 14.2, + “DHCPv6 Server Configuration” for details. + o Upon start, the server will open sockets on all interfaces that are not loopback, are up, running and are multicast capable and have IPv6 address. Support for multiple interfaces is not coded in reception routines yet, so if you are running this code on a machine that has many interfaces and b10-dhcp6 happens to listen on wrong interface, the easiest way to work around this problem is to turn down other interfaces. This limitation will be fixed shortly. - o ORO (Option Request Option, a list of options requested by a client) + o ORO (Option Request Option, a list of options requested by a client) is currently ignored and server assigns DNS SERVER option. - o Temporary addresses are not supported yet. - o Prefix delegation is not supported yet. - o Address renewal (RENEW), rebinding (REBIND), confirmation (CONFIRM), + o Temporary addresses are not supported yet. + o Prefix delegation is not supported yet. + o Address renewal (RENEW), rebinding (REBIND), confirmation (CONFIRM), duplication report (DECLINE) and release (RELEASE) are not supported yet. - o DNS Update is not supported yet. - o Interface detection is currently working on Linux only. See - Section 15.1, "Interface detection" for details. - o -v (verbose) command line option is currently the default, and cannot + o DNS Update is not supported yet. + o Interface detection is currently working on Linux only. See + Section 15.1, “Interface detection” for details. + o -v (verbose) command line option is currently the default, and cannot be disabled. -Chapter 15. libdhcp++ library +Chapter 15. libdhcp++ library Table of Contents @@ -1722,33 +1719,22 @@ Chapter 15. libdhcp++ library is designed to be portable, universal library useful for any kind of DHCP-related software. -15.1. Interface detection +15.1. Interface detection Both DHCPv4 and DHCPv6 components share network interface detection routines. Interface detection is currently only supported on Linux systems. - For non-Linux systems, there is currently stub implementation provided. As - DHCP servers need to know available addresses, there is a simple mechanism - implemented to provide that information. User is expected to create - interfaces.txt file. Format of this file is simple. It contains list of - interfaces along with available address on each interface. This mechanism - is temporary and is going to be removed as soon as interface detection - becomes available on non-Linux systems. Here is an example of the - interfaces.txt file: - - # For DHCPv6, please specify link-local address (starts with fe80::) - # If in doubt, check output of 'ifconfig -a' command. - eth0 fe80::21e:8cff:fe9b:7349 - - # For DHCPv4, please use following format: - #eth0 192.0.2.5 + For non-Linux systems, there is currently stub implementation provided. + Interface manager detects loopback interfaces only as their name (lo or + lo0) can be easily predicted. Please contact BIND10 development team if + you are interested in running DHCP components on systems other than Linux. -15.2. DHCPv4/DHCPv6 packet handling +15.2. DHCPv4/DHCPv6 packet handling TODO: Describe packet handling here, with pointers to wiki -Chapter 16. Statistics +Chapter 16. Statistics The b10-stats process is started by bind10. It periodically collects statistics data from various modules and aggregates it. @@ -1780,7 +1766,7 @@ Chapter 16. Statistics } -Chapter 17. Logging +Chapter 17. Logging Table of Contents @@ -1794,13 +1780,13 @@ Chapter 17. Logging 17.2. Logging Message Format -17.1. Logging configuration +17.1. Logging configuration The logging system in BIND 10 is configured through the Logging module. All BIND 10 modules will look at the configuration in Logging to see what should be logged and to where. - 17.1.1. Loggers + 17.1.1. Loggers Within BIND 10, a message is logged through a component called a "logger". Different parts of BIND 10 log messages through different loggers, and @@ -1813,78 +1799,78 @@ Chapter 17. Logging (the component that is generating the messages), the severity (what to log), and the output_options (where to log). - 17.1.1.1. name (string) + 17.1.1.1. name (string) Each logger in the system has a name, the name being that of the component using it to log messages. For instance, if you want to configure logging - for the resolver module, you add an entry for a logger named "Resolver". + for the resolver module, you add an entry for a logger named “Resolver”. This configuration will then be used by the loggers in the Resolver module, and all the libraries used by it. If you want to specify logging for one specific library within the module, you set the name to module.library. For example, the logger used by the - nameserver address store component has the full name of "Resolver.nsas". + nameserver address store component has the full name of “Resolver.nsas”. If there is no entry in Logging for a particular library, it will use the configuration given for the module. To illustrate this, suppose you want the cache library to log messages of severity DEBUG, and the rest of the resolver code to log messages of severity INFO. To achieve this you specify two loggers, one with the name - "Resolver" and severity INFO, and one with the name "Resolver.cache" with + “Resolver” and severity INFO, and one with the name “Resolver.cache” with severity DEBUG. As there are no entries for other libraries (e.g. the - nsas), they will use the configuration for the module ("Resolver"), so + nsas), they will use the configuration for the module (“Resolver”), so giving the desired behavior. - One special case is that of a module name of "*" (asterisks), which is + One special case is that of a module name of “*” (asterisks), which is interpreted as any module. You can set global logging options by using this, including setting the logging configuration for a library that is - used by multiple modules (e.g. "*.config" specifies the configuration + used by multiple modules (e.g. “*.config” specifies the configuration library code in whatever module is using it). If there are multiple logger specifications in the configuration that might match a particular logger, the specification with the more specific logger name takes precedence. For example, if there are entries for for - both "*" and "Resolver", the resolver module -- and all libraries it uses - -- will log messages according to the configuration in the second entry - ("Resolver"). All other modules will use the configuration of the first - entry ("*"). If there was also a configuration entry for "Resolver.cache", + both “*” and “Resolver”, the resolver module — and all libraries it uses — + will log messages according to the configuration in the second entry + (“Resolver”). All other modules will use the configuration of the first + entry (“*”). If there was also a configuration entry for “Resolver.cache”, the cache library within the resolver would use that in preference to the - entry for "Resolver". + entry for “Resolver”. One final note about the naming. When specifying the module name within a logger, use the name of the module as specified in bindctl, e.g. - "Resolver" for the resolver module, "Xfrout" for the xfrout module, etc. + “Resolver” for the resolver module, “Xfrout” for the xfrout module, etc. When the message is logged, the message will include the name of the logger generating the message, but with the module name replaced by the name of the process implementing the module (so for example, a message - generated by the "Auth.cache" logger will appear in the output with a - logger name of "b10-auth.cache"). + generated by the “Auth.cache” logger will appear in the output with a + logger name of “b10-auth.cache”). - 17.1.1.2. severity (string) + 17.1.1.2. severity (string) This specifies the category of messages logged. Each message is logged with an associated severity which may be one of the following (in descending order of severity): - o FATAL - o ERROR - o WARN - o INFO - o DEBUG + o FATAL + o ERROR + o WARN + o INFO + o DEBUG When the severity of a logger is set to one of these values, it will only log messages of that severity, and the severities above it. The severity may also be set to NONE, in which case all messages from that logger are inhibited. - 17.1.1.3. output_options (list) + 17.1.1.3. output_options (list) Each logger can have zero or more output_options. These specify where log messages are sent to. These are explained in detail below. The other options for a logger are: - 17.1.1.4. debuglevel (integer) + 17.1.1.4. debuglevel (integer) When a logger's severity is set to DEBUG, this value specifies what debug messages should be printed. It ranges from 0 (least verbose) to 99 (most @@ -1892,80 +1878,80 @@ Chapter 17. Logging If severity for the logger is not DEBUG, this value is ignored. - 17.1.1.5. additive (true or false) + 17.1.1.5. additive (true or false) If this is true, the output_options from the parent will be used. For - example, if there are two loggers configured; "Resolver" and - "Resolver.cache", and additive is true in the second, it will write the - log messages not only to the destinations specified for "Resolver.cache", + example, if there are two loggers configured; “Resolver” and + “Resolver.cache”, and additive is true in the second, it will write the + log messages not only to the destinations specified for “Resolver.cache”, but also to the destinations as specified in the output_options in the - logger named "Resolver". + logger named “Resolver”. - 17.1.2. Output Options + 17.1.2. Output Options The main settings for an output option are the destination and a value called output, the meaning of which depends on the destination that is set. - 17.1.2.1. destination (string) + 17.1.2.1. destination (string) The destination is the type of output. It can be one of: - o console - o file - o syslog + o console + o file + o syslog - 17.1.2.2. output (string) + 17.1.2.2. output (string) Depending on what is set as the output destination, this value is interpreted as follows: - destination is "console" + destination is “console” - The value of output must be one of "stdout" (messages printed to - standard output) or "stderr" (messages printed to standard error). + The value of output must be one of “stdout” (messages printed to + standard output) or “stderr” (messages printed to standard error). - Note: if output is set to "stderr" and a lot of messages are + Note: if output is set to “stderr” and a lot of messages are produced in a short time (e.g. if the logging level is set to DEBUG), you may occasionally see some messages jumbled up together. This is due to a combination of the way that messages are written to the screen and the unbuffered nature of the standard error stream. If this occurs, it is recommended that - output be set to "stdout". + output be set to “stdout”. - destination is "file" + destination is “file” The value of output is interpreted as a file name; log messages will be appended to this file. - destination is "syslog" + destination is “syslog” The value of output is interpreted as the syslog facility (e.g. local0) that should be used for log messages. The other options for output_options are: - 17.1.2.2.1. flush (true of false) + 17.1.2.2.1. flush (true of false) Flush buffers after each log message. Doing this will reduce performance but will ensure that if the program terminates abnormally, all messages up to the point of termination are output. - 17.1.2.2.2. maxsize (integer) + 17.1.2.2.2. maxsize (integer) Only relevant when destination is file, this is maximum file size of output files in bytes. When the maximum size is reached, the file is renamed and a new file opened. (For example, a ".1" is appended to the - name -- if a ".1" file exists, it is renamed ".2", etc.) + name — if a ".1" file exists, it is renamed ".2", etc.) If this is 0, no maximum file size is used. - 17.1.2.2.3. maxver (integer) + 17.1.2.2.3. maxver (integer) Maximum number of old log files to keep around when rolling the output - file. Only relevant when destination is "file". + file. Only relevant when destination is “file”. - 17.1.3. Example session + 17.1.3. Example session In this example we want to set the global logging to write to the file /var/log/my_bind10.log, at severity WARN. We want the authoritative server @@ -2064,9 +2050,9 @@ Chapter 17. Logging > config remove Logging/loggers[1] > config commit - And every module will now be using the values from the logger named "*". + And every module will now be using the values from the logger named “*”. -17.2. Logging Message Format +17.2. Logging Message Format Each message written by BIND 10 to the configured logging destinations comprises a number of components that identify the origin of the message diff --git a/doc/guide/bind10-guide.xml b/doc/guide/bind10-guide.xml index 1bdc0053f5cc7cb4c0688e8da3ed30eac9722f2c..48862c4858d9f4c3db2073b31dfd5cde47cf6190 100644 --- a/doc/guide/bind10-guide.xml +++ b/doc/guide/bind10-guide.xml @@ -2455,7 +2455,7 @@ then change those defaults with config set Resolver/forward_addresses[0]/address > config commit - At start, the server will detect available network interfaces + During start-up the server will detect available network interfaces and will attempt to open UDP sockets on all interfaces that are up, running, are not loopback, and have IPv4 address assigned. @@ -2465,17 +2465,8 @@ then change those defaults with config set Resolver/forward_addresses[0]/address will respond to them with OFFER and ACK, respectively. Since the DHCPv4 server opens privileged ports, it requires root - access. Make sure you run this daemon as root. - - - - Integration with bind10 is - planned. Ultimately, b10-dhcp4 will not - be started directly, but rather via - bind10. Please be aware of this planned - change. - - + access. Make sure you run this daemon as root. + @@ -2640,22 +2631,25 @@ const std::string HARDCODED_SERVER_ID = "192.0.2.1"; - The DHCPv6 server is implemented as b10-dhcp6 - daemon. As it is not configurable yet, it is fully autonomous, - that is it does not interact with b10-cfgmgr. - To start DHCPv6 server, simply input: - - -#cd src/bin/dhcp6 -#./b10-dhcp6 - + b10-dhcp6 is a BIND10 component and is being + run under BIND10 framework. To add a DHCPv6 process to the set of running + BIND10 services, you can use following commands in bindctl: + > config add Boss/components b10-dhcp6 +> config set Boss/components/b10-dhcp6/kind dispensable +> config commit + - Depending on your installation, b10-dhcp6 - binary may reside in src/bin/dhcp6 in your source code - directory, in /usr/local/bin/b10-dhcp6 or other directory - you specified during compilation. + + To shutdown running b10-dhcp6, please use the + following command: + > Dhcp6 shutdown + or + > config remove Boss/components b10-dhcp6 +> config commit + - At start, server will detect available network interfaces + + During start-up the server will detect available network interfaces and will attempt to open UDP sockets on all interfaces that are up, running, are not loopback, are multicast-capable, and have IPv6 address assigned. @@ -2668,16 +2662,6 @@ const std::string HARDCODED_SERVER_ID = "192.0.2.1"; access. Make sure you run this daemon as root. - - - Integration with bind10 is - planned. Ultimately, b10-dhcp6 will not - be started directly, but rather via - bind10. Please be aware of this planned - change. - - -

@@ -2691,7 +2675,7 @@ const std::string HARDCODED_SERVER_ID = "192.0.2.1"; At this stage of development, the only way to alter server configuration is to tweak its source code. To do so, please - edit src/bin/dhcp6/dhcp6_srv.cc file and modify following + edit src/bin/dhcp6/dhcp6_srv.cc file, modify the following parameters and recompile: const std::string HARDCODED_LEASE = "2001:db8:1::1234:abcd"; diff --git a/doc/guide/bind10-messages.html b/doc/guide/bind10-messages.html index 456aec4f0586d24b4e3c8246295afa9c3e4fb9a8..1766c0f3c2d49b16fc3f146bdbf54af6752f4d52 100644 --- a/doc/guide/bind10-messages.html +++ b/doc/guide/bind10-messages.html @@ -1,4 +1,4 @@ -BIND 10 Messages Manual

BIND 10 Messages Manual

This is the messages manual for BIND 10 version +BIND 10 Messages Manual

BIND 10 Messages Manual

This is the messages manual for BIND 10 version 20120405.

Abstract

BIND 10 is a Domain Name System (DNS) suite managed by Internet Systems Consortium (ISC). It includes DNS libraries and modular components for controlling authoritative and diff --git a/src/bin/dhcp6/Makefile.am b/src/bin/dhcp6/Makefile.am index 16b17eddf802f5c8c50ba9f46ad885a0b3f97a2f..7947903f05b38bc050b9ddaf67ce180549f24f57 100644 --- a/src/bin/dhcp6/Makefile.am +++ b/src/bin/dhcp6/Makefile.am @@ -33,6 +33,7 @@ BUILT_SOURCES = spec_config.h pkglibexec_PROGRAMS = b10-dhcp6 b10_dhcp6_SOURCES = main.cc dhcp6_srv.cc dhcp6_srv.h +b10_dhcp6_SOURCES += ctrl_dhcp6_srv.cc ctrl_dhcp6_srv.h if USE_CLANGPP # Disable unused parameter warning caused by some of the @@ -44,6 +45,8 @@ b10_dhcp6_LDADD = $(top_builddir)/src/lib/exceptions/libexceptions.la b10_dhcp6_LDADD += $(top_builddir)/src/lib/asiolink/libasiolink.la b10_dhcp6_LDADD += $(top_builddir)/src/lib/log/liblog.la b10_dhcp6_LDADD += $(top_builddir)/src/lib/dhcp/libdhcp++.la +b10_dhcp6_LDADD += $(top_builddir)/src/lib/config/libcfgclient.la +b10_dhcp6_LDADD += $(top_builddir)/src/lib/cc/libcc.la b10_dhcp6dir = $(pkgdatadir) b10_dhcp6_DATA = dhcp6.spec diff --git a/src/bin/dhcp6/ctrl_dhcp6_srv.cc b/src/bin/dhcp6/ctrl_dhcp6_srv.cc new file mode 100644 index 0000000000000000000000000000000000000000..461d5f1d64ebc9b51fcaa9e6c16da8a6d043b77c --- /dev/null +++ b/src/bin/dhcp6/ctrl_dhcp6_srv.cc @@ -0,0 +1,159 @@ +// Copyright (C) 2012 Internet Systems Consortium, Inc. ("ISC") +// +// Permission to use, copy, modify, and/or distribute this software for any +// purpose with or without fee is hereby granted, provided that the above +// copyright notice and this permission notice appear in all copies. +// +// THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH +// REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY +// AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, +// INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM +// LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE +// OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR +// PERFORMANCE OF THIS SOFTWARE. + +#include +#include +#include + +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +using namespace std; +using namespace isc::util; +using namespace isc::dhcp; +using namespace isc::util; +using namespace isc::data; +using namespace isc::cc; +using namespace isc::config; +using namespace isc::asiolink; + +namespace isc { +namespace dhcp { + +ControlledDhcpv6Srv* ControlledDhcpv6Srv::server_ = NULL; + +ConstElementPtr +ControlledDhcpv6Srv::dhcp6ConfigHandler(ConstElementPtr new_config) { + cout << "b10-dhcp6: Received new config:" << new_config->str() << endl; + ConstElementPtr answer = isc::config::createAnswer(0, + "Thank you for sending config."); + return (answer); +} + +ConstElementPtr +ControlledDhcpv6Srv::dhcp6CommandHandler(const string& command, ConstElementPtr args) { + cout << "b10-dhcp6: Received new command: [" << command << "], args=" + << args->str() << endl; + if (command == "shutdown") { + if (ControlledDhcpv6Srv::server_) { + ControlledDhcpv6Srv::server_->shutdown(); + } else { + cout << "Server not initialized yet or already shut down." << endl; + ConstElementPtr answer = isc::config::createAnswer(1, + "Shutdown failure."); + return (answer); + } + ConstElementPtr answer = isc::config::createAnswer(0, + "Shutting down."); + return (answer); + } + + ConstElementPtr answer = isc::config::createAnswer(1, + "Unrecognized command."); + + return (answer); +} + +void ControlledDhcpv6Srv::sessionReader(void) { + // Process one asio event. If there are more events, iface_mgr will call + // this callback more than once. + if (server_) { + server_->io_service_.run_one(); + } +} + +void ControlledDhcpv6Srv::establishSession() { + + string specfile; + if (getenv("B10_FROM_BUILD")) { + specfile = string(getenv("B10_FROM_BUILD")) + + "/src/bin/dhcp6/dhcp6.spec"; + } else { + specfile = string(DHCP6_SPECFILE_LOCATION); + } + + /// @todo: Check if session is not established already. Throw, if it is. + + cout << "b10-dhcp6: my specfile is " << specfile << endl; + + cc_session_ = new Session(io_service_.get_io_service()); + + config_session_ = new ModuleCCSession(specfile, *cc_session_, + dhcp6ConfigHandler, + dhcp6CommandHandler, false); + config_session_->start(); + + /// Integrate the asynchronous I/O model of BIND 10 configuration + /// control with the "select" model of the DHCP server. This is + /// fully explained in \ref dhcpv6Session. + int ctrl_socket = cc_session_->getSocketDesc(); + cout << "b10-dhcp6: Control session started, socket=" + << ctrl_socket << endl; + IfaceMgr::instance().set_session_socket(ctrl_socket, sessionReader); +} + +void ControlledDhcpv6Srv::disconnectSession() { + if (config_session_) { + delete config_session_; + config_session_ = NULL; + } + if (cc_session_) { + cc_session_->disconnect(); + delete cc_session_; + cc_session_ = NULL; + } + + // deregister session socket + IfaceMgr::instance().set_session_socket(IfaceMgr::INVALID_SOCKET, NULL); +} + +ControlledDhcpv6Srv::ControlledDhcpv6Srv(uint16_t port /*= DHCP6_SERVER_PORT*/) + :Dhcpv6Srv(port), cc_session_(NULL), config_session_(NULL) { + server_ = this; // remember this instance for use in callback +} + +void ControlledDhcpv6Srv::shutdown() { + io_service_.stop(); // Stop ASIO transmissions + Dhcpv6Srv::shutdown(); // Initiate DHCPv6 shutdown procedure. +} + +ControlledDhcpv6Srv::~ControlledDhcpv6Srv() { + disconnectSession(); + + server_ = NULL; // forget this instance. There should be no callback anymore + // at this stage anyway. +} + +isc::data::ConstElementPtr +ControlledDhcpv6Srv::execDhcpv6ServerCommand(const std::string& command_id, + isc::data::ConstElementPtr args) { + try { + return (dhcp6CommandHandler(command_id, args)); + } catch (const Exception& ex) { + ConstElementPtr answer = isc::config::createAnswer(1, ex.what()); + return (answer); + } +} + + +}; +}; diff --git a/src/bin/dhcp6/ctrl_dhcp6_srv.h b/src/bin/dhcp6/ctrl_dhcp6_srv.h new file mode 100644 index 0000000000000000000000000000000000000000..91fc80acb2a17a5824d0354f119cf79024f209cd --- /dev/null +++ b/src/bin/dhcp6/ctrl_dhcp6_srv.h @@ -0,0 +1,123 @@ +// Copyright (C) 2012 Internet Systems Consortium, Inc. ("ISC") +// +// Permission to use, copy, modify, and/or distribute this software for any +// purpose with or without fee is hereby granted, provided that the above +// copyright notice and this permission notice appear in all copies. +// +// THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH +// REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY +// AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, +// INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM +// LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE +// OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR +// PERFORMANCE OF THIS SOFTWARE. + +#ifndef CTRL_DHCPV6_SRV_H +#define CTRL_DHCPV6_SRV_H + +#include +#include +#include +#include +#include + +namespace isc { +namespace dhcp { + +/// @brief Controlled version of the DHCPv6 server +/// +/// This is a class that is responsible for establishing connection +/// with msqg (receving commands and configuration). This is an extended +/// version of Dhcpv6Srv class that is purely a DHCPv6 server, without +/// external control. ControlledDhcpv6Srv should be used in typical BIND10 +/// (i.e. featuring msgq) environment, while Dhcpv6Srv should be used in +/// embedded environments. +/// +/// For detailed explanation or relations between main(), ControlledDhcpv6Srv, +/// Dhcpv6Srv and other classes, see \ref dhcpv6Session. +class ControlledDhcpv6Srv : public isc::dhcp::Dhcpv6Srv { +public: + + /// @brief Constructor + /// + /// @param port UDP port to be opened for DHCP traffic + ControlledDhcpv6Srv(uint16_t port = DHCP6_SERVER_PORT); + + /// @brief Destructor. + ~ControlledDhcpv6Srv(); + + /// @brief Establishes msgq session. + /// + /// Creates session that will be used to receive commands and updated + /// configuration from boss (or indirectly from user via bindctl). + void establishSession(); + + /// @brief Terminates existing msgq session. + /// + /// This method terminates existing session with msgq. After calling + /// it, no further messages over msgq (commands or configuration updates) + /// may be received. + /// + /// It is ok to call this method when session is disconnected already. + void disconnectSession(); + + /// @brief Initiates shutdown procedure for the whole DHCPv6 server. + void shutdown(); + + /// @brief Session callback, processes received commands. + /// + /// @param command_id text represenation of the command (e.g. "shutdown") + /// @param args optional parameters + /// + /// @return status of the command + static isc::data::ConstElementPtr + execDhcpv6ServerCommand(const std::string& command, + isc::data::ConstElementPtr args); + +protected: + /// @brief Static pointer to the sole instance of the DHCP server. + /// + /// This is required for config and command handlers to gain access to + /// the server + static ControlledDhcpv6Srv* server_; + + /// @brief A callback for handling incoming configuration updates. + /// + /// As pointer to this method is used a callback in ASIO used in + /// ModuleCCSession, it has to be static. + /// + /// @param new_config textual representation of the new configuration + /// + /// @return status of the config update + static isc::data::ConstElementPtr + dhcp6ConfigHandler(isc::data::ConstElementPtr new_config); + + /// @brief A callback for handling incoming commands. + /// + /// @param command textual representation of the command + /// @param args parameters of the command + /// + /// @return status of the processed command + static isc::data::ConstElementPtr + dhcp6CommandHandler(const std::string& command, isc::data::ConstElementPtr args); + + /// @brief Callback that will be called from iface_mgr when command/config arrives. + /// + /// This static callback method is called from IfaceMgr::receive6() method, + /// when there is a new command or configuration sent over msgq. + static void sessionReader(void); + + /// @brief IOService object, used for all ASIO operations. + isc::asiolink::IOService io_service_; + + /// @brief Helper session object that represents raw connection to msgq. + isc::cc::Session* cc_session_; + + /// @brief Session that receives configuation and commands + isc::config::ModuleCCSession* config_session_; +}; + +}; // namespace isc::dhcp +}; // namespace isc + +#endif diff --git a/src/bin/dhcp6/dhcp6_srv.cc b/src/bin/dhcp6/dhcp6_srv.cc index 293e6004ae4becae931c16f723b206654663554e..55a925c1ede7daf7ada84a2a9d4ab53410e05e40 100644 --- a/src/bin/dhcp6/dhcp6_srv.cc +++ b/src/bin/dhcp6/dhcp6_srv.cc @@ -48,12 +48,12 @@ Dhcpv6Srv::Dhcpv6Srv(uint16_t port) { IfaceMgr::instance(); } catch (const std::exception &e) { cout << "Failed to instantiate InterfaceManager:" << e.what() << ". Aborting." << endl; - shutdown = true; + shutdown_ = true; } if (IfaceMgr::instance().countIfaces() == 0) { cout << "Failed to detect any network interfaces. Aborting." << endl; - shutdown = true; + shutdown_ = true; } // Now try to open IPv6 sockets on detected interfaces. @@ -63,7 +63,7 @@ Dhcpv6Srv::Dhcpv6Srv(uint16_t port) { setServerID(); - shutdown = false; + shutdown_ = false; } Dhcpv6Srv::~Dhcpv6Srv() { @@ -72,8 +72,13 @@ Dhcpv6Srv::~Dhcpv6Srv() { IfaceMgr::instance().closeSockets(); } +void Dhcpv6Srv::shutdown() { + cout << "b10-dhcp6: DHCPv6 server shutdown." << endl; + shutdown_ = true; +} + bool Dhcpv6Srv::run() { - while (!shutdown) { + while (!shutdown_) { // client's message and server's response Pkt6Ptr query = IfaceMgr::instance().receive6(); diff --git a/src/bin/dhcp6/dhcp6_srv.h b/src/bin/dhcp6/dhcp6_srv.h index b6ae6376f27bf75061e10f4cbbf6d56f88a6131d..9d1bf19497267dbdd76eec9911e685714e87accb 100644 --- a/src/bin/dhcp6/dhcp6_srv.h +++ b/src/bin/dhcp6/dhcp6_srv.h @@ -67,6 +67,8 @@ public: /// critical error. bool run(); + /// @brief Instructs the server to shut down. + void shutdown(); protected: /// @brief Processes incoming SOLICIT and returns response. /// @@ -184,7 +186,7 @@ protected: /// indicates if shutdown is in progress. Setting it to true will /// initiate server shutdown procedure. - volatile bool shutdown; + volatile bool shutdown_; }; }; // namespace isc::dhcp diff --git a/src/bin/dhcp6/main.cc b/src/bin/dhcp6/main.cc index 62c0d208076e193712e10dca11f24ec7ab13cde9..1cd52913bff35caa4e46e616e236e39759726357 100644 --- a/src/bin/dhcp6/main.cc +++ b/src/bin/dhcp6/main.cc @@ -13,47 +13,34 @@ // PERFORMANCE OF THIS SOFTWARE. #include - -#include -#include -#include -#include -#include -#include -#include - -#include #include - -#include -#if 0 -// TODO cc is not used yet. It should be eventually -#include -#include -#endif - -#include #include - -#include -#include "dhcp6/dhcp6_srv.h" +#include +#include using namespace std; -using namespace isc::util; - -using namespace isc; using namespace isc::dhcp; +/// This file contains entry point (main() function) for standard DHCPv6 server +/// component for BIND10 framework. It parses command-line arguments and +/// instantiates ControlledDhcpv6Srv class that is responsible for establishing +/// connection with msgq (receiving commands and configuration) and also +/// creating Dhcpv6 server object as well. +/// +/// For detailed explanation or relations between main(), ControlledDhcpv6Srv, +/// Dhcpv6Srv and other classes, see \ref dhcpv6Session. + namespace { -bool verbose_mode = false; +const char* const DHCP6_NAME = "b10-dhcp6"; void usage() { - cerr << "Usage: b10-dhcp6 [-v]" + cerr << "Usage: b10-dhcp6 [-v]" << endl; cerr << "\t-v: verbose output" << endl; - cerr << "\t-p number: specify non-standard port number 1-65535 (useful for testing only)" << endl; + cerr << "\t-p number: specify non-standard port number 1-65535 " + << "(useful for testing only)" << endl; exit(EXIT_FAILURE); } } // end of anonymous namespace @@ -63,6 +50,7 @@ main(int argc, char* argv[]) { int ch; int port_number = DHCP6_SERVER_PORT; // The default. Any other values are // useful for testing only. + bool verbose_mode = false; // Should server be verbose? while ((ch = getopt(argc, argv, "vp:")) != -1) { switch (ch) { @@ -84,7 +72,13 @@ main(int argc, char* argv[]) { } } - cout << "My pid=" << getpid() << endl; + // Initialize logging. If verbose, we'll use maximum verbosity. + isc::log::initLogger(DHCP6_NAME, + (verbose_mode ? isc::log::DEBUG : isc::log::INFO), + isc::log::MAX_DEBUG_LEVEL, NULL); + + cout << "b10-dhcp6: My pid=" << getpid() << ", binding to port " + << port_number << ", verbose " << (verbose_mode?"yes":"no") << endl; if (argc - optind > 0) { usage(); @@ -92,24 +86,18 @@ main(int argc, char* argv[]) { int ret = EXIT_SUCCESS; - // TODO remainder of auth to dhcp6 code copy. We need to enable this in - // dhcp6 eventually -#if 0 - Session* cc_session = NULL; - Session* statistics_session = NULL; - ModuleCCSession* config_session = NULL; -#endif try { - string specfile; - if (getenv("B10_FROM_BUILD")) { - specfile = string(getenv("B10_FROM_BUILD")) + - "/src/bin/auth/dhcp6.spec"; - } else { - specfile = string(DHCP6_SPECFILE_LOCATION); - } + + cout << "b10-dhcp6: Initiating DHCPv6 server operation." << endl; + + ControlledDhcpv6Srv* server = new ControlledDhcpv6Srv(port_number); + server->run(); + delete server; + server = NULL; cout << "[b10-dhcp6] Initiating DHCPv6 operation." << endl; + /// @todo: pass verbose to the actual server once logging is implemented Dhcpv6Srv* srv = new Dhcpv6Srv(port_number); srv->run(); diff --git a/src/bin/dhcp6/tests/Makefile.am b/src/bin/dhcp6/tests/Makefile.am index ac20d56830a2e4b98f3dade76fd040dde95f50f3..298be41a13234701962ea874181e7cf7c2afe632 100644 --- a/src/bin/dhcp6/tests/Makefile.am +++ b/src/bin/dhcp6/tests/Makefile.am @@ -42,9 +42,10 @@ if HAVE_GTEST TESTS += dhcp6_unittests -dhcp6_unittests_SOURCES = ../dhcp6_srv.h ../dhcp6_srv.cc +dhcp6_unittests_SOURCES = ../dhcp6_srv.h ../dhcp6_srv.cc ../ctrl_dhcp6_srv.cc dhcp6_unittests_SOURCES += dhcp6_unittests.cc dhcp6_unittests_SOURCES += dhcp6_srv_unittest.cc +dhcp6_unittests_SOURCES += ctrl_dhcp6_srv_unittest.cc if USE_CLANGPP # Disable unused parameter warning caused by some of the @@ -59,6 +60,8 @@ dhcp6_unittests_LDADD += $(top_builddir)/src/lib/asiolink/libasiolink.la dhcp6_unittests_LDADD += $(top_builddir)/src/lib/dhcp/libdhcp++.la dhcp6_unittests_LDADD += $(top_builddir)/src/lib/log/liblog.la dhcp6_unittests_LDADD += $(top_builddir)/src/lib/exceptions/libexceptions.la +dhcp6_unittests_LDADD += $(top_builddir)/src/lib/config/libcfgclient.la +dhcp6_unittests_LDADD += $(top_builddir)/src/lib/cc/libcc.la endif diff --git a/src/bin/dhcp6/tests/ctrl_dhcp6_srv_unittest.cc b/src/bin/dhcp6/tests/ctrl_dhcp6_srv_unittest.cc new file mode 100644 index 0000000000000000000000000000000000000000..1e88f83bba78d93e15afd51a6e1f1d8b6b87b623 --- /dev/null +++ b/src/bin/dhcp6/tests/ctrl_dhcp6_srv_unittest.cc @@ -0,0 +1,85 @@ +// Copyright (C) 2012 Internet Systems Consortium, Inc. ("ISC") +// +// Permission to use, copy, modify, and/or distribute this software for any +// purpose with or without fee is hereby granted, provided that the above +// copyright notice and this permission notice appear in all copies. +// +// THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH +// REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY +// AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, +// INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM +// LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE +// OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR +// PERFORMANCE OF THIS SOFTWARE. + +#include +#include +#include +#include + +#include +#include + +#include +#include +#include + +using namespace std; +using namespace isc; +using namespace isc::dhcp; +using namespace isc::asiolink; +using namespace isc::data; +using namespace isc::config; + +namespace { + +class NakedControlledDhcpv6Srv: public ControlledDhcpv6Srv { + // "naked" DHCPv6 server, exposes internal fields +public: + NakedControlledDhcpv6Srv():ControlledDhcpv6Srv(DHCP6_SERVER_PORT + 10000) { } +}; + +class CtrlDhcpv6SrvTest : public ::testing::Test { +public: + CtrlDhcpv6SrvTest() { + } + + ~CtrlDhcpv6SrvTest() { + }; +}; + +TEST_F(CtrlDhcpv6SrvTest, commands) { + + ControlledDhcpv6Srv* srv = NULL; + ASSERT_NO_THROW({ + srv = new ControlledDhcpv6Srv(DHCP6_SERVER_PORT + 10000); + }); + + // use empty parameters list + ElementPtr params(new isc::data::MapElement()); + int rcode = -1; + + // case 1: send bogus command + ConstElementPtr result = ControlledDhcpv6Srv::execDhcpv6ServerCommand("blah", params); + ConstElementPtr comment = parseAnswer(rcode, result); + EXPECT_EQ(1, rcode); // expect failure (no such command as blah) + + // case 2: send shutdown command without any parameters + result = ControlledDhcpv6Srv::execDhcpv6ServerCommand("shutdown", params); + comment = parseAnswer(rcode, result); + EXPECT_EQ(0, rcode); // expect success + + const pid_t pid(getpid()); + ConstElementPtr x(new isc::data::IntElement(pid)); + params->set("pid", x); + + // case 3: send shutdown command with 1 parameter: pid + result = ControlledDhcpv6Srv::execDhcpv6ServerCommand("shutdown", params); + comment = parseAnswer(rcode, result); + EXPECT_EQ(0, rcode); // expect success + + + delete srv; +} + +} // end of anonymous namespace diff --git a/src/bin/dhcp6/tests/dhcp6_test.py b/src/bin/dhcp6/tests/dhcp6_test.py index cf04f60be72ebe053419bdf9864d6bc67f1ce56e..230588fd7320384685c42cd565b6da75bad5065b 100644 --- a/src/bin/dhcp6/tests/dhcp6_test.py +++ b/src/bin/dhcp6/tests/dhcp6_test.py @@ -1,4 +1,4 @@ -# Copyright (C) 2011,2012 Internet Systems Consortium. +# copyright (C) 2011,2012 Internet Systems Consortium. # # Permission to use, copy, modify, and distribute this software for any # purpose with or without fee is hereby granted, provided that the above @@ -131,7 +131,7 @@ class TestDhcpv6Daemon(unittest.TestCase): print(" not that is can bind sockets correctly. Please ignore binding errors.") (returncode, output, error) = self.runCommand(["../b10-dhcp6", "-v"]) - self.assertEqual( str(output).count("[b10-dhcp6] Initiating DHCPv6 operation."), 1) + self.assertEqual( str(output).count("b10-dhcp6: Initiating DHCPv6 server operation."), 1) def test_portnumber_0(self): print("Check that specifying port number 0 is not allowed.")