This is the reference guide for BIND 10 version - 20110809.
Copyright © 2010-2011 Internet Systems Consortium, Inc.
Abstract
BIND 10 is a Domain Name System (DNS) suite managed by +
This is the reference guide for BIND 10 version + 20111021.
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 recursive DNS servers.
- This is the reference guide for BIND 10 version 20110809. + This is the reference guide for BIND 10 version 20111021. 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
Table of Contents
+
Table of Contents
Table of Contents
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 and provides a modular environment for serving and maintaining DNS.
This guide covers the experimental prototype of - BIND 10 version 20110809. + BIND 10 version 20111021.
BIND 10 provides a EDNS0- and DNSSEC-capable
authoritative DNS server and a caching recursive name server
@@ -315,11 +315,11 @@
var/bind10-devel/ —
data source and configuration databases.
-
Table of Contents
BIND 10 provides the bind10 command which starts up the required processes. bind10 - will also restart processes that exit unexpectedly. + will also restart some processes that exit unexpectedly. This is the only command needed to start the BIND 10 system.
After starting the b10-msgq communications channel, @@ -327,17 +327,20 @@ runs the configuration manager, and reads its own configuration. Then it starts the other modules.
- The b10-msgq and b10-cfgmgr + The b10-sockcreator, b10-msgq and + b10-cfgmgr services make up the core. The b10-msgq daemon provides the communication channel between every part of the system. The b10-cfgmgr daemon is always needed by every module, if only to send information about themselves somewhere, but more importantly to ask about their own settings, and - about other modules. - The bind10 master process will also start up + about other modules. The b10-sockcreator will + allocate sockets for the rest of the system. +
+ In its default configuration, the bind10 + master process will also start up b10-cmdctl for admins to communicate with the - system, b10-auth for authoritative DNS service or - b10-resolver for recursive name service, + system, b10-auth for authoritative DNS service, b10-stats for statistics collection, b10-xfrin for inbound DNS zone transfers, b10-xfrout for outbound DNS zone transfers, @@ -351,7 +354,107 @@ the process names for the Python-based daemons will be renamed to better identify them instead of just “python”. This is not needed on some operating systems. -
+ The processes to be started can be configured, with the exception + of the b10-sockcreator, b10-msgq + and b10-cfgmgr. +
+ 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
+
+ To add a process to the set, let's say the resolver (which not started + by default), you would do this: +
>config add Boss/components b10-resolver+>config set Boss/components/b10-resolver/special resolver+>config set Boss/components/b10-resolver/kind needed+>config set Boss/components/b10-resolver/priority 10+>config commit
+ Now, what it means. We add an entry called b10-resolver. It is both a + name used to reference this component in the configuration and the + name of the process to start. Then we set some parameters on how to + start it. +
+ The special one is for components that need some kind of special care + 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.
| Component | Special | Description |
|---|---|---|
| b10-auth | auth | Authoritative server |
| b10-resolver | resolver | The resolver |
| b10-cmdctl | cmdctl | The command control (remote control interface) |
| setuid | setuid | Virtual component, see below |
+
+ The kind specifies how a failure of the component should + be handled. If it is set to “dispensable” + (the default unless you set something else), it will get + started again if it fails. If it is set to “needed” + and it fails at startup, the whole bind10 + shuts down and exits with error exit code. But if it fails + some time later, it is just started again. If you set it + to “core”, you indicate that the system is + not usable without the 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 priority defines order in which the components should start. + The ones with higher number are started sooner than the ones with + lower ones. If you don't set it, 0 (zero) is used as the priority. +
+ There are other parameters we didn't use in our example. + One of them is “address”. It is the address + used by the component on the b10-msgq + message bus. The special components already know their + address, but the usual ones don't. The address is by + convention the thing after b10-, with + the first letter capital (eg. b10-stats + would have “Stats” as its address). + +
+ The last one is process. It is the name of the process to be started. + It defaults to the name of the component if not set, but you can use + this to override it. +
+ 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 + support is yet to be implemented. +
+ The configuration is quite powerful, but that includes + a lot of space for mistakes. You could turn off the + 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 + b10-stats, b10-xfrout + needs the b10-auth to be running, etc. + + + +
+ In short, you should think twice before disabling something here. +
+ Now, to the mysterious setuid virtual component. If you + use the -u option to start the + bind10 as root, but change the user + later, we need to start the b10-auth or + b10-resolver as root (until the socket + creator is finished). 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, b10-auth + has 10 to be started before the switch and everything else + is without priority, so it is started after the switch. +
The BIND 10 components use the b10-msgq message routing daemon to communicate with other BIND 10 components. The b10-msgq implements what is called the @@ -507,12 +610,12 @@ shutdown the details and relays (over a b10-msgq command channel) the configuration on to the specified module.
-
Table of Contents
+
Table of Contents
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. -
+
b10-auth is configured via the b10-cfgmgr configuration manager. The module name is “Auth”. @@ -532,7 +635,7 @@ This may be a temporary setting until then.
-
+
For the development prototype release, b10-auth
supports a SQLite3 data source backend and in-memory data source
backend.
@@ -546,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.
-
RFC 1035 style DNS master zone files may imported into a BIND 10 data source by using the b10-loadzone utility. @@ -575,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. -
Table of Contents
+
Table of Contents
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 @@ -593,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. -
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
@@ -609,7 +712,7 @@ This may be a temporary setting until then.
> config commit
(We assume there has been no zone configuration before). -
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
@@ -631,7 +734,7 @@ This may be a temporary setting until then.
make this selection automatically.
These features will be implemented in a near future
version, at which point we will enable IXFR by default.
-
To manually trigger a zone transfer to retrieve a remote zone, you may use the bindctl utility. For example, at the bindctl prompt run: @@ -641,16 +744,53 @@ This may be a temporary setting until then. The b10-xfrout process is started by bind10. When the b10-auth authoritative DNS server - receives an AXFR request, b10-xfrout - sends the zone. - This is used to provide master DNS service to share zones + receives an AXFR or IXFR request, b10-auth + internally forwards the request to b10-xfrout, + which handles the rest of request processing. + This is used to provide primary DNS service to share zones to secondary name servers. The b10-xfrout is also used to send - NOTIFY messages to slaves. + NOTIFY messages to secondary servers. +
+ A global or per zone transfer_acl configuration
+ can be used to control accessibility of the outbound zone
+ transfer service.
+ By default, b10-xfrout allows any clients to
+ perform zone transfers for any zones:
+
> config show Xfrout/transfer_acl
+Xfrout/transfer_acl[0] {"action": "ACCEPT"} any (default)+ You can change this to, for example, rejecting all transfer + requests by default while allowing requests for the transfer + of zone "example.com" from 192.0.2.1 and 2001:db8::1 as follows: +
>config set Xfrout/transfer_acl[0] {"action": "REJECT"}+>config add Xfrout/zone_config+>config set Xfrout/zone_config[0]/origin "example.com"+>config set Xfrout/zone_config[0]/transfer_acl [{"action": "ACCEPT", "from": "192.0.2.1"},+{"action": "ACCEPT", "from": "2001:db8::1"}]+>config commit
+ In the above example the lines
+ for transfer_acl were divided for
+ readability. In the actual input it must be in a single line.
+
+ If you want to require TSIG in access control, a separate TSIG + "key ring" must be configured specifically + for b10-xfrout as well as a system wide + key ring, both containing a consistent set of keys. + For example, to change the previous example to allowing requests + from 192.0.2.1 signed by a TSIG with a key name of + "key.example", you'll need to do this: +
>config set tsig_keys/keys ["key.example:<base64-key>"]+>config set Xfrout/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
+ The first line of configuration defines a system wide key ring. + This is necessary because the b10-auth server + also checks TSIGs and it uses the system wide configuration.
- The current development release of BIND 10 only supports - AXFR. (IXFR is not supported.) - Access control is not yet provided. + In a future version, b10-xfrout will also + use the system wide TSIG configuration. + The way to specify zone specific configuration (ACLs, etc) is + likely to be changed, too.
The b10-zonemgr process is started by bind10. @@ -665,7 +805,7 @@ This may be a temporary setting until then.
Access control (such as allowing notifies) is not yet provided. The primary/secondary service is not yet complete. -
Table of Contents
The b10-resolver process is started by bind10. @@ -678,8 +818,13 @@ This may be a temporary setting until then. You may change this using bindctl, for example:
->config set Boss/start_auth false->config set Boss/start_resolver true+>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+>config set Boss/components/b10-resolver/priority 10>config commit
@@ -699,7 +844,7 @@ This may be a temporary setting until then.
(Replace the “2”
as needed; run “config show
- Resolver/listen_on” if needed.)
+ Resolver/listen_on” if needed.)
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
@@ -732,7 +877,7 @@ This may be a temporary setting until then.
(Replace the “2”
as needed; run “config show
Resolver/query_acl” if needed.)
This prototype access control configuration - syntax may be changed.
To enable forwarding, the upstream address and port must be configured to forward queries to, such as: @@ -786,7 +931,7 @@ This may be a temporary setting until then. } }
-
The logging system in BIND 10 is configured through the Logging module. All BIND 10 modules will look at the @@ -795,7 +940,7 @@ This may be a temporary setting until then. -
+
Within BIND 10, a message is logged through a component
called a "logger". Different parts of BIND 10 log messages
@@ -816,7 +961,7 @@ This may be a temporary setting until then.
(what to log), and the output_options
(where to log).
-
+
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, @@ -889,7 +1034,7 @@ This may be a temporary setting until then. “Auth.cache” logger will appear in the output with a logger name of “b10-auth.cache”). -
This specifies the category of messages logged. Each message is logged with an associated severity which @@ -905,7 +1050,7 @@ This may be a temporary setting until then. -
Each logger can have zero or more
output_options. These specify where log
@@ -915,7 +1060,7 @@ This may be a temporary setting until then.
The other options for a logger are:
-
When a logger's severity is set to DEBUG, this value specifies what debug messages should be printed. It ranges @@ -924,7 +1069,7 @@ This may be a temporary setting until then. If severity for the logger is not DEBUG, this value is ignored. -
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.
-
+
Depending on what is set as the output destination, this
value is interpreted as follows:
@@ -971,12 +1116,12 @@ This may be a temporary setting until then.
The other options for output_options are:
-
+
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. -
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. @@ -985,11 +1130,11 @@ This may be a temporary setting until then. etc.)
If this is 0, no maximum file size is used. -
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-messages.html b/doc/guide/bind10-messages.html index 237b7adf80..f2f57f1a1d 100644 --- a/doc/guide/bind10-messages.html +++ b/doc/guide/bind10-messages.html @@ -1,10 +1,10 @@ -
This is the messages manual for BIND 10 version - 20110809.
Copyright © 2011 Internet Systems Consortium, Inc.
Abstract
BIND 10 is a Domain Name System (DNS) suite managed by +
This is the messages manual for BIND 10 version + 20111021.
Copyright © 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 recursive DNS servers.
- This is the messages manual for BIND 10 version 20110809. + This is the messages manual for BIND 10 version 20111021. The most up-to-date version of this document, along with other documents for BIND 10, can be found at http://bind10.isc.org/docs. @@ -107,6 +107,9 @@ This is a debug message, generated by the authoritative server when an attempt to parse the header of a received DNS packet has failed. (The reason for the failure is given in the message.) The server will drop the packet. +
+An error was encountered when the authoritiative server specified +statistics data which is invalid for the auth specification file.
This is a debug message indicating that the authoritative server has requested the keyring holding TSIG keys from the configuration @@ -263,12 +266,58 @@ NOTIFY request will not be honored. The boss process is starting up and will now check if the message bus daemon is already running. If so, it will not be able to start, as it needs a dedicated message bus. -
-This message shows whether or not the authoritative server should be -started according to the configuration. -
-This message shows whether or not the resolver should be -started according to the configuration. +
+The process terminated, but the bind10 boss didn't expect it to, which means +it must have failed. +
+The named component failed previously and we will try to restart it to provide +as flawless service as possible, but it should be investigated what happened, +as it could happen again. +
+The named component is about to be started by the boss process. +
+An exception (mentioned in the message) happened during the startup of the +named component. The componet is not considered started and further actions +will be taken about it. +
+A component is about to be asked to stop willingly by the boss. +
+A component failed for some reason (see previous messages). It is either a core +component or needed component that was just started. In any case, the system +can't continue without it and will terminate. +
+A debug message. This indicates that the configurator is building a plan +how to change configuration from the older one to newer one. This does no +real work yet, it just does the planning what needs to be done. +
+There was an exception during some planned task. The plan will not continue and +only some tasks of the plan were completed. The rest is aborted. The exception +will be propagated. +
+A different configuration of which components should be running is being +installed. All components that are no longer needed will be stopped and +newly introduced ones started. This happens at startup, when the configuration +is read the first time, or when an operator changes configuration of the boss. +
+A debug message. The configurator is about to execute a plan of actions it +computed previously. +
+The part that cares about starting and stopping the right component from the +boss process is starting up. This happens only once at the startup of the +boss process. It will start the basic set of processes now (the ones boss +needs to read the configuration), the rest will be started after the +configuration is known. +
+The part that cares about starting and stopping processes in the boss is +shutting down. All started components will be shut down now (more precisely, +asked to terminate by their own, if they fail to comply, other parts of +the boss process will try to force them). +
+A debug message. The configurator is about to perform one task of the plan it +is currently executing on the named component. +
+An error was encountered when the boss module specified +statistics data which is invalid for the boss specification file.
The boss process was started with the -u option, to drop root privileges and continue running as the specified user, but the user is unknown. @@ -284,24 +333,14 @@ There already appears to be a message bus daemon running. Either an old process was not shut down correctly, and needs to be killed, or another instance of BIND10, with the same msgq domain socket, is running, which needs to be stopped. -
-The message bus daemon has died. This is a fatal error, since it may -leave the system in an inconsistent state. BIND10 will now shut down.
While listening on the message bus channel for messages, it suddenly disappeared. The msgq daemon may have died. This might lead to an inconsistent state of the system, and BIND 10 will now shut down. -
-The given process ended unexpectedly, but no exit status is -available. See BIND10_PROCESS_ENDED_WITH_EXIT_STATUS for a longer -description. -
-The given process ended unexpectedly with the given exit status. -Depending on which module it was, it may simply be restarted, or it -may be a problem that will cause the boss module to shut down too. -The latter happens if it was the message bus daemon, which, if it has -died suddenly, may leave the system in an inconsistent state. BIND10 -will also shut down now if it has been run with --brittle. +
+This indicates a process started previously terminated. The process id +and component owning the process are indicated, as well as the exit code. +This doesn't distinguish if the process was supposed to terminate or not.
The boss process is starting up, and will now process the initial configuration, as received from the configuration manager. @@ -327,6 +366,8 @@ so BIND 10 will now shut down. The specific error is printed. The boss module is sending a SIGKILL signal to the given process.
The boss module is sending a SIGTERM signal to the given process. +
+The boss switches the user it runs as to the given UID.
The boss process received a command or signal telling it to shut down. It will send a shutdown command to each process. The processes that do @@ -341,10 +382,6 @@ which failed is unknown (not one of 'S' for socket or 'B' for bind).
The boss requested a socket from the creator, but the answer is unknown. This looks like a programmer error. -
-The socket creator terminated unexpectedly. It is not possible to restart it -(because the boss already gave up root privileges), so the system is going -to terminate.
There should be more data from the socket creator, but it closed the socket. It probably crashed. @@ -368,12 +405,18 @@ The socket creator failed to create the requested socket. It failed on the indicated OS API function with given error.
The boss forwards a request for a socket to the socket creator. +
+Debug message given when BIND 10 has successfull started the object that +handles configuration and commands.
The given process has successfully been started.
The given process has successfully been started, and has the given PID.
Informational message on startup that shows the full version. +
+Informational message given when BIND 10 is starting the session object +that handles configuration and commands.
The boss module is starting the given process.
@@ -387,8 +430,24 @@ All modules have been successfully started, and BIND 10 is now running.
There was a fatal error when BIND10 was trying to start. The error is shown, and BIND10 will now shut down. -
-The given module is being started or restarted without root privileges. +
+During the startup process, a number of messages are exchanged between the +Boss process and the processes it starts. This error is output when a +message received by the Boss process is recognised as being of the +correct format but is unexpected. It may be that processes are starting +of sequence. +
+During the startup process, a number of messages are exchanged between the +Boss process and the processes it starts. This error is output when a +message received by the Boss process is not recognised. +
+The authoritative server is being started or restarted without root privileges. +If the module needs these privileges, it may have problems starting. +Note that this issue should be resolved by the pending 'socket-creator' +process; once that has been implemented, modules should not need root +privileges anymore. See tickets #800 and #801 for more information. +
+The resolver is being started or restarted without root privileges. If the module needs these privileges, it may have problems starting. Note that this issue should be resolved by the pending 'socket-creator' process; once that has been implemented, modules should not need root @@ -399,6 +458,15 @@ the message channel.
An unknown child process has exited. The PID is printed, but no further action will be taken by the boss process. +
+The configuration manager process is so critical to operation of BIND 10 +that after starting it, the Boss module will wait for it to initialize +itself before continuing. This debug message is produced during the +wait and may be output zero or more times depending on how long it takes +the configuration manager to start up. The total length of time Boss +will wait for the configuration manager before reporting an error is +set with the command line --wait switch, which has a default value of +ten seconds.
The cache tried to generate the complete answer message. It knows the structure of the message, but some of the RRsets to be put there are not in cache (they @@ -487,7 +555,7 @@ Debug message. The RRset cache to hold at most this many RRsets for the given class is being created.
Debug message. The resolver is trying to look up data in the RRset cache. -
+
Debug message which can follow CACHE_RRSET_LOOKUP. This means the data is not in the cache.
@@ -642,6 +710,8 @@ The user was denied because the SSL connection could not successfully be set up. The specific error is given in the log message. Possible causes may be that the ssl request itself was bad, or the local key or certificate file could not be read. +
+The cmdctl daemon has started and is now listening for connections.
There was a keyboard interrupt signal to stop the cmdctl daemon. The daemon will now shut down. @@ -756,28 +826,18 @@ Debug information. An item is being removed from the hotspot cache. The maximum allowed number of items of the hotspot cache is set to the given number. If there are too many, some of them will be dropped. The size of 0 means no limit. -
-This was an internal error while reading data from a datasource. This can either -mean the specific data source implementation is not behaving correctly, or the -data it provides is invalid. The current search is aborted. -The error message contains specific information about the error. +
+The datasource tried to provide an NSEC proof that the named domain does not +exist, but the database backend doesn't support DNSSEC. No proof is included +in the answer as a result.
Debug information. The database data source is looking up records with the given name and type in the database.
The datasource backend provided resource records for the given RRset with -different TTL values. The TTL of the RRSET is set to the lowest value, which -is printed in the log message. -
-There was an uncaught general exception while reading data from a datasource. -This most likely points to a logic error in the code, and can be considered a -bug. The current search is aborted. Specific information about the exception is -printed in this error message. -
-There was an uncaught ISC exception while reading data from a datasource. This -most likely points to a logic error in the code, and can be considered a bug. -The current search is aborted. Specific information about the exception is -printed in this error message. +different TTL values. This isn't allowed on the wire and is considered +an error, so we set it to the lowest value we found (but we don't modify the +database). The data in database should be checked and fixed.
When searching for a domain, the program met a delegation to a different zone at the given domain name. It will return that one instead. @@ -789,6 +849,10 @@ It will return the NS record instead. When searching for a domain, the program met a DNAME redirection to a different place in the domain space at the given domain name. It will return that one instead. +
+The domain name doesn't have any RRs, so it doesn't exist in the database. +However, it has a subdomain, so it exists in the DNS address space. So we +return NXRRSET instead of NXDOMAIN.
The data returned by the database backend did not contain any data for the given domain name, class and type. @@ -799,6 +863,91 @@ name and class, but not for the given type. The data returned by the database backend contained data for the given domain name, and it either matches the type or has a relevant type. The RRset that is returned is printed. +
+The program is reading the whole zone, eg. not searching for data, but going +through each of the RRsets there. +
+While iterating through the zone, the program reached end of the data. +
+While iterating through the zone, the program extracted next RRset from it. +The name and RRtype of the RRset is indicated in the message. +
+While iterating through the zone, the time to live for RRs of the given RRset +were found to be different. This isn't allowed on the wire and is considered +an error, so we set it to the lowest value we found (but we don't modify the +database). The data in database should be checked and fixed. +
+This is a debug message indicating that the program (successfully) +reaches the end of sequences of a zone's differences. The zone's name +and class, database name, and the start and end serials are shown in +the message. +
+This is a debug message indicating that the program retrieves one +difference in difference sequences of a zone and successfully converts +it to an RRset. The zone's name and class, database name, and the +name and RR type of the retrieved diff are shown in the message. +
+This is a debug message indicating that the program starts reading +a zone's difference sequences from a database-based data source. The +zone's name and class, database name, and the start and end serials +are shown in the message. +
+This is an error message indicating that a zone's diff is broken and +the data source library failed to convert it to a valid RRset. The +most likely cause of this is that someone has manually modified the +zone's diff in the database and inserted invalid data as a result. +The zone's name and class, database name, and the start and end +serials, and an additional detail of the error are shown in the +message. The administrator should examine the diff in the database +to find any invalid data and fix it. +
+Debug information. A set of updates to a zone has been successfully +committed to the corresponding database backend. The zone name, +its class and the database name are printed. +
+Debug information. A zone updater object is created to make updates to +the shown zone on the shown backend database. +
+Debug information. A zone updater object is destroyed, either successfully +or after failure of, making updates to the shown zone on the shown backend +database. +
+A zone updater is being destroyed without committing the changes. +This would typically mean the update attempt was aborted due to some +error, but may also be a bug of the application that forgets committing +the changes. The intermediate changes made through the updater won't +be applied to the underlying database. The zone name, its class, and +the underlying database name are shown in the log message. +
+A zone updater is being destroyed without committing the changes to +the database, and attempts to rollback incomplete updates, but it +unexpectedly fails. The higher level implementation does not expect +it to fail, so this means either a serious operational error in the +underlying data source (such as a system failure of a database) or +software bug in the underlying data source implementation. In either +case if this message is logged the administrator should carefully +examine the underlying data source to see what exactly happens and +whether the data is still valid. The zone name, its class, and the +underlying database name as well as the error message thrown from the +database module are shown in the log message. +
+The database doesn't contain directly matching domain, but it does contain a +wildcard one which is being used to synthesize the answer. +
+The database was queried to provide glue data and it didn't find direct match. +It could create it from given wildcard, but matching wildcards is forbidden +under a zone cut, which was found. Therefore the delegation will be returned +instead. +
+The answer could be constructed using the wildcard, but the given subdomain +exists, therefore this name is something like empty non-terminal (actually, +from the protocol point of view, it is empty non-terminal, but the code +discovers it differently). +
+The given wildcard exists implicitly in the domainspace, as empty nonterminal +(eg. there's something like subdomain.*.example.org, so *.example.org exists +implicitly, but is empty). This will produce NXRRSET, because the constructed +domain is empty as well as the wildcard.
A debug message indicating that a query for the given name and RR type is being processed. @@ -1138,6 +1287,19 @@ data source.
This indicates a programming error. An internal task of unknown type was generated. +
+The xfrin module received an update containing multiple rdata changes for the +same RRset. But the TTLs of these don't match each other. As we combine them +together, the later one get's overwritten to the earlier one in the sequence. +
+An attempt was made to create a Diff object with journaling enabled, but +the underlying data source didn't support journaling (while still allowing +updates) and so the created object has it disabled. At a higher level this +means that the updates will be applied to the zone but subsequent IXFR requests +will result in a full zone transfer (i.e., an AXFR-style IXFR). Unless the +overhead of the full transfer is an issue this message can be ignored; +otherwise you may want to check why the journaling wasn't allowed on the +data source and either fix the issue or use a different type of data source.
A message from the interface to the underlying logger implementation reporting that the debug level (as set by an internally-created string DEBUGn, where n @@ -1259,6 +1421,16 @@ Within a message file, a line starting with a dollar symbol was found
The specified error was encountered by the message compiler when writing to the named output file. +
+notify_out failed to get access to one of configured data sources. +Detailed error is shown in the log message. This can be either a +configuration error or installation setup failure. +
+notify_out attempted to get slave information of a zone but the zone +isn't found in the expected data source. This shouldn't happen, +because notify_out first identifies a list of available zones before +this process. So this means some critical inconsistency in the data +source or software bug.
The notify_out library tried to send a notify message to the given address, but it appears to be an invalid address. The configuration @@ -1315,6 +1487,13 @@ provide more information. The notify message to the given address (noted as address#port) has timed out, and the message will be resent until the max retry limit is reached. +
+This is a warning issued when the notify_out module finds a zone that +doesn't have an SOA RR or has multiple SOA RRs. Notify message won't +be sent to such a zone. +
+This is a warning issued when the notify_out module finds a zone that +doesn't have an NS RR. Notify message won't be sent to such a zone.
A debug message issued when the NSAS (nameserver address store - part of the resolver) is making a callback into the resolver to retrieve the @@ -1732,6 +1911,11 @@ respond with 'Stats Httpd is up.' and its PID. An unknown command has been sent to the stats-httpd module. The stats-httpd module will respond with an error, and the command will be ignored. +
+An internal error occurred while handling an HTTP request. An HTTP 404 +response will be sent back, and the specific error is printed. This +is an error condition that likely points the specified data +corresponding to the requested URI is incorrect.
An internal error occurred while handling an HTTP request. An HTTP 500 response will be sent back, and the specific error is printed. This @@ -1776,14 +1960,10 @@ control bus. A likely problem is that the message bus daemon
This debug message is printed when the stats module has received a configuration update from the configuration manager. -
-A remove command for the given name was sent to the stats module, and -the given statistics value will now be removed. It will not appear in -statistics reports until it appears in a statistics update from a -module again. -
-The stats module received a command to clear all collected statistics. -The data is cleared until it receives an update from the modules again. +
+The stats module received a command to show all statistics schemas of all modules. +
+The stats module received a command to show the specified statistics schema of the specified module.
The stats module received a command to show all statistics that it has collected. @@ -1801,6 +1981,11 @@ will respond with an error and the command will be ignored.
This debug message is printed when a request is sent to the boss module to send its data to the stats module. +
+The stats module will be now starting. +
+An internal error occurred while starting the stats module. The stats +module will be now shutting down.
There was a keyboard interrupt signal to stop the stats module. The daemon will now shut down. @@ -1812,19 +1997,23 @@ from a different version of BIND 10 than the stats module itself. Please check your installation.
The AXFR transfer for the given zone has failed due to a database problem. -The error is shown in the log message. -
-The AXFR transfer for the given zone has failed due to an internal -problem in the bind10 python wrapper library. -The error is shown in the log message. -
-The AXFR transfer for the given zone has failed due to a protocol error. -The error is shown in the log message. -
-A connection to the master server has been made, the serial value in -the SOA record has been checked, and a zone transfer has been started. -
-The AXFR transfer of the given zone was successfully completed. +The error is shown in the log message. Note: due to the code structure +this can only happen for AXFR. +
+The serial fields of the first and last SOAs of AXFR (including AXFR-style +IXFR) are not the same. According to RFC 5936 these two SOAs must be the +"same" (not only for the serial), but it is still not clear what the +receiver should do if this condition does not hold. There was a discussion +about this at the IETF dnsext wg: +http://www.ietf.org/mail-archive/web/dnsext/current/msg07908.html +and the general feeling seems that it would be better to reject the +transfer if a mismatch is detected. On the other hand, also as noted +in that email thread, neither BIND 9 nor NSD performs any comparison +on the SOAs. For now, we only check the serials (ignoring other fields) +and only leave a warning log message when a mismatch is found. If it +turns out to happen with a real world primary server implementation +and that server actually feeds broken data (e.g. mixed versions of +zone), we can consider a stricter action.
The given master address is not a valid IP address.
@@ -1843,6 +2032,17 @@ error is given in the log message.
There was an error opening a connection to the master. The error is shown in the log message. +
+In an attempt of IXFR processing, the begenning SOA of the first difference +(following the initial SOA that specified the final SOA for all the +differences) was found. This means a connection for xfrin tried IXFR +and really aot a response for incremental updates. +
+Non incremental transfer was detected at the "first data" of a transfer, +which is the RR following the initial SOA. Non incremental transfer is +either AXFR or AXFR-style IXFR. In the latter case, it means that +in a response to IXFR query the first data is not SOA or its SOA serial +is not equal to the requested SOA serial.
There was an error importing the python DNS module pydnspp. The most likely cause is a PYTHONPATH problem. @@ -1853,6 +2053,11 @@ was killed.
There was a problem sending a message to the zone manager. This most likely means that the msgq daemon has quit or was killed. +
+The system received a notify for the given zone, but the address it came +from does not match the master address in the Xfrin configuration. The notify +is ignored. This may indicate that the configuration for the master is wrong, +that a wrong machine is sending notifies, or that fake notifies are being sent.
There was an internal command to retransfer the given zone, but the zone is not known to the system. This may indicate that the configuration @@ -1866,24 +2071,37 @@ daemon will now shut down.
An uncaught exception was raised while running the xfrin daemon. The exception message is printed in the log message. -
-The transfer of the given zone has been completed successfully, or was -aborted due to a shutdown event. -
-An uncaught exception was encountered while sending the response to -an AXFR query. The error message of the exception is included in the -log message, but this error most likely points to incomplete exception -handling in the code. -
-A transfer out for the given zone failed. An error response is sent -to the client. The given rcode is the rcode that is set in the error -response. This is either NOTAUTH (we are not authoritative for the -zone), SERVFAIL (our internal database is missing the SOA record for -the zone), or REFUSED (the limit of simultaneous outgoing AXFR -transfers, as specified by the configuration value -Xfrout/max_transfers_out, has been reached). -
-A transfer out of the given zone has started. +
+The XFR transfer for the given zone has failed due to a problem outside +of the xfrin module. Possible reasons are a broken DNS message or failure +in database connection. The error is shown in the log message. +
+An XFR session failed outside the main protocol handling. This +includes an error at the data source level at the initialization +phase, unexpected failure in the network connection setup to the +master server, or even more unexpected failure due to unlikely events +such as memory allocation failure. Details of the error are shown in +the log message. In general, these errors are not really expected +ones, and indicate an installation error or a program bug. The +session handler thread tries to clean up all intermediate resources +even on these errors, but it may be incomplete. So, if this log +message continuously appears, system resource consumption should be +checked, and you may even want to disable the corresponding transfers. +You may also want to file a bug report if this message appears so +often. +
+The XFR transfer for the given zone has failed due to a protocol error. +The error is shown in the log message. +
+The IXFR transfer of the given zone failed. This might happen in many cases, +such that the remote server doesn't support IXFR, we don't have the SOA record +(or the zone at all), we are out of sync, etc. In many of these situations, +AXFR could still work. Therefore we try that one in case it helps. +
+A connection to the master server has been made, the serial value in +the SOA record has been checked, and a zone transfer has been started. +
+The XFR transfer of the given zone was successfully completed.
The TSIG key string as read from the configuration does not represent a valid TSIG key. @@ -1894,6 +2112,9 @@ most likely cause is that the msgq daemon is not running. There was a problem reading a response from another module over the command and control channel. The most likely cause is that the configuration manager b10-cfgmgr is not running. +
+The xfrout process encountered an error when installing the configuration at +startup time. Details of the error are included in the log message.
There was a socket error while contacting the b10-auth daemon to fetch a transfer request. The auth daemon may have shutdown. @@ -1908,6 +2129,45 @@ by xfrout could not be found. This suggests that either some libraries are missing on the system, or the PYTHONPATH variable is not correct. The specific place where this library needs to be depends on your system and your specific installation. +
+An IXFR request was received with more than one SOA RRs in the authority +section. The xfrout daemon rejects the request with an RCODE of +FORMERR. +
+An IXFR request was received but the underlying data source did +not support journaling. The xfrout daemon fell back to AXFR-style +IXFR. +
+An IXFR request was received with no SOA RR in the authority section. +The xfrout daemon rejects the request with an RCODE of FORMERR. +
+An IXFR request was received, but the requested range of differences +were not found in the data source. The xfrout daemon fell back to +AXFR-style IXFR. +
+The requested zone in IXFR was not found in the data source +even though the xfrout daemon sucessfully found the SOA RR of the zone +in the data source. This can happen if the administrator removed the +zone from the data source within the small duration between these +operations, but it's more likely to be a bug or broken data source. +Unless you know why this message was logged, and especially if it +happens often, it's advisable to check whether the data source is +valid for this zone. The xfrout daemon considers it a possible, +though unlikely, event, and returns a response with an RCODE of +NOTAUTH. +
+An IXFR request was received, but the client's SOA version is the same as +or newer than that of the server. The xfrout server responds to the +request with the answer section being just one SOA of that version. +Note: as of this wrting the 'newer version' cannot be identified due to +the lack of support for the serial number arithmetic. This will soon +be implemented. +
+There was a problem in the lower level module handling configuration and +control commands. This could happen for various reasons, but the most likely +cause is that the configuration database contains a syntax error and xfrout +failed to start at initialization. A detailed error message from the module +will also be displayed.
New configuration settings have been sent from the configuration manager. The xfrout daemon will now apply them. @@ -1929,15 +2189,25 @@ There was an error processing a transfer request. The error is included in the log message, but at this point no specific information other than that could be given. This points to incomplete exception handling in the code. -
-The xfrout process silently dropped a request to transfer zone to given host. -This is required by the ACLs. The %1 and %2 represent the zone name and class, -the %3 and %4 the IP address and port of the peer requesting the transfer. -
+
+The xfrout process silently dropped a request to transfer zone to +given host. This is required by the ACLs. The %2 represents the IP +address and port of the peer requesting the transfer, and the %3 +represents the zone name and class. +
+The xfr request was rejected because the server was already handling +the maximum number of allowable transfers as specified in the transfers_out +configuration parameter, which is also shown in the log message. The +request was immediately responded and terminated with an RCODE of REFUSED. +This can happen for a busy xfrout server, and you may want to increase +this parameter; if the server is being too busy due to requests from +unexpected clients you may want to restrict the legitimate clients +with ACL. +
The xfrout process rejected (by REFUSED rcode) a request to transfer zone to -given host. This is because of ACLs. The %1 and %2 represent the zone name and -class, the %3 and %4 the IP address and port of the peer requesting the -transfer. +given host. This is because of ACLs. The %2 represents the IP +address and port of the peer requesting the transfer, and the %3 +represents the zone name and class.
The xfrout daemon received a shutdown command from the command channel and will now shut down. @@ -1973,6 +2243,30 @@ socket needed for contacting the b10-auth daemon to pass requests on, but the file is in use. The most likely cause is that another xfrout daemon process is still running. This xfrout daemon (the one printing this message) will not start. +
+Pre-response check for an incomding XFR request failed unexpectedly. +The most likely cause of this is that some low level error in the data +source, but it may also be other general (more unlikely) errors such +as memory shortage. Some detail of the error is also included in the +message. The xfrout server tries to return a SERVFAIL response in this case. +
+The transfer of the given zone has been completed successfully, or was +aborted due to a shutdown event. +
+An uncaught exception was encountered while sending the response to +an AXFR query. The error message of the exception is included in the +log message, but this error most likely points to incomplete exception +handling in the code. +
+A transfer out for the given zone failed. An error response is sent +to the client. The given rcode is the rcode that is set in the error +response. This is either NOTAUTH (we are not authoritative for the +zone), SERVFAIL (our internal database is missing the SOA record for +the zone), or REFUSED (the limit of simultaneous outgoing AXFR +transfers, as specified by the configuration value +Xfrout/max_transfers_out, has been reached). +
+A transfer out of the given zone has started.
An error was encountered on the command channel. The message indicates
the nature of the error.
diff --git a/doc/guide/bind10-messages.xml b/doc/guide/bind10-messages.xml
index bade381d2e..4dc02d46f4 100644
--- a/doc/guide/bind10-messages.xml
+++ b/doc/guide/bind10-messages.xml
@@ -573,19 +573,117 @@ needs a dedicated message bus.
-