Add tool for validating XML & fix misc bugs in virsh POD docs

.hgignore

@@ -46,12 +46,19 @@ docs/examples/info1
 docs/examples/python/Makefile
 docs/examples/python/Makefile.in
 docs/examples/suspend
+docs/schemas/Makefile
+docs/schemas/Makefile.in
 examples/domain-events/events-c/*.exe
 examples/domain-events/events-c/.deps
 examples/domain-events/events-c/.libs
 examples/domain-events/events-c/Makefile
 examples/domain-events/events-c/Makefile.in
 examples/domain-events/events-c/event-test
+examples/hellolibvirt/.deps
+examples/hellolibvirt/.libs
+examples/hellolibvirt/Makefile
+examples/hellolibvirt/Makefile.in
+examples/hellolibvirt/hellolibvirt
 gnulib/lib/*.la
 gnulib/lib/*.lo
 gnulib/lib/.deps
@@ -260,6 +267,7 @@ tests/qemuxml2argvtest
 tests/qemuxml2xmltest
 tests/qparamtest
 tests/reconnect
+tests/seclabeltest
 tests/sexpr2xmldata/Makefile
 tests/sexpr2xmldata/Makefile.in
 tests/sexpr2xmltest
@@ -274,4 +282,8 @@ tests/xmconfigtest
 tests/xml2sexprdata/Makefile
 tests/xml2sexprdata/Makefile.in
 tests/xml2sexprtest
+tools/Makefile
+tools/Makefile.in
+tools/virt-xml-validate
+tools/virt-xml-validate.1
 update.log

ChangeLog

+Sun Apr 19 16:00:22 BST 2009 Daniel P. Berrange <berrange@redhat.com>
+
+	Add command line tool for validating XML and improve POD docs
+	for virsh
+	* Makefile.am, configure.in: Add tools/ sub-directory
+	* docs/virsh.pod, docs/Makefile.am, virsh.1: Fix misc errors
+	in POD formating, and improve licensing/copyright/bugs section
+	* libvirt.spec.in: Add virt-xml-validate tool & man page
+	* tools/virt-xml-validate.in, tools/Makefile.am: Add tool for
+	validating XML files against schemas
+	* .hgignore, tools/.gitignore, tools/.cvsignore, m4/.gitignore:
+	Update to ignore more generated files
+
 Sun Apr 19 15:44:22 BST 2009 Daniel P. Berrange <berrange@redhat.com>
 
 	* src/qemu_conf.c, src/qemu_conf.h: Pass in virDomainDefPtr to
@@ -40,7 +53,7 @@ Thu Apr 16 17:48:30 CEST 2009 Guido Günther <agx@sigxcpu.org>
 Thu Apr 16 16:48:51 CEST 2009 Guido Günther <agx@sigxcpu.org>
 
 	* src/qemud.c (remoteReadConfigFile): don't hardcode buffer for
-	  getgrnam_r to 1024 bytes and increase it on ERANGE. 
+	  getgrnam_r to 1024 bytes and increase it on ERANGE.
 
 Thu Apr 16 15:20:02 GMT 2009 Mark McLoughlin <markmc@redhat.com>
 

Makefile.am

@@ -3,7 +3,7 @@
 LCOV = lcov
 GENHTML = genhtml
 
-SUBDIRS = gnulib/lib include src qemud proxy docs gnulib/tests \
+SUBDIRS = gnulib/lib include src qemud tools proxy docs gnulib/tests \
   python tests po examples/domain-events/events-c examples/hellolibvirt
 
 ACLOCAL_AMFLAGS = -I m4 -I gnulib/m4

docs/Makefile.am

@@ -72,7 +72,7 @@ EXTRA_DIST=					\
 all: web $(top_builddir)/NEWS $(man_MANS)
 
 virsh.1: virsh.pod
-	pod2man -c "Virtualization Support" $(srcdir)/virsh.pod > $@-t
+	pod2man -c "Virtualization Support" -r "$(PACKAGE)-$(VERSION)" $(srcdir)/virsh.pod > $@-t
 	mv $@-t $@
 	cp $@ $(top_builddir)
 

docs/virsh.pod

@@ -150,13 +150,13 @@ B<virsh> list
 Name is the name of the domain.  ID the domain numeric id.
 State is the run state (see below).
 
-=over 4
-
 B<STATES>
 
 The State field lists 6 states for a domain, and which ones the
 current domain is in.
 
+=over 4
+
 =item B<running>
 
 The domain is currently running on a CPU
@@ -198,12 +198,16 @@ crashed.
 Prints the available amount of memory on the machine or within a
 NUMA cell if I<cellno> is provided.
 
+=back
+
 =head1 DOMAIN COMMANDS
 
 The following commands manipulate domains directly, as stated
 previously most commands take domain-id as the first parameter. The
 I<domain-id> can be specified as an short integer, a name or a full UUID.
 
+=over 4
+
 =item B<autostart> optional I<--disable> I<domain-id>
 
 Configure a domain to be automatically started at boot.
@@ -401,7 +405,9 @@ and I<cpulist> is a comma separated list of physical CPU numbers.
 Output the IP address and port number for the VNC display. If the information
 is not available the processes will provide an exit code of 1.
 
-=head1 DEVICES COMMANDS
+=back
+
+=head1 DEVICE COMMANDS
 
 The following commands manipulate devices associated to domains.
 The domain-id can be specified as an short integer, a name or a full UUID.
@@ -409,6 +415,8 @@ To better understand the values allowed as options for the command
 reading the documentation at L<http://libvirt.org/format.html> on the
 format of the device sections to get the most accurate set of accepted values.
 
+=over 4
+
 =item B<attach-device> I<domain-id> I<FILE>
 
 Attach a device to the domain, using a device definition in an XML file.
@@ -449,7 +457,9 @@ I<type> can be either I<network> to indicate a physical network device or I<brid
 It is recommended to use the I<mac> option to distinguish between the interfaces
 if more than one are present on the domain.
 
-=head1 VIRTUAL NETWORKS COMMANDS
+=back
+
+=head1 VIRTUAL NETWORK COMMANDS
 
 The following commands manipulate networks. Libvirt has the capability to
 define virtual networks which can then be used by domains and linked to
@@ -458,6 +468,8 @@ see the documentation at L<http://libvirt.org/format.html#Net1> . A lot
 of the command for virtual networks are similar to the one used for domains,
 but the way to name a virtual network is either by its name or UUID.
 
+=over 4
+
 =item B<net-autostart> I<network> optional I<--disable>
 
 Configure a virtual network to be automatically started at boot.
@@ -517,18 +529,55 @@ Undefine the configuration for an inactive network.
 
 Convert a network name to network UUID.
 
+=back
+
 =head1 ENVIRONMENT
 
+The following environment variables can be set to alter the behaviour
+of C<virsh>
+
+=over 4
+
 =item VIRSH_DEFAULT_CONNECT_URI
 
 The hypervisor to connect to by default. Set this to a URI, in the same
 format as accepted by the B<connect> option.
 
-=head1 SEE ALSO
+=item LIBVIRT_DEBUG=LEVEL
 
-L<virt-install(1)>, L<xm(1)>, L<virt-top(1)>, L<virt-mem(1)>, L<virt-df(1)>, L<http://www.libvirt.org/>
+Turn on verbose debugging of all libvirt API calls. Valid levels are
 
-=head1 AUTHOR
+=over 4
+
+=item * LIBVIRT_DEBUG=1
+
+Messages at level DEBUG or above
+
+=item * LIBVIRT_DEBUG=2
+
+Messages at level INFO or above
+
+=item * LIBVIRT_DEBUG=3
+
+Messages at level WARNING or above
+
+=item * LIBVIRT_DEBUG=4
+
+Messages at level ERROR or above
+
+=back
+
+For further information about debugging options consult C<http://libvirt.org/logging.html>
+
+=back
+
+=head1 BUGS
+
+Report any bugs discovered to the libvirt community via the mailing
+list C<http://libvirt.org/contact.html> or bug tracker C<http://libvirt.org/bugs.html>.
+Alternatively report bugs to your software distributor / vendor.
+
+=head1 AUTHORS
 
   Andrew Puch <apuch @ redhat.com>
   Daniel Veillard <veillard @ redhat.com>
@@ -537,12 +586,19 @@ L<virt-install(1)>, L<xm(1)>, L<virt-top(1)>, L<virt-mem(1)>, L<virt-df(1)>, L<h
   Sean Dague <sean at dague dot net>
   Daniel Stekloff <dsteklof at us dot ibm dot com>
 
+=head1 COPYRIGHT
 
-=head1 BUGS
+Copyright (C) 2005, 2007-2009 Red Hat, Inc.
+
+=head1 LICENSE
 
-Bugs can be filed in Red Hat bugzilla under the Virtualization Tools/libvirt
-L<https://bugzilla.redhat.com/>
+virsh is distributed under the terms of the GNU LGPL v2+.
+This is free software; see the source for copying conditions. There
+is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
+PURPOSE
+
+=head1 SEE ALSO
 
-L<https://bugzilla.redhat.com/buglist.cgi?product=Virtualization+Tools&component=libvirt&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED>
+L<virt-install(1)>, L<virt-xml-validate(1)>, L<virt-top(1)>, L<virt-mem(1)>, L<virt-df(1)>, L<http://www.libvirt.org/>
 
-=end
+=cut

libvirt.spec.in

@@ -373,8 +373,10 @@ fi
 %defattr(-, root, root)
 
 %doc AUTHORS ChangeLog NEWS README COPYING.LIB TODO
-%doc %{_mandir}/man1/virsh.1*
+%{_mandir}/man1/virsh.1*
+%{_mandir}/man1/virt-xml-validate.1*
 %{_bindir}/virsh
+%{_bindir}/virt-xml-validate
 %{_libdir}/lib*.so.*
 %dir %attr(0700, root, root) %{_sysconfdir}/libvirt/
 

tools/.cvsignore

+virt-xml-validate
+virt-xml-validate.1
+Makefile
+Makefile.in

tools/.gitignore

+virt-xml-validate
+virt-xml-validate.1
+Makefile
+Makefile.in

tools/Makefile.am

+
+bin_SCRIPTS = \
+	virt-xml-validate
+
+virt-xml-validate: virt-xml-validate.in Makefile
+	sed -e 's,@SCHEMADIR@,$(pkgdatadir)/schemas,' < $< > $@ || (rm $@ && exit 1)
+	chmod +x $@
+
+man1_MANS = virt-xml-validate.1
+
+EXTRA_DIST = virt-xml-validate.in
+
+CLEANFILES = $(bin_SCRIPTS) $(man1_MANS)
+
+%.1: %
+	pod2man -c "Virtualization Support" -r "$(PACKAGE)-$(VERSION)" $< $@

tools/virt-xml-validate.in

+#!/bin/sh
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+
+
+set -e
+
+XMLFILE=$1
+TYPE=$2
+
+if [ -z "$XMLFILE" ]; then
+  echo "syntax: $0 XMLFILE [TYPE]"
+  exit 1
+fi
+
+if [ ! -f "$XMLFILE" ]; then
+  echo "$0: document $XMLFILE does not exist"
+  exit 2
+fi
+
+if [ -z "$TYPE" ]; then
+  ROOT=`xmllint --stream --debug $XMLFILE 2>/dev/null | grep "^0 1 " | awk '{ print $3 }'`
+  case $ROOT in
+     *domain*)
+        TYPE="domain"
+        ;;
+     *network*)
+        TYPE="network"
+        ;;
+     *pool*)
+        TYPE="storagepool"
+        ;;
+     *volume*)
+        TYPE="storagevol"
+        ;;
+     *capabilities*)
+        TYPE="capability"
+        ;;
+     *device*)
+        TYPE="nodedev"
+        ;;
+     *)
+       echo "$0: cannot determine schema type for $XMLFILE"
+       exit 3
+  esac
+fi
+
+SCHEMA="@SCHEMADIR@/${TYPE}.rng"
+
+if [ ! -f "$SCHEMA" ]; then
+  echo "$0: schema $SCHEMA does not exist"
+  exit 4
+fi
+
+xmllint --noout --relaxng $SCHEMA $XMLFILE
+
+exit 0
+
+: <<=cut
+=pod
+
+=head1 NAME
+
+  virt-xml-validate - validate libvirt XML files against a schema
+
+=head1 SYNOPSIS
+
+  virt-xml-validate XML-FILE [SCHEMA-NAME]
+
+=head1 DESCRIPTION
+
+Validates a libvirt XML for compliance with the published schema.
+The first compulsory argument is the path to the XML file to be
+validated. The optional second argument is the name of the schema
+to validate against. If omitted, the schema name will be inferred
+from the name of the root element in the XML document.
+
+Valid schema names currently include
+
+=over 4
+
+=item C<domain>
+
+The schema for the XML format used by guest domains configuration
+
+=item C<network>
+
+The schema for the XML format used by virtual network configuration
+
+=item C<storagepool>
+
+The schema for the XML format used by storage pool configuration
+
+=item C<storagevol>
+
+The schema for the XML format used by storage volume descriptions
+
+=item C<nodedev>
+
+The schema for the XML format used by node device descriptions
+
+=item C<capability>
+
+The schema for the XML format used to declare driver capabilities
+
+=back
+
+=head1 EXIT STATUS
+
+Upon successful validation, an exit status of 0 will be set. Upon
+failure a non-zero status will be set.
+
+=head1 AUTHOR
+
+Daniel P.Berrange
+
+=head1 BUGS
+
+Report any bugs discovered to the libvirt community via the
+mailing list C<http://libvirt.org/contact.html> or bug tracker C<http://libvirt.org/bugs.html>.
+Alternatively report bugs to your software distributor / vendor.
+
+=head1 COPYRIGHT
+
+Copyright 2009 by Red Hat, Inc
+Copyright 2009 by Daniel P. Berrange
+
+=head1 LICENSE
+
+virt-xml-validate is distributed under the terms of the GNU GPL v2+.
+This is free software; see the source for copying conditions. There
+is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
+PURPOSE
+
+=head1 SEE ALSO
+
+C<virsh(1)>, online XML format descriptions C<http://libvirt.org/format.html>
+
+=cut

virsh.1

-.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
+.\" Automatically generated by Pod::Man 2.16 (Pod::Simple 3.07)
 .\"
 .\" Standard preamble:
 .\" ========================================================================
@@ -25,11 +25,11 @@
 ..
 .\" Set up some character translations and predefined strings.  \*(-- will
 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
-.\" double quote, and \*(R" will give a right double quote.  | will give a
-.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
-.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
-.\" expand to `' in nroff, nothing in troff, for use with C<>.
-.tr \(*W-|\(bv\*(Tr
+.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
+.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
+.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
+.\" nothing in troff, for use with C<>.
+.tr \(*W-
 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
 .ie n \{\
 .    ds -- \(*W-
@@ -48,22 +48,25 @@
 .    ds R" ''
 'br\}
 .\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
 .\" If the F register is turned on, we'll generate index entries on stderr for
 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
 .\" entries marked with X<> in POD.  Of course, you'll have to process the
 .\" output yourself in some meaningful fashion.
-.if \nF \{\
+.ie \nF \{\
 .    de IX
 .    tm Index:\\$1\t\\n%\t"\\$2"
 ..
 .    nr % 0
 .    rr F
 .\}
-.\"
-.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
-.\" way too many mistakes in technical documents.
-.hy 0
-.if n .na
+.el \{\
+.    de IX
+..
+.\}
 .\"
 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
@@ -129,7 +132,11 @@
 .\" ========================================================================
 .\"
 .IX Title "VIRSH 1"
-.TH VIRSH 1 "2008-04-15" "perl v5.8.8" "Virtualization Support"
+.TH VIRSH 1 "2009-04-16" "libvirt-0.6.2" "Virtualization Support"
+.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
 .SH "NAME"
 virsh \- management user interface
 .SH "SYNOPSIS"
@@ -144,7 +151,7 @@ domains. It can also be used to list current domains. Libvirt is a C toolkit to
 The basic structure of most virsh usage is:
 .PP
 .Vb 1
-\&  virsh <command> <domain-id> [OPTIONS]
+\&  virsh <command> <domain\-id> [OPTIONS]
 .Ve
 .PP
 Where \fIcommand\fR is one of the commands listed below, \fIdomain-id\fR
@@ -222,7 +229,7 @@ this is used to connect to the local Xen hypervisor, this is the default
 allow to connect locally as root to the daemon supervising QEmu and \s-1KVM\s0 domains
 .IP "qemu:///session" 4
 .IX Item "qemu:///session"
-allow to connect locally as a normal user to the his own set of QEmu and \s-1KVM\s0 domains
+allow to connect locally as a normal user to his own set of QEmu and \s-1KVM\s0 domains
 .RE
 .RS 4
 .Sp
@@ -261,54 +268,53 @@ An example format for the list is as follows:
 \&\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
 .Sp
 .Vb 2
-\&  0 Domain-0             running
+\&  0 Domain\-0             running
 \&  2 fedora               paused
 .Ve
 .Sp
 Name is the name of the domain.  \s-1ID\s0 the domain numeric id.
- State is the run state (see below).
-.IP "\fBfreecell\fR optional \fIcellno\fR" 4
-.IX Item "freecell optional cellno"
-Prints the available amount of memory on the machine or within a
-\&\s-1NUMA\s0 cell if \fIcellno\fR is provided.
-.RS 4
+State is the run state (see below).
 .Sp
-.RS 4
 \&\fB\s-1STATES\s0\fR
 .Sp
-The State field lists 6 states for a Xen Domain, and which ones the
-current Domain is in.
-.RE
-.IP "\fBr \- running\fR" 4
-.IX Item "r - running"
+The State field lists 6 states for a domain, and which ones the
+current domain is in.
+.RS 4
+.IP "\fBrunning\fR" 4
+.IX Item "running"
 The domain is currently running on a \s-1CPU\s0
-.IP "\fBb \- blocked\fR" 4
-.IX Item "b - blocked"
-The domain is blocked, and not running or runnable.  This can be caused
+.IP "\fBidle\fR" 4
+.IX Item "idle"
+The domain is idle, and not running or runnable.  This can be caused
 because the domain is waiting on \s-1IO\s0 (a traditional wait state) or has
 gone to sleep because there was nothing else for it to do.
-.IP "\fBp \- paused\fR" 4
-.IX Item "p - paused"
+.IP "\fBpaused\fR" 4
+.IX Item "paused"
 The domain has been paused, usually occurring through the administrator
-running \fBxm pause\fR.  When in a paused state the domain will still
+running \fBvirsh suspend\fR.  When in a paused state the domain will still
 consume allocated resources like memory, but will not be eligible for
-scheduling by the Xen hypervisor.
-.IP "\fBs \- shutdown\fR" 4
-.IX Item "s - shutdown"
+scheduling by the hypervisor.
+.IP "\fBshutdown\fR" 4
+.IX Item "shutdown"
 The domain is in the process of shutting down, i.e. the guest operating system
 has been notified and should be in the process of stopping its operations
 gracefully.
-.IP "\fBc \- crashed\fR" 4
-.IX Item "c - crashed"
+.IP "\fBcrashed\fR" 4
+.IX Item "crashed"
 The domain has crashed, which is always a violent ending.  Usually
 this state can only occur if the domain has been configured not to
-restart on crash.  See xmdomain.cfg for more info.
-.IP "\fBd \- dying\fR" 4
-.IX Item "d - dying"
+restart on crash.
+.IP "\fBdying\fR" 4
+.IX Item "dying"
 The domain is in process of dying, but hasn't completely shutdown or
 crashed.
 .RE
 .RS 4
+.RE
+.IP "\fBfreecell\fR optional \fIcellno\fR" 4
+.IX Item "freecell optional cellno"
+Prints the available amount of memory on the machine or within a
+\&\s-1NUMA\s0 cell if \fIcellno\fR is provided.
 .SH "DOMAIN COMMANDS"
 .IX Header "DOMAIN COMMANDS"
 The following commands manipulate domains directly, as stated
@@ -324,7 +330,7 @@ The option \fI\-\-disable\fR disable autostarting.
 Connect the virtual serial console for the guest.
 .IP "\fBcreate\fR \fI\s-1FILE\s0\fR" 4
 .IX Item "create FILE"
-Create a domain from an \s-1XML\s0 <file> an easy way to create one if you have a pre-existing xen guest created via \fBxm\fR create <\s-1XMLFILE\s0>.
+Create a domain from an \s-1XML\s0 <file>. An easy way to create the \s-1XML\s0 <file> is to use the \fBdumpxml\fR command to obtain the definition of a pre-existing guest.
 .Sp
 \&\fBExample\fR
 .Sp
@@ -335,7 +341,7 @@ Define a domain from an \s-1XML\s0 <file>. The domain definitions is registered
 but not started.
 .IP "\fBdestroy\fR \fIdomain-id\fR" 4
 .IX Item "destroy domain-id"
-Immediately terminate the domain domain\-id.  This doesn't give the domain
+Immediately terminate the domain domain-id.  This doesn't give the domain
 \&\s-1OS\s0 any chance to react, and it the equivalent of ripping the power
 cord out on a physical machine.  In most cases you will want to use
 the \fBshutdown\fR command instead.
@@ -369,6 +375,18 @@ Dumps the core of a domain to a file for analysis.
 .IP "\fBdumpxml\fR \fIdomain-id\fR" 4
 .IX Item "dumpxml domain-id"
 Output the domain information as an \s-1XML\s0 dump to stdout, this format can be used by the \fBcreate\fR command.
+.IP "\fBedit\fR \fIdomain-id\fR" 4
+.IX Item "edit domain-id"
+Edit the \s-1XML\s0 configuration file for a domain.
+.Sp
+This is equivalent to:
+ virsh dumpxml domain > domain.xml
+ edit domain.xml
+ virsh define domain.xml
+except that it does some error checking.
+.Sp
+The editor used can be supplied by the \f(CW$EDITOR\fR environment
+variable, or if that is not defined defaults to \f(CW\*(C`vi\*(C'\fR.
 .IP "\fBmigrate\fR optional \fI\-\-live\fR \fIdomain-id\fR \fIdesturi\fR \fImigrateuri\fR" 4
 .IX Item "migrate optional --live domain-id desturi migrateuri"
 Migrate domain to another host.  Add \-\-live for live migration. The \fIdesturi\fR
@@ -381,9 +399,8 @@ command run from the console.  The command returns as soon as it has
 executed the reboot action, which may be significantly before the
 domain actually reboots.
 .Sp
-For xen vm the behavior of what happens to a domain when it reboots is set by the
-\&\fIon_reboot\fR parameter of the xmdomain.cfg file when the domain was
-created.
+The exact behavior of a domain when it reboots is set by the
+\&\fIon_reboot\fR parameter in the domain's \s-1XML\s0 definition.
 .IP "\fBrestore\fR \fIstate-file\fR" 4
 .IX Item "restore state-file"
 Restores a domain from an \fBvirsh save\fR state file.  See \fIsave\fR for more info.
@@ -397,12 +414,16 @@ other domains to use.  \fBvirsh restore\fR restores from this state file.
 This is roughly equivalent to doing a hibernate on a running computer,
 with all the same limitations.  Open network connections may be
 severed upon restore, as \s-1TCP\s0 timeouts may have expired.
+.IP "\fBschedinfo\fR optional \fI\-\-set\fR \fBparameter=value\fR \fIdomain-id\fR" 4
+.IX Item "schedinfo optional --set parameter=value domain-id"
+.PD 0
 .IP "\fBschedinfo\fR optional \fI\-\-weight\fR \fBnumber\fR optional \fI\-\-cap\fR \fBnumber\fR \fIdomain-id\fR" 4
 .IX Item "schedinfo optional --weight number optional --cap number domain-id"
-Allows to show (and set) the domain scheduler parameters. This is currently
-only defined for \s-1XEN_CREDIT\s0 scheduler, and the optional weight and cap
-arguments allows to set the associated parameters in that scheduler if
-provided.
+.PD
+Allows to show (and set) the domain scheduler parameters.
+.Sp
+\&\fBNote\fR: The weight and cap parameters are defined only for the
+\&\s-1XEN_CREDIT\s0 scheduler and are now \fI\s-1DEPRECATED\s0\fR.
 .IP "\fBsetmem\fR \fIdomain-id\fR \fBkilobytes\fR" 4
 .IX Item "setmem domain-id kilobytes"
 Change the current memory allocation in the guest domain. This should take
@@ -431,9 +452,8 @@ to perform graceful shutdown, so there is no guarantee that it will
 succeed, and may take a variable length of time depending on what
 services must be shutdown in the domain.
 .Sp
-For a xen guest vm the behavior of what happens to a domain when it reboots is set by the
-\&\fIon_shutdown\fR parameter of the xmdomain.cfg file when the domain was
-created.
+The exact behavior of a domain when it shuts down is set by the
+\&\fIon_shutdown\fR parameter in the domain's \s-1XML\s0 definition.
 .IP "\fBstart\fR \fIdomain-name\fR" 4
 .IX Item "start domain-name"
 Start a (previously defined) inactive domain.
@@ -466,10 +486,8 @@ and \fIcpulist\fR is a comma separated list of physical \s-1CPU\s0 numbers.
 .IX Item "vncdisplay domain-id"
 Output the \s-1IP\s0 address and port number for the \s-1VNC\s0 display. If the information
 is not available the processes will provide an exit code of 1.
-.RE
-.RS 4
-.SH "DEVICES COMMANDS"
-.IX Header "DEVICES COMMANDS"
+.SH "DEVICE COMMANDS"
+.IX Header "DEVICE COMMANDS"
 The following commands manipulate devices associated to domains.
 The domain-id can be specified as an short integer, a name or a full \s-1UUID\s0.
 To better understand the values allowed as options for the command
@@ -509,10 +527,8 @@ Detach a network interface from a domain.
 \&\fItype\fR can be either \fInetwork\fR to indicate a physical network device or \fIbridge\fR to indicate a bridge to a device.
 It is recommended to use the \fImac\fR option to distinguish between the interfaces
 if more than one are present on the domain.
-.RE
-.RS 4
-.SH "VIRTUAL NETWORKS COMMANDS"
-.IX Header "VIRTUAL NETWORKS COMMANDS"
+.SH "VIRTUAL NETWORK COMMANDS"
+.IX Header "VIRTUAL NETWORK COMMANDS"
 The following commands manipulate networks. Libvirt has the capability to
 define virtual networks which can then be used by domains and linked to
 actual network devices. For more detailed information about this feature
@@ -538,6 +554,18 @@ effect immediately.
 .IP "\fBnet-dumpxml\fR \fInetwork\fR" 4
 .IX Item "net-dumpxml network"
 Output the virtual network information as an \s-1XML\s0 dump to stdout.
+.IP "\fBnet-edit\fR \fInetwork\fR" 4
+.IX Item "net-edit network"
+Edit the \s-1XML\s0 configuration file for a network.
+.Sp
+This is equivalent to:
+ virsh net-dumpxml network > network.xml
+ edit network.xml
+ virsh define network.xml
+except that it does some error checking.
+.Sp
+The editor used can be supplied by the \f(CW$EDITOR\fR environment
+variable, or if that is not defined defaults to \f(CW\*(C`vi\*(C'\fR.
 .IP "\fBnet-list\fR optional \fI\-\-inactive\fR or \fI\-\-all\fR" 4
 .IX Item "net-list optional --inactive or --all"
 Returns the list of active networks, if \fI\-\-all\fR is specified this will also
@@ -555,34 +583,63 @@ Undefine the configuration for an inactive network.
 .IP "\fBnet-uuid\fR \fInetwork-name\fR" 4
 .IX Item "net-uuid network-name"
 Convert a network name to network \s-1UUID\s0.
-.RE
-.RS 4
 .SH "ENVIRONMENT"
 .IX Header "ENVIRONMENT"
+The following environment variables can be set to alter the behaviour
+of \f(CW\*(C`virsh\*(C'\fR
 .IP "\s-1VIRSH_DEFAULT_CONNECT_URI\s0" 4
 .IX Item "VIRSH_DEFAULT_CONNECT_URI"
 The hypervisor to connect to by default. Set this to a \s-1URI\s0, in the same
 format as accepted by the \fBconnect\fR option.
+.IP "LIBVIRT_DEBUG=LEVEL" 4
+.IX Item "LIBVIRT_DEBUG=LEVEL"
+Turn on verbose debugging of all libvirt \s-1API\s0 calls. Valid levels are
+.RS 4
+.IP "\(bu" 4
+LIBVIRT_DEBUG=1
+.Sp
+Messages at level \s-1DEBUG\s0 or above
+.IP "\(bu" 4
+LIBVIRT_DEBUG=2
+.Sp
+Messages at level \s-1INFO\s0 or above
+.IP "\(bu" 4
+LIBVIRT_DEBUG=3
+.Sp
+Messages at level \s-1WARNING\s0 or above
+.IP "\(bu" 4
+LIBVIRT_DEBUG=4
+.Sp
+Messages at level \s-1ERROR\s0 or above
 .RE
 .RS 4
-.SH "SEE ALSO"
-.IX Header "SEE ALSO"
-\&\fIxm\fR\|(1), \fIxmdomain.cfg\fR\|(5), \fIxentop\fR\|(1) , <http://www.libvirt.org/>
-.SH "AUTHOR"
-.IX Header "AUTHOR"
+.Sp
+For further information about debugging options consult \f(CW\*(C`http://libvirt.org/logging.html\*(C'\fR
+.RE
+.SH "BUGS"
+.IX Header "BUGS"
+Report any bugs discovered to the libvirt community via the mailing
+list \f(CW\*(C`http://libvirt.org/contact.html\*(C'\fR or bug tracker \f(CW\*(C`http://libvirt.org/bugs.html\*(C'\fR.
+Alternatively report bugs to your software distributor / vendor.
+.SH "AUTHORS"
+.IX Header "AUTHORS"
 .Vb 2
 \&  Andrew Puch <apuch @ redhat.com>
 \&  Daniel Veillard <veillard @ redhat.com>
-.Ve
-.Sp
-.Vb 3
-\&  Based on the xm man paged by
+\&
+\&  Based on the xm man page by:
 \&  Sean Dague <sean at dague dot net>
 \&  Daniel Stekloff <dsteklof at us dot ibm dot com>
 .Ve
-.SH "BUGS"
-.IX Header "BUGS"
-Bugs can be view on the RedHat buzilla page under the libvirt
-<https://bugzilla.redhat.com/>
-.Sp
-<https://bugzilla.redhat.com/bugzilla/buglist.cgi?product=Fedora+Core&component=libvirt&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&bug_status=MODIFIED&short_desc_type=allwordssubstr&short_desc=&long_desc_type=allwordssubstr>
+.SH "COPYRIGHT"
+.IX Header "COPYRIGHT"
+Copyright (C) 2005, 2007\-2009 Red Hat, Inc.
+.SH "LICENSE"
+.IX Header "LICENSE"
+virsh is distributed under the terms of the \s-1GNU\s0 \s-1LGPL\s0 v2+.
+This is free software; see the source for copying conditions. There
+is \s-1NO\s0 warranty; not even for \s-1MERCHANTABILITY\s0 or \s-1FITNESS\s0 \s-1FOR\s0 A \s-1PARTICULAR\s0
+\&\s-1PURPOSE\s0
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+\&\fIvirt\-install\fR\|(1), \fIvirt\-xml\-validate\fR\|(1), \fIvirt\-top\fR\|(1), \fIvirt\-mem\fR\|(1), \fIvirt\-df\fR\|(1), <http://www.libvirt.org/>