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   DELETE MODES
128       The following constants are useful for the "flags" parameter of the
129       "delete" method
130
131       Sys::Virt::StorageVol::DELETE_NORMAL
132           Do a plain delete without any attempt to scrub data.
133
134       Sys::Virt::StorageVol::DELETE_ZEROED
135           Zero out current allocated blocks when deleting the volume
136
137       Sys::Virt::StorageVol::DELETE_WITH_SNAPSHOTS
138           Delete snapshots associated with the volume
139
140   WIPE ALGORITHM CONSTANTS
141       The following constants specify the algorithm for erasing data
142
143       Sys::Virt::StorageVol::WIPE_ALG_BSI
144           9-pass method recommended by the German Center of Security in
145           Information Technologies
146
147       Sys::Virt::StorageVol::WIPE_ALG_DOD
148           4-pass Dod 5220.22-M section, 8-306 procedure
149
150       Sys::Virt::StorageVol::WIPE_ALG_GUTMANN
151           The canonical 35-pass sequence
152
153       Sys::Virt::StorageVol::WIPE_ALG_NNSA
154           4-pass NNSA Policy Letter NAP-14.1-C (XVI-8)
155
156       Sys::Virt::StorageVol::WIPE_ALG_PFITZNER7
157           7-pass random
158
159       Sys::Virt::StorageVol::WIPE_ALG_PFITZNER33
160           33-pass random
161
162       Sys::Virt::StorageVol::WIPE_ALG_RANDOM
163           1-pass random
164
165       Sys::Virt::StorageVol::WIPE_ALG_SCHNEIER
166           7-pass method described by Bruce Schneier in "Applied Cryptography"
167           (1996)
168
169       Sys::Virt::StorageVol::WIPE_ALG_ZERO
170           1-pass, all zeroes
171
172       Sys::Virt::StorageVol::WIPE_ALG_TRIM
173           1-pass, trim all data on the volume by using TRIM or DISCARD
174
175       VOLUME RESIZE CONSTANTS
176
177       The following constants control how storage volumes can be resized
178
179       Sys::Virt::StorageVol::RESIZE_ALLOCATE
180           Fully allocate the extra space required during resize
181
182       Sys::Virt::StorageVol::RESIZE_DELTA
183           Treat the new capacity as a delta to the current capacity
184
185       Sys::Virt::StorageVol::RESIZE_SHRINK
186           Treat the new capacity as an amount to remove from the capacity
187

AUTHORS

189       Daniel P. Berrange <berrange@redhat.com>
190

COPYRIGHT

192       Copyright (C) 2006-2009 Red Hat Copyright (C) 2006-2009 Daniel P.
193       Berrange
194

LICENSE

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