[virtualization-guide] Added decently thorough explanation on how to reference volumes, with examples from virsh.

[Justin Clift]

commit 0045930f57cac236ac061f5986982b7ce67edc83
Author: Justin Clift <justin at 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">