Bug 1996299

Summary: LVM2 Documentation insufficiencies.
Product: [Community] LVM and device-mapper Reporter: Stirling <swestrup>
Component: lvm2Assignee: LVM Team <lvm-team>
lvm2 sub component: Manual pages and Documentation QA Contact: cluster-qe <cluster-qe>
Status: NEW --- Docs Contact:
Severity: low    
Priority: unspecified CC: agk, heinzm, jbrassow, msnitzer, prajnoha, zkabelac
Version: unspecifiedFlags: pm-rhel: lvm-technical-solution?
pm-rhel: lvm-test-coverage?
Target Milestone: ---   
Target Release: ---   
Hardware: Unspecified   
OS: Unspecified   
Whiteboard:
Fixed In Version: Doc Type: If docs needed, set a value
Doc Text:
Story Points: ---
Clone Of: Environment:
Last Closed: Type: Bug
Regression: --- Mount Type: ---
Documentation: --- CRM:
Verified Versions: Category: ---
oVirt Team: --- RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: --- Target Upstream Version:
Embargoed:

Description Stirling 2021-08-21 17:00:52 UTC 
Description of problem:
Current LVM2 documentation lacks information needed by folks new to the project.

For example. The main document accessed by 'man lvm' details how to create an LV as a virtual device, but does NOT mention what the device will be called in the /dev/ subdirectory. One has to infer this from examples given.

Secondly, lvcreate has a --type option, and the main lvm documentation says that for information on types linear, raid0, raid1, ... ect, see the lvmraid documentation. However the lvmraid manpage does not actually document the linear option anywhere.

Finally, there are numerous places in the main lvm manpage that refers to various storage technologies (raid, thin-pools, caches, etc) long before there is any indication of what these are or when one may want to use them. Since these items are LVM specific (or their implementations are). It would be helpful for the introductory information at the beginning to at least introduce these concepts and give pointers to the more in-depth documentation so that someone new to using LVM2 can more easily determine what information is in the scope of their current project.
Comment 1 Zdenek Kabelac 2021-08-21 19:12:31 UTC 
Quick help for some issues:

/dev/volumegroupname/logicalvolumename  is described in "VALID NAMES" section of man lvm.

---

Usage of '--types' option is specific to individual types:

aka 'raid' type,  linear,  thin....

so segtypes have 'individual' man pages like 'man lvmraid,  man lvmthin, man lvmcache...'
linear & stripe are some 'basic' types.

However actual types are 'kernel' type are described in kernel documentation 
(note: only some selected types do have lvm2 support)

https://www.kernel.org/doc/html/latest/admin-guide/device-mapper/index.html

Lvm2 does provide it's 'copy' of those target descriptions  - but it does not seem to be packages and this should likely be fixed - although given kernel link is always more authoritative.

---

For rather a high-level abstract - it's likely better to follow RHEL administration guides like i.e.:

https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html-single/configuring_and_managing_logical_volumes/index#logical_volumes-configuring-and-managing-logical-volumes

as man pages targets more quick' look for option description.