diff --git a/.hgignore b/.hgignore index 32820fc64eaa121e36c931d22ad6c5f131a14ff2..bfc08495f06c952ac24a56619409955ed1f2f047 100644 --- a/.hgignore +++ b/.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 diff --git a/ChangeLog b/ChangeLog index cb085461858bcd00598983977d02d33c85ab6056..975075286e880336b92a5c913d88b3ad0e828653 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,16 @@ +Sun Apr 19 16:00:22 BST 2009 Daniel P. Berrange + + 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 * 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 Thu Apr 16 16:48:51 CEST 2009 Guido Günther * 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 diff --git a/Makefile.am b/Makefile.am index 928a93cc908f8197fe56bbb8d1451fe5e8632cd7..7a3438edaedce6e7045b5e1036e349f0385d4fd5 100644 --- a/Makefile.am +++ b/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 diff --git a/docs/Makefile.am b/docs/Makefile.am index 4a559652136091d2de487b59c2808ae55806a75d..97b445686dd4d1b544b867995b6b47af58de5e98 100644 --- a/docs/Makefile.am +++ b/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) diff --git a/docs/virsh.pod b/docs/virsh.pod index 58bba6b6578f3f1612927451cf86d8a2c641ded6..24389842546a95affda927f5d17b8637967a7d55 100644 --- a/docs/virsh.pod +++ b/docs/virsh.pod @@ -150,13 +150,13 @@ B list Name is the name of the domain. ID the domain numeric id. State is the run state (see below). -=over 4 - B The State field lists 6 states for a domain, and which ones the current domain is in. +=over 4 + =item B 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 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 can be specified as an short integer, a name or a full UUID. +=over 4 + =item B optional I<--disable> I Configure a domain to be automatically started at boot. @@ -401,7 +405,9 @@ and I 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 on the format of the device sections to get the most accurate set of accepted values. +=over 4 + =item B I I Attach a device to the domain, using a device definition in an XML file. @@ -449,7 +457,9 @@ I can be either I to indicate a physical network device or I 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 . 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 I 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 + +=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 option. -=head1 SEE ALSO +=item LIBVIRT_DEBUG=LEVEL -L, L, L, L, L, L +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 + +=back + +=head1 BUGS + +Report any bugs discovered to the libvirt community via the mailing +list C or bug tracker C. +Alternatively report bugs to your software distributor / vendor. + +=head1 AUTHORS Andrew Puch Daniel Veillard @@ -537,12 +586,19 @@ L, L, L, L, L, L Daniel Stekloff +=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 +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 +L, L, L, L, L, L -=end +=cut diff --git a/libvirt.spec.in b/libvirt.spec.in index 68535d5f1332896bb608022222fae2ff26697628..4e85f9e0551871da8cfd959b13e11d4751098909 100644 --- a/libvirt.spec.in +++ b/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/ diff --git a/tools/.cvsignore b/tools/.cvsignore new file mode 100644 index 0000000000000000000000000000000000000000..380dc96b430203039b92179e5c2ce6896a91e93c --- /dev/null +++ b/tools/.cvsignore @@ -0,0 +1,4 @@ +virt-xml-validate +virt-xml-validate.1 +Makefile +Makefile.in diff --git a/tools/.gitignore b/tools/.gitignore new file mode 100644 index 0000000000000000000000000000000000000000..380dc96b430203039b92179e5c2ce6896a91e93c --- /dev/null +++ b/tools/.gitignore @@ -0,0 +1,4 @@ +virt-xml-validate +virt-xml-validate.1 +Makefile +Makefile.in diff --git a/tools/Makefile.am b/tools/Makefile.am new file mode 100644 index 0000000000000000000000000000000000000000..44ff44206bb1cdc41efaacd284d61f0201ee44ff --- /dev/null +++ b/tools/Makefile.am @@ -0,0 +1,16 @@ + +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)" $< $@ diff --git a/tools/virt-xml-validate.in b/tools/virt-xml-validate.in new file mode 100644 index 0000000000000000000000000000000000000000..03bd1a1cc5b3903a6cbae4c11d3eaa1d35113209 --- /dev/null +++ b/tools/virt-xml-validate.in @@ -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 --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 + +The schema for the XML format used by guest domains configuration + +=item C + +The schema for the XML format used by virtual network configuration + +=item C + +The schema for the XML format used by storage pool configuration + +=item C + +The schema for the XML format used by storage volume descriptions + +=item C + +The schema for the XML format used by node device descriptions + +=item C + +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 or bug tracker C. +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, online XML format descriptions C + +=cut diff --git a/virsh.1 b/virsh.1 index 063dde7857a1b28449fdcf3d2b13ed951060224f..2197c2023d23ccd24cd969e5f6de0336e17ebbc9 100644 --- a/virsh.1 +++ b/virsh.1 @@ -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 current domains. Libvirt is a C toolkit to The basic structure of most virsh usage is: .PP .Vb 1 -\& virsh [OPTIONS] +\& virsh [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 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 . An easy way to create the \s-1XML\s0 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 . 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) , -.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 \& Daniel Veillard -.Ve -.Sp -.Vb 3 -\& Based on the xm man paged by +\& +\& Based on the xm man page by: \& Sean Dague \& Daniel Stekloff .Ve -.SH "BUGS" -.IX Header "BUGS" -Bugs can be view on the RedHat buzilla page under the libvirt - -.Sp - +.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),