Provided by: ploop_1.15-5_amd64 
NAME
ploop - ploop device management utility
SYNOPSYS
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
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
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
init
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
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
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
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
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
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
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
info
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
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
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
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
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
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
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
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
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
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)
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)
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
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
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
The following image formats are currently supported.
raw Raw format, with 1:1 mapping between the image file and the ploop device.
ploop1, expanded
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
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.
2, SYSEXIT_DEVICE
Error getting or opening a ploop device.
3, SYSEXIT_DEVIOC
Error doing ioctl(2) on ploop device.
4, SYSEXIT_OPEN
Error opening a file.
5, SYSEXIT_MALLOC
Not enough memory (error from malloc(3), realloc(3), calloc(3), or posix_memalign(3)).
6, SYSEXIT_READ
Error during read.
7, SYSEXIT_WRITE
Error during write.
9, SYSEXIT_SYSFS
Error reading from a sysfs file (usually under /sys/block/ploop...).
11, SYSEXIT_PLOOPFMT
Corrupted ploop image detected.
12, SYSEXIT_SYS
Other system error.
13, SYSEXIT_PROTOCOL
Broken protocol (unexpected value received).
14, SYSEXIT_LOOP
pcopy command can't finalize copying (frozen filesystem is changing).
15, SYSEXIT_FSTAT
Error from stat(2), fstat(2), or statfs(2).
16, SYSEXIT_FSYNC
Error from fsync(2) or syncfs(2).
17, SYSEXIT_EBUSY
Can't continue, another operation is in progress.
18, SYSEXIT_FLOCK
Error from flock(2).
19, SYSEXIT_FTRUNCATE
Error from ftruncate(2) or truncate(2).
20, SYSEXIT_FALLOCATE
Error from fallocate(2).
21, SYSEXIT_MOUNT
Can't mount ploop image or file system.
22, SYSEXIT_UMOUNT
Can't unmount ploop image or file system.
23, SYSEXIT_LOCK
Locking failed (another operation in progress?).
24, SYSEXIT_MKFS
Can't create file system.
26, SYSEXIT_RESIZE_FS
Utility resizefs failed.
27, SYSEXIT_MKDIR
Error from mkdir(2).
28, SYSEXIT_RENAME
Error from rename(2).
29, SYSEXIT_ABORT
Operation aborted.
30, SYSEXIT_RELOC
Block relocation failed.
33, SYSEXIT_CHANGE_GPT
Error resizing GPT partition table.
35, SYSEXIT_UNLINK
Error from unlink(2).
36, SYSEXIT_MKNOD
Error from mknod(2).
37, SYSEXIT_PLOOPINUSE
Image is already in use.
38, SYSEXIT_PARAM
Invalid parameter.
39, SYSEXIT_DISKDESCR
Problem with DiskDescriptor.xml file.
40, SYSEXIT_DEV_NOT_MOUNTED
Ploop image is not mounted.
41, SYSEXIT_FSCK
Error from fsck(8).
43, SYSEXIT_NOSNAP
Can't find specified snapshot UUID.
SEE ALSO
vzctl(8), vzmigrate(8), http://openvz.org/Ploop.