From: Tomek Mrugalski Date: Wed, 28 Dec 2011 12:39:21 +0000 (+0100) Subject: [1367] BIND10 Guide update (DHCP) X-Git-Tag: trac2351_base~310^2~10^2~2 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=bc24ccba8ce6cca78548a2ff6a0db7cf26831f3a;p=thirdparty%2Fkea.git [1367] BIND10 Guide update (DHCP) - Supported standards section added - Numerous smaller updates --- diff --git a/doc/guide/bind10-guide.html b/doc/guide/bind10-guide.html index 1f5154a498..3fc27954ad 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 20111129.

Copyright © 2010-2011 Internet Systems Consortium, Inc.

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

1. Introduction
Supported Platforms
Required Software
Starting and Stopping the Server
Managing BIND 10
2. Installation
Building Requirements
Quick start
Installation from source
Download Tar File
Retrieve from Git
Configure before the build
Build
Install
Install Hierarchy
3. Starting BIND10 with bind10
Starting BIND 10
Configuration of started processes
4. Command channel
5. Configuration manager
6. Remote control daemon
Configuration specification for b10-cmdctl
7. Control and configure user interface
8. Authoritative Server
Server Configurations
Data Source Backends
Loading Master Zones Files
9. Incoming Zone Transfers
Configuration for Incoming Zone Transfers
Enabling IXFR
Secondary Manager
Trigger an Incoming Zone Transfer Manually
10. Outbound Zone Transfers
11. Recursive Name Server
Access Control
Forwarding
12. DHCPv4 Server
DHCPv4 Server Usage
DHCPv4 Server Configuration
DHCPv4 Server Limitations
13. DHCPv6 Server
DHCPv6 Server Usage
DHCPv6 Server Configuration
DHCPv6 Server Limitations
14. libdhcp++ library
Interface detection
DHCPv4/DHCPv6 packet handling
15. Statistics
16. Logging
Logging configuration
Loggers
Output Options
Example session
Logging Message Format

List of Tables

3.1.

Chapter 1. Introduction

Table of Contents

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

+

Table of Contents

1. Introduction
Supported Platforms
Required Software
Starting and Stopping the Server
Managing BIND 10
2. Installation
Building Requirements
Quick start
Installation from source
Download Tar File
Retrieve from Git
Configure before the build
Build
Install
Install Hierarchy
3. Starting BIND10 with bind10
Starting BIND 10
Configuration of started processes
4. Command channel
5. Configuration manager
6. Remote control daemon
Configuration specification for b10-cmdctl
7. Control and configure user interface
8. Authoritative Server
Server Configurations
Data Source Backends
Loading Master Zones Files
9. Incoming Zone Transfers
Configuration for Incoming Zone Transfers
Enabling IXFR
Secondary Manager
Trigger an Incoming Zone Transfer Manually
10. Outbound Zone Transfers
11. Recursive Name Server
Access Control
Forwarding
12. DHCPv4 Server
DHCPv4 Server Usage
DHCPv4 Server Configuration
Supported standards
DHCPv4 Server Limitations
13. DHCPv6 Server
DHCPv6 Server Usage
DHCPv6 Server Configuration
Supported DHCPv6 Standards
DHCPv6 Server Limitations
14. libdhcp++ library
Interface detection
DHCPv4/DHCPv6 packet handling
15. Statistics
16. Logging
Logging configuration
Loggers
Output Options
Example session
Logging Message Format

List of Tables

3.1.

Chapter 1. Introduction

Table of Contents

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

BIND is the popular implementation of a DNS server, developer interfaces, and DNS tools. BIND 10 is a rewrite of BIND 9. BIND 10 is written in C++ and Python @@ -20,7 +20,7 @@ BIND 10 provides a EDNS0- and DNSSEC-capable authoritative DNS server and a caching recursive name server which also provides forwarding. -

Supported Platforms

+

Supported Platforms

BIND 10 builds have been tested on Debian GNU/Linux 5, Ubuntu 9.10, NetBSD 5, Solaris 10, FreeBSD 7 and 8, and CentOS Linux 5.3. @@ -30,7 +30,7 @@ It is planned for BIND 10 to build, install and run on Windows and standard Unix-type platforms. -

Required Software

+

Required Software

BIND 10 requires Python 3.1. Later versions may work, but Python 3.1 is the minimum version which will work.

@@ -140,7 +140,7 @@ and, of course, DNS. These include detailed developer documentation and code examples. -

Chapter 2. Installation

Table of Contents

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

Building Requirements

+

Chapter 2. Installation

Table of Contents

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

Building Requirements

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

Note

@@ -204,14 +204,14 @@ the Git code revision control system or as a downloadable tar file. It may also be available in pre-compiled ready-to-use packages from operating system vendors. -

Download Tar File

+

Download Tar File

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

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

Retrieve from Git

+

Retrieve from Git

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

Configure before the build

+

Configure before the build

BIND 10 uses the GNU Build System to discover build environment details. To generate the makefiles using the defaults, simply run: @@ -276,16 +276,16 @@

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

Build

+

Build

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

$ make

-

Install

+

Install

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

$ make install

-

Note

The install step may require superuser privileges.

Install Hierarchy

+

Note

The install step may require superuser privileges.

Install Hierarchy

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

  • bin/ — @@ -385,7 +385,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)
    setuidsetuidVirtual component, see below


    +

    Table 3.1. 

    ComponentSpecialDescription
    b10-authauthAuthoritative server
    b10-resolverresolverThe resolver
    b10-cmdctlcmdctlThe command control (remote control interface)
    setuidsetuidVirtual component, see below


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

    -

Chapter 8. Authoritative Server

Table of Contents

Server Configurations
Data Source Backends
Loading Master Zones Files

+

Chapter 8. Authoritative Server

Table of Contents

Server Configurations
Data Source Backends
Loading Master Zones Files

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

Server Configurations

+

Server Configurations

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

shutdown
Stop the authoritative DNS server.

-

Data Source Backends

Note

+

Data Source Backends

Note

For the development prototype release, b10-auth supports a SQLite3 data source backend and in-memory data source backend. @@ -649,7 +649,7 @@ This may be a temporary setting until then. The default is /usr/local/var/.) This data file location may be changed by defining the “database_file” configuration. -

Loading Master Zones Files

+

Loading Master Zones Files

RFC 1035 style DNS master zone files may imported into a BIND 10 data source by using the b10-loadzone utility. @@ -678,7 +678,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

Table of Contents

Configuration for Incoming Zone Transfers
Enabling IXFR
Secondary Manager
Trigger an Incoming Zone Transfer Manually

+

Chapter 9. Incoming Zone Transfers

Table of Contents

Configuration for Incoming Zone Transfers
Enabling IXFR
Secondary Manager
Trigger an Incoming Zone Transfer Manually

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 @@ -696,7 +696,7 @@ This may be a temporary setting until then. In the current development release of BIND 10, incoming zone transfers are only available for SQLite3-based data sources, that is, they don't work for an in-memory data source. -

Configuration for Incoming Zone Transfers

+

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 @@ -712,7 +712,7 @@ This may be a temporary setting until then. > config commit

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

Enabling IXFR

+

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

Trigger an Incoming Zone Transfer Manually

+

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: @@ -821,7 +821,7 @@ Xfrout/transfer_acl[0] {"action": "ACCEPT"} any (default)

use the system wide TSIG configuration. The way to specify zone specific configuration (ACLs, etc) is likely to be changed, too. -

Chapter 11. Recursive Name Server

Table of Contents

Access Control
Forwarding

+

Chapter 11. Recursive Name Server

Table of Contents

Access Control
Forwarding

The b10-resolver process is started by bind10. @@ -860,7 +860,7 @@ Xfrout/transfer_acl[0] {"action": "ACCEPT"} any (default)

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

Access Control

+ Resolver/listen_on” if needed.)

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 @@ -893,7 +893,7 @@ Xfrout/transfer_acl[0] {"action": "ACCEPT"} any (default)

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

Note

This prototype access control configuration - syntax may be changed.

Forwarding

+ syntax may be changed.

Forwarding

To enable forwarding, the upstream address and port must be configured to forward queries to, such as: @@ -913,7 +913,7 @@ Xfrout/transfer_acl[0] {"action": "ACCEPT"} any (default)

> config set Resolver/forward_addresses [] > config commit

-

Chapter 12. DHCPv4 Server

Table of Contents

DHCPv4 Server Usage
DHCPv4 Server Configuration
DHCPv4 Server Limitations

Dynamic Host Configuration Protocol for IPv4 (DHCP or +

Chapter 12. DHCPv4 Server

Table of Contents

DHCPv4 Server Usage
DHCPv4 Server Configuration
Supported standards
DHCPv4 Server Limitations

Dynamic Host Configuration Protocol for IPv4 (DHCP or DHCPv4) and Dynamic Host Configuration Protocol for IPv6 (DHCPv6) are protocols that allow one node (server) to provision configuration parameters to many hosts and devices (clients). To @@ -923,7 +923,11 @@ Xfrout/transfer_acl[0] {"action": "ACCEPT"} any (default)

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 description of - DHCPv6 server, see Chapter 13, DHCPv6 Server.

Note

+ DHCPv6 server, see Chapter 13, DHCPv6 Server.

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.

DHCPv4 and DHCPv6 components in BIND10 architecture are + internally code named “Kea”.

Note

As of December 2011, both DHCPv4 and DHCPv6 components are skeleton servers. That means that while they are capable of performing DHCP configuration, they are not fully functional @@ -931,14 +935,15 @@ Xfrout/transfer_acl[0] {"action": "ACCEPT"} any (default)

databases. This means that they will assign the same, fixed, hardcoded addresses to any client that will ask. See the section called “DHCPv4 Server Limitations” and the section called “DHCPv6 Server Limitations” for detailed description. -

DHCPv4 Server Usage

BIND10 provides DHCPv4 server component since - December 2011. It is currently described as skeleton server and - can be described as an early prototype that is not yet fully - functional. It is mature enough to conduct first tests in lab - environment, but it has significant limitations. See the section called “DHCPv4 Server Limitations” for details. +

DHCPv4 Server Usage

BIND10 provides 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 the section called “DHCPv4 Server Limitations” for + details.

DHCPv4 server is implemented as b10-dhcp4 - daemon. As it is configurable yet, it is fully autonomous, + daemon. As it is not configurable yet, it is fully autonomous, i.e. it does not interact with b10-cfgmgr. To start DHCPv4 server, simply input: @@ -952,7 +957,7 @@ Xfrout/transfer_acl[0] {"action": "ACCEPT"} any (default)

directory, in /usr/local/bin/b10-dhcp4 or other directory you specified during compilation. - Afre start, server will detect available network interfaces + After start, 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. @@ -962,16 +967,22 @@ Xfrout/transfer_acl[0] {"action": "ACCEPT"} any (default)

will respond to them with OFFER and ACK, respectively. As DHCPv4 server opens privileged ports, it requires root - access. Make sure you run this daemon as root. -

DHCPv4 Server Configuration

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

DHCPv4 Server Configuration

DHCPv4 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) will be assigned every time.

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/dhcp4/dhcp4_srv.cc file and modify following parameters: + configuration is to tweak its source code. To do so, please + edit src/bin/dhcp4/dhcp4_srv.cc file and modify following + parameters and recompile: 

 const std::string HARDCODED_LEASE = "192.0.2.222"; // assigned lease
 const std::string HARDCODED_NETMASK = "255.255.255.0";
@@ -982,16 +993,20 @@ const std::string HARDCODED_DOMAIN_NAME = "isc.example.com";
 const std::string HARDCODED_SERVER_ID = "192.0.2.1";

Lease database and configuration support is planned for 2012. -

DHCPv4 Server Limitations

- This are the current limitations of DHCPv4 server - software. Most of them are reflection of the early stage of - development. -

  • During initial IPv4 node configuration, where - server has to send packet to a node that does not have - IPv4 address assigned yet, server requires certain tricks - (or hacks) to transmit such packets. This is not - implemented yet, therefore DHCPv4 server supports relayed - traffic only.
  • b10-dhcp4 provides a single, +

Supported standards

The following standards and draft standards are currently + supported:

  • RFC2131: Supported messages are DISCOVER, OFFER, + REQUEST, and ACK.
  • 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).

DHCPv4 Server Limitations

These are the current limitations of 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.

  • During initial IPv4 node configuration, server is + expected to send packets to a node that does not have IPv4 + address assigned yet. 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).
  • 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 @@ -1005,21 +1020,29 @@ const std::string HARDCODED_SERVER_ID = "192.0.2.1";

    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 down other interfaces. This limitation will be fixed - shortly.

  • PRL (Parameter Request List) is currently ignored - and server assigns DNS SERVER and DOMAIN NAME - options.
  • b10-dhcp4 does not support + to turn down other interfaces. This limitation will be + fixed shortly.
  • PRL (Parameter Request List, a list of options + requested by a client) is currently ignored and server + assigns DNS SERVER and DOMAIN NAME options.
  • 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.
  • Interface detection is currently working on Linux - only. See the section called “Interface detection” for details.
  • Address renewal (RENEW), rebinding (REBIND), - confirmation (CONFIRM), duplication report (DECLINE) and - release (RELEASE) are not supported yet.
  • DNS Update is not supported yet.

Chapter 13. DHCPv6 Server

Table of Contents

DHCPv6 Server Usage
DHCPv6 Server Configuration
DHCPv6 Server Limitations

Dynamic Host Configuration Protocol for IPv6 (DHCPv6) is + only. See the section called “Interface detection” for details.

  • 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.
  • Address renewal (RENEW), rebinding (REBIND), + confirmation (CONFIRM), duplication report (DECLINE) and + release (RELEASE) are not supported yet.
  • DNS Update is not supported yet.
  • -v (verbose) command line option is currently + permanently enabled.

    • Chapter 13. DHCPv6 Server

    Table of Contents

    DHCPv6 Server Usage
    DHCPv6 Server Configuration
    Supported DHCPv6 Standards
    DHCPv6 Server Limitations

    Dynamic Host Configuration Protocol for IPv6 (DHCPv6) is specified in RFC3315. BIND10 provides DHCPv6 server implementation that is described in this chapter. For DHCPv4 server implementation, see Chapter 12, DHCPv4 Server. -

    Note

    +

    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.

    DHCPv4 and DHCPv6 components in BIND10 architecture are + internally code named “Kea”.

    Note

    As of December 2011, both DHCPv4 and DHCPv6 components are skeleton servers. That means that while they are capable of performing DHCP configuration, they are not fully functional @@ -1029,13 +1052,14 @@ const std::string HARDCODED_SERVER_ID = "192.0.2.1";

    detailed description.

    DHCPv6 Server Usage

    BIND10 provides DHCPv6 server component since September - 2011. It is currently described as skeleton server and can be - described as an early prototype that is not yet fully - functional. It is mature enough to conduct first tests in lab - environment, but it has significant limitations. See the section called “DHCPv6 Server Limitations” for details. + 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 the section called “DHCPv6 Server Limitations” for + details.

    DHCPv6 server is implemented as b10-dhcp6 - daemon. As it is configurable yet, it is fully autonomous, + daemon. As it is not configurable yet, it is fully autonomous, i.e. it does not interact with b10-cfgmgr. To start DHCPv6 server, simply input: @@ -1049,10 +1073,10 @@ const std::string HARDCODED_SERVER_ID = "192.0.2.1";

    directory, in /usr/local/bin/b10-dhcp6 or other directory you specified during compilation. - Afre start, server will detect available network interfaces + After start, 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. + are up, running, are not loopback, are multicast-capable and + have IPv6 address assigned. Server will then listen to incoming traffic. Currently supported client messages are SOLICIT and REQUEST. Server @@ -1060,15 +1084,22 @@ const std::string HARDCODED_SERVER_ID = "192.0.2.1";

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

    DHCPv6 Server Configuration

    +

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

    DHCPv6 Server Configuration

    DHCPv4 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) will be assigned every time.

    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: + configuration is to tweak its source code. To do so, please + edit src/bin/dhcp6/dhcp6_srv.cc file and modify following + parameters and recompile: 

     const std::string HARDCODED_LEASE = "2001:db8:1::1234:abcd";
 const uint32_t HARDCODED_T1 = 1500; // in seconds
@@ -1078,7 +1109,13 @@ const uint32_t HARDCODED_VALID_LIFETIME = 7200; // in seconds
 const std::string HARDCODED_DNS_SERVER = "2001:db8:1::1";

    Lease database and configuration support is planned for 2012. -

    DHCPv6 Server Limitations

    +

    Supported DHCPv6 Standards

    The following standards and draft standards are currently + supported:

    • RFC3315: Supported messages are SOLICIT, + ADVERTISE, REQUEST, and REPLY. Supported options are + SERVER_ID, CLIENT_ID, IA_NA, and IAADDRESS.
    • RFC3646: Supported option is DNS_SERVERS.

    DHCPv6 Server Limitations

    These are the current limitations of 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.

    • Relayed traffic is not supported.
    • b10-dhcp6 provides a single, fixed, hardcoded lease to any client that asks. There is no lease manager implemented. If two clients request addresses, @@ -1092,31 +1129,36 @@ const std::string HARDCODED_DNS_SERVER = "2001:db8:1::1";

      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 down other interfaces. This limitation - will be fixed shortly.

    • Temporary addresses are not supported yet.
    • Prefix delegation is not supported yet.
    • Address renewal (RENEW), rebinding (REBIND), + this problem is to turn down other interfaces. This + limitation will be fixed shortly.
    • ORO (Option Request Option, a list of options + requested by a client) is currently ignored and server + assigns DNS SERVER option.
    • Temporary addresses are not supported yet.
    • Prefix delegation is not supported yet.
    • Address renewal (RENEW), rebinding (REBIND), confirmation (CONFIRM), duplication report (DECLINE) and release (RELEASE) are not supported yet.
    • DNS Update is not supported yet.
    • Interface detection is currently working on Linux - only. See the section called “Interface detection” for details.

    -

    Chapter 14. libdhcp++ library

    Table of Contents

    Interface detection
    DHCPv4/DHCPv6 packet handling

    libdhcp++ is a common library written in C++ that is - handles many DHCP-related tasks, like DHCPv4 and DHCPv6 packets - parsing, manipulation and assembly, option parsing, manipulation - and assembly, network interface detection and socket operations. + only. See the section called “Interface detection” for details.

  • -v (verbose) command line option is currently permanently + enabled.

    • +

    Chapter 14. libdhcp++ library

    Table of Contents

    Interface detection
    DHCPv4/DHCPv6 packet handling

    libdhcp++ is a common library written in C++ that handles + many DHCP-related tasks, like DHCPv4 and DHCPv6 packets parsing, + manipulation and assembly, option parsing, manipulation and + assembly, network interface detection and socket operations, like + socket creations, data transmission and reception and socket + closing.

    While this library is currently used by - b10-dhcp6 and b10-dhcp4 - only, it is designed to be portable, universal library useful - for any kind of DHCP-related software. + b10-dhcp4 and b10-dhcp6 + only, it is designed to be portable, universal library useful for + any kind of DHCP-related software.

    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 was 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. Example of interfaces.txt file looks as follows: + 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. Example of interfaces.txt file looks as follows: 

     # For DHCPv6, please specify link-local address (starts with fe80::)
 # If in doubt, check output of 'ifconfig -a' command.
@@ -1158,7 +1200,7 @@ eth0 fe80::21e:8cff:fe9b:7349
     }
 }

    -

    Chapter 16. Logging

    Table of Contents

    Logging configuration
    Loggers
    Output Options
    Example session
    Logging Message Format

    Logging configuration

    +

    Chapter 16. Logging

    Table of Contents

    Logging configuration
    Loggers
    Output Options
    Example session
    Logging Message Format

    Logging configuration

    The logging system in BIND 10 is configured through the Logging module. All BIND 10 modules will look at the @@ -1167,7 +1209,7 @@ eth0 fe80::21e:8cff:fe9b:7349 -

    Loggers

    +

    Loggers

    Within BIND 10, a message is logged through a component called a "logger". Different parts of BIND 10 log messages @@ -1188,7 +1230,7 @@ eth0 fe80::21e:8cff:fe9b:7349 (what to log), and the output_options (where to log). -

    name (string)

    +

    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, @@ -1261,7 +1303,7 @@ eth0 fe80::21e:8cff:fe9b:7349 “Auth.cache” logger will appear in the output with a logger name of “b10-auth.cache”). -

    severity (string)

    +

    severity (string)

    This specifies the category of messages logged. Each message is logged with an associated severity which @@ -1277,7 +1319,7 @@ eth0 fe80::21e:8cff:fe9b:7349 -

    output_options (list)

    +

    output_options (list)

    Each logger can have zero or more output_options. These specify where log @@ -1287,7 +1329,7 @@ eth0 fe80::21e:8cff:fe9b:7349 The other options for a logger are: -

    debuglevel (integer)

    +

    debuglevel (integer)

    When a logger's severity is set to DEBUG, this value specifies what debug messages should be printed. It ranges @@ -1296,7 +1338,7 @@ eth0 fe80::21e:8cff:fe9b:7349 If severity for the logger is not DEBUG, this value is ignored. -

    additive (true or false)

    +

    additive (true or false)

    If this is true, the output_options from the parent will be used. For example, if there are two @@ -1310,18 +1352,18 @@ eth0 fe80::21e:8cff:fe9b:7349 -

    Output Options

    +

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

    destination (string)

    +

    destination (string)

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

    • console
    • file
    • syslog

    output (string)

    +

    • console
    • file
    • syslog

    output (string)

    Depending on what is set as the output destination, this value is interpreted as follows: @@ -1343,12 +1385,12 @@ eth0 fe80::21e:8cff:fe9b:7349 The other options for output_options are: -

    flush (true of false)

    +

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

    maxsize (integer)

    +

    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. @@ -1357,11 +1399,11 @@ eth0 fe80::21e:8cff:fe9b:7349 etc.)

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

    maxver (integer)

    +

    maxver (integer)

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

    Example session

    +

    Example session

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

    Logging Message Format

    +

    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.xml b/doc/guide/bind10-guide.xml index 4fb781d56e..847cb413a8 100644 --- a/doc/guide/bind10-guide.xml +++ b/doc/guide/bind10-guide.xml @@ -1820,6 +1820,16 @@ then change those defaults with config set Resolver/forward_addresses[0]/address and DHCPv6. This chapter is about DHCP for IPv4. For description of DHCPv6 server, see . + 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. + + DHCPv4 and DHCPv6 components in BIND10 architecture are + internally code named Kea. + As of December 2011, both DHCPv4 and DHCPv6 components are @@ -1835,17 +1845,17 @@ then change those defaults with config set Resolver/forward_addresses[0]/address

    DHCPv4 Server Usage - BIND10 provides DHCPv4 server component since - December 2011. It is currently described as skeleton server and - can be described as an early prototype that is not yet fully - functional. It is mature enough to conduct first tests in lab - environment, but it has significant limitations. See for details. + BIND10 provides 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 for + details. DHCPv4 server is implemented as b10-dhcp4 - daemon. As it is configurable yet, it is fully autonomous, + daemon. As it is not configurable yet, it is fully autonomous, i.e. it does not interact with b10-cfgmgr. To start DHCPv4 server, simply input: @@ -1859,7 +1869,7 @@ then change those defaults with config set Resolver/forward_addresses[0]/address directory, in /usr/local/bin/b10-dhcp4 or other directory you specified during compilation. - Afre start, server will detect available network interfaces + After start, 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. @@ -1869,8 +1879,18 @@ then change those defaults with config set Resolver/forward_addresses[0]/address will respond to them with OFFER and ACK, respectively. As DHCPv4 server opens privileged ports, it requires root - access. Make sure you run this daemon as 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. + + +
    @@ -1883,8 +1903,9 @@ then change those defaults with config set Resolver/forward_addresses[0]/address 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/dhcp4/dhcp4_srv.cc file and modify following parameters: + configuration is to tweak its source code. To do so, please + edit src/bin/dhcp4/dhcp4_srv.cc file and modify following + parameters and recompile: const std::string HARDCODED_LEASE = "192.0.2.222"; // assigned lease const std::string HARDCODED_NETMASK = "255.255.255.0"; @@ -1898,21 +1919,38 @@ const std::string HARDCODED_SERVER_ID = "192.0.2.1";
    +
    + Supported standards + The following standards and draft standards are currently + supported: + + + RFC2131: Supported messages are DISCOVER, OFFER, + REQUEST, and ACK. + + + 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). + + +
    +
    - DHCPv4 Server Limitations - - This are the current limitations of DHCPv4 server - software. Most of them are reflection of the early stage of - development. - + DHCPv4 Server Limitations + These are the current limitations of 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. - During initial IPv4 node configuration, where - server has to send packet to a node that does not have - IPv4 address assigned yet, server requires certain tricks - (or hacks) to transmit such packets. This is not - implemented yet, therefore DHCPv4 server supports relayed - traffic only. + During initial IPv4 node configuration, server is + expected to send packets to a node that does not have IPv4 + address assigned yet. 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). b10-dhcp4 provides a single, @@ -1936,13 +1974,13 @@ const std::string HARDCODED_SERVER_ID = "192.0.2.1"; 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 down other interfaces. This limitation will be fixed - shortly. + to turn down other interfaces. This limitation will be + fixed shortly. - PRL (Parameter Request List) is currently ignored - and server assigns DNS SERVER and DOMAIN NAME - options. + PRL (Parameter Request List, a list of options + requested by a client) is currently ignored and server + assigns DNS SERVER and DOMAIN NAME options. b10-dhcp4 does not support @@ -1955,17 +1993,27 @@ const std::string HARDCODED_SERVER_ID = "192.0.2.1"; Interface detection is currently working on Linux only. See for details. - - Address renewal (RENEW), rebinding (REBIND), - confirmation (CONFIRM), duplication report (DECLINE) and - release (RELEASE) are not supported yet. - - - DNS Update is not supported yet. - + + 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. + + + Address renewal (RENEW), rebinding (REBIND), + confirmation (CONFIRM), duplication report (DECLINE) and + release (RELEASE) are not supported yet. + + + DNS Update is not supported yet. + + + -v (verbose) command line option is currently + permanently enabled. + -
    + @@ -1976,6 +2024,16 @@ const std::string HARDCODED_SERVER_ID = "192.0.2.1"; implementation, see . + 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. + + DHCPv4 and DHCPv6 components in BIND10 architecture are + internally code named Kea. + As of December 2011, both DHCPv4 and DHCPv6 components are @@ -1993,16 +2051,16 @@ const std::string HARDCODED_SERVER_ID = "192.0.2.1"; DHCPv6 Server Usage BIND10 provides DHCPv6 server component since September - 2011. It is currently described as skeleton server and can be - described as an early prototype that is not yet fully - functional. It is mature enough to conduct first tests in lab - environment, but it has significant limitations. See for details. + 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 for + details. DHCPv6 server is implemented as b10-dhcp6 - daemon. As it is configurable yet, it is fully autonomous, + daemon. As it is not configurable yet, it is fully autonomous, i.e. it does not interact with b10-cfgmgr. To start DHCPv6 server, simply input: @@ -2016,10 +2074,10 @@ const std::string HARDCODED_SERVER_ID = "192.0.2.1"; directory, in /usr/local/bin/b10-dhcp6 or other directory you specified during compilation. - Afre start, server will detect available network interfaces + After start, 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. + are up, running, are not loopback, are multicast-capable and + have IPv6 address assigned. Server will then listen to incoming traffic. Currently supported client messages are SOLICIT and REQUEST. Server @@ -2028,6 +2086,17 @@ const std::string HARDCODED_SERVER_ID = "192.0.2.1"; As DHCPv6 server opens privileged ports, it requires root 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. + + +
    @@ -2040,8 +2109,9 @@ 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 parameters: + configuration is to tweak its source code. To do so, please + edit src/bin/dhcp6/dhcp6_srv.cc file and modify following + parameters and recompile: const std::string HARDCODED_LEASE = "2001:db8:1::1234:abcd"; const uint32_t HARDCODED_T1 = 1500; // in seconds @@ -2055,8 +2125,28 @@ const std::string HARDCODED_DNS_SERVER = "2001:db8:1::1";
    +
    + Supported DHCPv6 Standards + The following standards and draft standards are currently + supported: + + + RFC3315: Supported messages are SOLICIT, + ADVERTISE, REQUEST, and REPLY. Supported options are + SERVER_ID, CLIENT_ID, IA_NA, and IAADDRESS. + + + RFC3646: Supported option is DNS_SERVERS. + + +
    +
    DHCPv6 Server Limitations + These are the current limitations of 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. @@ -2083,8 +2173,13 @@ const std::string HARDCODED_DNS_SERVER = "2001:db8:1::1"; 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 down other interfaces. This limitation - will be fixed shortly. + this problem is to turn down other interfaces. This + limitation will be fixed shortly. + + + ORO (Option Request Option, a list of options + requested by a client) is currently ignored and server + assigns DNS SERVER option. Temporary addresses are not supported yet. @@ -2104,6 +2199,10 @@ const std::string HARDCODED_DNS_SERVER = "2001:db8:1::1"; Interface detection is currently working on Linux only. See for details. + + -v (verbose) command line option is currently permanently + enabled. +
    @@ -2112,17 +2211,19 @@ const std::string HARDCODED_DNS_SERVER = "2001:db8:1::1"; libdhcp++ library - libdhcp++ is a common library written in C++ that is - handles many DHCP-related tasks, like DHCPv4 and DHCPv6 packets - parsing, manipulation and assembly, option parsing, manipulation - and assembly, network interface detection and socket operations. + libdhcp++ is a common library written in C++ that handles + many DHCP-related tasks, like DHCPv4 and DHCPv6 packets parsing, + manipulation and assembly, option parsing, manipulation and + assembly, network interface detection and socket operations, like + socket creations, data transmission and reception and socket + closing. While this library is currently used by - b10-dhcp6 and b10-dhcp4 - only, it is designed to be portable, universal library useful - for any kind of DHCP-related software. + b10-dhcp4 and b10-dhcp6 + only, it is designed to be portable, universal library useful for + any kind of DHCP-related software.
    @@ -2132,14 +2233,14 @@ const std::string HARDCODED_DNS_SERVER = "2001:db8:1::1"; 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 was 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. Example of interfaces.txt file looks as follows: + 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. Example of interfaces.txt file looks as follows: # For DHCPv6, please specify link-local address (starts with fe80::) # If in doubt, check output of 'ifconfig -a' command.