[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