LVM/liblvm

libLVM Project Plan

<DRAFT>

Introduction / Problem Description

LVM is currently being used by other software projects. These projects interface with LVM by calling the LVM commandline either by invoking a shell or calling the string-based liblvmcmd. These interface methods are problematic for the following reasons:

1. Interacting with LVM requires creating and parsing command line strings
2. Error handling is problematic
3. High level CLI functionality may not meet the needs of all consumers
4. CLI is complex, often leading to improper use or confusion
5. The command line utilities have to be called with a system call type interface which could lead into problems. Strict string analysis and type checking is needed altogether with escaping values.
6. Return values have to be parsed to get the wanted information. This requires to use the locale C to be able to parse the output.
7. If an error occurs in a command line tool, used by an application with a system call type interface, the application only knows what happened if it is parsing error messages. Because of LANG=C for the call, the error message is in english but might not be useful for the user with a different language. It might be needed that the application understands what went wrong to propose a solution. There might also be the need to process lvm commands without user interaction (think of kickstart install).
8. Changes in the output format of informational output or error messages will lead into parsing problems.

libLVM proposes to create a real API for use by application programs to overcome at least some of the aforementioned limitations.

libLVM features will be driven by the needs of the known primary consumers of the API which are anaconda, system-config-storage, libvirt, and others as detailed in Appendix A. Note that some requests from existing LVM consumers in context of libLVM are really requests for LVM design changes or functionality. While important to meeting the needs of libLVM consumers, many of these issues are orthogonal to libLVM and so will be listed separately, and most likely not appear in the intial release.

One of the main drivers of libLVM is the anaconda storage rewrite, and specifically, system-config-storage. Much of the contents of the initial release of libLVM centers around supporting this effort.

Architecture

There are at least two possible approaches to libLVM, and each have their own merits.

One approach is to have libLVM strictly mimic the LVM commandline, albeit in a more well-defined way than the existing string-based liblvmcmd library. A second approach is a more low-level API, based on LVM objects (the PV, VG, and LV), with finer-grained operations on these objects focusing on a get/set paradigm of object attributes.

In the first approach, where the library simply mimics the commandline, things like PVs, VGs, and LVs would be specified simply by their names, as is done on the commandline. The most common options for each operation would be supported, and other options could be added over time. Operations which would result in ambiguous or hard to handle errors may be restricted or broken into multiple operations such that the error is less ambiguous (for example, a pvcreate operation may be restricted to a single PV, and the caller would just call the pvcreate operation multiple times). This approach has the following advantages:

1. It is most likely the fastest way to produce a library
2. It should solve the problem of misuse of LVM as the operations will be more defined
3. All the locking is handled internal to the operation, and no locks are held upon return from an operation
4. Use of parameter structures isolates application memory from libLVM

The disadvantages of the commandline approach are:

1. Operations are more high-level, as a result errors are more coarse
2. Code does not look as elegant as with the object based approach
3. More overhead as attributes need to be copied into structures to be read

The second approach, the object based approach, is different from the first approach to mimicing the commandline in that the objects are more low-level, and many, if not all, LVM operations are implemented simply by modifying one or more attributes of the LVM objects. While the object based approach may certainly have similarities to the commandline approach, the key difference is that handles to objects are obtained first, then attributes are queried or changed based on these handles. The command line approach simply names things based on device paths and APIs are the operations themselves.

Advantages to the object based approach are:

1. Low-level design will most likely facilitate formation of other LVM tools
2. Provides very fine-grained errors
3. Same object API will be used with existing LVM commandline tools

Disadvantages of the object based approach are:

1. Might take longer to get a first release of libLVM
2. Most likely harder for a consumer to program, as it will diverge from the commandline that they are most likely accustomed to
3. Locking is tied to an object handle rather than an operation. This makes it possible for an application to hold a lock longer than intended resulting in programming errors such as deadlock, holding too many open files, etc
4. Certain commandline operations might require more API calls in an object-based approach than they would in a commandline approach.

At this stage in the project, no firm decision has been made on the long-term approach to libLVM. However, the first release will most likely focus on the commandline approach. A functional specification will accompany this doucment and outline the details of this approach.

libLVM Release content

The functionality of libLVM will be divided into releases, with the first release targetting the most widely used functionality of existing consumers.

The first release of libLVM will contain the equivalent of the following CLI commands:

1. pvs: pv_name,vg_name,pv_size,pv_free,pv_attr,pv_fmt,pv_uuid,vg_extent_size, dev_size
2. vgs: vg_name,vg_attr,vg_size,vg_extent_size,vg_free_count,max_lv,max_pv,vg_uuid,vg_free_count
3. lvs: lv_name,vg_name,stripes,stripesize,lv_attr,lv_uuid,devices,origin,snap_percent,seg_start,seg_size,vg_extent_size,lv_size,vg_free_count,vg_attr
4. "pvcreate -ff -y -f pvname"
5. "pvremove -ff -y pvname"
6. "vgcreate -v -An -s pesize vgname pvname"
7. "vgremove -f vgname
8. "lvcreate -v -L lvsize -n lvname -An vgname"
9. "lvremove -f -v"
10. "vgchange -ay -v"
11. "vgchange -an -v"
12. "vgscan -v"
13. "vgmknodes -v"
14. "vgextend vgname pvname"
15. "vgreduce vgname pvname"
16. --config option with devices filters for various commands

In addition to the above functionalty used by existing consumers, the following LVM RFEs were noted in discussions with existing LVM CLI consumers as items of interest. The first release of libLVM may or may not contain any of these items as they are open to debate, and they may not be possible in the timeframe of the first libLVM release.

1. Allow duplicate volumes to be activated for virtualized guest image manipulation (http://bugzilla.redhat.com/show_bug.cgi?id=207470)
2. Provide an interface for efficient scanning of disks for LVM metadata.

LVM should take as input one or more devices to scan and not try to figure out the set of devices as it does today in its dev-cache subsystem. In this new mode of operation, with LVM's dev-cache disabled, it will be the application's responsibility to handle any errors or incomplete information that results from limiting LVM to a set of devices. The following BZs relate to the scanning problem: (5.3 bz ON_QA) http://bugzilla.redhat.com/show_bug.cgi?id=461771, http://bugzilla.redhat.com/show_bug.cgi?id=277271, http://bugzilla.redhat.com/show_bug.cgi?id=464877, http://bugzilla.redhat.com/show_bug.cgi?id=464724

1. Cloning volumes: http://bugzilla.redhat.com/show_bug.cgi?id=409031

The remaining LVM functionality group of lowest priority is listed below. This functionality was found in some consumers but was prioritized to a later release of libLVM.

1. lvcreate --snapshot --name lvname --size lvsize origin_path
2. lvresize -An -L lvsize -v lvname
3. vgcreate --physicalextentsize pesize -c clustered vgname
4. vgchange -c clustered vgname
5. lvchange -an path; lvchange -ay path
6. lvreduce -f -L size lvpath
7. lvextend -L lvsize path
8. /etc/lvm/lvm.conf: get/set locking_type

Deliverables

Deliverables will be a shared object library with matching header file. Documentation will be included and may be in the form of header file comments, coding examples, man pages, and/or web pages.

Responsibilities

The following people are identified as having a significant role in libLVM.

• Alasdair Kergon (agk@redhat.com): libLVM design review, signoff
• Thomas Woerner (twoerner@redhat.com): system-config-storage requirements, libLVM coding, unit testing, design
• Petr Rockai (prockai@redhat.com): libLVM coding, unit testing, design
• Dave Wysochanski (dwysocha@redhat.com): libLVM coding, unit testing, design other members of LVM team (TBD): libLVM coding, unit testing
• Dave Lehman (dlehman@redhat.com): libLVM scanning requirements
• Peter Jones (pjones@redhat.com): anaconda requirements, signoff
• David Zeuthen <davidz@redhat.com>: Device-kit disks requirements, signoff
• Tom Coughlan <coughlan@redhat.com>: libLVM planning, milestone signoff

Schedule

The general timeframe for all libLVM deliverables will be Fedora 11: http://fedoraproject.org/wiki/Releases/11/Schedule

As of Nov 2008, I have received no detailed input regarding dates of specific libLVM functionality needs. Thus, the below timeline with deliverables is subject to change. Based on previous fedora releases, and the fact that F10 was just released at the end of Nov 2008, we will target libLVM development to conclude by April, 2009.

Milestones in the project are as follows:

Project Plan
11/18/2008 - 11/26/2008: Draft project plan</tr>
12/02/2008 - 12/02/2008: Draft functional spec due
11/26/2008 - 12/12/2008: Plan review; update project plan and functional spec
12/12/2008 - 12/16/2008: Updated plan due with final functional spec
12/16/2008 - 12/22/2008: Final plan approval; monthly status review
01/01/2009 - 04/01/2009: libLVM development
01/26/2009 - 01/26/2009: Monthly status review
02/23/2009 - 02/23/2009: Monthly status review
03/30/2009 - 03/30/2009: Monthly status review

Implementation tasks will focus on a specific portion of libLVM and will be broken into no more than 2 week increments. Tasks will begin after plan approval, tenatively starting 1/5/2009.

Implementation Tasks
01/05/2009 - xx/xx/2009: Initial library build and initialization
xx/xx/2009 - xx/xx/2009: configuration (/etc/lvm.conf)
xx/xx/2009 - xx/xx/2009: scanning
xx/xx/2009 - xx/xx/2009: scanning
xx/xx/2009 - xx/xx/2009: pvs
xx/xx/2009 - xx/xx/2009: vgs
xx/xx/2009 - xx/xx/2009: lvs
xx/xx/2009 - xx/xx/2009: pvcreate
xx/xx/2009 - xx/xx/2009: Improve error codes / handling
02/15/2009 - 02/21/2009: Unit test existing functionality
xx/xx/2009 - xx/xx/2009: vgcreate
xx/xx/2009 - xx/xx/2009: lvcreate
xx/xx/2009 - xx/xx/2009: pvremove
xx/xx/2009 - xx/xx/2009: vgremove
xx/xx/2009 - xx/xx/2009: lvremove
xx/xx/2009 - xx/xx/2009: vgchange -ay, -an
xx/xx/2009 - xx/xx/2009: vgextend
xx/xx/2009 - xx/xx/2009: vgreduce
03/22/2009 - 03/31/2009: Final unit testing

Outstanding Issues

• Translation of LVM error messages

twoerner: Investigate transifex for translation of error messages.

• Require 'force' parameter to API commands

Appendix A: Per consumer LVM functionality usage/needs

Anaconda

• "pvs --noheadings --units b --nosuffix --options pv_name,vg_name,dev_size"
• "pvremove -ff -y -v pvname"
• "pvcreate -ff -y -v pvname"
• "pvcreate -ff -y -v node"
• "vgs --noheadings --units b --nosuffix \

--options vg_name,vg_size,vg_extent_size,vg_free"

• "vgcreate -v -An -s pesize vgname"
• "vgremove -v vgname"
• "vgscan -v"
• "vgmknodes -v"
• "vgchange -ay -v"
• "vgchange -an -v"
• "lvs --noheadings --units b --nosuffix --separator \

--options vg_name,lv_name,attr

• "lvdisplay -C --units b vg_name,lv_name,lv_size,origin"
• "lvcreate -v -L lvsize -n lvname -An vgname"
• "lvremove -f -v"
• "lvresize -An -L lvsize -v"

system-config-storage

• All functionality as listed for anaconda.
• Allow duplicate volumes to be activated for virtualized guest image

manipulation. - https://bugzilla.redhat.com/show_bug.cgi?id=207470

• Provide an interface for efficient scanning of disks for LVM metadata

(Needs more detail / bz)

libvirt

• "vgchange -ay", "vgchange -an"
• lvs --separator , --noheadings --units b --unbuffered --nosuffix --options "l

v_name,uuid,devices,seg_size,vg_extent_size" VGNAME

• pvs --noheadings -o pv_name,vg_name
• vgcreate
• pvcreate
• vgs --separator : --noheadings --units b --unbuffered --nosuffix --options "v

g_size,vg_free" VGNAME

• vgremove -f
• pvremove
• lvcreate --name LVNAME -L SIZE
• lvremove -f
• vgscan
• Cloning volumes: https://bugzilla.redhat.com/show_bug.cgi?id=409031

conga (rhel5 extraction)

• pvs --options pv_name,vg_name,pv_size,pv_free,pv_attr,pv_fmt,pv_uuid,vg_exten

t_size

• lvs --units b --options lv_name,vg_name,stripes,stripesize,lv_attr,lv_uuid,devices,origin,snap_percent,seg_start,seg_size,vg_extent_size,lv_size,vg_free_coun

t,vg_attr

• pvdisplay -c
• vgs -o vg_name,vg_attr,vg_size,vg_extent_size,vg_free_count,max_lv,max_pv,vg_

uuid

• lvsdisplay -c --units b
• lvs -o lv_name,vg_name,origin
• pvcreate -y -f path
• pvremove -y -f path
• vgcreate --physicalextentsize pesize -c clustered vgname
• vgremove vgname
• vgextend vgname pv_path
• vgreduce vgname pv_path
• vgchange -c clustered vgname
• lvcreate --name lvname --size lvsize vgname
• lvcreate --snapshot --name lvname --size lvsize origin_path
• lvchange -an path; lvchange -ay path
• lvremove --force path
• lvreduce -f -L size lvpath
• lvextend -L lvsize path
• /etc/lvm/lvm.conf: get/set locking_type