Commit 2d4063b1 authored by Jeremy C. Reed's avatar Jeremy C. Reed
Browse files

[master]Merge branch 'trac1687'

parents c0c5ff35 8ca0f76d
......@@ -113,8 +113,12 @@ systest:
cd tests/system; \
sh $(abs_srcdir)/tests/system/runall.sh
### include tool to generate documentation from log message specifications
### in the distributed tarball:
EXTRA_DIST = tools/system_messages.py
#### include external sources in the distributed tarball:
EXTRA_DIST = ext/asio/README
EXTRA_DIST += ext/asio/README
EXTRA_DIST += ext/asio/README
EXTRA_DIST += ext/asio/asio.hpp
EXTRA_DIST += ext/asio/asio/basic_socket.hpp
......
......@@ -1027,10 +1027,32 @@ AC_SUBST(PERL)
AC_PATH_PROGS(AWK, gawk awk)
AC_SUBST(AWK)
AC_ARG_ENABLE(man, [AC_HELP_STRING([--enable-man],
[regenerate man pages [default=no]])], enable_man=$enableval, enable_man=no)
AC_ARG_ENABLE(generate_docs, [AC_HELP_STRING([--enable-generate-docs],
[regenerate documentation using Docbook [default=no]])],
enable_generate_docs=$enableval, enable_generate_docs=no)
# Check for xsltproc
if test "x$enable_generate_docs" != xno ; then
AC_PATH_PROG([XSLTPROC], [xsltproc])
if test -z "$XSLTPROC"; then
AC_MSG_ERROR("xsltproc not found; it is required for --enable-generate-docs")
else
AC_MSG_CHECKING([if $XSLTPROC works])
# run xsltproc to see if works
$XSLTPROC --novalid --xinclude --nonet http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl
if test $? -ne 0 ; then
AC_MSG_ERROR("Error with $XSLTPROC using release/xsl/current/manpages/docbook.xsl")
fi
$XSLTPROC --novalid --xinclude --nonet http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl
if test $? -ne 0 ; then
AC_MSG_ERROR("Error with $XSLTPROC using release/xsl/current/html/docbook.xsl")
fi
AC_MSG_RESULT(yes)
fi
fi
AM_CONDITIONAL(ENABLE_MAN, test x$enable_man != xno)
AM_CONDITIONAL(GENERATE_DOCS, test x$enable_generate_docs != xno)
AC_ARG_ENABLE(install-configurations,
[AC_HELP_STRING([--disable-install-configurations],
......@@ -1376,7 +1398,7 @@ Developer:
C++ Code Coverage: $USE_LCOV
Python Code Coverage: $USE_PYCOVERAGE
Logger checks: $enable_logger_checks
Generate Manuals: $enable_man
Generate Documentation: $enable_generate_docs
END
......
dist_doc_DATA = bind10-guide.txt
dist_html_DATA = bind10-guide.css bind10-guide.html bind10-messages.html
# generated documentation
HTMLDOCS = bind10-guide.html bind10-messages.html
DOCS = bind10-guide.txt
EXTRA_DIST = bind10-guide.xml bind10-messages.xml
dist_doc_DATA = $(DOCS)
dist_html_DATA = $(HTMLDOCS) bind10-guide.css
# This is not a "man" manual, but reuse this for now for docbook.
if ENABLE_MAN
EXTRA_DIST = bind10-guide.xml
CLEANFILES = $(HTMLDOCS) $(DOCS) bind10-messages.xml
.PHONY: bind10-messages.xml
# This is not a "man" manual, but reuse this for now for docbook.
if GENERATE_DOCS
bind10-guide.html: bind10-guide.xml
xsltproc --novalid --xinclude --nonet \
@XSLTPROC@ --novalid --xinclude --nonet \
--path $(top_builddir)/doc \
-o $@ \
--stringparam section.autolabel 1 \
......@@ -21,18 +24,23 @@ bind10-guide.html: bind10-guide.xml
HTML2TXT = elinks -dump -no-numbering -no-references
bind10-guide.txt: bind10-guide.html
$(HTML2TXT) $(srcdir)/bind10-guide.html > $@
$(HTML2TXT) bind10-guide.html > $@
bind10-messages.html: bind10-messages.xml
xsltproc --novalid --xinclude --nonet \
@XSLTPROC@ --novalid --xinclude --nonet \
--path $(top_builddir)/doc \
-o $@ \
--stringparam html.stylesheet $(srcdir)/bind10-guide.css \
http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl \
$(srcdir)/bind10-messages.xml
bind10-messages.xml
# So many dependencies that it's easiest just to regenerate it every time
bind10-messages.xml:
$(PYTHON) $(top_srcdir)/tools/system_messages.py -o $@ $(top_srcdir)
else
$(HTMLDOCS) $(DOCS):
@echo Doc generation disabled. Creating dummy $@. Configure with --enable-generate-docs to enable it.
@echo Doc generation disabled. Remove this file, configure with --enable-generate-docs, and rebuild BIND 10 > $@
endif
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
......@@ -20,12 +20,19 @@ CLEANFILES = *.gcno *.gcda auth.spec spec_config.h
CLEANFILES += auth_messages.h auth_messages.cc
man_MANS = b10-auth.8
CLEANFILES += $(man_MANS)
EXTRA_DIST = $(man_MANS) b10-auth.xml
if ENABLE_MAN
if GENERATE_DOCS
b10-auth.8: b10-auth.xml
xsltproc --novalid --xinclude --nonet -o $@ http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $(srcdir)/b10-auth.xml
@XSLTPROC@ --novalid --xinclude --nonet -o $@ http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $(srcdir)/b10-auth.xml
else
$(man_MANS):
@echo Man generation disabled. Creating dummy $@. Configure with --enable-generate-docs to enable it.
@echo Man generation disabled. Remove this file, configure with --enable-generate-docs, and rebuild BIND 10 > $@
endif
......
'\" t
.\" Title: b10-auth
.\" Author: [FIXME: author] [see http://docbook.sf.net/el/author]
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
.\" Date: June 20, 2012
.\" Manual: BIND10
.\" Source: BIND10
.\" Language: English
.\"
.TH "B10\-AUTH" "8" "June 20, 2012" "BIND10" "BIND10"
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
b10-auth \- Authoritative DNS server
.SH "SYNOPSIS"
.HP \w'\fBb10\-auth\fR\ 'u
\fBb10\-auth\fR [\fB\-v\fR]
.SH "DESCRIPTION"
.PP
The
\fBb10\-auth\fR
daemon provides the BIND 10 authoritative DNS server\&. Normally it is started by the
\fBbind10\fR(8)
boss process\&.
.PP
This daemon communicates with other BIND 10 components over a
\fBb10-msgq\fR(8)
C\-Channel connection\&. If this connection is not established,
\fBb10\-auth\fR
will exit\&.
It receives its configurations from
\fBb10-cfgmgr\fR(8)\&.
.SH "OPTIONS"
.PP
The arguments are as follows:
.PP
\fB\-v\fR
.RS 4
Enable verbose logging mode\&. This enables logging of diagnostic messages at the maximum debug level\&.
.RE
.SH "CONFIGURATION AND COMMANDS"
.PP
The configurable settings are:
.PP
\fIdatabase_file\fR
defines the path to the SQLite3 zone file when using the sqlite datasource\&. The default is
/usr/local/var/bind10\-devel/zone\&.sqlite3\&.
.PP
\fIdatasources\fR
configures data sources\&. The list items include:
\fItype\fR
to define the required data source type (such as
\(lqmemory\(rq);
\fIclass\fR
to optionally select the class (it defaults to
\(lqIN\(rq); and
\fIzones\fR
to define the
\fIfile\fR
path name,
\fIorigin\fR
(default domain), and optional
\fIfiletype\fR\&. By default,
\fIzones\fR
is empty\&. For the in\-memory data source (i\&.e\&., the
\fItype\fR
is
\(lqmemory\(rq), the optional
\fIfiletype\fR
configuration item for
\fIzones\fR
can be specified so the in\-memory zone data can be built from another data source that is based on a database backend (in practice with current implementation, it would be an SQLite3 database file for the SQLite3 data source)\&. See the
BIND 10 Guide
for configuration details\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.sp
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 \fBnamed\-compilezone \-D\fR\&.
.sp .5v
.RE
.PP
\fIlisten_on\fR
is a list of addresses and ports for
\fBb10\-auth\fR
to listen on\&. The list items are the
\fIaddress\fR
string and
\fIport\fR
number\&. By default,
\fBb10\-auth\fR
listens on port 53 on the IPv6 (::) and IPv4 (0\&.0\&.0\&.0) wildcard addresses\&.
.PP
\fIstatistics\-interval\fR
is the timer interval in seconds for
\fBb10\-auth\fR
to share its statistics information to
\fBb10-stats\fR(8)\&. Statistics updates can be disabled by setting this to 0\&. The default is 60\&.
.PP
The configuration commands are:
.PP
\fBloadzone\fR
tells
\fBb10\-auth\fR
to load or reload a zone file\&. The arguments include:
\fIclass\fR
which optionally defines the class (it defaults to
\(lqIN\(rq);
\fIorigin\fR
is the domain name of the zone; and
\fIdatasrc\fR
optionally defines the type of datasource (it defaults to
\(lqmemory\(rq)\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.sp
In this development version, currently this only supports the IN class and the memory data source\&.
.sp .5v
.RE
.PP
\fBsendstats\fR
tells
\fBb10\-auth\fR
to send its statistics data to
\fBb10-stats\fR(8)
immediately\&.
.PP
\fBshutdown\fR
exits
\fBb10\-auth\fR\&. This has an optional
\fIpid\fR
argument to select the process ID to stop\&. (Note that the BIND 10 boss process may restart this service if configured\&.)
.SH "STATISTICS DATA"
.PP
The statistics data collected by the
\fBb10\-stats\fR
daemon for
\(lqAuth\(rq
include:
.PP
queries\&.tcp
.RS 4
Total count of queries received by the
\fBb10\-auth\fR
server over TCP since startup\&.
.RE
.PP
queries\&.udp
.RS 4
Total count of queries received by the
\fBb10\-auth\fR
server over UDP since startup\&.
.RE
.SH "FILES"
.PP
/usr/local/var/bind10\-devel/zone\&.sqlite3
\(em Location for the SQLite3 zone database when
\fIdatabase_file\fR
configuration is not defined\&.
.SH "SEE ALSO"
.PP
\fBb10-cfgmgr\fR(8),
\fBb10-loadzone\fR(8),
\fBb10-msgq\fR(8),
\fBb10-stats\fR(8),
\fBb10-zonemgr\fR(8),
\fBbind10\fR(8),
BIND 10 Guide\&.
.SH "HISTORY"
.PP
The
\fBb10\-auth\fR
daemon was first coded in October 2009\&.
.SH "COPYRIGHT"
.br
Copyright \(co 2010-2012 Internet Systems Consortium, Inc. ("ISC")
.br
......@@ -17,12 +17,26 @@ bind10_DATA = bob.spec
EXTRA_DIST = bob.spec
man_MANS = bind10.8
CLEANFILES += $(man_MANS)
EXTRA_DIST += $(man_MANS) bind10.xml bind10_messages.mes
if ENABLE_MAN
if GENERATE_DOCS
bind10.8: bind10.xml
xsltproc --novalid --xinclude --nonet -o $@ http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $(srcdir)/bind10.xml
@XSLTPROC@ --novalid --xinclude --nonet -o $@ http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $(srcdir)/bind10.xml
#dist-local-check-mans-enabled:
# @if grep "Man generation disabled" $(man_MANS) >/dev/null; then $(RM) $(man_MANS); fi
else
$(man_MANS):
@echo Man generation disabled. Creating dummy $@. Configure with --enable-generate-docs to enable it.
@echo Man generation disabled. Remove this file, configure with --enable-generate-docs, and rebuild BIND 10 > $@
#dist-local-check-mans-enabled:
# @echo "*** --enable-generate-docs must be used in order to make dist"
# @false
endif
......
'\" t
.\" Title: bind10
.\" Author: [see the "AUTHORS" section]
.\" Generator: DocBook XSL Stylesheets v1.77.1 <http://docbook.sf.net/>
.\" Date: April 12, 2012
.\" Manual: BIND10
.\" Source: BIND10
.\" Language: English
.\"
.TH "BIND10" "8" "April 12, 2012" "BIND10" "BIND10"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
bind10 \- BIND 10 boss process
.SH "SYNOPSIS"
.HP \w'\fBbind10\fR\ 'u
\fBbind10\fR [\fB\-c\ \fR\fB\fIconfig\-filename\fR\fR] [\fB\-i\fR] [\fB\-m\ \fR\fB\fIfile\fR\fR] [\fB\-p\ \fR\fB\fIdata_path\fR\fR] [\fB\-u\ \fR\fB\fIuser\fR\fR] [\fB\-v\fR] [\fB\-w\ \fR\fB\fIwait_time\fR\fR] [\fB\-\-clear\-config\fR] [\fB\-\-cmdctl\-port\fR\ \fIport\fR] [\fB\-\-config\-file\fR\ \fIconfig\-filename\fR] [\fB\-\-data\-path\fR\ \fIdirectory\fR] [\fB\-\-msgq\-socket\-file\ \fR\fB\fIfile\fR\fR] [\fB\-\-no\-kill\fR] [\fB\-\-pid\-file\fR\ \fIfilename\fR] [\fB\-\-pretty\-name\ \fR\fB\fIname\fR\fR] [\fB\-\-user\ \fR\fB\fIuser\fR\fR] [\fB\-\-verbose\fR] [\fB\-\-wait\ \fR\fB\fIwait_time\fR\fR]
.SH "DESCRIPTION"
.PP
The
\fBbind10\fR
daemon starts up other BIND 10 required daemons\&. It handles restarting of exiting programs and also the shutdown of all managed daemons\&.
.SH "ARGUMENTS"
.PP
The arguments are as follows:
.PP
\fB\-c\fR \fIconfig\-filename\fR, \fB\-\-config\-file\fR \fIconfig\-filename\fR
.RS 4
The configuration filename to use\&. Can be either absolute or relative to data path\&. In case it is absolute, value of data path is not considered\&. Defaults to
b10\-config\&.db\&.
.RE
.PP
\fB\-\-clear\-config\fR
.RS 4
This will create a backup of the existing configuration file, remove it and start
b10\-cfgmgr(8)
with the default configuration\&. The name of the backup file can be found in the logs (\fICFGMGR_BACKED_UP_CONFIG_FILE\fR)\&. (It will append a number to the backup filename if a previous backup file exists\&.)
.RE
.PP
\fB\-\-cmdctl\-port\fR \fIport\fR
.RS 4
The
\fBb10\-cmdctl\fR
daemon will listen on this port\&. (See
b10\-cmdctl(8)
for the default\&.)
.RE
.PP
\fB\-p\fR \fIdirectory\fR, \fB\-\-data\-path\fR \fIdirectory\fR
.RS 4
The path where BIND 10 programs look for various data files\&. Currently only
\fBb10-cfgmgr\fR(8)
uses it to locate the configuration file, but the usage might be extended for other programs and other types of files\&.
.RE
.PP
\fB\-m\fR \fIfile\fR, \fB\-\-msgq\-socket\-file\fR \fIfile\fR
.RS 4
The UNIX domain socket file for the
\fBb10-msgq\fR(8)
daemon to use\&. The default is
/usr/local/var/bind10\-devel/msg_socket\&.
.RE
.PP
\fB\-i\fR, \fB\-\-no\-kill\fR
.RS 4
When this option is passed,
\fBbind10\fR
does not send SIGTERM and SIGKILL signals to modules during shutdown\&. (This option was introduced for use during testing\&.)
.RE
.PP
\fB\-u\fR \fIuser\fR, \fB\-\-user\fR \fIname\fR
.RS 4
The username for
\fBbind10\fR
to run as\&.
\fBbind10\fR
must be initially ran as the root user to use this option\&. The default is to run as the current user\&.
.RE
.PP
\fB\-\-pid\-file\fR \fIfilename\fR
.RS 4
If defined, the PID of the
\fBbind10\fR
is stored in this file\&.
.RE
.PP
\fB\-\-pretty\-name \fR\fB\fIname\fR\fR
.RS 4
The name this process should have in tools like
\fBps\fR
or
\fBtop\fR\&. This is handy if you have multiple versions/installations of
\fBbind10\fR\&.
.RE
.PP
\fB\-v\fR, \fB\-\-verbose\fR
.RS 4
Display more about what is going on for
\fBbind10\fR
and its child processes\&.
.RE
.PP
\fB\-w\fR \fIwait_time\fR, \fB\-\-wait\fR \fIwait_time\fR
.RS 4
Sets the amount of time that BIND 10 will wait for the configuration manager (a key component of BIND 10) to initialize itself before abandoning the start up and terminating with an error\&. The
\fIwait_time\fR
is specified in seconds and has a default value of 10\&.
.RE
.SH "CONFIGURATION AND COMMANDS"
.PP
The configuration provides settings for components for
\fBbind10\fR
to manage under
\fI/Boss/components/\fR\&. The default elements are:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fI/Boss/components/b10\-cmdctl\fR
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fI/Boss/components/b10\-stats\fR
.RE
.PP
(Note that the startup of
\fBb10\-sockcreator\fR,
\fBb10\-cfgmgr\fR, and
\fBb10\-msgq\fR
is not configurable\&. They are hardcoded and
\fBbind10\fR
will not run without them\&.)
.PP
The named sets for components contain the following settings:
.PP
\fIaddress\fR
.RS 4
The name used for communicating to it on the message bus\&.
.RE
.PP
\fIkind\fR
.RS 4
This defines how required a component is\&. The possible settings for
\fIkind\fR
are:
\fIcore\fR
(system won\*(Aqt start if it won\*(Aqt start and
\fBbind10\fR
will shutdown if a
\(lqcore\(rq
component crashes),
\fIdispensable\fR
(\fBbind10\fR
will restart failing component), and
\fIneeded\fR
(\fBbind10\fR
will shutdown if component won\*(Aqt initially start, but if crashes later, it will attempt to restart)\&. This setting is required\&.
.RE
.PP
\fIpriority\fR
.RS 4
This is an integer\&.
\fBbind10\fR
will start the components with largest priority numbers first\&.
.RE
.PP
\fIprocess\fR
.RS 4
This is the filename of the executable to be started\&. If not defined, then
\fBbind10\fR
will use the component name instead\&.
.RE
.PP
\fIspecial\fR
.RS 4
This defines if the component is started a special, hardcoded way\&.
.RE
.PP
The
\fIBoss\fR
configuration commands are:
.PP
\fBgetstats\fR
tells
\fBbind10\fR
to send its statistics data to the
\fBb10\-stats\fR
daemon\&. This is an internal command and not exposed to the administrator\&.
.PP
\fBping\fR
is used to check the connection with the
\fBbind10\fR
daemon\&. It returns the text
\(lqpong\(rq\&.
.PP
\fBshow_processes\fR
lists the current processes managed by
\fBbind10\fR\&. The output is an array in JSON format containing the process ID, the name for each and the address name used on each message bus\&.
.PP
\fBshutdown\fR
tells
\fBbind10\fR
to shutdown the BIND 10 servers\&. It will tell each process it manages to shutdown and, when complete,
\fBbind10\fR
will exit\&.
.SH "STATISTICS DATA"
.PP
The statistics data collected by the
\fBb10\-stats\fR
daemon for
\(lqBoss\(rq
include:
.PP
boot_time
.RS 4
The date and time that the
\fBbind10\fR
process started\&. This is represented in ISO 8601 format\&.
.RE
.SH "FILES"
.PP
sockcreator\-XXXXXX/sockcreator
\(em the Unix Domain socket located in a temporary file directory for
\fBb10\-sockcreator\fR