[libvirt] [RFC PATCH] doc: add sample XML for disk
When I edit the xml config file, I need to know the format. The easiest way to know the format is a sample XML. But we do not have such sample now. TODO: 1. dir and network disk's sample 2. nic's sample If we need such document, I will continue doing it. --- libvirt.spec.in | 1 + tools/Makefile.am | 7 +- tools/libvirt-xml-sample-disk.pod | 294 +++++++++++++++++++++++++++++++++++++ 3 files changed, 301 insertions(+), 1 deletions(-) create mode 100644 tools/libvirt-xml-sample-disk.pod diff --git a/libvirt.spec.in b/libvirt.spec.in index bf220f3..8b7ac6b 100644 --- a/libvirt.spec.in +++ b/libvirt.spec.in @@ -1046,6 +1046,7 @@ fi %{_mandir}/man1/virsh.1* %{_mandir}/man1/virt-xml-validate.1* %{_mandir}/man1/virt-pki-validate.1* +%{_mandir}/man5/libvirt-xml-sample-disk.5* %{_bindir}/virsh %{_bindir}/virt-xml-validate %{_bindir}/virt-pki-validate diff --git a/tools/Makefile.am b/tools/Makefile.am index 62c275e..9996ae6 100644 --- a/tools/Makefile.am +++ b/tools/Makefile.am @@ -16,7 +16,8 @@ EXTRA_DIST = \ virt-sanlock-cleanup.8 \ virsh.pod \ libvirt-guests.init.sh \ - libvirt-guests.sysconf + libvirt-guests.sysconf \ + libvirt-xml-sample-disk.pod bin_SCRIPTS = virt-xml-validate virt-pki-validate bin_PROGRAMS = virsh @@ -26,6 +27,7 @@ sbin_SCRIPTS = virt-sanlock-cleanup endif dist_man1_MANS = virt-xml-validate.1 virt-pki-validate.1 virsh.1 +dist_man5_MANS = libvirt-xml-sample-disk.5 if HAVE_SANLOCK dist_man8_MANS = virt-sanlock-cleanup.8 endif @@ -141,6 +143,9 @@ endif virsh.1: virsh.pod $(AM_V_GEN)$(POD2MAN) $< $(srcdir)/$@ +libvirt-xml-sample-disk.5: libvirt-xml-sample-disk.pod + $(AM_V_GEN)$(POD2MAN) $< $(srcdir)/$@ + install-data-local: install-init uninstall-local: uninstall-init diff --git a/tools/libvirt-xml-sample-disk.pod b/tools/libvirt-xml-sample-disk.pod new file mode 100644 index 0000000..250608c --- /dev/null +++ b/tools/libvirt-xml-sample-disk.pod @@ -0,0 +1,294 @@ +=head1 NAME + +libvirt-xml-sample-disk - sample xml config file for disk + +=head1 DESCRIPTION + +=over 4 + +=item B<file> + +B<ide> + +=over 4 + +B<sample> + + <disk type='file' device='disk'> + <driver name='qemu' type='qcow2' cache='none' error_policy='stop' io='native' ioeventfd=''/> + <source file='/var/lib/libvirt/images/sample.img'/> + <target dev='hda' bus='ide'/> + <shareable/> + <encryption format='qcow'> + <secret type='passphrase' uuid='00000000-0000-0000-0000-000000000000'/> + </encryption> + <serial>Fujitsu-ide-001</serial> + <boot order='1'/> + <address type='drive' controller='0' bus='0' unit='0'/> + </disk> + +B<cache>: The value of B<cache> can be: B<default>, B<none>, B<writethrough>, +and B<writeback> + +B<error_policy>: The value of B<error_policy> can be: B<default>, B<stop>, +B<ignore>, and B<enospace> + +B<io>: The value of B<io> can be: B<default>, B<native>, and B<threads> + +B<format>: The value of foramt can be: B<default>, and B<qcow> + +B<type>: The type of B<secret> only can be B<passphrase> + +=back + +B<scsi> + +=over 4 + +B<sample> + + <disk type='file' device='disk'> + <driver name='qemu' type='qcow2' cache='none' error_policy='stop' io='native'/> + <source file='/var/lib/libvirt/images/sample.img'/> + <target dev='sda' bus='scsi'/> + <shareable/> + <encryption format='qcow'> + <secret type='passphrase' uuid='00000000-0000-0000-0000-000000000000'/> + </encryption> + <readonly/> + <serial>Fujitsu-scsi-001</serial> + <boot order='1'/> + <address type='drive' controller='0' bus='0' unit='0'/> + </disk> + +=back + +B<virtio> + +=over 4 + +B<sample> + + <disk type='file' device='disk'> + <driver name='qemu' type='qcow2' cache='none' error_policy='stop' io='native' ioeventfd='on'/> + <source file='/var/lib/libvirt/images/sample.img'/> + <target dev='vda' bus='virtio'/> + <shareable/> + <encryption format='qcow'> + <secret type='passphrase' uuid='00000000-0000-0000-0000-000000000000'/> + </encryption> + <readonly/> + <serial>Fujitsu-virtio-001</serial> + <boot order='1'/> + <address type='pci' domain='0x0000' bus='0x00' slot='0x07' function='0x0'/> + </disk> + +B<ioeventfd>: The value of B<ioeventfd> can be: B<default>, B<on>, and B<off> + +=back + +B<cdrom> + +=over 4 + +B<sample> + + <disk type='file' device='cdrom'> + <driver name='qemu' type='qcow2' cache='none' error_policy='stop' io='native'/> + <source file='/var/lib/libvirt/images/sample.iso'/> + <target dev='hda' bus='ide'/> + <shareable/> + <encryption format='qcow'> + <secret type='passphrase' uuid='00000000-0000-0000-0000-000000000000'/> + </encryption> + <readonly/> + <serial>Fujitsu-ide-001</serial> + <boot order='1'/> + <address type='drive' controller='0' bus='1' unit='0'/> + </disk> + +=back + +B<floppy> + +=over 4 + +B<sample> + + <disk type='file' device='floppy'> + <driver name='qemu' type='qcow2' cache='none' io='native'/> + <source file='/var/lib/libvirt/images/floppy.img'/> + <target dev='fda' bus='fdc'/> + <shareable/> + <encryption format='qcow'> + <secret type='passphrase' uuid='00000000-0000-0000-0000-000000000000'/> + </encryption> + <readonly/> + <serial>Fujitsu-ide-001</serial> + <boot order='1'/> + <address type='drive' controller='0' bus='0' unit='0'/> + </disk> + +=back + +B<usb storage> + +=over 4 + +B<sample> + + <disk type='file' device='disk'> + <driver name='qemu' type='qcow2' cache='none' error_policy='stop' io='native'/> + <source file='/var/lib/libvirt/images/sample.img'/> + <target dev='ubda' bus='usb'/> + <shareable/> + <encryption format='qcow'> + <secret type='passphrase' uuid='00000000-0000-0000-0000-000000000000'/> + </encryption> + <readonly/> + <serial>Fujitsu-ide-001</serial> + <boot order='1'/> + </disk> + +=back + +=item B<block> + +The difference between B<file> and B<block> is: the type of disk and the element +B<source> + +B<ide> + +=over 4 + +B<sample> + + <disk type='block' device='disk'> + <driver name='qemu' type='qcow2' cache='none' error_policy='stop' io='native' ioeventfd=''/> + <source dev='/dev/sdb'/> + <target dev='hda' bus='ide'/> + <shareable/> + <encryption format='qcow'> + <secret type='passphrase' uuid='00000000-0000-0000-0000-000000000000'/> + </encryption> + <serial>Fujitsu-ide-001</serial> + <boot order='1'/> + <address type='drive' controller='0' bus='0' unit='0'/> + </disk> + +=back + +B<scsi> + +=over 4 + +B<sample> + + <disk type='block' device='disk'> + <driver name='qemu' type='qcow2' cache='none' error_policy='stop' io='native'/> + <source dev='/dev/sdb'/> + <target dev='sda' bus='scsi'/> + <shareable/> + <encryption format='qcow'> + <secret type='passphrase' uuid='00000000-0000-0000-0000-000000000000'/> + </encryption> + <readonly/> + <serial>Fujitsu-scsi-001</serial> + <boot order='1'/> + <address type='drive' controller='0' bus='0' unit='0'/> + </disk> + +=back + +B<virtio> + +=over 4 + +B<sample> + + <disk type='block' device='disk'> + <driver name='qemu' type='qcow2' cache='none' error_policy='stop' io='native' ioeventfd='on'/> + <source dev='/dev/sdb'/> + <target dev='vda' bus='virtio'/> + <shareable/> + <encryption format='qcow'> + <secret type='passphrase' uuid='00000000-0000-0000-0000-000000000000'/> + </encryption> + <readonly/> + <serial>Fujitsu-virtio-001</serial> + <boot order='1'/> + <address type='pci' domain='0x0000' bus='0x00' slot='0x07' function='0x0'/> + </disk> + +B<ioeventfd>: The value of B<ioeventfd> can be: B<default>, B<on>, and B<off> + +=back + +B<cdrom> + +=over 4 + +B<sample> + + <disk type='block' device='cdrom'> + <driver name='qemu' type='qcow2' cache='none' error_policy='stop' io='native'/> + <source dev='/dev/cdrom'/> + <target dev='hda' bus='ide'/> + <shareable/> + <encryption format='qcow'> + <secret type='passphrase' uuid='00000000-0000-0000-0000-000000000000'/> + </encryption> + <readonly/> + <serial>Fujitsu-ide-001</serial> + <boot order='1'/> + <address type='drive' controller='0' bus='1' unit='0'/> + </disk> + +=back + +B<floppy> + +=over 4 + +B<sample> + + <disk type='block' device='floppy'> + <driver name='qemu' type='qcow2' cache='none' io='native'/> + <source dev='/dev/fd0'/> + <target dev='fda' bus='fdc'/> + <shareable/> + <encryption format='qcow'> + <secret type='passphrase' uuid='00000000-0000-0000-0000-000000000000'/> + </encryption> + <readonly/> + <serial>Fujitsu-ide-001</serial> + <boot order='1'/> + <address type='drive' controller='0' bus='0' unit='0'/> + </disk> + +=back + +B<usb storage> + +=over 4 + +B<sample> + + <disk type='block' device='disk'> + <driver name='qemu' type='qcow2' cache='none' error_policy='stop' io='native'/> + <source dev='/dev/sdb'/> + <target dev='ubda' bus='usb'/> + <shareable/> + <encryption format='qcow'> + <secret type='passphrase' uuid='00000000-0000-0000-0000-000000000000'/> + </encryption> + <readonly/> + <serial>Fujitsu-ide-001</serial> + <boot order='1'/> + </disk> + +=back + +=back + +=cut -- 1.7.1
On Thu, Jul 07, 2011 at 01:06:01PM +0800, Wen Congyang wrote:
When I edit the xml config file, I need to know the format. The easiest way to know the format is a sample XML. But we do not have such sample now.
TODO: 1. dir and network disk's sample 2. nic's sample
If we need such document, I will continue doing it.
I agree it would be useful to have man pages documenting the XML format. I wonder if we can somehow have one set of content, and from that generate both the docs/formatdomain.html and a docs/virt-xml-domain.pod file ? Likewise for the other XML schemas. Regards, Daniel -- |: http://berrange.com -o- http://www.flickr.com/photos/dberrange/ :| |: http://libvirt.org -o- http://virt-manager.org :| |: http://autobuild.org -o- http://search.cpan.org/~danberr/ :| |: http://entangle-photo.org -o- http://live.gnome.org/gtk-vnc :|
At 07/07/2011 05:33 PM, Daniel P. Berrange Write:
On Thu, Jul 07, 2011 at 01:06:01PM +0800, Wen Congyang wrote:
When I edit the xml config file, I need to know the format. The easiest way to know the format is a sample XML. But we do not have such sample now.
TODO: 1. dir and network disk's sample 2. nic's sample
If we need such document, I will continue doing it.
I agree it would be useful to have man pages documenting the XML format. I wonder if we can somehow have one set of content, and from that generate both the docs/formatdomain.html and a docs/virt-xml-domain.pod file ?
It's good idea to auto generate such document and formatdomain by one set of content. But it needs more time to do it, and I think we can add such document first and implement this idea later.
Likewise for the other XML schemas.
Regards, Daniel
At 07/07/2011 05:33 PM, Daniel P. Berrange Write:
On Thu, Jul 07, 2011 at 01:06:01PM +0800, Wen Congyang wrote:
When I edit the xml config file, I need to know the format. The easiest way to know the format is a sample XML. But we do not have such sample now.
TODO: 1. dir and network disk's sample 2. nic's sample
If we need such document, I will continue doing it.
I agree it would be useful to have man pages documenting the XML format. I wonder if we can somehow have one set of content, and from that generate both the docs/formatdomain.html and a docs/virt-xml-domain.pod file ?
I read docs/formatdomain.html.in, and think it is not easy to do it. formatdomain.html.in contains more information than pod file and some restriction does not written into html file(for example ide disk can not be set to readonly.) Most information in formatdoamin.html is not included in pod file, So I think there is no need to do it.
Likewise for the other XML schemas.
Regards, Daniel
participants (2)
-
Daniel P. Berrange -
Wen Congyang