1# Logical Volumes {#logical_volumes} 2 3The Logical Volumes library is a flexible storage space management system. It provides creating and managing virtual 4block devices with variable size. The SPDK Logical Volume library is built on top of @ref blob. 5 6## Terminology {#lvol_terminology} 7 8### Logical volume store {#lvs} 9 10* Shorthand: lvolstore, lvs 11* Type name: struct spdk_lvol_store 12 13A logical volume store uses the super blob feature of blobstore to hold uuid (and in future other metadata). 14Blobstore types are implemented in blobstore itself, and saved on disk. An lvolstore will generate a UUID on 15creation, so that it can be uniquely identified from other lvolstores. 16By default when creating lvol store data region is unmapped. Optional --clear-method parameter can be passed 17on creation to change that behavior to writing zeroes or performing no operation. 18 19### Logical volume {#lvol} 20 21* Shorthand: lvol 22* Type name: struct spdk_lvol 23 24A logical volume is implemented as an SPDK blob created from an lvolstore. An lvol is uniquely identified by 25its UUID. Lvol additional can have alias name. 26 27### Logical volume block device {#lvol_bdev} 28 29* Shorthand: lvol_bdev 30* Type name: struct spdk_lvol_bdev 31 32Representation of an SPDK block device (spdk_bdev) with an lvol implementation. 33A logical volume block device translates generic SPDK block device I/O (spdk_bdev_io) operations into the 34equivalent SPDK blob operations. Combination of lvol name and lvolstore name gives lvol_bdev alias name in 35a form "lvs_name/lvol_name". block_size of the created bdev is always 4096, due to blobstore page size. 36Cluster_size is configurable by parameter. Size of the new bdev will be rounded up to nearest multiple of 37cluster_size. By default lvol bdevs claim part of lvol store equal to their set size. When thin provision 38option is enabled, no space is taken from lvol store until data is written to lvol bdev. 39By default when deleting lvol bdev or resizing down, allocated clusters are unmapped. Optional --clear-method 40parameter can be passed on creation to change that behavior to writing zeroes or performing no operation. 41 42### Thin provisioning {#lvol_thin_provisioning} 43 44Thin provisioned lvols rely on dynamic cluster allocation (e.g. when the first write operation on a cluster is performed), only space 45required to store data is used and unallocated clusters are obtained from underlying device (e.g. zeroes_dev). 46 47Sample write operations of thin provisioned blob are shown on the diagram below: 48 49 50 51Sample read operations and the structure of thin provisioned blob are shown on the diagram below: 52 53 54 55### Snapshots and clone {#lvol_snapshots} 56 57Logical volumes support snapshots and clones functionality. User may at any given time create snapshot of existing 58logical volume to save a backup of current volume state. When creating snapshot original volume becomes thin provisioned 59and saves only incremental differences from its underlying snapshot. This means that every read from unallocated cluster 60is actually a read from the snapshot and every write to unallocated cluster triggers new cluster allocation and data copy 61from corresponding cluster in snapshot to the new cluster in logical volume before the actual write occurs. 62 63The read operation is performed as shown in the diagram below: 64 65 66The write operation is performed as shown in the diagram below: 67 68 69User may also create clone of existing snapshot that will be thin provisioned and it will behave in the same way as logical volume 70from which snapshot is created. There is no limit of clones and snapshots that may be created as long as there is enough space on 71logical volume store. Snapshots are read only. Clones may be created only from snapshots or read only logical volumes. 72 73A snapshot can be removed only if there is a single clone on top of it. The relation chain will be updated accordingly. 74The cluster map of clone and snapshot will be merged and entries for unallocated clusters in the clone will be updated with 75addresses from the snapshot cluster map. The entire operation modifies metadata only - no data is copied during this process. 76 77### External Snapshots 78 79With the external snapshots feature, clones can be made of any bdev. These clones are commonly called *esnap clones*. 80Esnap clones work very similarly to thin provisioning. Rather than the back device being an zeroes device, the external snapshot 81bdev is used as the back device. 82 83 84 85A bdev that is used as an external snapshot cannot be opened for writing by anything else so long as an esnap clone exists. 86 87A bdev may have multiple esnap clones and esnap clones can themselves be snapshotted and cloned. 88 89### Inflation {#lvol_inflation} 90 91Blobs can be inflated to copy data from backing devices (e.g. snapshots) and allocate all remaining clusters. As a result of this 92operation all dependencies for the blob are removed. 93 94 95 96### Decoupling {#lvol_decoupling} 97 98Blobs can be decoupled from their parent blob by copying data from backing devices (e.g. snapshots) for all allocated clusters. 99Remaining unallocated clusters are kept thin provisioned. 100Note: When decouple is performed, only single dependency is removed. To remove all dependencies in a chain of blobs depending 101on each other, multiple calls need to be issued. 102 103## Configuring Logical Volumes 104 105There is no static configuration available for logical volumes. All configuration is done through RPC. Information about 106logical volumes is kept on block devices. 107 108## RPC overview {#lvol_rpc} 109 110RPC regarding lvolstore: 111 112```bash 113bdev_lvol_create_lvstore [-h] [-c CLUSTER_SZ] bdev_name lvs_name 114 Constructs lvolstore on specified bdev with specified name. During 115 construction bdev is unmapped at initialization and all data is 116 erased. Then original bdev is claimed by 117 SPDK, but no additional spdk bdevs are created. 118 Returns uuid of created lvolstore. 119 Optional parameters: 120 -h show help 121 -c CLUSTER_SZ Specifies the size of cluster. By default its 4MiB. 122 --clear-method specify data region clear method "none", "unmap" (default), "write_zeroes" 123bdev_lvol_delete_lvstore [-h] [-u UUID] [-l LVS_NAME] 124 Destroy lvolstore on specified bdev. Removes lvolstore along with lvols on 125 it. User can identify lvol store by UUID or its name. Note that destroying 126 lvolstore requires using this call, while deleting single lvol requires 127 using bdev_lvol_delete rpc call. 128 optional arguments: 129 -h, --help show help 130bdev_lvol_get_lvstores [-h] [-u UUID] [-l LVS_NAME] 131 Display current logical volume store list 132 optional arguments: 133 -h, --help show help 134 -u UUID, --uuid UUID show details of specified lvol store 135 -l LVS_NAME, --lvs_name LVS_NAME show details of specified lvol store 136bdev_lvol_rename_lvstore [-h] old_name new_name 137 Change logical volume store name 138 optional arguments: 139 -h, --help show this help message and exit 140``` 141 142RPC regarding lvol and spdk bdev: 143 144```bash 145bdev_lvol_create [-h] [-u UUID] [-l LVS_NAME] [-t] [-c CLEAR_METHOD] lvol_name size 146 Creates lvol with specified size and name on lvolstore specified by its uuid 147 or name. Then constructs spdk bdev on top of that lvol and presents it as spdk bdev. 148 User may use -t switch to create thin provisioned lvol. 149 Returns the name of new spdk bdev 150 optional arguments: 151 -h, --help show help 152 -c, --clear-method specify data clusters clear method "none", "unmap" (default), "write_zeroes" 153bdev_lvol_get_lvols [-h] [-u LVS_UUID] [-l LVS_NAME] 154 Display logical volume list, including those that do not have associated bdevs. 155 optional arguments: 156 -h, --help show help 157 -u LVS_UUID, --lvs_uuid UUID show volumes only in the specified lvol store 158 -l LVS_NAME, --lvs_name LVS_NAME show volumes only in the specified lvol store 159bdev_get_bdevs [-h] [-b NAME] 160 User can view created bdevs using this call including those created on top of lvols. 161 optional arguments: 162 -h, --help show help 163 -b NAME, --name NAME Name of the block device. Example: Nvme0n1 164bdev_lvol_delete [-h] bdev_name 165 Deletes a logical volume previously created by bdev_lvol_create. 166 optional arguments: 167 -h, --help show help 168bdev_lvol_snapshot [-h] lvol_name snapshot_name 169 Create a snapshot with snapshot_name of a given lvol bdev. 170 optional arguments: 171 -h, --help show help 172bdev_lvol_clone [-h] snapshot_name clone_name 173 Create a clone with clone_name of a given lvol snapshot. 174 optional arguments: 175 -h, --help show help 176bdev_lvol_clone_bdev [-h] bdev_name_or_uuid lvs_name clone_name 177 Create a clone with clone_name of a bdev. The bdev must not be an lvol in the lvs_name lvstore. 178 optional arguments: 179 -h, --help show help 180bdev_lvol_rename [-h] old_name new_name 181 Change lvol bdev name 182 optional arguments: 183 -h, --help show help 184bdev_lvol_resize [-h] name size 185 Resize existing lvol bdev 186 optional arguments: 187 -h, --help show help 188bdev_lvol_set_read_only [-h] name 189 Mark lvol bdev as read only 190 optional arguments: 191 -h, --help show help 192bdev_lvol_inflate [-h] name 193 Inflate lvol bdev 194 optional arguments: 195 -h, --help show help 196bdev_lvol_decouple_parent [-h] name 197 Decouple parent of a logical volume 198 optional arguments: 199 -h, --help show help 200bdev_lvol_start_shallow_copy [-h] src_lvol_name dst_bdev_name 201 Make a shallow copy of lvol over a given bdev 202 This RPC starts the operation and returns an identifier that can be used to query the status 203 of the operation with the RPC bdev_lvol_check_shallow_copy. 204 optional arguments: 205 -h, --help show help 206bdev_lvol_check_shallow_copy [-h] operation_id 207 Get shallow copy status 208 optional arguments: 209 -h, --help show help 210bdev_lvol_set_parent [-h] lvol_name snapshot_name 211 Set the parent snapshot of a lvol 212 optional arguments: 213 -h, --help show help 214bdev_lvol_set_parent_bdev lvol_name esnap_name 215 Set the parent external snapshot of a lvol 216 optional arguments: 217 -h, --help show help 218``` 219
