Mapper is anything that imports block devices on one side, and
exports block devices on the other side, performing some mapping or
data manipulation.
Mappers abstract Volume Groups, Partition
Tables, RAIDs (Software and ATA), Multipath, dm-crypt, ... .
There
is also a special Mapper that doesn't import anything, and exports
local and remote physical Hard Drives.
Imported block devices are called “sources”, exported ones are called “targets”; programs write data to targets, mapper writes to sources.
Available mapper types (“mapper_type” see bellow):
“hard_drives” - Local and remote hard drives (no sources, just targets)
“volume_group” - Volume Group
“partition_table” - Partition Table
“multipath” - dm-multipath implementation of multipath
“mdraid” - Software RAID
“ataraid” - ATA-RAID
“crypto” - encrypting mappers (dm-crypt and cryptoloop)
Mappers are manipulated in different ways:
Existing mappers are retrieved using “get_mappers” function.
Mappers are created by submitting <mapper_template/> to Storage Module using “create_mapper” function. Mapper templates are retrieved using “get_mapper_templates” function.
Properties are changed by modifying <properties/> tag, see bellow, and submitting <mapper/> to Storage Module using “modify_mapper” function.
New sources are added by submitting <block_device/>s
from <new_sources/>, see below, to Storage Module using
“add_mapper_sources” function.
It is module's responsibility to insert, into <new_sources/>,
only those block devices which are appropriate to become this
mapper's sources.
For some mapper_types, it is also possible to
add new source manipulating <content/>
of <block_device/> of other
mappers.
New targets are created by submitting <block_device_template/> from <new_targets/>, see below, to Storage Module using “create_bd” function.
Mappers are removed by submitting <mapper/> to Storage Module using “remove_mapper” function. Operation will succeed only if mapper's “removable” property is “true”.
Mapper XML description:
<mapper mapper_id="unique ID" mapper_type="mapper type" state_ind="hashed properties"> <properties/> <sources/> <targets/> <new_sources/> <new_targets/> </mapper>
Every mapper has “mapper_id”, that uniquely identifies it
in a managed system.
It also has a “mapper_type” and
“state_ind”. State indicator “state_ind” is a hashed string
of mapper properties; if something changes within mapper, its state
indicator will change as well. It is used to detect mid-air
collisions.
<properties/> tag, which has variables
for children.
Some properties can be mutable; modifying them and
sending <mapper/> to Storage Module will commit changes to the
disk.
Every “mapper_type” has different set of properties
defined; some of them will be present in all mappers, eg
“removable”. See descriptions of respective LINKME mappers.
Example of properties for Volume Groups:
<properties> <var mutable="false" name="attrs" type="string" value="wz—n-"/> <var mutable="true" name="clustered" type="boolean" value="false"/> <var mutable="false" name="extent_size" type="int" value="33554432"/> <var mutable="false" name="extents_free" type="int" value="1374"/> <var mutable="false" name="extents_total" type="int" value="2366"/> <var mutable="false" name="extents_used" type="int" value="992"/> <var mutable="false" name="max_lvs" type="int" value="256"/> <var mutable="false" name="max_pvs" type="int" value="256"/> <var mutable="false" name="removable" type="boolean" value="true"/> <var mutable="false" name="uuid" type="string" value="di8aFc-RXYt-iyoK-ah0B-e10i-EiGb-5Lum1N"/> <var mutable="false" name="vgname" type="string" value="VG_main"/> </properties>
<sources/> tag, which has <block_device/>s for children. Content of those block devices will be LINKME “mapper_source”s of this mapper. Source block devices are exported by some other mappers.
<new_sources/> tag, which has <block_device/>s for children. These block devices can become new sources of this mapper.
<targets/> tag, which has <block_device/>s for children. Target block devices are block devices exported by this mapper, and can have anything for a content.
<new_targets/> tag, which has <block_device_template/>s for children. These templates are used for creation of new targets of this mapper.