summaryrefslogtreecommitdiffstats
path: root/src/guestfs.pod
diff options
context:
space:
mode:
authorRichard W.M. Jones <rjones@redhat.com>2012-10-03 10:50:51 +0100
committerRichard W.M. Jones <rjones@redhat.com>2012-10-08 20:04:47 +0100
commit7786d56db8c22413949f98ef6b15fe0ea367d195 (patch)
tree7234b2d5b450a21677a9cc19e0b1c506546fa1ee /src/guestfs.pod
parent3ad44c866042919374e2d840502e53da2ed8aef0 (diff)
downloadlibguestfs-7786d56db8c22413949f98ef6b15fe0ea367d195.tar.gz
libguestfs-7786d56db8c22413949f98ef6b15fe0ea367d195.tar.xz
libguestfs-7786d56db8c22413949f98ef6b15fe0ea367d195.zip
launch: Add add_drive 'label' option.
New API: list-disk-labels Allow the user to pass an optional disk label when adding a drive. This is passed through to qemu / libvirt using the disk serial field, and from there to the appliance which exposes it through udev, creating a special alias of the device /dev/disk/guestfs/<label>. Partitions are named /dev/disk/guestfs/<label><partnum>. virtio-blk and virtio-scsi limit the serial field to 20 bytes. We further limit the name to maximum 20 ASCII characters in [a-zA-Z]. list-devices and list-partitions are not changed: these calls still return raw block device names. However a new call, list-disk-labels, returns a hash table allowing callers to map between disk labels, and block device and partition names. This commit also includes a test.
Diffstat (limited to 'src/guestfs.pod')
-rw-r--r--src/guestfs.pod20
1 files changed, 20 insertions, 0 deletions
diff --git a/src/guestfs.pod b/src/guestfs.pod
index 2b33bf32..48d810b0 100644
--- a/src/guestfs.pod
+++ b/src/guestfs.pod
@@ -1191,6 +1191,26 @@ L</guestfs_list_devices>, L</guestfs_list_partitions> and similar calls
return the true names of the devices and partitions as known to the
appliance, but see L</guestfs_canonical_device_name>.
+=head3 DISK LABELS
+
+In libguestfs E<ge> 1.20, you can give a label to a disk when you add
+it, using the optional C<label> parameter to L</guestfs_add_drive_opts>.
+(Note that disk labels are different from and not related to
+filesystem labels).
+
+Not all versions of libguestfs support setting a disk label, and when
+it is supported, it is limited to 20 ASCII characters C<[a-zA-Z]>.
+
+When you add a disk with a label, it can either be addressed
+using C</dev/sd*>, or using C</dev/disk/guestfs/I<label>>.
+Partitions on the disk can be addressed using
+C</dev/disk/guestfs/I<label>I<partnum>>.
+
+Listing devices (L</guestfs_list_devices>) and partitions
+(L</guestfs_list_partitions>) returns the raw block device name.
+However you can use L</guestfs_list_disk_labels> to map disk labels
+to raw block device and partition names.
+
=head3 ALGORITHM FOR BLOCK DEVICE NAME TRANSLATION
Usually this translation is transparent. However in some (very rare)