<abstract>
<para>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
- recursive DNS servers.
+ Internet Systems Consortium (ISC). It includes DNS libraries
+ and modular components for controlling authoritative and
+ recursive DNS servers.
</para>
<para>
This is the reference guide for BIND 10 version &__VERSION__;.
- 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 <ulink url="http://bind10.isc.org/docs"/>.
- </para> </abstract>
+ 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 <ulink url="http://bind10.isc.org/docs"/>.
+ </para> </abstract>
<releaseinfo>This is the reference guide for BIND 10 version
&__VERSION__;.</releaseinfo>
</para>
<para>
- BIND 10 uses the Botan crypto library for C++. It requires
- at least Botan version 1.8.
+ BIND 10 uses the Botan crypto library for C++. It requires
+ at least Botan version 1.8.
</para>
<para>
- BIND 10 uses the log4cplus C++ logging library. It requires
- at least log4cplus version 1.0.3.
+ BIND 10 uses the log4cplus C++ logging library. It requires
+ at least log4cplus version 1.0.3.
</para>
<para>
- The authoritative server requires SQLite 3.3.9 or newer.
- The <command>b10-xfrin</command>, <command>b10-xfrout</command>,
- and <command>b10-zonemgr</command> modules require the
- libpython3 library and the Python _sqlite3.so module.
+ The authoritative server requires SQLite 3.3.9 or newer.
+ The <command>b10-xfrin</command>, <command>b10-xfrout</command>,
+ and <command>b10-zonemgr</command> modules require the
+ libpython3 library and the Python _sqlite3.so module.
</para>
<!-- TODO: this will change ... -->
<para>
BIND 10 is modular. Part of this modularity is
accomplished using multiple cooperating processes which, together,
- provide the server functionality. This is a change from
- the previous generation of BIND software, which used a
- single process.
+ provide the server functionality. This is a change from
+ the previous generation of BIND software, which used a
+ single process.
</para>
<para>
- At first, running many different processes may seem confusing.
- However, these processes are started, stopped, and maintained
- by a single command, <command>bind10</command>.
- This command starts a master process which will start other
- processes as needed.
- The processes started by the <command>bind10</command>
- command have names starting with "b10-", including:
+ At first, running many different processes may seem confusing.
+ However, these processes are started, stopped, and maintained
+ by a single command, <command>bind10</command>.
+ This command starts a master process which will start other
+ processes as needed.
+ The processes started by the <command>bind10</command>
+ command have names starting with "b10-", including:
</para>
<para>
<simpara>
<command>b10-xfrout</command> —
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.
+ This process is used to handle transfer requests to
+ send a local zone to a remote secondary server,
+ when acting as a master server.
</simpara>
</listitem>
<simpara>
<command>b10-zonemgr</command> —
Secondary manager.
- This process keeps track of timers and other
+ This process keeps track of timers and other
necessary information for BIND 10 to act as a slave server.
</simpara>
</listitem>
</para>
<para>
- These are ran automatically by <command>bind10</command>
- and do not need to be run manually.
+ These are ran automatically by <command>bind10</command>
+ and do not need to be run manually.
</para>
</section>
<title>Managing BIND 10</title>
<para>
- Once BIND 10 is running, a few commands are used to interact
- directly with the system:
+ Once BIND 10 is running, a few commands are used to interact
+ directly with the system:
<itemizedlist>
<listitem>
<simpara>
</para>
<para>
- To build BIND 10, also install the Botan (at least version
- 1.8) and the log4cplus (at least version 1.0.3)
+ To build BIND 10, also install the Botan (at least version
+ 1.8) and the log4cplus (at least version 1.0.3)
development include headers.
</para>
<para>
<!-- TODO: is this needed at build time? test time? -->
- The Python Library and Python _sqlite3 module are required to
+ The Python Library and Python _sqlite3 module are required to
enable the Xfrout and Xfrin support.
</para>
</para>
<para>
- The kind specifies how a failure of the component should
- be handled. If it is set to <quote>dispensable</quote>
- (the default unless you set something else), it will get
- started again if it fails. If it is set to <quote>needed</quote>
- and it fails at startup, the whole <command>bind10</command>
- 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 <quote>core</quote>, 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 core as well if you wish (but you can
- turn these off, they just can't fail).
+ The kind specifies how a failure of the component should
+ be handled. If it is set to <quote>dispensable</quote>
+ (the default unless you set something else), it will get
+ started again if it fails. If it is set to <quote>needed</quote>
+ and it fails at startup, the whole <command>bind10</command>
+ 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 <quote>core</quote>, 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 core as well if you wish (but you can
+ turn these off, they just can't fail).
</para>
<para>
<para>
There are other parameters we didn't use in our example.
- One of them is <quote>address</quote>. It is the address
- used by the component on the <command>b10-msgq</command>
- message bus. The special components already know their
- address, but the usual ones don't. The address is by
- convention the thing after <emphasis>b10-</emphasis>, with
- the first letter capital (eg. <command>b10-stats</command>
- would have <quote>Stats</quote> as its address).
+ One of them is <quote>address</quote>. It is the address
+ used by the component on the <command>b10-msgq</command>
+ message bus. The special components already know their
+ address, but the usual ones don't. The address is by
+ convention the thing after <emphasis>b10-</emphasis>, with
+ the first letter capital (eg. <command>b10-stats</command>
+ would have <quote>Stats</quote> as its address).
<!-- TODO: this should be simplified so we don't even have to document it -->
</para>
<note>
<para>
- The configuration is quite powerful, but that includes
- a lot of space for mistakes. You could turn off the
- <command>b10-cmdctl</command>, 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
- -- <command>b10-stats-httpd</command> need
- <command>b10-stats</command>, <command>b10-xfrout</command>
- needs the <command>b10-auth</command> to be running, etc.
+ The configuration is quite powerful, but that includes
+ a lot of space for mistakes. You could turn off the
+ <command>b10-cmdctl</command>, 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
+ -- <command>b10-stats-httpd</command> need
+ <command>b10-stats</command>, <command>b10-xfrout</command>
+ needs the <command>b10-auth</command> to be running, etc.
<!-- TODO: should we define dependencies? -->
</note>
<para>
- Now, to the mysterious setuid virtual component. If you
- use the <command>-u</command> option to start the
- <command>bind10</command> as root, but change the user
- later, we need to start the <command>b10-auth</command> or
- <command>b10-resolver</command> as root (until the socket
- creator is finished).<!-- TODO --> So we need to specify
- the time when the switch from root do the given user happens
- and that's what the setuid component is for. The switch is
- done at the time the setuid component would be started, if
- it was a process. The default configuration contains the
- setuid component with priority 5, <command>b10-auth</command>
- has 10 to be started before the switch and everything else
- is without priority, so it is started after the switch.
+ Now, to the mysterious setuid virtual component. If you
+ use the <command>-u</command> option to start the
+ <command>bind10</command> as root, but change the user
+ later, we need to start the <command>b10-auth</command> or
+ <command>b10-resolver</command> as root (until the socket
+ creator is finished).<!-- TODO --> So we need to specify
+ the time when the switch from root do the given user happens
+ and that's what the setuid component is for. The switch is
+ done at the time the setuid component would be started, if
+ it was a process. The default configuration contains the
+ setuid component with priority 5, <command>b10-auth</command>
+ has 10 to be started before the switch and everything else
+ is without priority, so it is started after the switch.
</para>
</section>
<section>
<title>Configuration for Incoming Zone Transfers</title>
<para>
- 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
- (see below)).
+ 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
+ (see below)).
</para>
<para>
- For example, to enable zone transfers for a zone named "example.com"
- (whose master address is assumed to be 2001:db8::53 here),
- run the following at the <command>bindctl</command> prompt:
+ For example, to enable zone transfers for a zone named "example.com"
+ (whose master address is assumed to be 2001:db8::53 here),
+ run the following at the <command>bindctl</command> prompt:
<screen>> <userinput>config add Xfrin/zones</userinput>
> <userinput>config set Xfrin/zones[0]/name "<option>example.com</option>"</userinput>
<title>Trigger an Incoming Zone Transfer Manually</title>
<para>
- To manually trigger a zone transfer to retrieve a remote zone,
- you may use the <command>bindctl</command> utility.
- For example, at the <command>bindctl</command> prompt run:
+ To manually trigger a zone transfer to retrieve a remote zone,
+ you may use the <command>bindctl</command> utility.
+ For example, at the <command>bindctl</command> prompt run:
- <screen>> <userinput>Xfrin retransfer zone_name="<option>foo.example.org</option>" master=<option>192.0.2.99</option></userinput></screen>
+ <screen>> <userinput>Xfrin retransfer zone_name="<option>foo.example.org</option>" master=<option>192.0.2.99</option></userinput></screen>
</para>
</section>
> <userinput>config commit</userinput></screen>
<note><simpara>
- In the above example the lines
- for <option>transfer_acl</option> were divided for
- readability. In the actual input it must be in a single line.
+ In the above example the lines
+ for <option>transfer_acl</option> were divided for
+ readability. In the actual input it must be in a single line.
</simpara></note>
<para>
</para>
<note><simpara>
- In a future version, <command>b10-xfrout</command> will also
- use the system wide TSIG configuration.
- The way to specify zone specific configuration (ACLs, etc) is
- likely to be changed, too.
+ In a future version, <command>b10-xfrout</command> will also
+ use the system wide TSIG configuration.
+ The way to specify zone specific configuration (ACLs, etc) is
+ likely to be changed, too.
</simpara></note>
<!--
By default, the <command>b10-resolver</command> daemon only accepts
DNS queries from the localhost (127.0.0.1 and ::1).
The <option>Resolver/query_acl</option> configuration may
- be used to reject, drop, or allow specific IPs or networks.
+ be used to reject, drop, or allow specific IPs or networks.
This configuration list is first match.
</para>
<para>
- The configuration's <option>action</option> item may be
- set to <quote>ACCEPT</quote> to allow the incoming query,
- <quote>REJECT</quote> to respond with a DNS REFUSED return
- code, or <quote>DROP</quote> to ignore the query without
- any response (such as a blackhole). For more information,
- see the respective debugging messages: <ulink
- url="bind10-messages.html#RESOLVER_QUERY_ACCEPTED">RESOLVER_QUERY_ACCEPTED</ulink>,
- <ulink
- url="bind10-messages.html#RESOLVER_QUERY_REJECTED">RESOLVER_QUERY_REJECTED</ulink>,
- and <ulink
+ The configuration's <option>action</option> item may be
+ set to <quote>ACCEPT</quote> to allow the incoming query,
+ <quote>REJECT</quote> to respond with a DNS REFUSED return
+ code, or <quote>DROP</quote> to ignore the query without
+ any response (such as a blackhole). For more information,
+
see the respective debugging messages: <ulink
+ url="bind10-messages.html#RESOLVER_QUERY_ACCEPTED">RESOLVER_QUERY_ACCEPTED</ulink>,
+ url="bind10-messages.html#RESOLVER_QUERY_REJECTED">RESOLVER_QUERY_REJECTED</ulink>,
url="bind10-messages.html#RESOLVER_QUERY_DROPPED">RESOLVER_QUERY_DROPPED</ulink>.
</para>
<para>
- The required configuration's <option>from</option> item is set
+ The required configuration's <option>from</option> item is set
to an IPv4 or IPv6 address, addresses with an network mask, or to
- the special lowercase keywords <quote>any6</quote> (for
- any IPv6 address) or <quote>any4</quote> (for any IPv4
- address).
+ the special lowercase keywords <quote>any6</quote> (for
+ any IPv6 address) or <quote>any4</quote> (for any IPv4
+ address).
</para>
<!-- TODO:
-->
<para>
- For example to allow the <replaceable>192.168.1.0/24</replaceable>
- network to use your recursive name server, at the
- <command>bindctl</command> prompt run:
+ For example to allow the <replaceable>192.168.1.0/24</replaceable>
+ network to use your recursive name server, at the
+ <command>bindctl</command> prompt run:
</para>
<screen>
</chapter>
+ <chapter id="dhcp4">
+ <title>DHCPv4 Server</title>
+ <para>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
+ ease deployment in larger networks, additional nodes (relays) may
+ be deployed that facilitate communication between servers and
+ 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.</para>
+
+ <note>
+ <para>
+ 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
+ yet. In particular, both do not have functional lease
+ databases. This means that they will assign the same, fixed,
+ hardcoded addresses to any client that will ask. See <xref
+ linkend="dhcp4-limit"/> and <xref linkend="dhcp6-limit"/> for
+ detailed description.
+ </para>
+ </note>
+
+ <section>
+ <title>Server Usage</title>
+ <para>BIND10 provides experimental 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 <xref
+ linkend="dhcp4-limit"/> for details.
+ </para>
+
+ <para>
+ DHCPv4 server is implemented as <command>b10-dhcp4</command>
+ daemon. As it is configurable yet, it is fully autonomous,
+ i.e. it does not interact with <command>b10-cfgmgr</command>.
+ To start DHCPv4 server, simply input:
+
+ <screen>
+#<userinput>cd src/bin/dhcp4</userinput>
+#<userinput>./b10-dhcp4</userinput>
+</screen>
+
+ Depending on your installation, <command>b10-dhcp4</command>
+ 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.
+
+ Afre 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.
+
+ Server will then listen to incoming traffic. Currently
+ supported client messages are DISCOVER and REQUEST. Server
+ 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.
+ </para>
+ </section>
+
+ <section>
+ <title>Server Configuration</title>
+ <para>
+ 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.
+ </para>
+ <para>
+ 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:
+ <screen>
+const std::string HARDCODED_LEASE = "10.3.2.222"; // assigned lease
+const std::string HARDCODED_NETMASK = "255.255.255.0";
+const uint32_t HARDCODED_LEASE_TIME = 60; // in seconds
+const std::string HARDCODED_GATEWAY = "10.3.2.2";
+const std::string HARDCODED_DNS_SERVER = "8.8.8.8";
+const std::string HARDCODED_DOMAIN_NAME = "isc.example.org";
+const std::string HARDCODED_SERVER_ID = "10.3.1.1";</screen>
+
+ Lease database and configuration support is planned for 2012.
+ </para>
+ </section>
+
+ <section id="dhcp4-limit">
+ <title>DHCPv4 Server Limitations</title>
+ <para>
+ 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.
+ </para>
+ </section>
+ </chapter>
+
+ <chapter id="dhcp6-srv">
+ <title>DHCPv6 Server</title>
+ <section id="dhcp6-limit">
+ <title>DHCPv6 Server Limitations</title>
+ <para>
+ Relayed traffic is not supported.
+ </para>
+ </section>
+
+
+ </chapter>
+
+ <chapter id="libdhcp++">
+ <title>libdhcp++ library</title>
+ <para>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.
+ </para>
+
+ <para>
+ While this library is currently used by
+ <command>b10-dhcp6</command> and <command>b10-dhcp4</command>
+ only, it is designed to be portable, universal library useful
+ for any kind of DHCP-related software.
+ </para>
+
+ <section>
+ <title>Interface detection</title>
+ <para>Both DHCPv4 and DHCPv6 components share network
+ interface detection routines (see <xref
+ linkend="libdhcp++"/> for details). Interface detection is
+ currently only supported on Linux systems.</para>
+
+ <para>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:
+ <screen>
+# 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</screen>
+ </para>
+ </section>
+
+ </chapter>
+
<chapter id="statistics">
<title>Statistics</title>
<para>
- 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.
+ 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.
<!-- TODO: what is context of Logging module for readers of this guide? -->
<para>
- Within BIND 10, a message is logged through a component
- called a "logger". Different parts of BIND 10 log messages
- through different loggers, and each logger can be configured
- independently of one another.
+ Within BIND 10, a message is logged through a component
+ called a "logger". Different parts of BIND 10 log messages
+ through different loggers, and each logger can be configured
+ independently of one another.
</para>
<para>
- In the Logging module, you can specify the configuration
- for zero or more loggers; any that are not specified will
- take appropriate default values..
+ In the Logging module, you can specify the configuration
+ for zero or more loggers; any that are not specified will
+ take appropriate default values..
</para>
<para>
- The three most important elements of a logger configuration
- are the <option>name</option> (the component that is
- generating the messages), the <option>severity</option>
- (what to log), and the <option>output_options</option>
- (where to log).
+ The three most important elements of a logger configuration
+ are the <option>name</option> (the component that is
+ generating the messages), the <option>severity</option>
+ (what to log), and the <option>output_options</option>
+ (where to log).
</para>
<title>name (string)</title>
<para>
- 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 <quote>Resolver</quote>. This
- configuration will then be used by the loggers in the
- Resolver module, and all the libraries used by it.
+ 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 <quote>Resolver</quote>. This
+ configuration will then be used by the loggers in the
+ Resolver module, and all the libraries used by it.
</para>
<!-- TODO: later we will have a way to know names of all modules
<para>
- If you want to specify logging for one specific library
- within the module, you set the name to
- <replaceable>module.library</replaceable>. For example, the
- logger used by the nameserver address store component
- has the full name of <quote>Resolver.nsas</quote>. If
- there is no entry in Logging for a particular library,
- it will use the configuration given for the module.
+ If you want to specify logging for one specific library
+ within the module, you set the name to
+ <replaceable>module.library</replaceable>. For example, the
+ logger used by the nameserver address store component
+ has the full name of <quote>Resolver.nsas</quote>. If
+ there is no entry in Logging for a particular library,
+ it will use the configuration given for the module.
<!-- TODO: how to know these specific names?
<!-- TODO: severity has not been covered yet -->
- 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
- <quote>Resolver</quote> and severity INFO, and one with
- the name <quote>Resolver.cache</quote> with severity
- DEBUG. As there are no entries for other libraries (e.g.
- the nsas), they will use the configuration for the module
- (<quote>Resolver</quote>), so giving the desired behavior.
+ 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
+ <quote>Resolver</quote> and severity INFO, and one with
+ the name <quote>Resolver.cache</quote> with severity
+ DEBUG. As there are no entries for other libraries (e.g.
+ the nsas), they will use the configuration for the module
+ (<quote>Resolver</quote>), so giving the desired behavior.
</para>
<para>
- One special case is that of a module name of <quote>*</quote>
- (asterisks), which is interpreted as <emphasis>any</emphasis>
- 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. <quote>*.config</quote>
- specifies the configuration library code in whatever
- module is using it).
+ One special case is that of a module name of <quote>*</quote>
+ (asterisks), which is interpreted as <emphasis>any</emphasis>
+ 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. <quote>*.config</quote>
+ specifies the configuration library code in whatever
+ module is using it).
</para>
<para>
- 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 <quote>*</quote> and <quote>Resolver</quote>, the
- resolver module — and all libraries it uses —
- will log messages according to the configuration in the
- second entry (<quote>Resolver</quote>). All other modules
- will use the configuration of the first entry
- (<quote>*</quote>). If there was also a configuration
- entry for <quote>Resolver.cache</quote>, the cache library
- within the resolver would use that in preference to the
- entry for <quote>Resolver</quote>.
+ 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 <quote>*</quote> and <quote>Resolver</quote>, the
+ resolver module — and all libraries it uses —
+ will log messages according to the configuration in the
+ second entry (<quote>Resolver</quote>). All other modules
+ will use the configuration of the first entry
+ (<quote>*</quote>). If there was also a configuration
+ entry for <quote>Resolver.cache</quote>, the cache library
+ within the resolver would use that in preference to the
+ entry for <quote>Resolver</quote>.
</para>
<para>
- One final note about the naming. When specifying the
- module name within a logger, use the name of the module
- as specified in <command>bindctl</command>, e.g.
- <quote>Resolver</quote> for the resolver module,
- <quote>Xfrout</quote> 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
- <quote>Auth.cache</quote> logger will appear in the output
- with a logger name of <quote>b10-auth.cache</quote>).
+ One final note about the naming. When specifying the
+ module name within a logger, use the name of the module
+ as specified in <command>bindctl</command>, e.g.
+ <quote>Resolver</quote> for the resolver module,
+ <quote>Xfrout</quote> 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
+ <quote>Auth.cache</quote> logger will appear in the output
+ with a logger name of <quote>b10-auth.cache</quote>).
</para>
<para>
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):
+ Each message is logged with an associated severity which
+ may be one of the following (in descending order of
+ severity):
</para>
<itemizedlist>
<para>
- 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.
+ 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.
<!-- TODO: worded wrong? If I set to INFO, why would it show DEBUG which is literally below in that list? -->
<para>
- Each logger can have zero or more
- <option>output_options</option>. These specify where log
- messages are sent to. These are explained in detail below.
+ Each logger can have zero or more
+ <option>output_options</option>. These specify where log
+ messages are sent to. These are explained in detail below.
</para>
<para>
- 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 verbose).
+ 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 verbose).
</para>
<!-- TODO: complete this sentence:
- The general classification of debug message types is
+ The general classification of debug message types is
TODO; there's a ticket to determine these levels, see #1074
<para>
- If this is true, the <option>output_options</option> from
- the parent will be used. For example, if there are two
- loggers configured; <quote>Resolver</quote> and
- <quote>Resolver.cache</quote>, and <option>additive</option>
- is true in the second, it will write the log messages
- not only to the destinations specified for
- <quote>Resolver.cache</quote>, but also to the destinations
- as specified in the <option>output_options</option> in
- the logger named <quote>Resolver</quote>.
+ If this is true, the <option>output_options</option> from
+ the parent will be used. For example, if there are two
+ loggers configured; <quote>Resolver</quote> and
+ <quote>Resolver.cache</quote>, and <option>additive</option>
+ is true in the second, it will write the log messages
+ not only to the destinations specified for
+ <quote>Resolver.cache</quote>, but also to the destinations
+ as specified in the <option>output_options</option> in
+ the logger named <quote>Resolver</quote>.
<!-- TODO: check this -->
<para>
- The main settings for an output option are the
- <option>destination</option> and a value called
- <option>output</option>, the meaning of which depends on
- the destination that is set.
+ The main settings for an output option are the
+ <option>destination</option> and a value called
+ <option>output</option>, the meaning of which depends on
+ the destination that is set.
</para>
<para>
- Depending on what is set as the output destination, this
- value is interpreted as follows:
+ Depending on what is set as the output destination, this
+ value is interpreted as follows:
</para>
<term><option>destination</option> is <quote>console</quote></term>
<listitem>
<simpara>
- The value of output must be one of <quote>stdout</quote>
- (messages printed to standard output) or
- <quote>stderr</quote> (messages printed to standard
- error).
+ The value of output must be one of <quote>stdout</quote>
+ (messages printed to standard output) or
+ <quote>stderr</quote> (messages printed to standard
+ error).
</simpara>
</listitem>
</varlistentry>
<term><option>destination</option> is <quote>file</quote></term>
<listitem>
<simpara>
- The value of output is interpreted as a file name;
- log messages will be appended to this file.
+ The value of output is interpreted as a file name;
+ log messages will be appended to this file.
</simpara>
</listitem>
</varlistentry>
<term><option>destination</option> is <quote>syslog</quote></term>
<listitem>
<simpara>
- The value of output is interpreted as the
- <command>syslog</command> facility (e.g.
- <emphasis>local0</emphasis>) that should be used
- for log messages.
+ The value of output is interpreted as the
+ <command>syslog</command> facility (e.g.
+ <emphasis>local0</emphasis>) that should be used
+ for log messages.
</simpara>
</listitem>
</varlistentry>
<title>flush (true of false)</title>
<para>
- 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.
+ 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.
</para>
</section>
<title>maxsize (integer)</title>
<para>
- 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",
+ 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.)
</para>
<title>maxver (integer)</title>
<para>
- Maximum number of old log files to keep around when
- rolling the output file. Only relevant when
- <option>destination</option> is <quote>file</quote>.
+ Maximum number of old log files to keep around when
+ rolling the output file. Only relevant when
+ <option>destination</option> is <quote>file</quote>.
</para>
</section>
<para>
- In this example we want to set the global logging to
- write to the file <filename>/var/log/my_bind10.log</filename>,
- at severity WARN. We want the authoritative server to
- log at DEBUG with debuglevel 40, to a different file
- (<filename>/tmp/debug_messages</filename>).
+ In this example we want to set the global logging to
+ write to the file <filename>/var/log/my_bind10.log</filename>,
+ at severity WARN. We want the authoritative server to
+ log at DEBUG with debuglevel 40, to a different file
+ (<filename>/tmp/debug_messages</filename>).
</para>
<para>
- By default, no specific loggers are configured, in which
- case the severity defaults to INFO and the output is
- written to stderr.
+ By default, no specific loggers are configured, in which
+ case the severity defaults to INFO and the output is
+ written to stderr.
</para>
<para>
- The loggers value line changed to indicate that it is no
- longer an empty list:
+ The loggers value line changed to indicate that it is no
+ longer an empty list:
</para>
<para>
- The name is mandatory, so we must set it. We will also
- change the severity as well. Let's start with the global
- logger.
+ The name is mandatory, so we must set it. We will also
+ change the severity as well. Let's start with the global
+ logger.
</para>
<para>
- Of course, we need to specify where we want the log
- messages to go, so we add an entry for an output option.
+ Of course, we need to specify where we want the log
+ messages to go, so we add an entry for an output option.
</para>
<para>
- Which would make the entire configuration for this logger
- look like:
+ Which would make the entire configuration for this logger
+ look like:
</para>
<para>
- That looks OK, so let's commit it before we add the
- configuration for the authoritative server's logger.
+ That looks OK, so let's commit it before we add the
+ configuration for the authoritative server's logger.
</para>
<para>
- Now that we have set it, and checked each value along
- the way, adding a second entry is quite similar.
+ Now that we have set it, and checked each value along
+ the way, adding a second entry is quite similar.
</para>
<para>
- And that's it. Once we have found whatever it was we
- needed the debug messages for, we can simply remove the
- second logger to let the authoritative server use the
- same settings as the rest.
+ And that's it. Once we have found whatever it was we
+ needed the debug messages for, we can simply remove the
+ second logger to let the authoritative server use the
+ same settings as the rest.
</para>
<para>
- And every module will now be using the values from the
- logger named <quote>*</quote>.
+ And every module will now be using the values from the
+ logger named <quote>*</quote>.
</para>
<title>Logging Message Format</title>
<para>
- 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
- a problem, information about the problem that may be
- useful in fixing it.
+ 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
+ a problem, information about the problem that may be
+ useful in fixing it.
</para>
<para>
<varlistentry>
<term>ASIODNS_OPENSOCK</term>
<listitem><para>
- The message identification. Every message in BIND 10
- has a unique identification, which can be used as an
- index into the <ulink
- url="bind10-messages.html"><citetitle>BIND 10 Messages
- Manual</citetitle></ulink> (<ulink
- url="http://bind10.isc.org/docs/bind10-messages.html"
- />) from which more information can be obtained.
+ The message identification. Every message in BIND 10
+ has a unique identification, which can be used as an
+ url="bind10-messages.html"><citetitle>BIND 10 Messages
+
Manual</citetitle></ulink> (<ulink
+ url="http://bind10.isc.org/docs/bind10-messages.html"
+ />) from which more information can be obtained.
</para></listitem>
</varlistentry>
<varlistentry>
<term>error 111 opening TCP socket to 127.0.0.1(53)</term>
<listitem><para>
- A brief description of the cause of the problem.
- Within this text, information relating to the condition
- that caused the message to be logged will be included.
- In this example, error number 111 (an operating
- system-specific error number) was encountered when
- trying to open a TCP connection to port 53 on the
- local system (address 127.0.0.1). The next step
- would be to find out the reason for the failure by
- consulting your system's documentation to identify
- what error number 111 means.
+ A brief description of the cause of the problem.
+ Within this text, information relating to the condition
+ that caused the message to be logged will be included.
+ In this example, error number 111 (an operating
+ system-specific error number) was encountered when
+ trying to open a TCP connection to port 53 on the
+ local system (address 127.0.0.1). The next step
+ would be to find out the reason for the failure by
+ consulting your system's documentation to identify
+ what error number 111 means.
</para></listitem>
</varlistentry>
</variablelist>
projects / thirdparty / kea.git / commitdiff
