Commit 45761a40 authored by Jeremy C. Reed's avatar Jeremy C. Reed
Browse files

Add several new manual pages in nroff format. These are generated

from docbook format (already in svn).

This updates bindctl.1 and msgq.8 already in svn.

Add Makefile.am additions so these are installed and also
to regenerate them. Assuming the nroff version is newer than the xml
version, make won't need to regenerate. It is created using
xsltproc. But this shouldn't be a build requirement -- so 
may need to redo this if notice any problem.

Also in the loadzone makefile, create the localstatedir. (Not
really needed since other makefile creates, but just in
case this becomes standalone.)


git-svn-id: svn://bind10.isc.org/svn/bind10/trunk@1506 e5f2f494-b856-4b98-b285-d166d9295462
parent aabe2982
......@@ -11,6 +11,12 @@ pkglibexecdir = $(libexecdir)/@PACKAGE@
CLEANFILES = *.gcno *.gcda
man_MANS = b10-auth.8
EXTRA_DIST = $(man_MANS) b10-auth.xml
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
pkglibexec_PROGRAMS = b10-auth
b10_auth_SOURCES = auth_srv.cc auth_srv.h
b10_auth_SOURCES += common.h
......@@ -31,5 +37,5 @@ endif
b10_authdir = $(DESTDIR)$(pkgdatadir)
b10_auth_DATA = auth.spec
EXTRA_DIST = auth.spec
EXTRA_DIST += auth.spec
'\" 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: March 16, 2010
.\" Manual: BIND10
.\" Source: BIND10
.\" Language: English
.\"
.TH "B10\-AUTH" "8" "March 16, 2010" "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\-4\fR] [\fB\-6\fR] [\fB\-p\ \fR\fB\fInumber\fR\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)
master process\&.
.PP
This daemon communicates over a
\fBmsgq\fR(8)
C\-Channel connection\&. If this connection is not established,
\fBb10\-auth\fR
will exit\&.
.PP
It also receives its configurations from
\fBb10-cfgmgr\fR(8)
using the REST\-ful interface provided by
\fBb10-cmdctl\fR(8)\&. It will honor the
\fIdatabase_file\fR
configuration to point to the SQLite3 zone file\&.
.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
.PP
This prototype version uses SQLite3 as its data source backend\&. Future versions will be configurable, supporting multiple data storage types\&.
.sp .5v
.RE
.SH "OPTIONS"
.PP
The arguments are as follows:
.PP
\fB\-4\fR
.RS 4
Enables IPv4 only mode\&. This switch may not be used with
\fB\-6\fR\&. By default, it listens on both IPv4 and IPv6 (if capable)\&.
.RE
.PP
\fB\-6\fR
.RS 4
Enables IPv6 only mode\&. This switch may not be used with
\fB\-4\fR\&. By default, it listens on both IPv4 and IPv6 (if capable)\&.
.RE
.PP
\fB\-p \fR\fB\fInumber\fR\fR
.RS 4
The port number it listens on\&. The default is 5300\&.
.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
The Y1 prototype runs on all interfaces and on this nonstandard port\&.
.sp .5v
.RE
.RE
.PP
\fB\-v\fR
.RS 4
Enabled verbose mode\&. This enables diagnostic messages to STDERR\&.
.RE
.SH "FILES"
.PP
/usr/local/var/db/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-cmdctl\fR(8),
\fBb10-loadzone\fR(8),
\fBbind10\fR(8),
\fBmsgq\fR(8),
BIND 10 User Guide\&.
.SH "HISTORY"
.PP
The
\fBb10\-auth\fR
daemon was first coded in October 2009\&.
.SH "COPYRIGHT"
.br
Copyright \(co 2010 Internet Systems Consortium, Inc. ("ISC")
.br
......@@ -5,9 +5,14 @@ pkglibexecdir = $(libexecdir)/@PACKAGE@
bind10dir = $(DESTDIR)$(pkgdatadir)
bind10_DATA = bob.spec
EXTRA_DIST = bob.spec
man_MANS = bind10.8
EXTRA_DIST += $(man_MANS) bind10.xml
bind10.8: bind10.xml
xsltproc --novalid --xinclude --nonet -o $@ http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $(srcdir)/bind10.xml
# TODO: does this need $$(DESTDIR) also?
# this is done here since configure.ac AC_OUTPUT doesn't expand exec_prefix
bind10: bind10.py
......
'\" t
.\" Title: bind10
.\" Author: [see the "AUTHORS" section]
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
.\" Date: February 22, 2010
.\" Manual: BIND10
.\" Source: BIND10
.\" Language: English
.\"
.TH "BIND10" "8" "February 22, 2010" "BIND10" "BIND10"
.\" -----------------------------------------------------------------
.\" * 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 master process
.SH "SYNOPSIS"
.HP \w'\fBbind10\fR\ 'u
\fBbind10\fR [\fB\-m\ \fR\fB\fInumber\fR\fR] [\fB\-v\fR] [\fB\-msgq\-port\ \fR\fB\fInumber\fR\fR] [\fB\-verbose\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\-m\fR \fInumber\fR, \fB\-\-msgq\-port\fR \fInumber\fR
.RS 4
The port number for the
\fBmsgq\fR(8)
daemon to listen on\&. The default is 9912\&.
.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
.SH "SEE ALSO"
.PP
\fBbindctl\fR(1),
\fBb10-auth\fR(8),
\fBb10-cfgmgr\fR(8),
\fBb10-cmdctl\fR(8),
\fBb10-xfrin\fR(8),
\fBmsgq\fR(8),
BIND 10 User Guide\&.
.SH "HISTORY"
.PP
The development of
\fBbind10\fR
was started in October 2009\&.
.SH "AUTHORS"
.PP
The
\fBbind10\fR
daemon was initially designed by Shane Kerr of ISC\&.
.SH "COPYRIGHT"
.br
Copyright \(co 2010 Internet Systems Consortium, Inc. ("ISC")
.br
bin_SCRIPTS = bindctl
man_MANS = bindctl.1
EXTRA_DIST = $(man_MANS)
EXTRA_DIST = $(man_MANS) bindctl.xml
python_PYTHON = __init__.py bindcmd.py cmdparse.py exception.py moduleinfo.py mycollections.py
pythondir = $(pyexecdir)/bindctl
......@@ -12,6 +12,9 @@ EXTRA_DIST += bindctl.pem
CLEANFILES = bindctl
bindctl.1: bindctl.xml
xsltproc --novalid --xinclude --nonet -o $@ http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $(srcdir)/bindctl.xml
bindctl: bindctl-source.py
$(SED) -e "s|@@PYTHONPATH@@|@pyexecdir@|" \
-e "s|@@SYSCONFDIR@@|@sysconfdir@|" \
......
.\" Copyright (C) 2010 Internet Systems Consortium, Inc. ("ISC")
.Dd January 19, 2010
.Dt BINDCTL 1
.Os
.Sh NAME
.Nm bindctl
.Nd control and configure BIND 10
.Sh SYNOPSIS
.\" TODO: option to choose the command channel?
.Nm
.Sh DESCRIPTION
'\" t
.\" Title: bindctl
.\" Author: [see the "AUTHORS" section]
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
.\" Date: January 19, 2010
.\" Manual: BIND10
.\" Source: BIND10
.\" Language: English
.\"
.TH "BINDCTL" "1" "January 19, 2010" "BIND10" "BIND10"
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
bindctl \- control and configure BIND 10
.SH "SYNOPSIS"
.HP \w'\fBbindctl\fR\ 'u
\fBbindctl\fR
.SH "DESCRIPTION"
.PP
The
.Nm
tool is a user interface to the BIND 10 services.
The program can be used to control the components
and configure the BIND 10 options.
The options may be specified as command-line arguments,
or via the interactive command interpreter.
.\" TODO: command-line arguments?
.Pp
.Nm
must communicate over a
.Xr msgq 8
C-Channel
connection.
If this connection is not established,
.Nm
will exit.
.\" TODO: what if msgq is running but no BindCtl or Boss groups?
.Pp
\fBbindctl\fR
tool is a user interface to the BIND 10 services\&. The program can be used to control the components and configure the BIND 10 options\&. The options may be specified
via its interactive command interpreter\&.
.PP
The
.Nm
\fBbindctl\fR
prompt shows
.Dq "\*[Gt] " .
The prompt will also display the location if changed.
The options are based on the module in use.
The
.Nm
usage is:
.Pp
.Ic module Ic command Op Ar "param1 = value1" Op Ar ", param2 = value2"
.Pp
.Nm Ap s
interactive interface provides command-line completion and hints.
Press the
.Li Tab
key to get a hint for the module, command, and/or parameters.
.\" TODO: no hints at a blank line though
The arrow keys and Emacs-style editing keys may be used to edit
and recall previous lines.
.\" TODO: all Emacs-style editing keys?
.Pp
\(lq> \(rq\&. The prompt will also display the location if changed\&. The options are based on the module in use\&. The usage is:
\fBmodule\fR
\fBcommand\fR
\fIparam1 = value1 , \fR\fI\fIparam2 = value2\fR\fR
.PP
\fBbindctl\fR\'s interactive interface provides command\-line completion and hints\&. Press the Tab key to get a hint for the module, command, and/or parameters\&.
The arrow keys and Emacs\-style editing keys may be used to edit and recall previous lines\&.
.PP
You can use the
.Ic help
keyword to receive usage assistance for a module or a module's
command.
.Pp
\fBhelp\fR
keyword to receive usage assistance for a module or a module\'s command\&.
.PP
The
.Ic quit
\fBquit\fR
command is used to exit
.Nm
(and doesn't stop the BIND 10 services).
.Pp
The following modules are available by default:
.Pp
.Bl -tag -width ".Li config" -compact -offset indent
.It Ic boss
Control BIND 10 services.
.It Ic config
Configuration commands.
.El
\fBbindctl\fR
(and doesn\'t stop the BIND 10 services)\&.
.PP
The following module is available by default:
\fBconfig\fR
for Configuration commands\&.
Additional modules may be available, such as
.Ic ParkingLot .
.\" TODO
.Sh BOSS COMMANDS
.Bl -tag -width Ic
.It Ic help
Get help for the
.Em boss
module.
.It Ic shutdown Op Ar module_name
Stop the defined BIND 10 process.
If
.Ar module_name
is not provided, then tell the
.\" TODO: write this manual page
.Xr boss 8
process to stop all the BIND 10 processes.
.El
.Sh CONFIGURATION COMMANDS
The following configuration commands are recognized by
.Nm :
.Bl -tag -width Ic
.It Ic add Ar identifier Ar value
Add a value to a list.
.\" TODO: explain better
.\" TODO: define list, map, others ...
.\" TODO: why the value?
.It Ic commit
Commit all local changes.
.\" TODO: what does this do?
.It Ic go Ar identifier
Go to the specified location within the configuration.
.\" TODO: explain this
.It Ic help
Get help for the
.Em config
module.
.It Ic remove Ar identifier Ar value
Remove a value from a list.
.\" TODO: why the value?
.It Ic revert
Revert all local changes (that have not been committed).
.\" TODO: what does this do?
.It Ic set Ar identifier Ar value
Set a configuration value.
.\" TODO
.It Ic show Op Ar identifier.
.\" TODO
Show the currently set configuration values.
If no
.Ar identifier
is given, the current location is used (as set by the
.Ic go
command).
If a config option is a list or a map, the value is not
shown directly, but must be requested separately.
.\" TODO: example of this list or map
.It Ic unset Ar identifier
Remove a configuration value.
If the option is mandatory, it will reset to the default value.
.\" TODO: how to know default values before?
.El
.\" This manual page only covers builtin commands.
.\" .Sh PARKINGLOT COMMANDS
.\" .Bl -tag -width Ic
.\" .It Ic help
.\" Get help for the
.\" .Em ParkingLot
.\" module.
.\" .It Ic print_message Ar string
.\" Print the given message to stdout.
.\" .El
.\"
.\" TODO: Command arguments which have embedded spaces may be quoted with
.\" quote
.\" .Sq \&"
.\" marks.
.Pp
.Pp command-line editing?
.Pp
.Sh EXAMPLES
The following are some
.Nm
examples:
.Bl -tag -width abcde
.It Ic "config help"
Show the commands for the
.Em config
module.
.It Ic "config go ParkingLot/"
Go to the
.Dq ParkingLot/
configuration location.
.It Ic "ParkingLot print_message help"
Show the one-line description and parameter for the
.Dq print_message
command available from the external
.Dq ParkingLot
module.
.\" TODO: why the trailing slash?
.El
.Sh SEE ALSO
.Xr boss 8 ,
.Xr msgq 8
.\" TODO: write boss and msgq manual pages
.\" .Sh STANDARDS
.Sh HISTORY
The initial version (with internal name of
.Dq BigTool )
was started in October 2009.
.Sh AUTHORS
\fBBoss\fR,
\fBXfrin\fR, and
\fBAuth\fR\&.
.SH "SEE ALSO"
.PP
\fBb10-auth\fR(8),
\fBb10-cfgmgr\fR(8),
\fBb10-cmdctl\fR(8),
\fBb10-xfrin\fR(8),
\fBbind10\fR(8),
\fBmsgq\fR(8),
BIND 10 User Guide\&.
.SH "AUTHORS"
.PP
The
.Nm
tool and library were initially coded by Zhang Likun of CNNIC
for the BIND 10 project.
The initial manual page was written by Jeremy C. Reed of ISC.
.\" .Sh BUGS
\fBbindctl\fR
tool and library were initially coded by Zhang Likun of CNNIC for the BIND 10 project\&. The initial manual page was written by Jeremy C\&. Reed of ISC\&.
.SH "HISTORY"
.PP
The initial version (with internal name of
\fBBigTool\fR) was started in October 2009\&.
.SH "COPYRIGHT"
.br
Copyright \(co 2010 Internet Systems Consortium, Inc. ("ISC")
.br
......@@ -7,6 +7,12 @@ CLEANFILES = b10-cfgmgr
b10_cfgmgrdir = @localstatedir@/@PACKAGE@
#B10_cfgmgr_DATA =
man_MANS = b10-cfgmgr.8
EXTRA_DIST = $(man_MANS) b10-cfgmgr.xml
b10-cfgmgr.8: b10-cfgmgr.xml
xsltproc --novalid --xinclude --nonet -o $@ http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $(srcdir)/b10-cfgmgr.xml
# TODO: does this need $$(DESTDIR) also?
# this is done here since configure.ac AC_OUTPUT doesn't expand exec_prefix
b10-cfgmgr: b10-cfgmgr.py
......
'\" t
.\" Title: b10-cfgmgr
.\" Author: [FIXME: author] [see http://docbook.sf.net/el/author]
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
.\" Date: March 10, 2010
.\" Manual: BIND10
.\" Source: BIND10
.\" Language: English
.\"
.TH "B10\-CFGMGR" "8" "March 10, 2010" "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-cfgmgr \- Configuration manager
.SH "DESCRIPTION"
.PP
The
\fBb10\-cfgmgr\fR
daemon handles all BIND 10 system configuration\&. It provides persistent storage for configuration, and notifies running BIND 10 modules of configuration changes\&.
.PP
The
\fBbindctl\fR
can be used to talk to this configuration manager via a
\fBb10\-cmdctl\fR
connection\&.
.PP
This daemon communicates over a
\fBmsgq\fR
C\-Channel connection\&. If this connection is not established,
\fBb10\-cfgmgr\fR
will exit\&.
.PP
The daemon may be cleanly stopped by sending the SIGTERM signal to the process\&. This shutdown does not notify the subscribers\&.
.PP
When it exits, it saves its current configuration to /var/bind10/b10\-config\&.db
.PP
The daemon has no command line options\&. It ignores any arguments\&.
.SH "FILES"
.PP
/var/bind10/b10\-config\&.db
\(em Configuration storage file\&.
.SH "SEE ALSO"
.PP
\fBbind10\fR(8),
\fBmsgq\fR(8)\&.
.SH "HISTORY"
.PP
The
\fBb10\-cfgmgr\fR
daemon and configuration specification were initially designed by Jelte Jansen of ISC\&. Its development began in October 2009\&.
.SH "COPYRIGHT"
.br
Copyright \(co 2010 Internet Systems Consortium, Inc. ("ISC")
.br
......@@ -16,6 +16,12 @@ EXTRA_DIST += cmdctl.spec
CLEANFILES= b10-cmdctl
man_MANS = b10-cmdctl.8
EXTRA_DIST += $(man_MANS) b10-cmdctl.xml
b10-cmdctl.8: b10-cmdctl.xml
xsltproc --novalid --xinclude --nonet -o $@ http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $(srcdir)/b10-cmdctl.xml
# TODO: does this need $$(DESTDIR) also?
# this is done here since configure.ac AC_OUTPUT doesn't expand exec_prefix
b10-cmdctl: cmdctl.py
......
'\" t
.\" Title: b10-cmdctl
.\" Author: [see the "AUTHORS" section]
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
.\" Date: March 9, 2010
.\" Manual: BIND10
.\" Source: BIND10
.\" Language: English
.\"
.TH "B10\-CMDCTL" "8" "March 9, 2010" "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-cmdctl \- BIND 10 remote control daemon
.SH "SYNOPSIS"
.HP \w'\fBb10\-cmdctl\fR\ 'u
\fBb10\-cmdctl\fR [\fB\-a\ \fR\fB\fIstring\fR\fR] [\fB\-h\fR] [\fB\-i\ \fR\fB\fInumber\fR\fR] [\fB\-p\ \fR\fB\fInumber\fR\fR] [\fB\-v\fR] [\fB\-\-address\ \fR\fB\fIstring\fR\fR] [\fB\-\-help\fR] [\fB\-\-idle\-timeout\ \fR\fB\fInumber\fR\fR] [\fB\-\-port\ \fR\fB\fInumber\fR\fR] [\fB\-\-verbose\fR] [\fB\-\-version\fR]
.SH "DESCRIPTION"
.PP
The
\fBb10\-cmdctl\fR
daemon provides an entry for commands sent to the BIND 10 services\&. For example, the
\fBbindctl\fR
user interface communicates via
\fBb10\-cmdctl\fR\&.
.PP
It is a lightweight HTTPS server with HTTP Digest Authentication (username and password validation)\&. It offers a RESTful style interface\&.
.SH "OPTIONS"