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

LIST FILTERING

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

AUTHORS

295       Daniel P. Berrange <berrange@redhat.com>
296

COPYRIGHT

298       Copyright (C) 2006-2009 Red Hat Copyright (C) 2006-2009 Daniel P.
299       Berrange
300

LICENSE

302       This program is free software; you can redistribute it and/or modify it
303       under the terms of either the GNU General Public License as published
304       by the Free Software Foundation (either version 2 of the License, or at
305       your option any later version), or, the Artistic License, as specified
306       in the Perl README file.
307