Sys::Virt::StoragePool(3pm)

1Sys::Virt::StoragePool(U3s)er Contributed Perl DocumentatSiyosn::Virt::StoragePool(3)
2
3
4

NAME

6       Sys::Virt::StoragePool - Represent & manage a libvirt storage pool
7

DESCRIPTION

9       The "Sys::Virt::StoragePool" module represents a storage pool managed
10       by libvirt. There are a variety of storage pool implementations for
11       LVM, Local directories/filesystems, network filesystems, disk
12       partitioning, iSCSI, and SCSI.
13

METHODS

15       my $uuid = $pool->get_uuid()
16           Returns a 16 byte long string containing the raw globally unique
17           identifier (UUID) for the storage pool.
18
19       my $uuid = $pool->get_uuid_string()
20           Returns a printable string representation of the raw UUID, in the
21           format 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'.
22
23       my $name = $pool->get_name()
24           Returns a string with a locally unique name of the storage pool
25
26       $pool->is_active()
27           Returns a true value if the storage pool is currently running
28
29       $pool->is_persistent()
30           Returns a true value if the storage pool has a persistent
31           configuration file defined
32
33       my $xml = $pool->get_xml_description()
34           Returns an XML document containing a complete description of the
35           storage pool's configuration
36
37       $pool->create()
38           Start a storage pool whose configuration was previously defined
39           using the "define_storage_pool" method in Sys::Virt.
40
41       $pool->undefine()
42           Remove the configuration associated with a storage pool previously
43           defined with the "define_storage pool" method in Sys::Virt. If the
44           storage pool is running, you probably want to use the "destroy"
45           method instead.
46
47       $pool->destroy()
48           Immediately stop the storage pool.
49
50       $flag = $pool->get_autostart();
51           Return a true value if the storage pool is configured to
52           automatically start upon boot. Return false, otherwise
53
54       $pool->set_autostart($flag)
55           Set the state of the autostart flag, which determines whether the
56           storage pool will automatically start upon boot of the host OS
57
58       $pool->refresh([$flags]);
59           Refresh the storage pool state. Typically this will rescan the list
60           of storage volumes. The $flags parameter is currently unused and if
61           omitted defaults to zero.
62
63       $pool->build([$flags]);
64           Construct the storage pool if it does not exist. As an example, for
65           a disk based storage pool this would ensure a partition table
66           exists.  The $flags parameter allows control over the build
67           operation and if omitted defaults to zero.
68
69       $pool->delete([$flags]);
70           Delete the storage pool. The $flags parameter allows the data to be
71           optionally wiped during delete and if omitted defaults to zero.
72
73       $info = $pool->get_info()
74           Retrieve information about the current storage pool state. The
75           returned hash reference has the following keys
76
77           state
78               The current status of the storage pool. See constants later.
79
80           capacity
81               The total logical size of the storage pool
82
83           allocation
84               The current physical allocation of the storage pool
85
86           available
87               The available space for creation of new volumes. This may be
88               less than the difference between capacity & allocation if there
89               are sizing / metadata constraints for volumes
90
91       my $nnames = $pool->num_of_storage_volumes()
92           Return the number of running volumes in this storage pool. The
93           value can be used as the "maxnames" parameter to
94           "list_storage_vol_names".
95
96       my @volNames = $pool->list_storage_vol_names($maxnames)
97           Return a list of all volume names in this storage pool. The names
98           can be used with the "get_volume_by_name" method.
99
100       my @vols = $pool->list_volumes()
101           Return a list of all volumes in the storage pool.  The elements in
102           the returned list are instances of the Sys::Virt::StorageVol class.
103           This method requires O(n) RPC calls, so the "list_all_volumes"
104           method is recommended as a more efficient alternative.
105
106       my @volumes = $pool->list_all_volumes($flags)
107           Return a list of all storage volumes associated with this pool.
108           The elements in the returned list are instances of the
109           Sys::Virt::StorageVol class. The $flags parameter can be used to
110           filter the list of return storage volumes.
111
112       my $vol = $pool->get_volume_by_name($name)
113           Return the volume with a name of $name. The returned object is an
114           instance of the Sys::Virt::StorageVol class.
115
116       my $vol = $pool->create_volume($xml)
117           Create a new volume based on the XML description passed into the
118           $xml parameter. The returned object is an instance of the
119           Sys::Virt::StorageVol class. If the optional "clonevol" is
120           provided, data will be copied from that source volume
121
122       my $vol = $pool->clone_volume($xml, $clonevol);
123           Create a new volume based on the XML description passed into the
124           $xml parameter. The returned object is an instance of the
125           Sys::Virt::StorageVol class. The new volume will be populated with
126           data from the specified clone source volume.
127

CONSTANTS

129       The following sets of constants may be useful in dealing with some of
130       the methods in this package
131
132   STORAGE POOL DEFINE
133       The following constants can be used to control the behaviour of storage
134       pool define operations
135
136       Sys::Virt::StoragePool::DEFINE_VALIDATE
137           Validate the XML document against the XML schema
138
139   POOL STATES
140       The following constants are useful for interpreting the "state" key
141       value in the hash returned by "get_info"
142
143       Sys::Virt::StoragePool::STATE_INACTIVE
144           The storage pool is not currently active
145
146       Sys::Virt::StoragePool::STATE_BUILDING
147           The storage pool is still being constructed and is not ready for
148           use yet.
149
150       Sys::Virt::StoragePool::STATE_RUNNING
151           The storage pool is running and can be queried for volumes
152
153       Sys::Virt::StoragePool::STATE_DEGRADED
154           The storage pool is running, but its operation is degraded due to a
155           failure.
156
157       Sys::Virt::StoragePool::STATE_INACCESSIBLE
158           The storage pool is not currently accessible
159
160   DELETION MODES
161       Sys::Virt::StoragePool::DELETE_NORMAL
162           Delete the pool without any attempt to scrub data
163
164       Sys::Virt::StoragePool::DELETE_ZEROED
165           Fill the allocated storage with zeros when deleting
166
167   BUILD MODES
168       Sys::Virt::StoragePool::BUILD_NEW
169           Construct a new storage pool from constituent bits
170
171       Sys::Virt::StoragePool::BUILD_RESIZE
172           Resize an existing built storage pool preserving data where
173           appropriate
174
175       Sys::Virt::StoragePool::BUILD_REPAIR
176           Repair an existing storage pool operating in degraded mode
177
178       Sys::Virt::StoragePool::BUILD_NO_OVERWRITE
179           Do not overwrite existing storage pool data
180
181       Sys::Virt::StoragePool::BUILD_OVERWRITE
182           Overwrite existing storage pool data
183
184   CREATE MODES
185       When creating a storage pool it can be built at the same time.  The
186       following values are therefore close to their BUILD counterparts.
187
188       Sys::Virt::StoragePool::CREATE_NORMAL
189           Just create the storage pool without building it.
190
191       Sys::Virt::StoragePool::CREATE_WITH_BUILD
192           When creating new storage pool also perform pool build without any
193           flags.
194
195       Sys::Virt::StoragePool::CREATE_WITH_BUILD_OVERWRITE
196           Create the pool and perform pool build using the BUILD_OVERWRITE
197           flag. This is mutually exclusive to CREATE_WITH_BUILD_NO_OVERWRITE.
198
199       Sys::Virt::StoragePool::CREATE_WITH_BUILD_NO_OVERWRITE
200           Create the pool and perform pool build using the BUILD_NO_OVERWRITE
201           flag. This is mutually exclusive to CREATE_WITH_BUILD_OVERWRITE.
202
203   XML DOCUMENTS
204       The following constants are useful when requesting XML for storage
205       pools
206
207       Sys::Virt::StoragePool::XML_INACTIVE
208           Return XML describing the inactive state of the storage pool.
209

LIST FILTERING

211       The following constants are used to filter object lists
212
213       Sys::Virt::StoragePool::LIST_ACTIVE
214           Include storage pools which are active
215
216       Sys::Virt::StoragePool::LIST_INACTIVE
217           Include storage pools which are inactive
218
219       Sys::Virt::StoragePool::LIST_AUTOSTART
220           Include storage pools which are marked for autostart
221
222       Sys::Virt::StoragePool::LIST_NO_AUTOSTART
223           Include storage pools which are not marked for autostart
224
225       Sys::Virt::StoragePool::LIST_PERSISTENT
226           Include storage pools which are persistent
227
228       Sys::Virt::StoragePool::LIST_TRANSIENT
229           Include storage pools which are transient
230
231       Sys::Virt::StoragePool::LIST_DIR
232           Include directory storage pools
233
234       Sys::Virt::StoragePool::LIST_DISK
235           Include disk storage pools
236
237       Sys::Virt::StoragePool::LIST_FS
238           Include filesystem storage pools
239
240       Sys::Virt::StoragePool::LIST_ISCSI
241           Include iSCSI storage pools
242
243       Sys::Virt::StoragePool::LIST_LOGICAL
244           Include LVM storage pools
245
246       Sys::Virt::StoragePool::LIST_MPATH
247           Include multipath storage pools
248
249       Sys::Virt::StoragePool::LIST_NETFS
250           Include network filesystem storage pools
251
252       Sys::Virt::StoragePool::LIST_RBD
253           Include RBD storage pools
254
255       Sys::Virt::StoragePool::LIST_SCSI
256           Include SCSI storage pools
257
258       Sys::Virt::StoragePool::LIST_SHEEPDOG
259           Include sheepdog storage pools
260
261       Sys::Virt::StoragePool::LIST_GLUSTER
262           Include gluster storage pools
263
264       Sys::Virt::StoragePool::LIST_ZFS
265           Include ZFS storage pools
266
267       Sys::Virt::StoragePool::LIST_VSTORAGE
268           Include VStorage storage pools
269
270       Sys::Virt::StoragePool::LIST_ISCSI_DIRECT
271           Include direct iSCSI pools
272
273   EVENT ID CONSTANTS
274       Sys::Virt::StoragePool::EVENT_ID_LIFECYCLE
275           Storage pool lifecycle events
276
277       Sys::Virt::StoragePool::EVENT_ID_REFRESH
278           Storage pool volume refresh events
279
280   LIFECYCLE CHANGE EVENTS
281       The following constants allow storage pool lifecycle change events to
282       be interpreted. The events contain both a state change, and a reason
283       though the reason is currently unused.
284
285       Sys::Virt::StoragePool::EVENT_DEFINED
286           Indicates that a persistent configuration has been defined for the
287           storage pool
288
289       Sys::Virt::StoragePool::EVENT_STARTED
290           The storage pool has started running
291
292       Sys::Virt::StoragePool::EVENT_STOPPED
293           The storage pool has stopped running
294
295       Sys::Virt::StoragePool::EVENT_UNDEFINED
296           The persistent configuration has gone away
297
298       Sys::Virt::StoragePool::EVENT_CREATED
299           The underlying storage has been built
300
301       Sys::Virt::StoragePool::EVENT_DELETED
302           The underlying storage has been released
303

AUTHORS

305       Daniel P. Berrange <berrange@redhat.com>
306

COPYRIGHT

308       Copyright (C) 2006-2009 Red Hat Copyright (C) 2006-2009 Daniel P.
309       Berrange
310

LICENSE

312       This program is free software; you can redistribute it and/or modify it
313       under the terms of either the GNU General Public License as published
314       by the Free Software Foundation (either version 2 of the License, or at
315       your option any later version), or, the Artistic License, as specified
316       in the Perl README file.
317