BIND 10 trac963, updated. b91bb9719ff759417ce8f6412ca5f8be57a2e19c [963] fix type in b10-dbutil manpage source
BIND 10 source code commits
bind10-changes at lists.isc.org
Fri Mar 23 12:53:43 UTC 2012
The branch, trac963 has been updated
via b91bb9719ff759417ce8f6412ca5f8be57a2e19c (commit)
via 2c0a8fc3bfa0fb8f5f6cb2df504b326741996025 (commit)
via b204a39d5b9003f991104c2bd6896013f19a05d0 (commit)
via 0f487a998063a01ea16e8be048076f53b11afd02 (commit)
from d85eda60ea4f2304859ff935f998585dae2f4854 (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
commit b91bb9719ff759417ce8f6412ca5f8be57a2e19c
Author: Jelte Jansen <jelte at isc.org>
Date: Fri Mar 23 13:53:10 2012 +0100
[963] fix type in b10-dbutil manpage source
commit 2c0a8fc3bfa0fb8f5f6cb2df504b326741996025
Author: Jelte Jansen <jelte at isc.org>
Date: Fri Mar 23 12:19:59 2012 +0100
[963] improve exit status
0 on success (or upgrade aborted by user)
1 on check and need update
2 on check and version of db too high
3 on command-line error
4 on db read error
5 on upgrade error
commit b204a39d5b9003f991104c2bd6896013f19a05d0
Author: Jelte Jansen <jelte at isc.org>
Date: Fri Mar 23 11:37:44 2012 +0100
[963] fix run_dbutil.sh script to not change cwd
with this change, you can pass run_dbutil.sh a relative path name for the db file
commit 0f487a998063a01ea16e8be048076f53b11afd02
Author: Jelte Jansen <jelte at isc.org>
Date: Fri Mar 23 11:29:09 2012 +0100
[963] fix b10-dbutil.8 creation rule add it to git
-----------------------------------------------------------------------
Summary of changes:
src/bin/dbutil/Makefile.am | 2 +-
src/bin/dbutil/b10-dbutil.8 | 87 ++++++++++++++++++++++++++++++++
src/bin/dbutil/b10-dbutil.xml | 10 +++-
src/bin/dbutil/dbutil.py.in | 40 ++++++++++----
src/bin/dbutil/run_dbutil.sh.in | 3 +-
src/bin/dbutil/tests/dbutil_test.sh.in | 4 +-
src/bin/xfrout/b10-xfrout.8 | 29 +++-------
7 files changed, 135 insertions(+), 40 deletions(-)
create mode 100644 src/bin/dbutil/b10-dbutil.8
-----------------------------------------------------------------------
diff --git a/src/bin/dbutil/Makefile.am b/src/bin/dbutil/Makefile.am
index 1ede4d6..5c05757 100644
--- a/src/bin/dbutil/Makefile.am
+++ b/src/bin/dbutil/Makefile.am
@@ -12,7 +12,7 @@ CLEANFILES = b10-dbutil b10-dbutil.pyc
if ENABLE_MAN
b10-dbutil.8: b10-dbutil.xml
- xsltproc --novalid --xinclude --nonet -o $@ http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $(srcdir)/bindctl.xml
+ xsltproc --novalid --xinclude --nonet -o $@ http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $(srcdir)/b10-dbutil.xml
endif
diff --git a/src/bin/dbutil/b10-dbutil.8 b/src/bin/dbutil/b10-dbutil.8
new file mode 100644
index 0000000..4fce304
--- /dev/null
+++ b/src/bin/dbutil/b10-dbutil.8
@@ -0,0 +1,87 @@
+'\" t
+.\" Title: b10-dbutil
+.\" Author: [FIXME: author] [see http://docbook.sf.net/el/author]
+.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
+.\" Date: March 20, 2012
+.\" Manual: BIND10
+.\" Source: BIND10
+.\" Language: English
+.\"
+.TH "B10\-DBUTIL" "8" "March 20, 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"
+b10-dbutil \- Zone Database Maintenance Utility
+.SH "SYNOPSIS"
+.HP \w'\fBb10\-dbutil\ \-\-check\fR\ 'u
+\fBb10\-dbutil \-\-check\fR [\-\-verbose] [\fIdbfile\fR]
+.HP \w'\fBb10\-dbutil\ \-\-upgrade\fR\ 'u
+\fBb10\-dbutil \-\-upgrade\fR [\-\-noconfirm] [\-\-verbose] [\fIdbfile\fR]
+.SH "DESCRIPTION"
+.PP
+The
+\fBb10\-dbutil\fR
+utility is a general administration utility for SQL databases\&. (Currently only SQLite is supported by BIND 10\&.) It can report the current verion of the schema, and upgrade an existing database to the latest version of the schema\&.
+.PP
+
+\fBb10\-dbutil\fR
+operates in one of two modes, check mode or upgrade mode\&.
+.PP
+In check mode (\fBb10\-dbutil \-\-check\fR), the utility reads the version of the database schema from the database and prints it\&. It will tell you whether the schema is at the latest version supported by BIND 10\&. Exit status is 0 if the schema is at the correct version, 1 if the schema is at an older version, 2 if the schema is at a version not yet supported by this version of b10\-dbutil\&. Any higher value indicates a read or command\-line error\&.
+.PP
+When the upgrade function is selected (\fBb10\-dbutil \-\-upgrade\fR), the utility takes a copy of the database, then upgrades it to the latest version of the schema\&. The contents of the database remain intact\&. (The backup file is a file in the same directory as the database file\&. It has the same name, with "\&.backup" appended to it\&. If a file of that name already exists, the file will have the suffix "\&.backup\-1"\&. If that exists, the file will be suffixed "\&.backup\-2", and so on)\&. Exit status is 0 if the upgrade is either succesful or aborted by the user, and non\-zero if there is an error\&.
+.PP
+When upgrading the database, it is
+\fIstrongly\fR
+recommended that BIND 10 not be running while the upgrade is in progress\&.
+.SH "ARGUMENTS"
+.PP
+The arguments are as follows:
+.PP
+\fB\-\-check\fR
+.RS 4
+Selects the version check function, which reports the current version of the database\&. This is incompatible with the \-\-upgrade option\&.
+.RE
+.PP
+\fB\-\-noconfirm\fR
+.RS 4
+Only valid with \-\-upgrade, this disables the prompt\&. Normally the utility will print a warning that an upgrade is about to take place and request that you type "Yes" to continue\&. If this switch is given on the command line, no prompt will be issued: the utility will just perform the upgrade\&.
+.RE
+.PP
+\fB\-\-upgrade\fR
+.RS 4
+Selects the upgrade function, which upgrades the database to the latest version of the schema\&. This is incompatible with the \-\-upgrade option\&.
+.sp
+The upgrade function will upgrade a BIND 10 database \- no matter how old the schema \- preserving all data\&. A backup file is created before the upgrade (with the same name as the database, but with "\&.backup" suffixed to it)\&. If the upgrade fails, this file can be copied back to restore the original database\&.
+.RE
+.PP
+\fB\-\-verbose\fR
+.RS 4
+Enable verbose mode\&. Each SQL command issued by the utility will be printed to before it is executed\&.
+.RE
+.PP
+\fB\fIdbfile\fR\fR
+.RS 4
+Name of the database file to check of upgrade\&.
+.RE
+.SH "COPYRIGHT"
+.br
+Copyright \(co 2012 Internet Systems Consortium, Inc. ("ISC")
+.br
diff --git a/src/bin/dbutil/b10-dbutil.xml b/src/bin/dbutil/b10-dbutil.xml
index 8d7a589..8178ac8 100644
--- a/src/bin/dbutil/b10-dbutil.xml
+++ b/src/bin/dbutil/b10-dbutil.xml
@@ -73,7 +73,10 @@
In check mode (<command>b10-dbutil --check</command>), the
utility reads the version of the database schema from the database
and prints it. It will tell you whether the schema is at the latest
- version supported by BIND 10.
+ version supported by BIND 10. Exit status is 0 if the schema is at
+ the correct version, 1 if the schema is at an older version, 2 if
+ the schema is at a version not yet supported by this version of
+ b10-dbutil. Any higher value indicates a read or command-line error.
</para>
<para>
@@ -85,7 +88,8 @@
file. It has the same name, with ".backup" appended to it. If a
file of that name already exists, the file will have the suffix
".backup-1". If that exists, the file will be suffixed ".backup-2",
- and so on.)
+ and so on). Exit status is 0 if the upgrade is either succesful or
+ aborted by the user, and non-zero if there is an error.
</para>
<para>
@@ -153,7 +157,7 @@
</term>
<listitem>
<para>Enable verbose mode. Each SQL command issued by the
- utility will be printed to before it is executed.</para>
+ utility will be printed to stdout before it is executed.</para>
</listitem>
</varlistentry>
diff --git a/src/bin/dbutil/dbutil.py.in b/src/bin/dbutil/dbutil.py.in
index a6e70a6..215fe31 100755
--- a/src/bin/dbutil/dbutil.py.in
+++ b/src/bin/dbutil/dbutil.py.in
@@ -47,6 +47,15 @@ isc.util.process.rename()
# configure.ac)
VERSION = "b10-dbutil 20120319 (BIND 10 @PACKAGE_VERSION@)"
+# Exit codes
+EXIT_SUCCESS = 0
+EXIT_NEED_UPDATE = 1
+EXIT_VERSION_TOO_HIGH = 2
+EXIT_COMMAND_ERROR = 3
+EXIT_READ_ERROR = 4
+EXIT_UPGRADE_ERROR = 5
+
+
# @brief Statements to Update the Database
# These are in the form of a list of dictionaries, each of which contains the
# information to perform an incremental upgrade from one version of the
@@ -445,6 +454,12 @@ def check_version(db):
an upgrade is needed.
@param db Database object
+
+ returns 0 if the database is up to date
+ returns EXIT_NEED_UPDATE if the database needs updating
+ returns EXIT_VERSION_TOO_HIGH if the database is at a later version
+ than this program knows about
+ These return values are intended to be passed on to sys.exit.
"""
current = get_version(db)
latest = get_latest_version()
@@ -454,18 +469,18 @@ def check_version(db):
info("database version " + version_string(current))
info("this is the latest version of the database schema, " +
"no upgrade is required")
-
+ return EXIT_SUCCESS
elif match < 0:
info("database version " + version_string(current) +
", latest version is " + version_string(latest))
info("re-run this program with the --upgrade switch to upgrade")
-
+ return EXIT_NEED_UPDATE
else:
warn("database is at a later version (" + version_string(current) +
") than this program can cope with (" +
version_string(get_latest_version()) + ")")
info("please get the latest version of b10-dbutil and re-run")
-
+ return EXIT_VERSION_TOO_HIGH
def perform_upgrade(db, upgrade):
"""
@@ -554,11 +569,11 @@ def parse_command():
if (len(args) > 1):
error("too many arguments to the command, maximum of one expected")
parser.print_usage()
- sys.exit(1)
+ sys.exit(EXIT_COMMAND_ERROR)
elif len(args) == 0:
error("must supply name of the database file to upgrade")
parser.print_usage()
- sys.exit(1)
+ sys.exit(EXIT_COMMAND_ERROR)
# Check for conflicting options. If some are found, output a suitable
# error message and print the usage.
@@ -573,22 +588,23 @@ def parse_command():
# Only get here on conflicting options
parser.print_usage()
- sys.exit(1)
+ sys.exit(EXIT_COMMAND_ERROR)
if __name__ == "__main__":
(options, args) = parse_command()
db = Database(args[0], options.verbose)
+ exit_code = EXIT_SUCCESS
if options.check:
# Check database - open, report, and close
try:
db.open()
- check_version(db)
+ exit_code = check_version(db)
db.close()
except Exception as ex:
error("unable to check database version - " + str(ex))
- sys.exit(1)
+ exit_code = EXIT_READ_ERROR
elif options.upgrade:
# Upgrade. Check if this is what they really want to do
@@ -596,7 +612,7 @@ if __name__ == "__main__":
proceed = prompt_user()
if not proceed:
info("upgrade abandoned - database has not been changed\n")
- sys.exit(0)
+ sys.exit(EXIT_SUCCESS)
# It is. Do a backup then do the upgrade.
in_progress = False
@@ -613,9 +629,9 @@ if __name__ == "__main__":
else:
error("upgrade preparation failed - " + str(ex))
info("database upgrade was not attempted")
- sys.exit(1)
+ exit_code = EXIT_UPGRADE_ERROR
else:
error("internal error, neither --check nor --upgrade selected")
- sys.exit(1)
+ exit_code = EXIT_COMMAND_ERROR
- sys.exit(0)
+ sys.exit(exit_code)
diff --git a/src/bin/dbutil/run_dbutil.sh.in b/src/bin/dbutil/run_dbutil.sh.in
index eaf4b0e..fea7482 100755
--- a/src/bin/dbutil/run_dbutil.sh.in
+++ b/src/bin/dbutil/run_dbutil.sh.in
@@ -37,5 +37,4 @@ export B10_FROM_SOURCE
BIND10_MSGQ_SOCKET_FILE=@abs_top_builddir@/msgq_socket
export BIND10_MSGQ_SOCKET_FILE
-cd ${DBUTIL_PATH}
-exec ${PYTHON_EXEC} -O b10-dbutil "$@"
+exec ${PYTHON_EXEC} -O ${DBUTIL_PATH}/b10-dbutil "$@"
diff --git a/src/bin/dbutil/tests/dbutil_test.sh.in b/src/bin/dbutil/tests/dbutil_test.sh.in
index 26b577c..7e13949 100755
--- a/src/bin/dbutil/tests/dbutil_test.sh.in
+++ b/src/bin/dbutil/tests/dbutil_test.sh.in
@@ -269,9 +269,9 @@ record_count_test() {
check_version() {
copy_file $1 $verfile
../run_dbutil.sh --check $verfile
- if [ $? -ne 0 ]
+ if [ $? -gt 2 ]
then
- fail "version check failed on database $1"
+ fail "version check failed on database $1; return code $?"
else
../run_dbutil.sh --check $verfile | grep "$2" > /dev/null
if [ $? -ne 0 ]
diff --git a/src/bin/xfrout/b10-xfrout.8 b/src/bin/xfrout/b10-xfrout.8
index 3670ec5..69682a3 100644
--- a/src/bin/xfrout/b10-xfrout.8
+++ b/src/bin/xfrout/b10-xfrout.8
@@ -9,6 +9,15 @@
.\"
.TH "B10\-XFROUT" "8" "February 28\&. 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
@@ -82,26 +91,6 @@ A list of JSON objects (i\&.e\&. maps) that define per zone configuration concer
\fBb10\-xfrout\fR\&. The supported names of each object are "origin" (the origin name of the zone), "class" (the RR class of the zone, optional, default to "IN"), and "transfer_acl" (ACL only applicable to transfer requests for that zone)\&. See the
BIND 10 Guide
for configuration examples\&. The default is an empty list, that is, no zone specific configuration\&.
-.PP
-
-\fIlog_name\fR
-.PP
-
-\fIlog_file\fR
-The location of the log file if using a file channel\&. If undefined, then the file channel is closed\&. The default is
-/usr/local/var/bind10\-devel/log/Xfrout\&.log\&.
-.PP
-
-\fIlog_severity\fR
-The default is "debug"\&.
-.PP
-
-\fIlog_versions\fR
-The default is 5\&.
-.PP
-
-\fIlog_max_bytes\fR
-The default is 1048576\&.
.if n \{\
.sp
.\}
More information about the bind10-changes
mailing list