Man/ploop.8

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 snapshot

[-u uuid] DiskDescriptor.xml

	ploop snapshot-merge	[-u uuid] 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

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.

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 fstype		File system type. If this parameter is specified, a partition, a filesystem, and a balloon file will be created inside the image. Currently supported types are ext3 and ext4. 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.i, /dev/ploop0. If not specified, the first unused 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 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. If not specified, the first unused ploop device will be used.

-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. Online resize is supported, and the tool can either grow or shrink 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 ploop image format or version.

	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. Only offline image version conversion is supported.

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

ADVANCED COMMANDS

shapshot

	ploop snapshot		[-F] [-d device] image_file
	-F		Freeze filesystem before making a snapshot. If the 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.
	-d device		Ploop device, e.g., /dev/ploop0.
	image_file		Path to a file to write a new snapshot to. If this file already exists, ploop snapshot will exit with an error.

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.

SEE ALSO

vzctl(8).