commit 0045930f57cac236ac061f5986982b7ce67edc83
Author: Justin Clift <justin(a)salasaga.org>
Date: Mon Jun 7 22:04:32 2010 +1000
Added decently thorough explanation on how to reference volumes, with examples from
virsh.
en-US/Storage_Concepts.xml | 146 ++++++++++++++++++++++++++++++++++++++++++++
1 files changed, 146 insertions(+), 0 deletions(-)
---
diff --git a/en-US/Storage_Concepts.xml b/en-US/Storage_Concepts.xml
index 1847014..bd80e72 100644
--- a/en-US/Storage_Concepts.xml
+++ b/en-US/Storage_Concepts.xml
@@ -17,6 +17,17 @@
Storage Pools
</title>
<para>
+ Storage Pools are collections of "storage media".
+ </para>
+ <para>
+ They hold within them storage <firstterm>volumes</firstterm>, which are
the storage devices your guest virtual machines will access.
+ (picture examples)
+ </para>
+ <para>
+ Placeholder for better explanation. Probably need diagrams to aid clarity as well.
+ </para>
+<!--
+ <para>
A Storage Pool is storage that can be divided up into smaller volumes or allocated
directly to a guest. Volumes of a storage pool can be allocated to virtualised guests.
There are two categories of Storage Pool available:
</para>
<itemizedlist>
@@ -35,6 +46,7 @@
</formalpara>
</listitem>
</itemizedlist>
+-->
</section>
<section id="sect-Virtualization-Storage_Concepts-Volumes">
@@ -44,6 +56,140 @@
<para>
Placeholder
</para>
+ <section>
+ <title>
+ Referencing Volumes
+ </title>
+ <para>
+ To reference a specific volume, three approaches are possible:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <formalpara>
+ <title>
+ The name of the volume, paired with the pool the volume belongs to
+ </title>
+ <para>
+ A volume may be referred to by name, along with an identifier for the storage pool
it belongs in. On the virsh command line, this takes the form
<parameter>--pool</parameter>
<replaceable>storage_pool</replaceable>
<replaceable>volume_name</replaceable>.
+ </para>
+ </formalpara>
+ <para>
+ For example, a volume named <replaceable>firstimage</replaceable> in
the <replaceable>guest_images</replaceable> pool.
+ </para>
+ <screen>virsh # vol-info --pool
<replaceable>guest_images</replaceable>
<replaceable>firstimage</replaceable>
+Name: <replaceable>firstimage</replaceable>
+Type: block
+Capacity: 20.00 GB
+Allocation: 20.00 GB
+
+virsh #</screen>
+ </listitem>
+ <listitem>
+ <formalpara>
+ <title>
+ The full path to the storage on the host system
+ </title>
+ <para>
+ A volume may also be referred to by its full path on the file system. When
using this approach, a pool identifier does not need to be included.
+ </para>
+ </formalpara>
+ <para>
+ For example, a volume named <replaceable>secondimage.img</replaceable>,
visible to the host system as
<replaceable>/images/secondimage.img</replaceable>. This can be refered to as
<replaceable>/images/secondimage.img</replaceable>.
+ </para>
+ <screen>virsh # vol-info
<replaceable>/images/secondimage.img</replaceable>
+Name: <replaceable>secondimage.img</replaceable>
+Type: file
+Capacity: 20.00 GB
+Allocation: 136.00 KB
+
+virsh #</screen>
+ </listitem>
+ <listitem>
+ <formalpara>
+ <title>
+ The unique volume key
+ </title>
+ <para>
+ When a volume is first created in the virtualization system, a unique
identifier is generated and assigned to it. The unique identifier is termed the
<firstterm>volume key</firstterm>. The format of this volume key varies upon
the storage used.
+ </para>
+ </formalpara>
+ <para>
+ When used with block based storage such as LVM, the volume key may follow this
format:
+ </para>
+ <screen>c3pKz4-qPVc-Xf7M-7WNM-WJc8-qSiz-mtvpGn</screen>
+ <para>
+ When used with file based storage, the volume key may instead be a copy of the
full path to the volume storage.
+ </para>
+ <screen>/images/secondimage.img</screen>
+ <para>
+ For example, a volume with the volume key of
<replaceable>Wlvnf7-a4a3-Tlje-lJDa-9eak-PZBv-LoZuUr</replaceable>:
+ </para>
+ <screen>virsh # vol-info Wlvnf7-a4a3-Tlje-lJDa-9eak-PZBv-LoZuUr
+Name: <replaceable>firstimage</replaceable>
+Type: block
+Capacity: 20.00 GB
+Allocation: 20.00 GB
+
+virsh #</screen>
+ </listitem>
+ </itemizedlist>
+ <para>
+ Virsh provides commands for converting between a volume name, volume path, or volume
key:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <formalpara>
+ <title>
+ vol-name
+ </title>
+ <para>
+ Returns the volume name when provided with a volume path or volume key.
+ </para>
+ </formalpara>
+ <screen>virsh # vol-name
/dev/<replaceable>guest_images</replaceable>/<replaceable>firstimage</replaceable>
+<replaceable>firstimage</replaceable>
+
+virsh # vol-name
<replaceable>Wlvnf7-a4a3-Tlje-lJDa-9eak-PZBv-LoZuUr</replaceable>
+<replaceable>firstimage</replaceable>
+
+virsh #</screen>
+ </listitem>
+ <listitem>
+ <formalpara>
+ <title>
+ vol-path
+ </title>
+ <para>
+ Returns the volume path when provided with a volume key, or a storage pool
identifier and volume name.
+ </para>
+ </formalpara>
+ <screen>virsh # vol-path Wlvnf7-a4a3-Tlje-lJDa-9eak-PZBv-LoZuUr
+/dev/<replaceable>guest_images</replaceable>/<replaceable>firstimage</replaceable>
+
+virsh # vol-path --pool <replaceable>guest_images</replaceable>
<replaceable>firstimage</replaceable>
+/dev/<replaceable>guest_images</replaceable>/<replaceable>firstimage</replaceable>
+
+virsh #</screen>
+ </listitem>
+ <listitem>
+ <formalpara>
+ <title>
+ vol-key
+ </title>
+ <para>
+ Returns the volume key when provided with a volume path, or a storage pool
identifier and volume name.
+ </para>
+ </formalpara>
+ <screen>virsh # vol-key
/dev/<replaceable>guest_images</replaceable>/<replaceable>firstimage</replaceable>
+Wlvnf7-a4a3-Tlje-lJDa-9eak-PZBv-LoZuUr
+
+virsh # vol-key --pool <replaceable>guest_images</replaceable>
<replaceable>firstimage</replaceable>
+Wlvnf7-a4a3-Tlje-lJDa-9eak-PZBv-LoZuUr
+
+virsh #</screen>
+ </listitem>
+ </itemizedlist>
+ </section>
</section>
<section
id="sect-Virtualization-Storage_Concepts-Not_Using_Storage_Pools">
Show replies by date