[pve-devel] [PATCH docs 08/10] Rewrite LVM - admin section

[Aaron Lauterer]

Polished phrasing, aligned CLI commands style

Signed-off-by: Aaron Lauterer <a.lauterer at proxmox.com>
---
 local-lvm.adoc | 126 ++++++++++++++++++++++++++++---------------------
 1 file changed, 72 insertions(+), 54 deletions(-)

diff --git a/local-lvm.adoc b/local-lvm.adoc
index 2489b9d..b153862 100644
--- a/local-lvm.adoc
+++ b/local-lvm.adoc
@@ -5,20 +5,23 @@ ifdef::wiki[]
 :pve-toplevel:
 endif::wiki[]
 
-Most people install {pve} directly on a local disk. The {pve}
-installation CD offers several options for local disk management, and
-the current default setup uses LVM. The installer let you select a
-single disk for such setup, and uses that disk as physical volume for
-the **V**olume **G**roup (VG) `pve`. The following output is from a
-test installation using a small 8GB disk:
+
+When using the official {pve} installation ISO the installer offers
+several file systems to use for the installation. If `ext3`, `ext4` or
+`xfs` is chosen {pve} will automatically use LVM beneath the file
+system.
+
+The selected disk is used as physical volume for the **V**olume
+**G**roup (VG) `pve`. The following output is from a test installation
+on a small 8GB disk.
 
 ----
 # pvs
-  PV         VG   Fmt  Attr PSize PFree  
+  PV         VG   Fmt  Attr PSize PFree
   /dev/sda3  pve  lvm2 a--  7.87g 876.00m
 
 # vgs
-  VG   #PV #LV #SN Attr   VSize VFree  
+  VG   #PV #LV #SN Attr   VSize VFree
   pve    1   3   0 wz--n- 7.87g 876.00m
 ----
 
@@ -30,109 +33,124 @@ VG:
   LV   VG   Attr       LSize   Pool Origin Data%  Meta%
   data pve  twi-a-tz--   4.38g             0.00   0.63
   root pve  -wi-ao----   1.75g
-  swap pve  -wi-ao---- 896.00m     
+  swap pve  -wi-ao---- 896.00m
 ----
 
-root:: Formatted as `ext4`, and contains the operation system.
+root:: Formatted as `ext4`, contains the operation system.
 
 swap:: Swap partition
 
-data:: This volume uses LVM-thin, and is used to store VM
-images. LVM-thin is preferable for this task, because it offers
-efficient support for snapshots and clones.
+data:: It stores the virtual machines. LVM-thin is used as it offers
+    efficient support for snapshots and clones.
 
 For {pve} versions up to 4.1, the installer creates a standard logical
-volume called ``data'', which is mounted at `/var/lib/vz`.
+volume called ``data'' which is mounted at `/var/lib/vz`.
 
-Starting from version 4.2, the logical volume ``data'' is a LVM-thin pool,
-used to store block based guest images, and `/var/lib/vz` is simply a
-directory on the root file system.
+Starting from version 4.2, the logical volume ``data'' is a
+LVM-thin pool. It isused to store block based images of gursts.
+`/var/lib/vz` is simply a directory on the root file system.
 
 Hardware
 ~~~~~~~~
 
-We highly recommend to use a hardware RAID controller (with BBU) for
-such setups. This increases performance, provides redundancy, and make
-disk replacements easier (hot-pluggable).
+It is highly recommended to use a hardware RAID controller (with BBU)
+for such a setup. This increases performance, provides redundancy and
+makes disk replacements easier (hot-plugging)
 
-LVM itself does not need any special hardware, and memory requirements
+LVM itself does not need any special hardware and memory requirements
 are very low.
 
 
 Bootloader
 ~~~~~~~~~~
 
-We install two boot loaders by default. The first partition contains
-the standard GRUB boot loader. The second partition is an **E**FI **S**ystem
-**P**artition (ESP), which makes it possible to boot on EFI systems.
+Two boot loaders are installed by default. The first partition
+contains the standard GRUB boot loader. The second partition is an
+**E**FI **S**ystem **P**artition (ESP) in order to be able to boot on
+EFI systems.
 
+Create a Volume Group
+~~~~~~~~~~~~~~~~~~~~~
 
-Creating a Volume Group
-~~~~~~~~~~~~~~~~~~~~~~~
-
-Let's assume we have an empty disk `/dev/sdb`, onto which we want to
-create a volume group named ``vmdata''.
+This example assumes and empty disk `/dev/sdb` onto which a volume
+group named ``vmdata'' is to be created.
 
 CAUTION: Please note that the following commands will destroy all
 existing data on `/dev/sdb`.
 
 First create a partition.
+----
+# sgdisk -N 1 /dev/sdb
+----
 
- # sgdisk -N 1 /dev/sdb
-
-
-Create a **P**hysical **V**olume (PV) without confirmation and 250K
-metadatasize.
-
- # pvcreate --metadatasize 250k -y -ff /dev/sdb1
+Create a **P**hysical **V**olume (PV) without confirmation and a
+metadatasize of `250K`.
+----
+# pvcreate --metadatasize 250k -y -ff /dev/sdb1
+----
 
 
 Create a volume group named ``vmdata'' on `/dev/sdb1`
 
- # vgcreate vmdata /dev/sdb1
+----
+# vgcreate vmdata /dev/sdb1
+----
 
 
-Creating an extra LV for `/var/lib/vz`
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+[[logical_volume_creation]]
+Create a logical volume for `/var/lib/vz`
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-This can be easily done by creating a new thin LV.
+This can be easily done by creating a new thin logical volume.
 
+----
  # lvcreate -n <Name> -V <Size[M,G,T]> <VG>/<LVThin_pool>
+----
 
 A real world example:
 
+----
  # lvcreate -n vz -V 10G pve/data
+----
 
-Now a filesystem must be created on the LV.
+A file system must be created on the new logical volume.
 
- # mkfs.ext4 /dev/pve/vz
+----
+# mkfs.ext4 /dev/pve/vz
+----
 
-At last this has to be mounted.
+At last mount the file system.
 
 WARNING: be sure that `/var/lib/vz` is empty. On a default
 installation it's not.
 
-To make it always accessible add the following line in `/etc/fstab`.
-
- # echo '/dev/pve/vz /var/lib/vz ext4 defaults 0 2' >> /etc/fstab
+In order to be automatically mounted on a reboot add the following
+line in `/etc/fstab` by running:
 
+----
+# echo '/dev/pve/vz /var/lib/vz ext4 defaults 0 2' >> /etc/fstab
+----
 
 Resizing the thin pool
 ~~~~~~~~~~~~~~~~~~~~~~
 
-Resize the LV and the metadata pool can be achieved with the following
-command.
+Resizing the LV and the metadata of the pool can be achieved with the
+following command.
 
- # lvresize --size +<size[\M,G,T]> --poolmetadatasize +<size[\M,G]> <VG>/<LVThin_pool>
+----
+# lvresize --size +<size[\M,G,T]> --poolmetadatasize +<size[\M,G]> <VG>/<LVThin_pool>
+----
 
-NOTE: When extending the data pool, the metadata pool must also be
-extended.
+NOTE: The metadata pool must be extended too when the data pool is
+extenced.
 
 
 Create a LVM-thin pool
 ~~~~~~~~~~~~~~~~~~~~~~
 
-A thin pool has to be created on top of a volume group.
-How to create a volume group see Section LVM.
+A thin pool must be created on top of a volume group. How to create a
+volume group is described in <<logical_volume_creation>>.
 
- # lvcreate -L 80G -T -n vmstore vmdata
+----
+# lvcreate -L 80G -T -n vmstore vmdata
+----
-- 
2.20.1