Ubuntu Manpage: ploop - ploop device management utility

NAME

       ploop - ploop device management utility

SYNOPSYS

       ploop init -s size [-f format] [-v version] [-t fstype] [-b blocksize] [-B fsblocksize]
                  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 resize -s size DiskDescriptor.xml

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

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

       ploop info [-s] DiskDescriptor.xml

       ploop list [-a]

       ploop snapshot [-u uuid] DiskDescriptor.xml

       ploop snapshot-merge [-u uuid | -A] DiskDescriptor.xml

       ploop snapshot-switch -u uuid DiskDescriptor.xml

       ploop snapshot-delete -u uuid DiskDescriptor.xml

       ploop snapshot-list [-H] [-u uuid] [-o field[,field...]]  DiskDescriptor.xml

       ploop copy -s device [-F stop_command] [-d file]

       ploop copy -d file

       ploop balloon discard [--automount] [--to-free size] [--min-block min_size]
                             DiskDescriptor.xml

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]
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.

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.

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. If DiskDescriptor.xml is supplied, all
the images one by one are checked.

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
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 DiskDescriptor.xml
Show information about ploop device size, block size, and format version.

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).

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.

ploop snapshot-merge [-u uuid | -A] DiskDescriptor.xml

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

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

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] [-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.

-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]

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 stdout (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.

copy (receiving)

ploop copy -d file

Reads the data block (provided by the source ploop copy) from the stdin and writes them to
the file.

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]
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 --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).

NAME

SYNOPSYS

DESCRIPTION

OPTIONS

EXIT STATUS

SEE ALSO