Difference between revisions of "Man/ploop.8"

From OpenVZ Virtuozzo Containers Wiki
< Man
Jump to: navigation, search
(Automated import of articles)
 
(Bot: Automated import of articles *** existing text overwritten ***)
 
(3 intermediate revisions by one other user not shown)
Line 20: Line 20:
 
[<b>-t&nbsp;</b><i>fstype</i>]
 
[<b>-t&nbsp;</b><i>fstype</i>]
 
[<b>-b&nbsp;</b><i>blocksize</i>]
 
[<b>-b&nbsp;</b><i>blocksize</i>]
[<b>-B&nbsp;</b><i>fsblocksize</i>] <i>delta_file</i></p></td></tr>
+
[<b>-B&nbsp;</b><i>fsblocksize</i>] [<b>--nolazy</b>]
 +
<i>delta_file</i></p> </td></tr>
 
<tr valign="top" align="left">
 
<tr valign="top" align="left">
 
<td width="11%"></td>
 
<td width="11%"></td>
Line 63: Line 64:
 
<b>-m</b> <i>mount_point</i> | <i>DiskDescriptor.xml</i> |
 
<b>-m</b> <i>mount_point</i> | <i>DiskDescriptor.xml</i> |
 
<i>image_file</i> }</p></td></tr>
 
<i>image_file</i> }</p></td></tr>
 +
<tr valign="top" align="left">
 +
<td width="11%"></td>
 +
<td width="20%">
 +
 +
<p style="margin-top: 1em"><b>ploop&nbsp;replace</b></p></td>
 +
<td width="69%">
 +
 +
<p style="margin-top: 1em">{ <b>-u</b> <i>uuid</i> |
 +
<b>-l</b> <i>level</i> | <b>-o</b> <i>cur_image_file</i> }
 +
[<b>--keep-name</b>] <b>-i</b> <i>image_file
 +
DiskDescriptor.xml</i></p> </td></tr>
 
<tr valign="top" align="left">
 
<tr valign="top" align="left">
 
<td width="11%"></td>
 
<td width="11%"></td>
Line 81: Line 93:
 
<p style="margin-top: 1em">{ <b>-f</b> <i>format</i> |
 
<p style="margin-top: 1em">{ <b>-f</b> <i>format</i> |
 
<b>-v</b> <i>version</i> } <i>DiskDescriptor.xml</i></p></td></tr>
 
<b>-v</b> <i>version</i> } <i>DiskDescriptor.xml</i></p></td></tr>
 +
<tr valign="top" align="left">
 +
<td width="11%"></td>
 +
<td width="20%">
 +
 +
<p style="margin-top: 1em"><b>ploop&nbsp;check</b></p></td>
 +
<td width="69%">
 +
</td></tr>
 +
</table>
 +
 +
<p style="margin-left:11%;">[<b>-u&nbsp;</b><i>uuid</i>]
 +
<i>DiskDescriptor.xml</i></p>
 +
 +
<table width="100%" border="0" rules="none" frame="void"
 +
      cellspacing="0" cellpadding="0">
 +
<tr valign="top" align="left">
 +
<td width="11%"></td>
 +
<td width="17%">
 +
 +
<p style="margin-top: 1em"><b>ploop&nbsp;check</b></p></td>
 +
<td width="72%">
 +
 +
<p style="margin-top: 1em">[<b>--force</b>]
 +
[<b>--hard-force</b>] [<b>--check</b>] [<b>--ro</b>]
 +
[<b>--silent</b>] [<b>--drop-inuse</b>] [<b>--raw</b>]
 +
[<b>--blocksize&nbsp;</b><i>size</i>]
 +
[<b>--repair-sparse</b>] <i>image_file</i></p></td></tr>
 +
<tr valign="top" align="left">
 +
<td width="11%"></td>
 +
<td width="17%">
 +
 +
<p style="margin-top: 1em"><b>ploop&nbsp;info</b></p></td>
 +
<td width="72%">
 +
 +
<p style="margin-top: 1em">[<b>-s</b>] [<b>-d</b>]
 +
<i>DiskDescriptor.xml</i></p> </td></tr>
 +
<tr valign="top" align="left">
 +
<td width="11%"></td>
 +
<td width="17%">
 +
 +
<p style="margin-top: 1em"><b>ploop&nbsp;list</b></p></td>
 +
<td width="72%">
 +
 +
<p style="margin-top: 1em">[<b>-a</b>]</p></td></tr>
 
</table>
 
</table>
  
Line 103: Line 158:
  
 
<p style="margin-top: 1em"><b>ploop&nbsp;snapshot-merge</b></p> </td>
 
<p style="margin-top: 1em"><b>ploop&nbsp;snapshot-merge</b></p> </td>
<td width="43%">
+
<td width="57%">
  
<p style="margin-top: 1em">[<b>-u&nbsp;</b><i>uuid</i>]
+
<p style="margin-top: 1em">[<b>-u&nbsp;</b><i>uuid&nbsp;</i>[<b>-U&nbsp;</b><i>uuid2</i>]&nbsp;|&nbsp;<b>-A</b>]
<i>DiskDescriptor.xml</i></p> </td>
+
[<b>-n&nbsp;</b><i>new_delta</i>]
<td width="14%">
+
<i>DiskDescriptor.xml</i></p> </td></tr>
</td></tr>
 
 
<tr valign="top" align="left">
 
<tr valign="top" align="left">
 
<td width="11%"></td>
 
<td width="11%"></td>
Line 114: Line 168:
  
 
<p style="margin-top: 1em"><b>ploop&nbsp;snapshot-switch</b></p> </td>
 
<p style="margin-top: 1em"><b>ploop&nbsp;snapshot-switch</b></p> </td>
<td width="43%">
+
<td width="57%">
  
 
<p style="margin-top: 1em"><b>-u</b> <i>uuid
 
<p style="margin-top: 1em"><b>-u</b> <i>uuid
DiskDescriptor.xml</i></p> </td>
+
DiskDescriptor.xml</i></p> </td></tr>
<td width="14%">
 
</td></tr>
 
 
<tr valign="top" align="left">
 
<tr valign="top" align="left">
 
<td width="11%"></td>
 
<td width="11%"></td>
Line 125: Line 177:
  
 
<p style="margin-top: 1em"><b>ploop&nbsp;snapshot-delete</b></p> </td>
 
<p style="margin-top: 1em"><b>ploop&nbsp;snapshot-delete</b></p> </td>
<td width="43%">
+
<td width="57%">
  
 
<p style="margin-top: 1em"><b>-u</b> <i>uuid
 
<p style="margin-top: 1em"><b>-u</b> <i>uuid
DiskDescriptor.xml</i></p> </td>
+
DiskDescriptor.xml</i></p> </td></tr>
<td width="14%">
 
</td></tr>
 
 
<tr valign="top" align="left">
 
<tr valign="top" align="left">
 
<td width="11%"></td>
 
<td width="11%"></td>
Line 136: Line 186:
  
 
<p style="margin-top: 1em"><b>ploop&nbsp;snapshot-list</b></p> </td>
 
<p style="margin-top: 1em"><b>ploop&nbsp;snapshot-list</b></p> </td>
<td width="43%"></td>
+
<td width="57%">
<td width="14%">
 
 
</td></tr>
 
</td></tr>
 
</table>
 
</table>
  
 
<p style="margin-left:11%;">[<b>-H</b>]
 
<p style="margin-left:11%;">[<b>-H</b>]
[<b>-u&nbsp;</b><i>uuid</i>]
+
[<b>-u&nbsp;</b><i>uuid</i>] [<b>-s</b>]
 
[<b>-o&nbsp;</b><i>field</i>[,<i>field</i>...]]
 
[<b>-o&nbsp;</b><i>field</i>[,<i>field</i>...]]
 
<i>DiskDescriptor.xml</i></p>
 
<i>DiskDescriptor.xml</i></p>
 +
 +
<table width="100%" border="0" rules="none" frame="void"
 +
      cellspacing="0" cellpadding="0">
 +
<tr valign="top" align="left">
 +
<td width="11%"></td>
 +
<td width="15%">
 +
 +
<p style="margin-top: 1em"><b>ploop&nbsp;copy</b></p></td>
 +
<td width="2%"></td>
 +
<td width="72%">
 +
 +
<p style="margin-top: 1em"><b>-s</b> <i>device</i>
 +
[<b>-F&nbsp;</b><i>stop_command</i>] {
 +
[<b>-d&nbsp;</b><i>file</i>] |
 +
[<b>-o&nbsp;</b><i>output_fd</i>]
 +
[<b>-f&nbsp;</b><i>feedback_fd</i>] }</p></td></tr>
 +
<tr valign="top" align="left">
 +
<td width="11%"></td>
 +
<td width="15%">
 +
 +
<p style="margin-top: 1em"><b>ploop&nbsp;copy</b></p></td>
 +
<td width="2%"></td>
 +
<td width="72%">
 +
 +
<p style="margin-top: 1em"><b>-d</b> <i>file</i>
 +
[<b>-i&nbsp;</b><i>input_fd</i>]
 +
[<b>-f&nbsp;</b><i>feedback_fd</i>]</p> </td></tr>
 +
</table>
 +
 +
<table width="100%" border="0" rules="none" frame="void"
 +
      cellspacing="0" cellpadding="0">
 +
<tr valign="top" align="left">
 +
 +
<p style="margin-top: 1em"><b>ploop&nbsp;balloon&nbsp;discard</b></p> <td width="45%"></td>
 +
<td width="50%">
 +
 +
<p style="margin-top: 1em">[<b>--automount</b>]
 +
[<b>--to-free&nbsp;</b><i>size</i>]
 +
[<b>--min-block&nbsp;</b><i>min_size</i>] [<b>--defrag</b>]
 +
<i>DiskDescriptor.xml</i></p> </td>
 +
<td width="5%">
 +
</td></tr>
 +
</table>
 +
 +
<table width="100%" border="0" rules="none" frame="void"
 +
      cellspacing="0" cellpadding="0">
 +
<tr valign="top" align="left">
 +
 +
<p style="margin-top: 1em"><b>ploop&nbsp;restore-descriptor</b></p> <td width="49%"></td>
 +
<td width="51%">
 +
 +
<p style="margin-top: 1em"><b>-f</b> <i>format</i>
 +
[<b>-b&nbsp;</b><i>blocksize</i>] <i>disk_dir
 +
delta_file</i></p> </td></tr>
 +
</table>
  
 
== DESCRIPTION ==
 
== DESCRIPTION ==
Line 168: Line 272:
 
the form with DiskDescriptor.xml.</p>
 
the form with DiskDescriptor.xml.</p>
  
=== BASIC COMMANDS ===
+
== OPTIONS ==
 +
 
 +
<p style="margin-left:11%; margin-top: 1em">Run
 +
<b>ploop</b> without any options to show a short synopsys,
 +
including a list of commands.</p>
 +
 
 +
<p style="margin-left:11%; margin-top: 1em">Run
 +
<b>ploop</b> <i>command</i> to show synopsys and a short
 +
description for a particular <i>command</i>.</p>
 +
 
 +
=== Basic commands ===
  
 
==== init ====
 
==== init ====
  
<p style="margin-left:11%; margin-top: 1em">Create and
+
<p style="margin-top: 1em">Create and initalize a ploop
initalize a ploop image file and a corresponding
+
image file and a corresponding <b>DiskDescriptor.xml</b>
<b>DiskDescriptor.xml</b> file.</p>
+
file.</p>
  
 
<table width="100%" border="0" rules="none" frame="void"
 
<table width="100%" border="0" rules="none" frame="void"
Line 191: Line 305:
 
[<b>-t&nbsp;</b><i>fstype</i>]
 
[<b>-t&nbsp;</b><i>fstype</i>]
 
[<b>-b&nbsp;</b><i>blocksize</i>]
 
[<b>-b&nbsp;</b><i>blocksize</i>]
[<b>-B&nbsp;</b><i>fsblocksize</i>] <i>delta_file</i></p></td></tr>
+
[<b>-B&nbsp;</b><i>fsblocksize</i>] [<b>--nolazy</b>]
 +
<i>delta_file</i></p> </td></tr>
 
<tr valign="top" align="left">
 
<tr valign="top" align="left">
 
<td width="11%"></td>
 
<td width="11%"></td>
Line 213: Line 328:
 
<td width="72%">
 
<td width="72%">
  
<p>Image format. See <b>IMAGE FORMATS</b> below.</p></td></tr>
+
<p>Image format. See <b>Image formats</b> below.</p></td></tr>
 
<tr valign="top" align="left">
 
<tr valign="top" align="left">
 
<td width="11%"></td>
 
<td width="11%"></td>
Line 224: Line 339:
 
<p>Image version, can be <b>1</b> or <b>2</b>. Default is
 
<p>Image version, can be <b>1</b> or <b>2</b>. Default is
 
<b>2</b>, if supported by the kernel.</p></td></tr>
 
<b>2</b>, if supported by the kernel.</p></td></tr>
<tr valign="top" align="left">
+
</table>
<td width="11%"></td>
 
<td width="15%">
 
  
<p><b>-t</b> <i>fstype</i></p></td>
+
<p style="margin-left:11%;"><b>-t
<td width="2%"></td>
+
none</b>|<b>ext3</b>|<b>ext4</b></p>
<td width="72%">
 
  
<p>File system type. If this parameter is specified, a
+
<p style="margin-left:28%;">File system type to create,
 +
default is <b>ext4</b>. Unless <b>none</b> is specified, a
 
partition, a filesystem, and a balloon file will be created
 
partition, a filesystem, and a balloon file will be created
inside the image. Currently supported types are <b>ext3</b>
+
inside the image. Using <b>ext3</b> is not recommended.</p>
and <b>ext4</b>. Using <b>ext3</b> is not recommended.</p></td></tr>
 
</table>
 
  
 
<p style="margin-left:11%;"><b>-b</b> <i>blocksize</i></p>
 
<p style="margin-left:11%;"><b>-b</b> <i>blocksize</i></p>
Line 249: Line 360:
 
<p style="margin-left:28%;">Filesystem block size, in
 
<p style="margin-left:28%;">Filesystem block size, in
 
bytes. Default is 4096 bytes.</p>
 
bytes. Default is 4096 bytes.</p>
 +
 +
<p style="margin-left:11%;"><b>-n</b>, <b>--nolazy</b></p>
 +
 +
<p style="margin-left:28%;">Disable lazy mkfs
 +
initialization (which is enabled by default). Currently that
 +
means if this flag is set, <b>mkfs.ext4</b>(8) is called
 +
with <b>-Elazy_itable_init=0,lazy_journal_init=0</b>
 +
options.</p>
  
 
<table width="100%" border="0" rules="none" frame="void"
 
<table width="100%" border="0" rules="none" frame="void"
Line 265: Line 384:
 
==== mount ====
 
==== mount ====
  
<p style="margin-left:11%; margin-top: 1em">Assemble a
+
<p style="margin-top: 1em">Assemble a ploop device from one
ploop device from one or more delta images, start it, and
+
or more delta images, start it, and optionally mount the
optionally mount the file system residing on the device.</p>
+
file system residing on the device.</p>
  
<p style="margin-left:11%; margin-top: 1em">Two forms of
+
<p style="margin-top: 1em">Two forms of this command are
this command are provided. The first one accepts a list of
+
provided. The first one accepts a list of delta images to be
delta images to be used for assembling the ploop device,
+
used for assembling the ploop device, while the second one
while the second one is using information from a
+
is using information from a DiskDescriptor.xml file. Please
DiskDescriptor.xml file. Please note that not all mount
+
note that not all mount options are applicable to both
options are applicable to both forms.</p>
+
forms.</p>
  
 
<table width="100%" border="0" rules="none" frame="void"
 
<table width="100%" border="0" rules="none" frame="void"
Line 355: Line 474:
 
<td width="71%">
 
<td width="71%">
  
<p>Ploop device to use, e.g.i, <b>/dev/ploop0</b>. If not
+
<p>Ploop device to use, e.g. <b>/dev/ploop0</b>. If not
specified, the first unused ploop device will be used.</p></td></tr>
+
specified, a randomly numbered ploop device will be
 +
used.</p> </td></tr>
 
</table>
 
</table>
  
Line 409: Line 529:
 
==== umount ====
 
==== umount ====
  
<p style="margin-left:11%; margin-top: 1em">Unmount a ploop
+
<p style="margin-top: 1em">Unmount a ploop device. Since a
device. Since a mounted ploop device consists of an image
+
mounted ploop device consists of an image (or multiple
(or multiple images), a device, and a file system mounted to
+
images), a device, and (optionally) a file system mounted to
 
a directory, one can refer to any of the above entities to
 
a directory, one can refer to any of the above entities to
 
specify what to unmount. The recommended way is to use
 
specify what to unmount. The recommended way is to use
Line 437: Line 557:
 
<td width="69%">
 
<td width="69%">
  
<p>Ploop device, e.g., <b>/dev/ploop0</b>. If not
+
<p>Ploop device, e.g., <b>/dev/ploop0</b>.</p></td></tr>
specified, the first unused ploop device will be used.</p></td></tr>
 
 
</table>
 
</table>
  
Line 466: Line 585:
 
</td></tr>
 
</td></tr>
 
</table>
 
</table>
 +
 +
==== replace ====
 +
 +
<p style="margin-top: 1em">Replaces a ploop image by a
 +
different (but identical) one, on a running ploop device.
 +
Only a read-only image (e.g. a non-top one in a stacked
 +
configuration) can be replaced. An image to be replaced is
 +
specified by either one of level, UUID, or the current image
 +
file.</p>
 +
 +
<p style="margin-top: 1em">If a new image is not identical
 +
to the old one (i.e. its content differs) or not suitable
 +
for ploop in any other way (e.g. it is sparse, or resides on
 +
a file system not supported by ploop), the result is
 +
undefined.</p>
 +
 +
<table width="100%" border="0" rules="none" frame="void"
 +
      cellspacing="0" cellpadding="0">
 +
<tr valign="top" align="left">
 +
<td width="11%"></td>
 +
<td width="20%">
 +
 +
<p style="margin-top: 1em"><b>ploop&nbsp;replace</b></p></td>
 +
<td width="1%"></td>
 +
<td width="68%">
 +
 +
<p style="margin-top: 1em">{ <b>-u</b> <i>uuid</i> |
 +
<b>-l</b> <i>level</i> | <b>-o</b> <i>cur_image_file</i> }
 +
[<b>--keep-name</b>] <b>-i</b> <i>image_file
 +
DiskDescriptor.xml</i></p> </td></tr>
 +
<tr valign="top" align="left">
 +
<td width="11%"></td>
 +
<td width="20%">
 +
 +
<p><b>-u</b> <i>uuid</i></p></td>
 +
<td width="1%"></td>
 +
<td width="68%">
 +
 +
<p>A <i>uuid</i> of an image to be replaced.</p></td></tr>
 +
<tr valign="top" align="left">
 +
<td width="11%"></td>
 +
<td width="20%">
 +
 +
<p><b>-l</b> <i>level</i></p></td>
 +
<td width="1%"></td>
 +
<td width="68%">
 +
 +
<p>A level of image to be replaced. A level is a distance
 +
of an image from the base delta.</p></td></tr>
 +
</table>
 +
 +
<p style="margin-left:11%;"><b>-o</b>
 +
<i>cur_image_file</i></p>
 +
 +
<p style="margin-left:32%;">A current image file (the one
 +
to replace).</p>
 +
 +
<p style="margin-left:11%;"><b>-k</b>,
 +
<b>--keep-name</b></p>
 +
 +
<p style="margin-left:32%;">A flag to keep the same image
 +
file name. If this flag is set, after the image is replaced,
 +
a new <i>image_file</i> is renamed to the old one (removing
 +
the old, now unused, image), so no modification to
 +
DiskDescriptor.xml is required.</p>
 +
 +
<table width="100%" border="0" rules="none" frame="void"
 +
      cellspacing="0" cellpadding="0">
 +
<tr valign="top" align="left">
 +
<td width="11%"></td>
 +
<td width="20%">
 +
 +
<p><b>-i</b> <i>image_file</i></p></td>
 +
<td width="1%"></td>
 +
<td width="37%">
 +
 +
<p>A new replacement image.</p></td>
 +
<td width="31%">
 +
</td></tr>
 +
</table>
 +
 +
<p style="margin-left:11%;"><i>DiskDescriptor.xml</i></p>
 +
 +
<p style="margin-left:32%;">Path to the DiskDescriptor.xml
 +
file with information about images.</p>
  
 
==== resize ====
 
==== resize ====
  
<p style="margin-left:11%; margin-top: 1em">Resize a ploop
+
<p style="margin-top: 1em">Resize a ploop image. Both
image. Online resize is supported, and the tool can either
+
online (i.e. when ploop is mounted and used) and offline
grow or shrink the ploop image and the underlying file
+
resize is supported, and the tool can either grow or shrink
system.</p>
+
both the ploop image and the underlying file system.</p>
  
 
<table width="100%" border="0" rules="none" frame="void"
 
<table width="100%" border="0" rules="none" frame="void"
Line 507: Line 711:
 
==== convert ====
 
==== convert ====
  
<p style="margin-left:11%; margin-top: 1em">Convert ploop
+
<p style="margin-top: 1em">Convert either ploop image
image format or version.</p>
+
format or version (but not both at the same time).
 +
Conversion can only be performed offline (i.e. image should
 +
not be in use).</p>
  
 
<table width="100%" border="0" rules="none" frame="void"
 
<table width="100%" border="0" rules="none" frame="void"
Line 530: Line 736:
 
<td width="68%">
 
<td width="68%">
  
<p>Image format. See <b>IMAGE FORMATS</b> below.</p></td></tr>
+
<p>Image format. See <b>Image formats</b> below.</p></td></tr>
 
<tr valign="top" align="left">
 
<tr valign="top" align="left">
 
<td width="11%"></td>
 
<td width="11%"></td>
Line 539: Line 745:
 
<td width="68%">
 
<td width="68%">
  
<p>Image version, can be <b>1</b> or <b>2</b>. Only offline
+
<p>Image version, can be <b>1</b> or <b>2</b>.</p></td></tr>
image version conversion is supported.</p></td></tr>
+
</table>
 +
 
 +
==== check ====
 +
 
 +
<p style="margin-top: 1em">Check the internal consistency
 +
of (and possibly repair) a ploop image (or images). Note
 +
that image(s) to be tested should not be in use.</p>
 +
 
 +
<table width="100%" border="0" rules="none" frame="void"
 +
      cellspacing="0" cellpadding="0">
 +
<tr valign="top" align="left">
 +
<td width="11%"></td>
 +
<td width="17%">
 +
 
 +
<p style="margin-top: 1em"><b>ploop&nbsp;check</b></p></td>
 +
<td width="1%"></td>
 +
<td width="43%">
 +
 
 +
<p style="margin-top: 1em">[<b>-u&nbsp;</b><i>uuid</i>]
 +
<i>DiskDescriptor.xml</i></p> </td>
 +
<td width="28%">
 +
</td></tr>
 +
</table>
 +
 
 +
<p style="margin-top: 1em">Check all the images in
 +
<i>DiskDescriptor.xml</i> up to the one denoted by the
 +
<i>uuid</i> (or default top delta, if UUID is not
 +
specified). Default built-in check options are used, and the
 +
ones specified on the command line, if any, are ignored.</p>
 +
 
 +
<table width="100%" border="0" rules="none" frame="void"
 +
      cellspacing="0" cellpadding="0">
 +
<tr valign="top" align="left">
 +
<td width="11%"></td>
 +
<td width="17%">
 +
 
 +
<p style="margin-top: 1em"><b>ploop&nbsp;check</b></p></td>
 +
<td width="1%"></td>
 +
<td width="71%">
 +
 
 +
<p style="margin-top: 1em">[<b>--force</b>]
 +
[<b>--hard-force</b>] [<b>--check</b>] [<b>--ro</b>]
 +
[<b>--silent</b>] [<b>--drop-inuse</b>] [<b>--raw</b>]
 +
[<b>--blocksize&nbsp;</b><i>size</i>]
 +
[<b>--repair-sparse</b>] <i>DiskDescriptor.xml</i> |
 +
<i>image_file</i></p> </td></tr>
 +
<tr valign="top" align="left">
 +
<td width="11%"></td>
 +
<td width="17%">
 +
 
 +
<p><b>-f</b>, <b>--force</b></p></td>
 +
<td width="1%"></td>
 +
<td width="71%">
 +
 
 +
<p>Force check even if image&rsquo;s dirty flag is not
 +
set.</p> </td></tr>
 +
</table>
 +
 
 +
<p style="margin-left:11%;"><b>-F</b>,
 +
<b>--hard-force</b></p>
 +
 
 +
<p style="margin-left:29%;">Same as <b>-f</b>, plus try to
 +
fix even fatal errors (can be dangerous).</p>
 +
 
 +
<table width="100%" border="0" rules="none" frame="void"
 +
      cellspacing="0" cellpadding="0">
 +
<tr valign="top" align="left">
 +
<td width="11%"></td>
 +
<td width="17%">
 +
 
 +
<p><b>-c</b>, <b>--check</b></p></td>
 +
<td width="1%"></td>
 +
<td width="63%">
 +
 
 +
<p>Check for duplicated blocks and holes.</p></td>
 +
<td width="8%">
 +
</td></tr>
 +
<tr valign="top" align="left">
 +
<td width="11%"></td>
 +
<td width="17%">
 +
 
 +
<p><b>-r</b>, <b>--ro</b></p></td>
 +
<td width="1%"></td>
 +
<td width="63%">
 +
 
 +
<p>Read-only access, do not modify image(s).</p></td>
 +
<td width="8%">
 +
</td></tr>
 +
</table>
 +
 
 +
<p style="margin-left:11%;"><b>-s</b>, <b>--silent</b></p>
 +
 
 +
<p style="margin-left:29%;">Be more silent, only report
 +
errors.</p>
 +
 
 +
<p style="margin-left:11%;"><b>-d</b>,
 +
<b>--drop-inuse</b></p>
 +
 
 +
<p style="margin-left:29%;">Drop image &quot;in use&quot;
 +
flag.</p>
 +
 
 +
<table width="100%" border="0" rules="none" frame="void"
 +
      cellspacing="0" cellpadding="0">
 +
<tr valign="top" align="left">
 +
<td width="11%"></td>
 +
<td width="14%">
 +
 
 +
<p><b>-R</b>, <b>--raw</b></p></td>
 +
<td width="4%"></td>
 +
<td width="71%">
 +
 
 +
<p>Specifies that <i>image_file</i> is a raw ploop
 +
image.</p> </td></tr>
 +
</table>
 +
 
 +
<p style="margin-left:11%;"><b>-b</b>, <b>--blocksize</b>
 +
<i>size</i></p>
 +
 
 +
<p style="margin-left:29%;">Image cluster block size, in
 +
sectors (for raw images).</p>
 +
 
 +
<p style="margin-left:11%;"><b>-S</b>,
 +
<b>--repair-sparse</b></p>
 +
 
 +
<p style="margin-left:29%;">Repair sparse image(s).</p>
 +
 
 +
=== Miscellaneous commands ===
 +
 
 +
==== info ====
 +
 
 +
<table width="100%" border="0" rules="none" frame="void"
 +
      cellspacing="0" cellpadding="0">
 +
<tr valign="top" align="left">
 +
<td width="11%"></td>
 +
<td width="15%">
 +
 
 +
<p style="margin-top: 1em"><b>ploop&nbsp;info</b></p></td>
 +
<td width="2%"></td>
 +
<td width="27%">
 +
 
 +
<p style="margin-top: 1em"><i>DiskDescriptor.xml</i></p></td>
 +
<td width="45%">
 +
</td></tr>
 +
</table>
 +
 
 +
<p>When run without any options, show information about
 +
disk space and inodes usage and limits on the inner ploop
 +
filesystem, somewhat similar to [[Man/vzquota.8|<b>vzquota</b>(8)]]
 +
<b>stat</b> or <b>show</b> commands.</p>
 +
 
 +
<table width="100%" border="0" rules="none" frame="void"
 +
      cellspacing="0" cellpadding="0">
 +
<tr valign="top" align="left">
 +
<td width="11%"></td>
 +
<td width="15%">
 +
 
 +
<p style="margin-top: 1em"><b>ploop&nbsp;info</b></p></td>
 +
<td width="2%"></td>
 +
<td width="43%">
 +
 
 +
<p style="margin-top: 1em">[<b>-s</b>] [<b>-d</b>]
 +
<i>DiskDescriptor.xml</i></p> </td>
 +
<td width="29%">
 +
</td></tr>
 +
</table>
 +
 
 +
<p>Either one or both options can be used together. Option
 +
<b>-s</b> is used to show information about ploop device
 +
size, block size, and format version. Option <b>-d</b> is
 +
used to show a corresponding ploop block device, it
 +
available. file.</p>
 +
 
 +
==== list ====
 +
 
 +
<table width="100%" border="0" rules="none" frame="void"
 +
      cellspacing="0" cellpadding="0">
 +
<tr valign="top" align="left">
 +
<td width="11%"></td>
 +
<td width="15%">
 +
 
 +
<p style="margin-top: 1em"><b>ploop&nbsp;list</b></p></td>
 +
<td width="2%"></td>
 +
<td width="6%">
 +
 
 +
<p style="margin-top: 1em">[<b>-a</b>]</p></td>
 +
<td width="66%">
 +
</td></tr>
 +
</table>
 +
 
 +
<p style="margin-top: 1em">Shows a list of running ploop
 +
devices (first column) and their corresponding base images.
 +
With option <b>-a</b> it also shows a mount point (third
 +
column).</p>
 +
 
 +
==== restore-descriptor ====
 +
 
 +
<p style="margin-top: 1em">Create DiskDescriptor.xml file
 +
suitable for <i>delta_file</i> and put it into
 +
<i>disk_dir</i>.</p>
 +
 
 +
<table width="100%" border="0" rules="none" frame="void"
 +
      cellspacing="0" cellpadding="0">
 +
<tr valign="top" align="left">
 +
<td width="11%"></td>
 +
<td width="37%">
 +
 
 +
<p style="margin-top: 1em"><b>ploop&nbsp;restore-descriptor</b></p> </td>
 +
<td width="1%"></td>
 +
<td width="51%">
 +
 
 +
<p style="margin-top: 1em"><b>-f</b> <i>format</i>
 +
[<b>-b&nbsp;</b><i>blocksize</i>] <i>disk_dir
 +
delta_file</i></p> </td></tr>
 
</table>
 
</table>
 +
 +
<p style="margin-top: 1em">Read image header in case of
 +
ploop1 format or check raw image size and generate proper
 +
DiskDescriptor.xml file. You can specify blocksize for raw
 +
images. If it&rsquo;s not specified it will be choosen
 +
automatically - largest possible value between 32K and 1M.
 +
Raw image size must be aligned to blocksize.</p>
 +
 +
<p style="margin-top: 1em">This command works only for base
 +
images. Snapshots are not supported.</p>
 +
 +
=== Working with snapshots ===
 +
 +
<p style="margin-top: 1em">Ploop snapshots is a mechanism
 +
for creating and managing instant states of a running file
 +
system. Creating a snapshot leads to creating a new empty
 +
ploop image which is layered on top of an old one, then all
 +
writes are ending up in the top image, and reads are falling
 +
through to a lower level. There can be up to 126) stacked
 +
ploop images (or snapshots). Online snapshot merging is also
 +
supported.</p>
 +
 +
<p style="margin-top: 1em">Snapshots are identified by a
 +
unique UUID. A snapshot can be mounted using <b>ploop mount
 +
-u</b> <i>uuid</i> command, see above.</p>
  
 
==== snapshot ====
 
==== snapshot ====
  
<p style="margin-left:11%; margin-top: 1em">Create a ploop
+
<p style="margin-top: 1em">Create a ploop snapshot.</p>
snapshot.</p>
 
  
 
<table width="100%" border="0" rules="none" frame="void"
 
<table width="100%" border="0" rules="none" frame="void"
Line 576: Line 1,018:
 
==== snapshot-merge ====
 
==== snapshot-merge ====
  
<p style="margin-left:11%; margin-top: 1em">Merge a
+
<p style="margin-top: 1em">Merge a snapshot with its
snapshot with its parent.</p>
+
parent. That is, contents of the delta file corresponding to
 +
the snapshot is merged to a parent delta, then the file is
 +
removed. Parent snapshot UUID is lost (as it is replaced
 +
with the <i>uuid</i> specified). All snapshots having the
 +
lost one as a parent are updated to have the <i>uuid</i> as
 +
its parent.</p>
  
 
<table width="100%" border="0" rules="none" frame="void"
 
<table width="100%" border="0" rules="none" frame="void"
Line 589: Line 1,036:
 
<td width="57%">
 
<td width="57%">
  
<p style="margin-top: 1em">[<b>-u&nbsp;</b><i>uuid</i>]
+
<p style="margin-top: 1em">[<b>-u&nbsp;</b><i>uuid&nbsp;</i>[<b>-U&nbsp;</b><i>uuid2</i>]&nbsp;|&nbsp;<b>-A</b>]
 +
[<b>-n&nbsp;</b><i>new_delta</i>]
 
<i>DiskDescriptor.xml</i></p> </td></tr>
 
<i>DiskDescriptor.xml</i></p> </td></tr>
 
<tr valign="top" align="left">
 
<tr valign="top" align="left">
Line 599: Line 1,047:
 
<td width="57%">
 
<td width="57%">
  
<p>Specify a snapshot <i>uuid</i> to merge. If this option
+
<p>Specify a single snapshot <i>uuid</i> to merge. If this
is not specified, the top delta will be used.</p></td></tr>
+
option is not specified, the top delta will be used.</p></td></tr>
 +
<tr valign="top" align="left">
 +
<td width="11%"></td>
 +
<td width="31%">
 +
 
 +
<p><b>-U</b> <i>uuid2</i></p></td>
 +
<td width="1%"></td>
 +
<td width="57%">
 +
 
 +
<p>Together with <b>-u</b> <i>uuid</i>, specify that all
 +
snapshots in the range <i>uuid</i>...<i>uuid2</i> are to be
 +
merged.</p> </td></tr>
 
<tr valign="top" align="left">
 
<tr valign="top" align="left">
 
<td width="11%"></td>
 
<td width="11%"></td>
Line 612: Line 1,071:
 
snapshots have more than a single child, they will be
 
snapshots have more than a single child, they will be
 
impossible to merge.</p></td></tr>
 
impossible to merge.</p></td></tr>
 +
<tr valign="top" align="left">
 +
<td width="11%"></td>
 +
<td width="31%">
 +
 +
<p><b>-n</b> <i>new_delta</i></p></td>
 +
<td width="1%"></td>
 +
<td width="57%">
 +
 +
<p>If this option is set, instead of merging the child
 +
delta into its parent, both the parent and the child deltas
 +
are merged into a newly created file <i>new_delta</i>, which
 +
replaces the parent delta. Both deltas are then removed.</p></td></tr>
 
</table>
 
</table>
  
 
==== snapshot-switch ====
 
==== snapshot-switch ====
  
<p style="margin-left:11%; margin-top: 1em">Switch to the
+
<p style="margin-top: 1em">Switch to the specified
specified snapshot. This operation can only be performed
+
snapshot. This operation can only be performed while ploop
while ploop is not running (i.e. is unmounted). The current
+
is not running (i.e. is unmounted). The current top delta
top delta image will be removed.</p>
+
image will be removed.</p>
  
 
<table width="100%" border="0" rules="none" frame="void"
 
<table width="100%" border="0" rules="none" frame="void"
Line 646: Line 1,117:
 
==== snapshot-delete ====
 
==== snapshot-delete ====
  
<p style="margin-left:11%; margin-top: 1em">Delete the
+
<p style="margin-top: 1em">Delete the specifed snapshot.
specifed snapshot. This operation can only be performed if
+
This operation can only be performed if the specified
the specified snapshot is not active. In case snapshot
+
snapshot is not active. In case snapshot doesn&rsquo;t have
doesn&rsquo;t have any children, it will simply be removed.
+
any children, it will simply be removed. In case snapshot
In case snapshot has a single child, it will be merged to
+
has a single child, it will be merged to that child.
that child. Deleting a snapshot that has multiple children
+
Deleting a snapshot that has multiple children is currently
is currently not supported (but can be performed manually in
+
not supported (but can be performed manually in an iterative
an iterative fashion).</p>
+
fashion).</p>
  
 
<table width="100%" border="0" rules="none" frame="void"
 
<table width="100%" border="0" rules="none" frame="void"
Line 680: Line 1,151:
 
==== snapshot-list ====
 
==== snapshot-list ====
  
<p style="margin-left:11%; margin-top: 1em">List available
+
<p style="margin-top: 1em">List available snapshots.</p>
snapshots.</p>
 
  
 
<table width="100%" border="0" rules="none" frame="void"
 
<table width="100%" border="0" rules="none" frame="void"
Line 694: Line 1,164:
  
 
<p style="margin-top: 1em">[<b>-H</b>]
 
<p style="margin-top: 1em">[<b>-H</b>]
[<b>-u&nbsp;</b><i>uuid</i>]
+
[<b>-u&nbsp;</b><i>uuid</i>] [<b>-s</b>]
 
[<b>-o&nbsp;</b><i>field</i>[,<i>field</i>...]]
 
[<b>-o&nbsp;</b><i>field</i>[,<i>field</i>...]]
 
<i>DiskDescriptor.xml</i></p> </td></tr>
 
<i>DiskDescriptor.xml</i></p> </td></tr>
Line 714: Line 1,184:
 
<p style="margin-left:42%;">Filter the output to a
 
<p style="margin-left:42%;">Filter the output to a
 
specified <i>uuid</i>.</p>
 
specified <i>uuid</i>.</p>
 +
 +
<table width="100%" border="0" rules="none" frame="void"
 +
      cellspacing="0" cellpadding="0">
 +
<tr valign="top" align="left">
 +
<td width="11%"></td>
 +
<td width="21%">
 +
 +
<p><b>-s</b>, <b>--snapshot</b></p></td>
 +
<td width="10%"></td>
 +
<td width="58%">
 +
 +
<p>List in terms of snapshots. By default (i.e. without
 +
this option) the command lists all deltas, and top delta is
 +
marked as current. When this option is used, top delta is
 +
not listed, and the snapshot which is the parent of top
 +
delta is marked as current.</p></td></tr>
 +
</table>
  
 
<p style="margin-left:11%;"><b>-o</b>, <b>--output</b>
 
<p style="margin-left:11%;"><b>-o</b>, <b>--output</b>
Line 727: Line 1,214:
 
&bull; <b>fname</b> - snapshot image file name.</p>
 
&bull; <b>fname</b> - snapshot image file name.</p>
  
=== ADVANCED COMMANDS ===
+
=== Image copying ===
 +
 
 +
<p style="margin-top: 1em"><b>ploop copy</b> is a mechanism
 +
of effective copying of a top ploop image with the help of
 +
build-in ploop kernel driver feature called write tracker.
 +
Write tracker is a feature that lets <b>ploop copy</b> to
 +
iteratively obtain a list of modified image blocks from the
 +
kernel. Two <b>ploop copy</b> processes are required for
 +
iterative top delta transfer. These are used by
 +
<b>vzmigrate(8).</b></p>
  
==== shapshot ====
+
==== copy (sending) ====
  
 
<table width="100%" border="0" rules="none" frame="void"
 
<table width="100%" border="0" rules="none" frame="void"
Line 735: Line 1,231:
 
<tr valign="top" align="left">
 
<tr valign="top" align="left">
 
<td width="11%"></td>
 
<td width="11%"></td>
<td width="21%">
+
<td width="15%">
  
<p style="margin-top: 1em"><b>ploop&nbsp;snapshot</b></p></td>
+
<p style="margin-top: 1em"><b>ploop&nbsp;copy</b></p></td>
 
<td width="2%"></td>
 
<td width="2%"></td>
<td width="66%">
+
<td width="72%">
 +
 
 +
<p style="margin-top: 1em"><b>-s</b> <i>device</i>
 +
[<b>-F&nbsp;</b><i>stop_command</i>] {
 +
[<b>-d&nbsp;</b><i>file</i>] |
 +
[<b>-o&nbsp;</b><i>output_fd</i>]
 +
[<b>-f&nbsp;</b><i>feedback_fd</i>] }</p></td></tr>
 +
</table>
 +
 
 +
<p style="margin-top: 1em">This command enables the
 +
in-kernel write tracker for the specified ploop
 +
<i>device,</i> then sends all the data blocks from the top
 +
delta image to a pipe specified by the <i>output_fd</i>
 +
argument (<b>stdout</b>, i.e. <b>1</b> by default),
 +
supposedly read by destination <b>ploop copy</b>, or a
 +
<i>file</i>. After that, it iteratively gets the list of the
 +
modified data blocks from the kernel and sends those blocks
 +
again. After a number of iterations (or when the list is
 +
empty), it executes the <i>stop_command</i> (this could be
 +
<b>vzctl stop</b> or <b>vzctl chkpnt</b>) and does the last
 +
iteration of sending the modified data blocks. Finally, it
 +
checks that the data were not modified, error is returned
 +
otherwise.</p>
 +
 
 +
<p style="margin-top: 1em">If <i>feedback_fd</i> is
 +
specified, it is used to read back from the ploop copy
 +
receiving side. The feedback channel is currently used to
 +
wait for <b>fdatasync</b>(2) completion.</p>
 +
 
 +
==== copy (receiving) ====
  
<p style="margin-top: 1em">[<b>-F</b>]
+
<table width="100%" border="0" rules="none" frame="void"
[<b>-d&nbsp;</b><i>device</i>] <i>image_file</i></p></td></tr>
+
      cellspacing="0" cellpadding="0">
 
<tr valign="top" align="left">
 
<tr valign="top" align="left">
 
<td width="11%"></td>
 
<td width="11%"></td>
<td width="21%">
+
<td width="15%">
  
<p><b>-F</b></p></td>
+
<p style="margin-top: 1em"><b>ploop&nbsp;copy</b></p></td>
 
<td width="2%"></td>
 
<td width="2%"></td>
<td width="66%">
+
<td width="58%">
 +
 
 +
<p style="margin-top: 1em"><b>-d</b> <i>file</i>
 +
[<b>-i&nbsp;</b><i>input_fd</i>]
 +
[<b>-f&nbsp;</b><i>feedback_fd</i>]</p> </td>
 +
<td width="14%">
 +
</td></tr>
 +
</table>
 +
 
 +
<p style="margin-top: 1em">Reads the data blocks (provided
 +
by the source <b>ploop copy</b>) from the file descriptor
 +
<i>input_fd</i> (<b>stdin</b>, i.e. <b>0</b> by default) and
 +
writes them to the <i>file</i>.</p>
 +
 
 +
<p style="margin-top: 1em">If <i>feedback_fd</i> is
 +
specified, it is used to send status back to the ploop copy
 +
sending side.</p>
 +
 
 +
=== Ballooning ===
 +
 
 +
<p style="margin-top: 1em">Since there is no online shrink
 +
support in <b>ext4</b> file system, ploop internally uses a
 +
technique called &quot;ballooning&quot; as a work around to
 +
shrink its images.</p>
 +
 
 +
<p style="margin-top: 1em">Ballooning operation consists of
 +
inflating a special balloon file (invisible for ordinary
 +
users), loading fiemap info of the inflated balloon to the
 +
kernel, relocating blocks of the image file from the tail to
 +
the space specified by fiemap info, and truncating the tail
 +
of the image file. Result is the image file of a smaller
 +
size.</p>
 +
 
 +
<p style="margin-top: 1em">However, it is quite possible
 +
that inflated balloon file will only span blocks that were
 +
never touched before. Those will look like &quot;not
 +
allocated&quot; space from the kernel ploop point of view.
 +
In this case nothing will be relocated and nothing
 +
truncated.</p>
 +
 
 +
<p style="margin-top: 1em">So, if balloon operation
 +
succeeded, it&rsquo;s only guaranteed that a user of ploop
 +
device won&rsquo;t be able to consume more space than the
 +
initial block device size minus the size of the inflated
 +
balloon. On the other hand, if a user of block device used a
 +
lot of space on it, then freed the significant part of used
 +
space, balloon operation will result in significant truncate
 +
of image file.</p>
 +
 
 +
<p style="margin-top: 1em">All the ploop ballooning logic
 +
is hidden from the end user, so while a number of low-level
 +
commands exist for working with ploop ballooning, those are
 +
not needed and therefore are not documented here, except for
 +
a single command.</p>
  
<p>Freeze filesystem before making a snapshot. If the
+
==== balloon discard ====
option is not given, the file system will not be frozen and
 
snapshot will have an inconsistent file system. If you need
 
a quick snapshot, do not use this option. Journal will be
 
replayed when you mount the snapshot.</p></td></tr>
 
<tr valign="top" align="left">
 
<td width="11%"></td>
 
<td width="21%">
 
  
<p><b>-d</b> <i>device</i></p></td>
+
<p style="margin-top: 1em">In a situation when a lot of
<td width="2%"></td>
+
disk space were freed on an in-ploop filesystem, use
<td width="66%">
+
<b>ploop balloon discard</b> to optimize the ploop image
 +
size.</p>
  
<p>Ploop device, e.g., <b>/dev/ploop0</b>.</p></td></tr>
+
<table width="100%" border="0" rules="none" frame="void"
 +
      cellspacing="0" cellpadding="0">
 
<tr valign="top" align="left">
 
<tr valign="top" align="left">
 
<td width="11%"></td>
 
<td width="11%"></td>
<td width="21%">
+
<td width="32%">
  
<p><i>image_file</i></p></td>
+
<p style="margin-top: 1em"><b>ploop&nbsp;balloon&nbsp;discard</b></p> </td>
 
<td width="2%"></td>
 
<td width="2%"></td>
<td width="66%">
+
<td width="50%">
  
<p>Path to a file to write a new snapshot to. If this file
+
<p style="margin-top: 1em">[<b>--automount</b>]
already exists, <b>ploop snapshot</b> will exit with an
+
[<b>--to-free&nbsp;</b><i>size</i>]
error.</p> </td></tr>
+
[<b>--min-block&nbsp;</b><i>min_size</i>] [<b>--defrag</b>]
 +
<i>DiskDescriptor.xml</i></p> </td>
 +
<td width="5%">
 +
</td></tr>
 
</table>
 
</table>
  
== IMAGE FORMATS ==
+
<p style="margin-top: 1em">Iteratively try to relocate and
 +
discard unused blocks from a ploop image, reducing its
 +
size.</p>
 +
 
 +
<p style="margin-top: 1em">Note that ploop device and its
 +
inner file system should be mounted. If not, one can use
 +
<b>--automount</b> option to automatically mount ploop for
 +
the duration of the operation.</p>
 +
 
 +
<p style="margin-top: 1em">Option <b>--defrag</b> can be
 +
used to run a filesystem defragmentation utility (currently
 +
e4defrag2 on ext4 only) before the main operation.</p>
 +
 
 +
<p style="margin-top: 1em">Option <b>--to-free</b> can be
 +
used to specify a maximum disk space to be freed. In other
 +
words, stop the process once freed space exceeded requested
 +
<i>size</i>. Default is 0, meaning to try to free as much
 +
space as possible.</p>
 +
 
 +
<p style="margin-top: 1em">Option <b>--min-block</b> can be
 +
used to specify a minimum size of an extent to free. The
 +
smallest possible extent is 1 cluster (currently 1 MB), one
 +
can specify higher value to speed up the whole discarding
 +
operation.</p>
 +
 
 +
<p style="margin-top: 1em">Note that the same functionality
 +
is available by means of <b>vzctl compact</b> command.</p>
  
<p style="margin-left:11%; margin-top: 1em">The following
+
=== Image formats ===
image formats are currently supported.</p>
+
following image formats are currently supported.</p>
  
 
<table width="100%" border="0" rules="none" frame="void"
 
<table width="100%" border="0" rules="none" frame="void"
Line 787: Line 1,389:
 
<tr valign="top" align="left">
 
<tr valign="top" align="left">
 
<td width="11%"></td>
 
<td width="11%"></td>
<td width="4%">
+
<td width="24%">
 +
 
 +
<p><b>raw</b></p></td>
 +
<td width="10%"></td>
 +
<td width="55%">
 +
 
 +
<p>Raw format, with 1:1 mapping between the image file and
 +
the ploop device.</p></td></tr>
 +
<tr valign="top" align="left">
 +
<td width="11%"></td>
 +
<td width="24%">
 +
 
 +
<p><b>ploop1</b>,&nbsp;<b>expanded</b></p></td>
 +
<td width="10%"></td>
 +
<td width="55%">
 +
 
 +
<p>Expanded format. The image will grow according to the
 +
needs of the underlying file system. This format is the
 +
default. Names &rsquo;<b>ploop1</b>&rsquo; and
 +
&rsquo;<b>expanded</b>&rsquo; are aliases.</p></td></tr>
 +
<tr valign="top" align="left">
 +
<td width="11%"></td>
 +
<td width="24%">
  
<p style="margin-top: 1em"><b>raw</b></p></td>
+
<p><b>preallocated</b></p></td>
<td width="7%"></td>
+
<td width="10%"></td>
<td width="78%">
+
<td width="55%">
  
<p style="margin-top: 1em">Raw format, with 1:1 mapping
+
<p>This is the same as &rsquo;<b>ploop1</b>&rsquo; or
between the image file and the ploop device.</p></td></tr>
+
&rsquo;<b>expanded</b>&rsquo;, the only difference is all
 +
the file blocks are allocated during creation.</p></td></tr>
 
</table>
 
</table>
  
<p style="margin-left:11%;"><b>ploop1</b>,&nbsp;<b>expanded</b></p>
+
== EXIT STATUS ==
 +
 
 +
<p style="margin-left:11%; margin-top: 1em"><b>ploop</b>
 +
exits with status 0 in case of successful execution. Any
 +
status greater than 0 signifies an error. <b><br>
 +
1</b>,&nbsp;<b>SYSEXIT_CREAT</b></p>
 +
 
 +
<p style="margin-left:22%;">Error creating a file.</p>
 +
 
 +
<p style="margin-left:11%;"><b>2</b>,&nbsp;<b>SYSEXIT_DEVICE</b></p>
 +
 
 +
<p style="margin-left:22%;">Error getting or opening a
 +
ploop device.</p>
 +
 
 +
<p style="margin-left:11%;"><b>3</b>,&nbsp;<b>SYSEXIT_DEVIOC</b></p>
 +
 
 +
<p style="margin-left:22%;">Error doing <b>ioctl</b>(2) on
 +
ploop device.</p>
 +
 
 +
<p style="margin-left:11%;"><b>4</b>,&nbsp;<b>SYSEXIT_OPEN</b></p>
 +
 
 +
<p style="margin-left:22%;">Error opening a file.</p>
 +
 
 +
<p style="margin-left:11%;"><b>5</b>,&nbsp;<b>SYSEXIT_MALLOC</b></p>
 +
 
 +
<p style="margin-left:22%;">Not enough memory (error from
 +
<b>malloc</b>(3), <b>realloc</b>(3), <b>calloc</b>(3), or
 +
<b>posix_memalign</b>(3)).</p>
 +
 
 +
<p style="margin-left:11%;"><b>6</b>,&nbsp;<b>SYSEXIT_READ</b></p>
 +
 
 +
<p style="margin-left:22%;">Error during read.</p>
 +
 
 +
<p style="margin-left:11%;"><b>7</b>,&nbsp;<b>SYSEXIT_WRITE</b></p>
 +
 
 +
<p style="margin-left:22%;">Error during write.</p>
 +
 
 +
<p style="margin-left:11%;"><b>9</b>,&nbsp;<b>SYSEXIT_SYSFS</b></p>
 +
 
 +
<p style="margin-left:22%;">Error reading from a sysfs file
 +
(usually under <b>/sys/block/ploop...</b>).</p>
 +
 
 +
<p style="margin-left:11%;"><b>11</b>,&nbsp;<b>SYSEXIT_PLOOPFMT</b></p>
 +
 
 +
<p style="margin-left:22%;">Corrupted ploop image
 +
detected.</p>
 +
 
 +
<p style="margin-left:11%;"><b>12</b>,&nbsp;<b>SYSEXIT_SYS</b></p>
 +
 
 +
<p style="margin-left:22%;">Other system error.</p>
 +
 
 +
<p style="margin-left:11%;"><b>13</b>,&nbsp;<b>SYSEXIT_PROTOCOL</b></p>
 +
 
 +
<p style="margin-left:22%;">Broken protocol (unexpected
 +
value received).</p>
 +
 
 +
<p style="margin-left:11%;"><b>14</b>,&nbsp;<b>SYSEXIT_LOOP</b></p>
 +
 
 +
<p style="margin-left:22%;"><b>pcopy</b> command
 +
can&rsquo;t finalize copying (frozen filesystem is
 +
changing).</p>
 +
 
 +
<p style="margin-left:11%;"><b>15</b>,&nbsp;<b>SYSEXIT_FSTAT</b></p>
 +
 
 +
<p style="margin-left:22%;">Error from <b>stat</b>(2),
 +
<b>fstat</b>(2), or <b>statfs</b>(2).</p>
 +
 
 +
<p style="margin-left:11%;"><b>16</b>,&nbsp;<b>SYSEXIT_FSYNC</b></p>
 +
 
 +
<p style="margin-left:22%;">Error from <b>fsync</b>(2) or
 +
<b>syncfs</b>(2).</p>
 +
 
 +
<p style="margin-left:11%;"><b>17</b>,&nbsp;<b>SYSEXIT_EBUSY</b></p>
 +
 
 +
<p style="margin-left:22%;">Can&rsquo;t continue, another
 +
operation is in progress.</p>
 +
 
 +
<p style="margin-left:11%;"><b>18</b>,&nbsp;<b>SYSEXIT_FLOCK</b></p>
 +
 
 +
<p style="margin-left:22%;">Error from <b>flock</b>(2).</p>
 +
 
 +
<p style="margin-left:11%;"><b>19</b>,&nbsp;<b>SYSEXIT_FTRUNCATE</b></p>
 +
 
 +
<p style="margin-left:22%;">Error from <b>ftruncate</b>(2)
 +
or <b>truncate</b>(2).</p>
 +
 
 +
<p style="margin-left:11%;"><b>20</b>,&nbsp;<b>SYSEXIT_FALLOCATE</b></p>
 +
 
 +
<p style="margin-left:22%;">Error from
 +
<b>fallocate</b>(2).</p>
 +
 
 +
<p style="margin-left:11%;"><b>21</b>,&nbsp;<b>SYSEXIT_MOUNT</b></p>
 +
 
 +
<p style="margin-left:22%;">Can&rsquo;t mount ploop image
 +
or file system.</p>
 +
 
 +
<p style="margin-left:11%;"><b>22</b>,&nbsp;<b>SYSEXIT_UMOUNT</b></p>
 +
 
 +
<p style="margin-left:22%;">Can&rsquo;t unmount ploop image
 +
or file system.</p>
 +
 
 +
<p style="margin-left:11%;"><b>23</b>,&nbsp;<b>SYSEXIT_LOCK</b></p>
 +
 
 +
<p style="margin-left:22%;">Locking failed (another
 +
operation in progress?).</p>
 +
 
 +
<p style="margin-left:11%;"><b>24</b>,&nbsp;<b>SYSEXIT_MKFS</b></p>
 +
 
 +
<p style="margin-left:22%;">Can&rsquo;t create file
 +
system.</p>
 +
 
 +
<p style="margin-left:11%;"><b>26</b>,&nbsp;<b>SYSEXIT_RESIZE_FS</b></p>
 +
 
 +
<p style="margin-left:22%;">Utility <b>resizefs</b>
 +
failed.</p>
 +
 
 +
<p style="margin-left:11%;"><b>27</b>,&nbsp;<b>SYSEXIT_MKDIR</b></p>
 +
 
 +
<p style="margin-left:22%;">Error from <b>mkdir</b>(2).</p>
 +
 
 +
<p style="margin-left:11%;"><b>28</b>,&nbsp;<b>SYSEXIT_RENAME</b></p>
 +
 
 +
<p style="margin-left:22%;">Error from
 +
<b>rename</b>(2).</p>
 +
 
 +
<p style="margin-left:11%;"><b>29</b>,&nbsp;<b>SYSEXIT_ABORT</b></p>
 +
 
 +
<p style="margin-left:22%;">Operation aborted.</p>
 +
 
 +
<p style="margin-left:11%;"><b>30</b>,&nbsp;<b>SYSEXIT_RELOC</b></p>
 +
 
 +
<p style="margin-left:22%;">Block relocation failed.</p>
 +
 
 +
<p style="margin-left:11%;"><b>33</b>,&nbsp;<b>SYSEXIT_CHANGE_GPT</b></p>
 +
 
 +
<p style="margin-left:22%;">Error resizing GPT partition
 +
table.</p>
 +
 
 +
<p style="margin-left:11%;"><b>35</b>,&nbsp;<b>SYSEXIT_UNLINK</b></p>
 +
 
 +
<p style="margin-left:22%;">Error from
 +
<b>unlink</b>(2).</p>
 +
 
 +
<p style="margin-left:11%;"><b>36</b>,&nbsp;<b>SYSEXIT_MKNOD</b></p>
 +
 
 +
<p style="margin-left:22%;">Error from <b>mknod</b>(2).</p>
 +
 
 +
<p style="margin-left:11%;"><b>37</b>,&nbsp;<b>SYSEXIT_PLOOPINUSE</b></p>
 +
 
 +
<p style="margin-left:22%;">Image is already in use.</p>
 +
 
 +
<p style="margin-left:11%;"><b>38</b>,&nbsp;<b>SYSEXIT_PARAM</b></p>
 +
 
 +
<p style="margin-left:22%;">Invalid parameter.</p>
 +
 
 +
<p style="margin-left:11%;"><b>39</b>,&nbsp;<b>SYSEXIT_DISKDESCR</b></p>
 +
 
 +
<p style="margin-left:22%;">Problem with DiskDescriptor.xml
 +
file.</p>
  
<p style="margin-left:22%;">Expanded format. The image will
+
<p style="margin-left:11%;"><b>40</b>,&nbsp;<b>SYSEXIT_DEV_NOT_MOUNTED</b></p>
grow according to the needs of the underlying file system.
 
This format is the default. Names
 
&rsquo;<b>ploop1</b>&rsquo; and
 
&rsquo;<b>expanded</b>&rsquo; are aliases.</p>
 
  
<p style="margin-left:11%;"><b>preallocated</b></p>
+
<p style="margin-left:22%;">Ploop image is not mounted.</p>
  
<p style="margin-left:22%;">This is the same as
+
<p style="margin-left:11%;"><b>41</b>,&nbsp;<b>SYSEXIT_FSCK</b></p>
&rsquo;<b>ploop1</b>&rsquo; or
+
 
&rsquo;<b>expanded</b>&rsquo;, the only difference is all
+
<p style="margin-left:22%;">Error from <b>fsck</b>(8).</p>
the file blocks are allocated during creation.</p>
+
 
 +
<p style="margin-left:11%;"><b>43</b>,&nbsp;<b>SYSEXIT_NOSNAP</b></p>
 +
 
 +
<p style="margin-left:22%;">Can&rsquo;t find specified
 +
snapshot UUID.</p>
  
 
== SEE ALSO ==
 
== SEE ALSO ==
  
<p style="margin-left:11%; margin-top: 1em">[[Man/vzctl.8|<b>vzctl</b>(8)]].</p>
+
<p style="margin-left:11%; margin-top: 1em">[[Man/vzctl.8|<b>vzctl</b>(8)]],
 +
[[Man/vzmigrate.8|<b>vzmigrate</b>(8)]], <b>http://openvz.org/Ploop</b>.</p>

Latest revision as of 18:51, 28 November 2016

NAME[edit]

ploop − ploop device management utility

SYNOPSYS[edit]

ploop init

-s size [-f format] [-v version] [-t fstype] [-b blocksize] [-B fsblocksize] [--nolazy] delta_file

ploop mount

[-r] [-F] [-f format] [-b blocksize] [-d device] [-m mount_point] [-o mount_options] [-t fstype] base_delta [... top_delta]

ploop mount

[-r] [-F] [-d device] [-m mount_point] [-o mount_options] [-t fstype] [-u uuid] DiskDescriptor.xml

ploop umount

{ -d device | -m mount_point | DiskDescriptor.xml | image_file }

ploop replace

{ -u uuid | -l level | -o cur_image_file } [--keep-name] -i image_file DiskDescriptor.xml

ploop resize

-s size DiskDescriptor.xml

ploop convert

{ -f format | -v version } DiskDescriptor.xml

ploop check

[-u uuid] DiskDescriptor.xml

ploop check

[--force] [--hard-force] [--check] [--ro] [--silent] [--drop-inuse] [--raw] [--blocksize size] [--repair-sparse] image_file

ploop info

[-s] [-d] DiskDescriptor.xml

ploop list

[-a]

ploop snapshot

[-u uuid] DiskDescriptor.xml

ploop snapshot-merge

[-u uuid [-U uuid2] | -A] [-n new_delta] DiskDescriptor.xml

ploop snapshot-switch

-u uuid DiskDescriptor.xml

ploop snapshot-delete

-u uuid DiskDescriptor.xml

ploop snapshot-list

[-H] [-u uuid] [-s] [-o field[,field...]] DiskDescriptor.xml

ploop copy

-s device [-F stop_command] { [-d file] | [-o output_fd] [-f feedback_fd] }

ploop copy

-d file [-i input_fd] [-f feedback_fd]

ploop balloon discard

[--automount] [--to-free size] [--min-block min_size] [--defrag] DiskDescriptor.xml

ploop restore-descriptor

-f format [-b blocksize] disk_dir delta_file

DESCRIPTION[edit]

ploop is a kernel block device, similar to the traditional loop device (which is controlled by losetup(8)) but with more features added, such as dynamic disk space allocation, stackable images, online resize, snapshotting, and live migration helper (write tracker). This manual page describes the ploop user space tool which is used to perform various operations related to ploop devices and images.

Note that this ploop tool is not aware of container entities. Commands that have DiskDescriptor.xml as an argument work with an XML file that contains meta-information about a particular ploop device configuration: device characteristics (block size etc.), storage information (names and formats of images used for the device), snapshot information, etc. If a particular command can be used both with and without the DiskDescriptor.xml argument, it is strongly advised to use the form with DiskDescriptor.xml.

OPTIONS[edit]

Run ploop without any options to show a short synopsys, including a list of commands.

Run ploop command to show synopsys and a short description for a particular command.

Basic commands[edit]

init[edit]

Create and initalize a ploop image file and a corresponding DiskDescriptor.xml file.

ploop init

-s size [-f format] [-v version] [-t fstype] [-b blocksize] [-B fsblocksize] [--nolazy] delta_file

-s size

Image size. If no suffix is specified, the size is in sector units (one sector is 512 bytes). One can specify optional K, M, G or T suffix to set the size in kilo-, mega-, giga- or terabytes.

-f format

Image format. See Image formats below.

-v version

Image version, can be 1 or 2. Default is 2, if supported by the kernel.

-t none|ext3|ext4

File system type to create, default is ext4. Unless none is specified, a partition, a filesystem, and a balloon file will be created inside the image. Using ext3 is not recommended.

-b blocksize

Device block size, in 512 byte sectors. Default block size is 2048 sectors, or 1 megabyte.

-B fsblocksize

Filesystem block size, in bytes. Default is 4096 bytes.

-n, --nolazy

Disable lazy mkfs initialization (which is enabled by default). Currently that means if this flag is set, mkfs.ext4(8) is called with -Elazy_itable_init=0,lazy_journal_init=0 options.

delta_file

Path to a non-existent image file to be created.

mount[edit]

Assemble a ploop device from one or more delta images, start it, and optionally mount the file system residing on the device.

Two forms of this command are provided. The first one accepts a list of delta images to be used for assembling the ploop device, while the second one is using information from a DiskDescriptor.xml file. Please note that not all mount options are applicable to both forms.

ploop mount

[-r] [-F] [-f format] [-b blocksize] [-d device] [-m mount_point] [-o mount_options] [-t fstype] base_delta [... top_delta]

ploop mount

[-r] [-F] [-d device] [-m mount_point] [-o mount_options] [-t fstype] [-u uuid] DiskDescriptor.xml

-r

Mount as read-only.

-F

Run fsck(8) on inner filesystem before mounting it. This option is ignored if -m is not used.

-f format

Image format. Ignored if DiskDescriptor.xml is specified. Otherwise, one need to specify raw as an argument, if raw image format is used.

-b blocksize

Device block size, in 512 byte sectors. Ignored if DiskDescriptor.xml is specified. Otherwise, required for raw images.

-d device

Ploop device to use, e.g. /dev/ploop0. If not specified, a randomly numbered ploop device will be used.

-m mount_point

If this option is specified, ploop goes on to mount the file system to directory denoted by mount_point.

-o mount_options

Any additional mount options, comma-separated. Used if -m is set.

-t fstype

File system type used for mounting. Used if -m is set. The default is ext4.

-u uuid | base

GUID of the image from the DiskDescriptor.xml to be mounted. By default, top GUID is used. The special ’base’ value can be used to mount the base (lower-level) image.

base_delta [... top_delta]

List of image files to mount, with the first one being the base delta and the last one being the top delta (i.e. the one that will be writable unless -r is specified).

DiskDescriptor.xml

Path to the DiskDescriptor.xml file with information about images.

umount[edit]

Unmount a ploop device. Since a mounted ploop device consists of an image (or multiple images), a device, and (optionally) a file system mounted to a directory, one can refer to any of the above entities to specify what to unmount. The recommended way is to use DiskDescriptor.xml.

ploop umount

{ -d device | -m mount_point | DiskDescriptor.xml | image_file }

-d device

Ploop device, e.g., /dev/ploop0.

-m mount_point

Mount point of a ploop device to unmount.

DiskDescriptor.xml

Path to the DiskDescriptor.xml file with information about images.

image_file

Path to a mounted image file.

replace[edit]

Replaces a ploop image by a different (but identical) one, on a running ploop device. Only a read-only image (e.g. a non-top one in a stacked configuration) can be replaced. An image to be replaced is specified by either one of level, UUID, or the current image file.

If a new image is not identical to the old one (i.e. its content differs) or not suitable for ploop in any other way (e.g. it is sparse, or resides on a file system not supported by ploop), the result is undefined.

ploop replace

{ -u uuid | -l level | -o cur_image_file } [--keep-name] -i image_file DiskDescriptor.xml

-u uuid

A uuid of an image to be replaced.

-l level

A level of image to be replaced. A level is a distance of an image from the base delta.

-o cur_image_file

A current image file (the one to replace).

-k, --keep-name

A flag to keep the same image file name. If this flag is set, after the image is replaced, a new image_file is renamed to the old one (removing the old, now unused, image), so no modification to DiskDescriptor.xml is required.

-i image_file

A new replacement image.

DiskDescriptor.xml

Path to the DiskDescriptor.xml file with information about images.

resize[edit]

Resize a ploop image. Both online (i.e. when ploop is mounted and used) and offline resize is supported, and the tool can either grow or shrink both the ploop image and the underlying file system.

ploop resize

-s size DiskDescriptor.xml

-s size

Image size. If no suffix is specified, size is in sector units (one sector is 512 bytes). One can specify optional K, M, G or T suffix to set the size in kilo-, mega-, giga- or terabytes.

DiskDescriptor.xml

Path to the DiskDescriptor.xml file with information about images.

convert[edit]

Convert either ploop image format or version (but not both at the same time). Conversion can only be performed offline (i.e. image should not be in use).

ploop convert

{ -f format | -v version } DiskDescriptor.xml

-f format

Image format. See Image formats below.

-v version

Image version, can be 1 or 2.

check[edit]

Check the internal consistency of (and possibly repair) a ploop image (or images). Note that image(s) to be tested should not be in use.

ploop check

[-u uuid] DiskDescriptor.xml

Check all the images in DiskDescriptor.xml up to the one denoted by the uuid (or default top delta, if UUID is not specified). Default built-in check options are used, and the ones specified on the command line, if any, are ignored.

ploop check

[--force] [--hard-force] [--check] [--ro] [--silent] [--drop-inuse] [--raw] [--blocksize size] [--repair-sparse] DiskDescriptor.xml | image_file

-f, --force

Force check even if image’s dirty flag is not set.

-F, --hard-force

Same as -f, plus try to fix even fatal errors (can be dangerous).

-c, --check

Check for duplicated blocks and holes.

-r, --ro

Read-only access, do not modify image(s).

-s, --silent

Be more silent, only report errors.

-d, --drop-inuse

Drop image "in use" flag.

-R, --raw

Specifies that image_file is a raw ploop image.

-b, --blocksize size

Image cluster block size, in sectors (for raw images).

-S, --repair-sparse

Repair sparse image(s).

Miscellaneous commands[edit]

info[edit]

ploop info

DiskDescriptor.xml

When run without any options, show information about disk space and inodes usage and limits on the inner ploop filesystem, somewhat similar to vzquota(8) stat or show commands.

ploop info

[-s] [-d] DiskDescriptor.xml

Either one or both options can be used together. Option -s is used to show information about ploop device size, block size, and format version. Option -d is used to show a corresponding ploop block device, it available. file.

list[edit]

ploop list

[-a]

Shows a list of running ploop devices (first column) and their corresponding base images. With option -a it also shows a mount point (third column).

restore-descriptor[edit]

Create DiskDescriptor.xml file suitable for delta_file and put it into disk_dir.

ploop restore-descriptor

-f format [-b blocksize] disk_dir delta_file

Read image header in case of ploop1 format or check raw image size and generate proper DiskDescriptor.xml file. You can specify blocksize for raw images. If it’s not specified it will be choosen automatically - largest possible value between 32K and 1M. Raw image size must be aligned to blocksize.

This command works only for base images. Snapshots are not supported.

Working with snapshots[edit]

Ploop snapshots is a mechanism for creating and managing instant states of a running file system. Creating a snapshot leads to creating a new empty ploop image which is layered on top of an old one, then all writes are ending up in the top image, and reads are falling through to a lower level. There can be up to 126) stacked ploop images (or snapshots). Online snapshot merging is also supported.

Snapshots are identified by a unique UUID. A snapshot can be mounted using ploop mount -u uuid command, see above.

snapshot[edit]

Create a ploop snapshot.

ploop snapshot

[-u uuid] DiskDescriptor.xml

-u uuid

Specify a uuid for a new snapshot. If option is not given, uuid is generated automatically. To generate uuid manually, one can use the uuidgen(1) utility. Note that UUID must be enclosed in curly brackets.

snapshot-merge[edit]

Merge a snapshot with its parent. That is, contents of the delta file corresponding to the snapshot is merged to a parent delta, then the file is removed. Parent snapshot UUID is lost (as it is replaced with the uuid specified). All snapshots having the lost one as a parent are updated to have the uuid as its parent.

ploop snapshot-merge

[-u uuid [-U uuid2] | -A] [-n new_delta] DiskDescriptor.xml

-u uuid

Specify a single snapshot uuid to merge. If this option is not specified, the top delta will be used.

-U uuid2

Together with -u uuid, specify that all snapshots in the range uuid...uuid2 are to be merged.

-A

Merge all snapshots down to base delta. If some snapshots have more than a single child, they will be impossible to merge.

-n new_delta

If this option is set, instead of merging the child delta into its parent, both the parent and the child deltas are merged into a newly created file new_delta, which replaces the parent delta. Both deltas are then removed.

snapshot-switch[edit]

Switch to the specified snapshot. This operation can only be performed while ploop is not running (i.e. is unmounted). The current top delta image will be removed.

ploop snapshot-switch

-u uuid DiskDescriptor.xml

-u uuid

Specify a snapshot uuid to switch to.

snapshot-delete[edit]

Delete the specifed snapshot. This operation can only be performed if the specified snapshot is not active. In case snapshot doesn’t have any children, it will simply be removed. In case snapshot has a single child, it will be merged to that child. Deleting a snapshot that has multiple children is currently not supported (but can be performed manually in an iterative fashion).

ploop snapshot-delete

-u uuid DiskDescriptor.xml

-u uuid

Specify a snapshot uuid to be deleted.

snapshot-list[edit]

List available snapshots.

ploop snapshot-list

[-H] [-u uuid] [-s] [-o field[,field...]] DiskDescriptor.xml

-H, --no-header

Suppress displaying the header row. Usable for scripts.

-u, --uuid, --id uuid

Filter the output to a specified uuid.

-s, --snapshot

List in terms of snapshots. By default (i.e. without this option) the command lists all deltas, and top delta is marked as current. When this option is used, top delta is not listed, and the snapshot which is the parent of top delta is marked as current.

-o, --output field[,field...]

Display only the specified fields. Possible fields are:
uuid - snapshot’s UUID;
parent_uuid - snapshot’s parent UUID;
current - if this snapshot is the current one;
fname - snapshot image file name.

Image copying[edit]

ploop copy is a mechanism of effective copying of a top ploop image with the help of build-in ploop kernel driver feature called write tracker. Write tracker is a feature that lets ploop copy to iteratively obtain a list of modified image blocks from the kernel. Two ploop copy processes are required for iterative top delta transfer. These are used by vzmigrate(8).

copy (sending)[edit]

ploop copy

-s device [-F stop_command] { [-d file] | [-o output_fd] [-f feedback_fd] }

This command enables the in-kernel write tracker for the specified ploop device, then sends all the data blocks from the top delta image to a pipe specified by the output_fd argument (stdout, i.e. 1 by default), supposedly read by destination ploop copy, or a file. After that, it iteratively gets the list of the modified data blocks from the kernel and sends those blocks again. After a number of iterations (or when the list is empty), it executes the stop_command (this could be vzctl stop or vzctl chkpnt) and does the last iteration of sending the modified data blocks. Finally, it checks that the data were not modified, error is returned otherwise.

If feedback_fd is specified, it is used to read back from the ploop copy receiving side. The feedback channel is currently used to wait for fdatasync(2) completion.

copy (receiving)[edit]

ploop copy

-d file [-i input_fd] [-f feedback_fd]

Reads the data blocks (provided by the source ploop copy) from the file descriptor input_fd (stdin, i.e. 0 by default) and writes them to the file.

If feedback_fd is specified, it is used to send status back to the ploop copy sending side.

Ballooning[edit]

Since there is no online shrink support in ext4 file system, ploop internally uses a technique called "ballooning" as a work around to shrink its images.

Ballooning operation consists of inflating a special balloon file (invisible for ordinary users), loading fiemap info of the inflated balloon to the kernel, relocating blocks of the image file from the tail to the space specified by fiemap info, and truncating the tail of the image file. Result is the image file of a smaller size.

However, it is quite possible that inflated balloon file will only span blocks that were never touched before. Those will look like "not allocated" space from the kernel ploop point of view. In this case nothing will be relocated and nothing truncated.

So, if balloon operation succeeded, it’s only guaranteed that a user of ploop device won’t be able to consume more space than the initial block device size minus the size of the inflated balloon. On the other hand, if a user of block device used a lot of space on it, then freed the significant part of used space, balloon operation will result in significant truncate of image file.

All the ploop ballooning logic is hidden from the end user, so while a number of low-level commands exist for working with ploop ballooning, those are not needed and therefore are not documented here, except for a single command.

balloon discard[edit]

In a situation when a lot of disk space were freed on an in-ploop filesystem, use ploop balloon discard to optimize the ploop image size.

ploop balloon discard

[--automount] [--to-free size] [--min-block min_size] [--defrag] DiskDescriptor.xml

Iteratively try to relocate and discard unused blocks from a ploop image, reducing its size.

Note that ploop device and its inner file system should be mounted. If not, one can use --automount option to automatically mount ploop for the duration of the operation.

Option --defrag can be used to run a filesystem defragmentation utility (currently e4defrag2 on ext4 only) before the main operation.

Option --to-free can be used to specify a maximum disk space to be freed. In other words, stop the process once freed space exceeded requested size. Default is 0, meaning to try to free as much space as possible.

Option --min-block can be used to specify a minimum size of an extent to free. The smallest possible extent is 1 cluster (currently 1 MB), one can specify higher value to speed up the whole discarding operation.

Note that the same functionality is available by means of vzctl compact command.

Image formats[edit]

following image formats are currently supported.

raw

Raw format, with 1:1 mapping between the image file and the ploop device.

ploop1expanded

Expanded format. The image will grow according to the needs of the underlying file system. This format is the default. Names ’ploop1’ and ’expanded’ are aliases.

preallocated

This is the same as ’ploop1’ or ’expanded’, the only difference is all the file blocks are allocated during creation.

EXIT STATUS[edit]

ploop exits with status 0 in case of successful execution. Any status greater than 0 signifies an error.
1
SYSEXIT_CREAT

Error creating a file.

2SYSEXIT_DEVICE

Error getting or opening a ploop device.

3SYSEXIT_DEVIOC

Error doing ioctl(2) on ploop device.

4SYSEXIT_OPEN

Error opening a file.

5SYSEXIT_MALLOC

Not enough memory (error from malloc(3), realloc(3), calloc(3), or posix_memalign(3)).

6SYSEXIT_READ

Error during read.

7SYSEXIT_WRITE

Error during write.

9SYSEXIT_SYSFS

Error reading from a sysfs file (usually under /sys/block/ploop...).

11SYSEXIT_PLOOPFMT

Corrupted ploop image detected.

12SYSEXIT_SYS

Other system error.

13SYSEXIT_PROTOCOL

Broken protocol (unexpected value received).

14SYSEXIT_LOOP

pcopy command can’t finalize copying (frozen filesystem is changing).

15SYSEXIT_FSTAT

Error from stat(2), fstat(2), or statfs(2).

16SYSEXIT_FSYNC

Error from fsync(2) or syncfs(2).

17SYSEXIT_EBUSY

Can’t continue, another operation is in progress.

18SYSEXIT_FLOCK

Error from flock(2).

19SYSEXIT_FTRUNCATE

Error from ftruncate(2) or truncate(2).

20SYSEXIT_FALLOCATE

Error from fallocate(2).

21SYSEXIT_MOUNT

Can’t mount ploop image or file system.

22SYSEXIT_UMOUNT

Can’t unmount ploop image or file system.

23SYSEXIT_LOCK

Locking failed (another operation in progress?).

24SYSEXIT_MKFS

Can’t create file system.

26SYSEXIT_RESIZE_FS

Utility resizefs failed.

27SYSEXIT_MKDIR

Error from mkdir(2).

28SYSEXIT_RENAME

Error from rename(2).

29SYSEXIT_ABORT

Operation aborted.

30SYSEXIT_RELOC

Block relocation failed.

33SYSEXIT_CHANGE_GPT

Error resizing GPT partition table.

35SYSEXIT_UNLINK

Error from unlink(2).

36SYSEXIT_MKNOD

Error from mknod(2).

37SYSEXIT_PLOOPINUSE

Image is already in use.

38SYSEXIT_PARAM

Invalid parameter.

39SYSEXIT_DISKDESCR

Problem with DiskDescriptor.xml file.

40SYSEXIT_DEV_NOT_MOUNTED

Ploop image is not mounted.

41SYSEXIT_FSCK

Error from fsck(8).

43SYSEXIT_NOSNAP

Can’t find specified snapshot UUID.

SEE ALSO[edit]

vzctl(8), vzmigrate(8), http://openvz.org/Ploop.