Storage module manages all aspects of storage. Supports partition
tables, LVM, software raid, ATA-raid, multipath, iSCSI targets,
dm-crypt, md-crypt, filesystems, their properties, mounts,
...
Currently, as of version 1.0, it supports LVM, partition
tables, software RAID, ext2/3, swap, GFS and mountpoints.
Module name: “storage”
Module version: 1.0
See Modules - Common API for general module description.
Storage module has six objects defined, and they describe all aspects of storage.
There are three main objects:
mappers map source BDs to target BDs (Volume Group, Partition Table, Raids, multipath, ...)
targets are block devices exported by the mapper (Logical Volume, partition, Raid Volumes, ...)
BD content is data that lives on target
There are also:
mapper templates, used to create new mappers
block device templates, user to create new block devices
content templates, used to replace existing content of block devices
All functions might fail with generic error (-1), see Modules - Common API for error description, or one of Storage Module Specific:
1 – mid-air collision
Every object has a state indicator
associated with it. Before anything is committed to disk, storage is
probed and local state indicator is calculated. Local indicator is
compared with the one committed by client, if different, mid-air
error is raised. This prevents accidental data destruction.
2 – validation error
Every property has constraints
associated with it. If property is modified, and it is not within
valid constraints, validation error is returned, before anything is
committed to disk.
3 – umount error
It will happen in the case of umount
failure.
4 – clvmd not running
Clustered Volume Groups need clvmd
daemon running, and yet clvmd is not running.
Storage module
will try to start it. On failure, this error will be raised.
User
should either start clvmd, or mark VG non-clustered.
In order to
start clvmd:
1. lvm2-cluster needs to be installed
2. cluster
infrastructure needs to be started
3. clvmd should be started
(service clvmd start)
5 – cluster not quorate
LVM is configured to use cluster
locking mechanism, but cluster is not quorate. That would cause LVM
operations to hang until quorum is regained. User should make
cluster quorate before continuing.
6 – cluster locking not enabled
LVM is not configured to use cluster
locking mechanism, but some volumes are marked clustered.
User should enable cluster locking.
7 – cluster not running on node
LVM is configured to use cluster
locking mechanism, but cluster is not running on local node.
Functions:
APIs
Get supported API versions. See Modules - Common API for description.
report
Assemble all info into a single report.
No input variables.
Output variables:
- “mapper_templates”
(list_xml) – list of <mapper_template/>s,
if any, see get_mapper_templates function
- “mapper_ids”
(list_xml) – list of IDs in format <mapper_id
mapper_type=”type” mapper_id=”ID”/>
- “mappers”
(list_xml) – list of all <mapper/>s
on the system
On failure:
- No special errors defined, only generic ones
might get returned.
get_mapper_templates
Retrieve all mapper templates on the system. If “mapper_type” is specified, retrieve mapper templates of specified type only.
Input variables:
- “mapper_type” (string) – optional,
if specified, retrieve mapper templates of specified type
Output variables:
- “mapper_templates”
(list_xml) – list of <mapper_template/>s,
if any
On failure:
- No special errors defined, only generic ones
might get returned
get_mapper_ids
Retrieve “mapper_id”s of all mappers on the
system. If “mapper_type” is specified, retrieve “mapper_id”s
of specified type only.
Mapper id can be used to retrieve
mapper using “get_mappers” function.
Input variables:
- “mapper_type” (string) – optional,
if specified, retrieve IDs of mappers of specified type, otherwise,
return all mapper_ids
Output variables:
- “mapper_ids” (list_xml) –
list of IDs in format <mapper_id mapper_type=”type”
mapper_id=”ID”/>
On failure:
- No special errors defined, only
generic ones might get returned
get_mappers
Retrieve all mappers on the system. “mapper_type” and “mapper_id” can be used to limit the scope of search.
Input variables:
- “mapper_type” (string) – optional,
if specified, retrieve IDs of mappers of specified type
-
“mapper_id” (string) – optional, if specified, retrieve only
mapper with specified ID
Output variables:
- “mappers” (list_xml) –
list of <mapper/>s
matching search criteria
On failure:
- No special errors defined, only
generic ones might get returned
create_mapper
Create a new mapper.
Mappers are created by
submitting <mapper_template/>
using this function. Available mapper templates are retrieved using
“get_mapper_templates” function.
Input variables:
- “mapper” (xml) – modified
<mapper_template/>
by which a new mapper will be created
Output variables:
- “mapper” (xml) – newly
created <mapper/>
On failure:
- Any of errors specified above
modify_mapper
Modify properties of already existing mapper.
Input variables:
- “mapper” (xml) – modified <mapper/>
to be changed on disk
Output variables:
- “mapper” (xml) –
<mapper/> with committed
changes
On failure:
- Any of errors specified above
add_mapper_sources
Add new sources to mapper.
Source addition
procedure:
1 – retrieve mapper
2 – extract one or more
block devices from <new_sources/> tag
3 – submit block
devices, from 2, and mapper attributes, using this function
Input variables:
- “bds” (list_xml) – list
of <block_device/>s, from
mapper's <new_sources/> tag, to be added as sources
-
“mapper_type” (string) – type of mapper to which new sources
are to be added
- “mapper_id” (string) – ID of mapper to
which new sources are to be added
- “mapper_state_ind”
(string) – state indicator of mapper to which new sources are to
be added
Output variables:
- “mapper” (xml) –
<mapper/> with new sources
added
On failure:
- Any of errors specified above
remove_mapper_source
Remove source from mapper.
Source removal
procedure:
1 – retrieve mapper
2 – extract block
device, which has alternative content, from <sources/> tag
3 – submit block
device, from 2, and mapper attributes, using this function
Input variables:
- “bd” (xml) –
<block_device/>, from
mapper's <sources/> tag, to be removed
-
“mapper_type” (string) – type of mapper from which source
is to be removed
- “mapper_id” (string) – ID of mapper from
which source is to be removed
- “mapper_state_ind”
(string) – state indicator of mapper from which source is to
be removed
Output variables:
- “mapper” (xml) –
<mapper/> with source
removed
On failure:
- Any of errors specified above
remove_mapper
Remove mapper. Be warned that all targets will be
removed, including their content.
Mapper is removable if its
“removable” property is “true”.
Input variables:
- “mapper” (xml) – mapper to be
removed
No output variables
On failure:
- Any of errors specified above,
especially unmount error if content of one of targets fails to
unmount
create_bd
Create new block device.
Block devices are
created by submitting <block_device_template/>
from <new_targets/> of <mapper/>,
using this function.
<block_device_template/>'s
properties and content can be modified before submission.
Input variables:
- “bd” (xml) – modified
<block_device_template/>
by which a new block device will be created
Output variables:
- “bd” (xml) – newly
created <block_device/>
-
“mapper” (xml) – mapper with new target added
On failure:
- Any of errors specified above
get_bd
Get a block device by its path.
Block devices can
also be retrieved by extraction of <block_device/>
from <mapper/>.
Input variables:
- “path” (string) – path to retrieve
block device for
Output variables:
- “bd” (xml) –
<block_device/> residing on
“path”
On failure:
- Any of errors specified above
modify_bd
Modify properties of block device, its content, or
replace content.
See <block_device/>
and <content/> for more
info.
Input variables:
- “bd” (xml) – modified
<block_device/> to be changed
on disk
Output variables:
- “bd” (xml) – modified
<block_device/>
On failure:
- Any of errors specified above,
especially unmount error if content fails to unmount
remove_bd
Remove block device. Be warned that its content will
be removed as well, destroying data!
Block device is removable
if its “removable” property is “true”.
Input variables:
- “bd” (xml) – <block_device/>
to be removed
Output variables:
- “mapper” (xml) – block
device's <mapper/> with
target removed
On failure:
- Any of errors specified above,
especially unmount error if content fails to unmount
enable_clustered_lvm
Enable LVM's cluster locking. It is an error to call this function if lvm2-cluster is not installed.
No input variables.
No output variables.
On failure:
- No special errors defined, only generic ones
might get returned.
disable_clustered_lvm
Disable LVM's cluster locking. It is an error to call this function if lvm2-cluster is not installed.
No input variables.
No output variables.
On failure:
- No special errors defined, only generic ones
might get returned.