[libvirt] PATCH: Add a tool virt-xml-validate

While we install our RNG schemas into the filesystem, and users could use xmllint to validate them, it is a little tedious to use this way. This patch adds a nice simple command virt-xml-validate XML-FILE [SCHEMA-NAME] You can use it on any XML file format that libvirt knows about # virt-xml-validate ~/rhel5xen.xml /home/berrange/rhel5xen.xml validates #$ echo $? 0 I normally figures out the SCHEMA-NAME from the top level element name, but you can override it if desired # virt-xml-validate ~/bug.xml virt-xml-validate: cannot determine schema type for /home/berrange/bug.xml # virt-xml-validate ~/bug.xml domain /home/berrange/bug.txt:1: parser error : Start tag expected, '<' not found From bugzilla(a)redhat.com Fri Feb 27 01:12:11 2009 ^ I've included a man page in the command. This patch also fixes numerous bugs in the virsh man page source The 'src/' directory is getting over large, so I decided we should have a separate 'tools' directory for command line programs included in the main libvirt source. We could consider moving virsh here perhaps. .hgignore | 12 ++ Makefile.am | 2 b/tools/.cvsignore | 4 b/tools/.gitignore | 4 b/tools/Makefile.am | 14 ++ b/tools/virt-xml-validate.in | 151 ++++++++++++++++++++++++++ configure.in | 1 docs/Makefile.am | 2 docs/virsh.pod | 80 ++++++++++++-- libvirt.spec.in | 4 virsh.1 | 241 ++++++++++++++++++++++++++----------------- 11 files changed, 408 insertions(+), 107 deletions(-) Daniel diff -r f861822d43db .hgignore --- a/.hgignore Thu Apr 16 10:34:11 2009 +0100 +++ b/.hgignore Thu Apr 16 12:44:17 2009 +0100 @@ -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 diff -r f861822d43db Makefile.am --- a/Makefile.am Thu Apr 16 10:34:11 2009 +0100 +++ b/Makefile.am Thu Apr 16 12:44:17 2009 +0100 @@ -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 diff -r f861822d43db configure.in --- a/configure.in Thu Apr 16 10:34:11 2009 +0100 +++ b/configure.in Thu Apr 16 12:44:17 2009 +0100 @@ -1342,6 +1342,7 @@ AC_OUTPUT(Makefile src/Makefile include/ include/libvirt/Makefile include/libvirt/libvirt.h \ python/Makefile python/tests/Makefile \ qemud/Makefile \ + tools/Makefile \ tests/Makefile proxy/Makefile \ tests/xml2sexprdata/Makefile \ tests/sexpr2xmldata/Makefile \ diff -r f861822d43db docs/Makefile.am --- a/docs/Makefile.am Thu Apr 16 10:34:11 2009 +0100 +++ b/docs/Makefile.am Thu Apr 16 12:44:17 2009 +0100 @@ -66,7 +66,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) diff -r f861822d43db docs/virsh.pod --- a/docs/virsh.pod Thu Apr 16 10:34:11 2009 +0100 +++ b/docs/virsh.pod Thu Apr 16 12:44:17 2009 +0100 @@ -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 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 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 indi 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://libvir 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 inacti 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 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. -Bugs can be filed in Red Hat bugzilla under the Virtualization Tools/libvirt -L<https://bugzilla.redhat.com/> +=head1 LICENSE -L<https://bugzilla.redhat.com/buglist.cgi?product=Virtualization+Tools&component=libvirt&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED> +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 -=end +=head1 SEE ALSO + +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/> + +=cut diff -r f861822d43db libvirt.spec.in --- a/libvirt.spec.in Thu Apr 16 10:34:11 2009 +0100 +++ b/libvirt.spec.in Thu Apr 16 12:44:17 2009 +0100 @@ -372,8 +372,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/ diff -r f861822d43db tools/.cvsignore --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/tools/.cvsignore Thu Apr 16 12:44:17 2009 +0100 @@ -0,0 +1,4 @@ +virt-xml-validate +virt-xml-validate.1 +Makefile +Makefile.in diff -r f861822d43db tools/.gitignore --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/tools/.gitignore Thu Apr 16 12:44:17 2009 +0100 @@ -0,0 +1,4 @@ +virt-xml-validate +virt-xml-validate.1 +Makefile +Makefile.in diff -r f861822d43db tools/Makefile.am --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/tools/Makefile.am Thu Apr 16 12:44:17 2009 +0100 @@ -0,0 +1,14 @@ + +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 + +CLEANFILES = $(bin_SCRIPTS) $(man1_MANS) + +%.1: % + pod2man -c "Virtualization Support" -r "$(PACKAGE)-$(VERSION)" $< $@ diff -r f861822d43db tools/virt-xml-validate.in --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/tools/virt-xml-validate.in Thu Apr 16 12:44:17 2009 +0100 @@ -0,0 +1,151 @@ +#!/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 --format $XMLFILE 2>/dev/null| head -2 | tail -1` + 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=&quot;@SCHEMADIR(a)/${TYPE}.rng&quot; + +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 diff -r f861822d43db virsh.1 --- a/virsh.1 Thu Apr 16 10:34:11 2009 +0100 +++ b/virsh.1 Thu Apr 16 12:44:17 2009 +0100 @@ -1,4 +1,4 @@ -.\" 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 cur 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 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 fol \&\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- .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). +State is the run state (see below). +.Sp +\&\fB\s-1STATES\s0\fR +.Sp +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 "\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 "\fBpaused\fR" 4 +.IX Item "paused" +The domain has been paused, usually occurring through the administrator +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 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 "\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. +.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. -.RS 4 -.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 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 -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" -The domain has been paused, usually occurring through the administrator -running \fBxm pause\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" -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" -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" -The domain is in process of dying, but hasn't completely shutdown or -crashed. -.RE -.RS 4 .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 aut 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 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 .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 comma 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\ 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 i 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 l .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 inacti .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/> -- |: Red Hat, Engineering, London -o- http://people.redhat.com/berrange/ :| |: http://libvirt.org -o- http://virt-manager.org -o- http://ovirt.org :| |: http://autobuild.org -o- http://search.cpan.org/~danberr/ :| |: GnuPG: 7D3B9505 -o- F3C9 553F A1DA 4AC2 5648 23C1 B3DF F742 7D3B 9505 :|