Sys::Virt::StorageVol(3pm)

1Sys::Virt::StorageVol(3U)ser Contributed Perl DocumentatiSoyns::Virt::StorageVol(3)
2
3
4

NAME

6       Sys::Virt::StorageVol - Represent & manage a libvirt storage volume
7

DESCRIPTION

9       The "Sys::Virt::StorageVol" module represents a storage volume managed
10       by libvirt. A storage volume is always associated with a containing
11       storage pool ("Sys::Virt::StoragePool").
12

METHODS

14       my $name = $vol->get_name()
15           Returns a string with a locally unique name of the storage vol
16
17       my $name = $vol->get_key()
18           Returns a string with a globally unique key for the storage vol
19
20       my $name = $vol->get_path()
21           Returns a string with a locally unique file path of the storage vol
22
23       my $xml = $vol->get_xml_description()
24           Returns an XML document containing a complete description of the
25           storage vol's configuration
26
27       $vol->delete($flags)
28           Immediately delete the storage volume freeing its storage
29           resources.  The "flags" parameter indicates any special action to
30           be taken when deleting the volume.
31
32       $vol->resize($newcapacity, $flags=0)
33           Adjust the size of the storage volume. The $newcapacity value
34           semantics depend on the $flags parameter. If $flags specifies
35           "RESIZE_DELTA" then the $newcapacity is relative to the current
36           size. If $flags specifies "RESIZE_SHRINK" then the $newcapacity
37           value is the amount of space to remove
38
39       $vol->wipe($flags = 0)
40           Clear the data in the storage volume to avoid future information
41           leak. The "flags" parameter is currently unused and defaults to
42           zero.
43
44       $vol->wipe_pattern($algorithm, $flags = 0)
45           Clear the data in the storage volume to avoid future information
46           leak. The $algorithm parameter specifies the data pattern used to
47           erase data, and should be one of the WIPE ALGORITHM CONSTANTS
48           listed later. The "flags" parameter is currently unused and
49           defaults to zero.
50
51       my $info = $vol->get_info($flags = 0)
52           Retrieve live information about the storage volume. The returned
53           $info hash reference contains three keys. "type" indicates whether
54           the volume is a file or block device. "capacity" provides the
55           maximum logical size of the volume. "allocation" provides the
56           current physical usage of the volume. The allocation may be less
57           than the capacity for sparse, or grow-on-demand volumes. The
58           allocation may also be larger than the capacity, if there is a
59           metadata overhead for the volume format. $flags may take one of the
60           values
61
62           Sys::Virt::StorageVol::USE_ALLOCATION
63               Return the current allocation in allocation
64
65           Sys::Virt::StorageVol::GET_PHYSICAL
66               Return the physical size in allocation
67
68       $vol->download($st, $offset, $length, $flags=0);
69           Download data from $vol using the stream $st. If $offset and
70           $length are non-zero, then restrict data to the specified volume
71           byte range. The $flags accept the following values:
72
73           Sys::Virt::StorageVol::VOL_DOWNLOAD_SPARSE_STREAM
74               If this flag is is set in @flags effective transmission of
75               holes is enabled. This assumes using the stream $st with
76               combination of "sparse_recv_all" or "recv($flags =
77               VIR_STREAM_RECV_STOP_AT_HOLE)" for honouring holes sent by
78               server.
79
80       $vol->upload($st, $offset, $length, $flags=0);
81           Upload data to $vol using the stream $st. If $offset and $length
82           are non-zero, then restrict data to the specified volume byte
83           range. The $flags accept the following values:
84
85           Sys::Virt::StorageVol::VOL_UPLOAD_SPARSE_STREAM
86               If this is set in $flags effective transmission of holes is
87               enabled. This assumes using the stream $st with combination of
88               "sparse_send_all" or "send_hole" to preserve source file
89               sparseness.
90

CONSTANTS

92       The following sets of constants are useful when dealing with storage
93       volumes
94
95   VOLUME TYPES
96       The following constants are useful for interpreting the "type" field in
97       the hash returned by the "get_info" method
98
99       Sys::Virt::StorageVol::TYPE_FILE
100           The volume is a plain file
101
102       Sys::Virt::StorageVol::TYPE_BLOCK
103           The volume is a block device
104
105       Sys::Virt::StorageVol::TYPE_DIR
106           The volume is a directory
107
108       Sys::Virt::StorageVol::TYPE_NETWORK
109           The volume is a network source
110
111       Sys::Virt::StorageVol::TYPE_NETDIR
112           The volume is a network directory
113
114       Sys::Virt::StorageVol::TYPE_PLOOP
115           The volume is a ploop directory
116
117   CREATE MODES
118       The following constants are useful for the "flags" parameter of the
119       "create" method
120
121       Sys::Virt::StorageVol::CREATE_PREALLOC_METADATA
122           Preallocate header metadata when creating the volume.
123
124       Sys::Virt::StorageVol::CREATE_REFLINK
125           Perform lightweight reference copy
126
127       Sys::Virt::StorageVol::CREATE_VALIDATE
128           Validate the XML document against schema
129
130   DELETE MODES
131       The following constants are useful for the "flags" parameter of the
132       "delete" method
133
134       Sys::Virt::StorageVol::DELETE_NORMAL
135           Do a plain delete without any attempt to scrub data.
136
137       Sys::Virt::StorageVol::DELETE_ZEROED
138           Zero out current allocated blocks when deleting the volume
139
140       Sys::Virt::StorageVol::DELETE_WITH_SNAPSHOTS
141           Delete snapshots associated with the volume
142
143   WIPE ALGORITHM CONSTANTS
144       The following constants specify the algorithm for erasing data
145
146       Sys::Virt::StorageVol::WIPE_ALG_BSI
147           9-pass method recommended by the German Center of Security in
148           Information Technologies
149
150       Sys::Virt::StorageVol::WIPE_ALG_DOD
151           4-pass Dod 5220.22-M section, 8-306 procedure
152
153       Sys::Virt::StorageVol::WIPE_ALG_GUTMANN
154           The canonical 35-pass sequence
155
156       Sys::Virt::StorageVol::WIPE_ALG_NNSA
157           4-pass NNSA Policy Letter NAP-14.1-C (XVI-8)
158
159       Sys::Virt::StorageVol::WIPE_ALG_PFITZNER7
160           7-pass random
161
162       Sys::Virt::StorageVol::WIPE_ALG_PFITZNER33
163           33-pass random
164
165       Sys::Virt::StorageVol::WIPE_ALG_RANDOM
166           1-pass random
167
168       Sys::Virt::StorageVol::WIPE_ALG_SCHNEIER
169           7-pass method described by Bruce Schneier in "Applied Cryptography"
170           (1996)
171
172       Sys::Virt::StorageVol::WIPE_ALG_ZERO
173           1-pass, all zeroes
174
175       Sys::Virt::StorageVol::WIPE_ALG_TRIM
176           1-pass, trim all data on the volume by using TRIM or DISCARD
177
178   VOLUME RESIZE CONSTANTS
179       The following constants control how storage volumes can be resized
180
181       Sys::Virt::StorageVol::RESIZE_ALLOCATE
182           Fully allocate the extra space required during resize
183
184       Sys::Virt::StorageVol::RESIZE_DELTA
185           Treat the new capacity as a delta to the current capacity
186
187       Sys::Virt::StorageVol::RESIZE_SHRINK
188           Treat the new capacity as an amount to remove from the capacity
189

AUTHORS

191       Daniel P. Berrange <berrange@redhat.com>
192

COPYRIGHT

194       Copyright (C) 2006-2009 Red Hat Copyright (C) 2006-2009 Daniel P.
195       Berrange
196

LICENSE

198       This program is free software; you can redistribute it and/or modify it
199       under the terms of either the GNU General Public License as published
200       by the Free Software Foundation (either version 2 of the License, or at
201       your option any later version), or, the Artistic License, as specified
202       in the Perl README file.
203