From: Stephen Morris Date: Tue, 17 Apr 2012 09:23:47 +0000 (+0100) Subject: [1704] Changes to documentation regarding jumbled up messages X-Git-Tag: trac2351_base~226^2~116^2~21^2^2~1 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=95410c80370f458bf2d3908e92a69c2602d071d3;p=thirdparty%2Fkea.git [1704] Changes to documentation regarding jumbled up messages Logging output from different processes can get jumbled up if written to stderr (because messages are output in multiple write(2) operations.) This change updates the documentation to suggest that the user switch to stdout if that happens. --- diff --git a/doc/guide/bind10-guide.html b/doc/guide/bind10-guide.html index 9a76d5a031..5d6297db5d 100644 --- a/doc/guide/bind10-guide.html +++ b/doc/guide/bind10-guide.html @@ -1,18 +1,18 @@ -BIND 10 Guide

BIND 10 Guide

Administrator Reference for BIND 10

This is the reference guide for BIND 10 version - 20120127.

Copyright © 2010-2012 Internet Systems Consortium, Inc.

Abstract

BIND 10 is a framework that features Domain Name System +BIND 10 Guide

BIND 10 Guide

Administrator Reference for BIND 10

This is the reference guide for BIND 10 version + 20120405.

Copyright © 2010-2012 Internet Systems Consortium, Inc.

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 includes DNS libraries, modular components for controlling authoritative and recursive DNS servers, and experimental DHCPv4 and DHCPv6 servers.

- This is the reference guide for BIND 10 version 20120127. + This is the reference guide for BIND 10 version 20120405. 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.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
10. Outbound Zone Transfers
11. Recursive Name Server
11.1. Access Control
11.2. Forwarding
12. DHCPv4 Server
12.1. DHCPv4 Server Usage
12.2. DHCPv4 Server Configuration
12.3. Supported standards
12.4. DHCPv4 Server Limitations
13. DHCPv6 Server
13.1. DHCPv6 Server Usage
13.2. DHCPv6 Server Configuration
13.3. Supported DHCPv6 Standards
13.4. DHCPv6 Server Limitations
14. libdhcp++ library
14.1. Interface detection
14.2. DHCPv4/DHCPv6 packet handling
15. Statistics
16. Logging
16.1. Logging configuration
16.1.1. Loggers
16.1.2. Output Options
16.1.3. Example session
16.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.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
10. Outbound Zone Transfers
11. Recursive Name Server
11.1. Access Control
11.2. Forwarding
12. DHCPv4 Server
12.1. DHCPv4 Server Usage
12.2. DHCPv4 Server Configuration
12.3. Supported standards
12.4. DHCPv4 Server Limitations
13. DHCPv6 Server
13.1. DHCPv6 Server Usage
13.2. DHCPv6 Server Configuration
13.3. Supported DHCPv6 Standards
13.4. DHCPv6 Server Limitations
14. libdhcp++ library
14.1. Interface detection
14.2. DHCPv4/DHCPv6 packet handling
15. Statistics
16. Logging
16.1. Logging configuration
16.1.1. Loggers
16.1.2. Output Options
16.1.3. Example session
16.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

Table of Contents

1.1. Supported Platforms
1.2. Required Software
1.3. Starting and Stopping the Server
1.4. Managing BIND 10

+ by Comcast.

Chapter 1. Introduction

Table of Contents

1.1. Supported Platforms
1.2. Required Software
1.3. Starting and Stopping the Server
1.4. 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 @@ -22,8 +22,8 @@ provides forwarding.

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

1.1. Supported Platforms

+ BIND 10 version 20120405. +

1.1. Supported Platforms

BIND 10 builds have been tested on Debian GNU/Linux 5 and unstable, Ubuntu 9.10, NetBSD 5, Solaris 10, FreeBSD 7 and 8, CentOS Linux 5.3, and MacOS 10.6. @@ -162,7 +162,7 @@ and, of course, DNS. These include detailed developer documentation and code examples. -

Chapter 2. Installation

Table of Contents

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

2.1. Building Requirements

+

Chapter 2. Installation

Table of Contents

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

2.1. Building Requirements

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

Note

@@ -224,14 +224,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. @@ -265,7 +265,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: @@ -296,16 +296,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/ — @@ -361,12 +361,8 @@ master process will also start up b10-cmdctl for administration tools to communicate with the system, - b10-auth for authoritative DNS service, - b10-stats for statistics collection, - b10-stats-httpd for statistics reporting, - b10-xfrin for inbound DNS zone transfers, - b10-xfrout for outbound DNS zone transfers, - and b10-zonemgr for secondary service. + b10-stats for statistics collection, and + b10-stats-httpd for statistics reporting.

    3.1. Starting BIND 10

    To start the BIND 10 service, simply run bind10. Run it with the --verbose switch to @@ -384,12 +380,7 @@ The configuration is in the Boss/components section. Each element represents one component, which is an abstraction of a process (currently there's also one component which doesn't represent - a process). If you didn't want to transfer out at all (your server - is a slave only), you would just remove the corresponding component - from the set, like this and the process would be stopped immediately - (and not started on the next startup): - 

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

    + a process).

    To add a process to the set, let's say the resolver (which not started by default), you would do this: @@ -407,7 +398,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” @@ -446,7 +437,7 @@ This system allows you to start the same component multiple times (by including it in the configuration with different names, but the same process setting). However, the rest of the system doesn't expect - such situation, so it would probably not do what you want. Such + such a situation, so it would probably not do what you want. Such support is yet to be implemented.

    Note

    The configuration is quite powerful, but that includes @@ -454,10 +445,10 @@ b10-cmdctl, but then you couldn't change it back the usual way, as it would require it to be running (you would have to find and edit the configuration - directly). Also, some modules might have dependencies - -- b10-stats-httpd need + directly). Also, some modules might have dependencies: + b10-stats-httpd needs b10-stats, b10-xfrout - needs the b10-auth to be running, etc. + needs b10-auth to be running, etc. @@ -511,7 +502,7 @@ manager via b10-cmdctl's REST-ful interface. b10-cmdctl is covered in Chapter 6, Remote control daemon.

    Note

    - The development prototype release only provides the + The development prototype release only provides bindctl as a user interface to b10-cmdctl. Upcoming releases will provide another interactive command-line @@ -598,7 +589,7 @@ The port can be set by using the --port command line option. The address to listen on can be set using the --address command line argument. - Each HTTPS connection is stateless and timesout in 1200 seconds + Each HTTPS 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

    @@ -635,32 +626,92 @@ 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

    8.1. Server Configurations
    8.2. Data Source Backends
    8.3. Loading Master Zones Files

    +

    Chapter 8. Authoritative Server

    Table of Contents

    8.1. Server Configurations
    8.2. Data Source Backends
    8.2.1. In-memory Data Source
    8.3. 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. -

    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 item is: + The configuration data items are:

    database_file
    This is an optional string to define the path to find the SQLite3 database file. Note: Later the DNS server will use various data source backends. This may be a temporary setting until then. +
    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 define the + file path name and the + origin (default domain). + + By default, this is empty. + +

    Note

    + In this development version, currently this is only used for the + memory data source. + Only the IN class is supported at this time. + By default, the memory data source is disabled. + Also, currently the zone file must be canonical such as + generated by named-compilezone -D. +

    + +
    listen_on
    + listen_on is a list of addresses and ports for + b10-auth to listen on. + The list items are the address string + and port number. + By default, b10-auth listens on port 53 + on the IPv6 (::) and IPv4 (0.0.0.0) wildcard addresses. +
    statistics-interval
    + statistics-interval is the timer interval + in seconds for b10-auth to share its + statistics information to + b10-stats(8). + Statistics updates can be disabled by setting this to 0. + The default is 60.

    - The configuration command is: - -

    shutdown
    Stop the authoritative DNS server. + The configuration commands are: + +

    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 + datasrc optionally defines the type of datasource + (it defaults to “memory”). + +

    Note

    + In this development version, currently this only supports the + IN class and the memory data source. +

    +
    sendstats
    + sendstats tells b10-auth + to send its statistics data to + b10-stats(8) + immediately. +
    shutdown
    Stop the authoritative DNS server. + This has an optional pid 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

    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. @@ -672,11 +723,57 @@ This may be a temporary setting until then. (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. -

    8.3. Loading Master Zones Files

    + This data file location may be changed by defining the + “database_file” configuration. +

    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”: + + + + 

    > config add Auth/datasources
+> config set Auth/datasources[0]/type "memory"
+> config add Auth/datasources[0]/zones
+> config set Auth/datasources[0]/zones[0]/origin "example.com"
+> config set Auth/datasources[0]/zones[0]/file "example.com.zone"
+> config commit

    + + The authoritative server will begin serving it immediately + after it is loaded. +

    + Use the Auth loadzone command in + bindctl to reload a changed master + file into memory; for example: + + 

    > Auth loadzone origin="example.com"
+

    + +

    + 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 Auth/datasources: + + + + 

    > config set Auth/datasources/ []
+> config commit

    +

    + The following example stops serving a specific zone: + + 

    > config remove Auth/datasources[0]/zones[0]
+> config commit

    + + (Replace the list number(s) in + datasources[0] + and/or zones[0] + for the relevant zone as needed.) + +

    8.3. Loading Master Zones Files

    RFC 1035 style DNS master zone files may imported - into a BIND 10 data source by using the + into a BIND 10 SQLite3 data source by using the b10-loadzone utility.

    b10-loadzone supports the following @@ -693,7 +790,7 @@ This may be a temporary setting until then. default origin for loaded zone file records.

    Note

    In the development prototype release, only the SQLite3 back - end is used. + end is used by b10-loadzone. By default, it stores the zone data in /usr/local/var/bind10-devel/zone.sqlite3 unless the -d switch is used to set the @@ -703,7 +800,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

    9.1. Configuration for Incoming Zone Transfers
    9.2. Enabling IXFR
    9.3. Secondary Manager
    9.4. Trigger an Incoming Zone Transfer Manually

    +

    Chapter 9. Incoming Zone Transfers

    Table of Contents

    9.1. Configuration for Incoming Zone Transfers
    9.2. Enabling IXFR
    9.3. Secondary Manager
    9.4. 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 @@ -721,7 +818,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. -

    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 @@ -737,7 +834,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 @@ -789,7 +886,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. -

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

    > config set tsig_keys/keys ["key.example:<base64-key>"]
 > config set Xfrout/zone_config[0]/transfer_acl [{"action": "ACCEPT", "from": "192.0.2.1", "key": "key.example"}]
 > config commit

    Both Xfrout and Auth will use the system wide keyring to check - TSIGs in the incomming messages and to sign responses.

    Note

    + 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. Recursive Name Server

    Table of Contents

    11.1. Access Control
    11.2. Forwarding

    +

    Chapter 11. Recursive Name Server

    Table of Contents

    11.1. Access Control
    11.2. Forwarding

    The b10-resolver process is started by bind10.

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

    -> config remove Boss/components b10-xfrout
-> config remove Boss/components b10-xfrin
-> config remove Boss/components b10-auth
 > config add Boss/components b10-resolver
 > config set Boss/components/b10-resolver/special resolver
 > config set Boss/components/b10-resolver/kind needed
@@ -877,7 +969,7 @@ Xfrout/transfer_acl[0]	{"action": "ACCEPT"}	any	(default)

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

    11.1. Access Control

    + Resolver/listen_on” if needed.)

    11.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 @@ -910,7 +1002,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.

    11.2. Forwarding

    + syntax may be changed.

    11.2. Forwarding

    To enable forwarding, the upstream address and port must be configured to forward queries to, such as: @@ -1222,7 +1314,7 @@ eth0 fe80::21e:8cff:fe9b:7349 } }

    -

    Chapter 16. Logging

    Table of Contents

    16.1. Logging configuration
    16.1.1. Loggers
    16.1.2. Output Options
    16.1.3. Example session
    16.2. Logging Message Format

    16.1. Logging configuration

    +

    Chapter 16. Logging

    Table of Contents

    16.1. Logging configuration
    16.1.1. Loggers
    16.1.2. Output Options
    16.1.3. Example session
    16.2. Logging Message Format

    16.1. Logging configuration

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

    16.1.1. Loggers

    +

    16.1.1. Loggers

    Within BIND 10, a message is logged through a component called a "logger". Different parts of BIND 10 log messages @@ -1242,7 +1334,7 @@ eth0 fe80::21e:8cff:fe9b:7349 In the Logging module, you can specify the configuration for zero or more loggers; any that are not specified will - take appropriate default values.. + take appropriate default values.

    @@ -1252,7 +1344,7 @@ eth0 fe80::21e:8cff:fe9b:7349 (what to log), and the output_options (where to log). -

    16.1.1.1. name (string)

    +

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

    16.1.1.2. severity (string)

    +

    16.1.1.2. severity (string)

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

    16.1.1.3. output_options (list)

    +

    16.1.1.3. output_options (list)

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

    16.1.1.4. debuglevel (integer)

    +

    16.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 @@ -1360,7 +1452,7 @@ eth0 fe80::21e:8cff:fe9b:7349 If severity for the logger is not DEBUG, this value is ignored. -

    16.1.1.5. additive (true or false)

    +

    16.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 @@ -1374,45 +1466,53 @@ eth0 fe80::21e:8cff:fe9b:7349 -

    16.1.2. Output Options

    +

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

    16.1.2.1. destination (string)

    +

    16.1.2.1. destination (string)

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

    • console
    • file
    • syslog

    16.1.2.2. output (string)

    +

    • console
    • file
    • syslog

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

    destination is “file”
    +

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

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

    16.1.2.2.1. flush (true of false)

    +

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

    16.1.2.2.2. maxsize (integer)

    +

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

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

    16.1.2.2.3. maxver (integer)

    +

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

    16.1.3. Example session

    +

    16.1.3. Example session

    In this example we want to set the global logging to write to the file /var/log/my_bind10.log, @@ -1519,7 +1619,7 @@ Logging/loggers[0]/output_options[0]/maxver 0 integer (default) 

    >  config set Logging/loggers[0]/output_options[0]/destination file
 >  config set Logging/loggers[0]/output_options[0]/output /var/log/bind10.log
->  config set Logging/loggers[0]/output_options[0]/maxsize 30000
+>  config set Logging/loggers[0]/output_options[0]/maxsize 204800
 >  config set Logging/loggers[0]/output_options[0]/maxver 8

    @@ -1538,7 +1638,7 @@ Logging/loggers[0]/additive false boolean (default) Logging/loggers[0]/output_options[0]/destination "file" string (modified) Logging/loggers[0]/output_options[0]/output "/var/log/bind10.log" string (modified) Logging/loggers[0]/output_options[0]/flush false boolean (default) -Logging/loggers[0]/output_options[0]/maxsize 30000 integer (modified) +Logging/loggers[0]/output_options[0]/maxsize 204800 integer (modified) Logging/loggers[0]/output_options[0]/maxver 8 integer (modified)

    @@ -1586,7 +1686,7 @@ Logging/loggers[0]/output_options[0]/maxver 8 integer (modified) And every module will now be using the values from the logger named “*”. -

    16.2. Logging Message Format

    +

    16.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.xml b/doc/guide/bind10-guide.xml index 1eaad90061..7031d18639 100644 --- a/doc/guide/bind10-guide.xml +++ b/doc/guide/bind10-guide.xml @@ -2809,34 +2809,43 @@ TODO; there's a ticket to determine these levels, see #1074 is console - + 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 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 a 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. + is file - + The value of output is interpreted as a file name; log messages will be appended to this file. - + is syslog - + The value of output is interpreted as the syslog facility (e.g. local0) that should be used for log messages. - +