Changes

← Older edit

Man/ploop.8

24,633 bytes added, 18:51, 28 November 2016

Bot: Automated import of articles *** existing text overwritten ***

[-t fstype]

[-b blocksize]

[-B fsblocksize] [--nolazy]delta_file</td></tr>

-m mount_point | DiskDescriptor.xml |

image_file }</td></tr>

ploop replace</td>

{ -u uuid |

-l level | -o cur_image_file }

[--keep-name] -i image_file

DiskDescriptor.xml </td></tr>

{ -f format |

-v version } DiskDescriptor.xml</td></tr>

ploop check</td>

</td></tr>

</table>

[-u uuid]

DiskDescriptor.xml

<table width="100%" border="0" rules="none" frame="void"

cellspacing="0" cellpadding="0">

ploop check</td>

[--force]

[--hard-force] [--check] [--ro]

[--silent] [--drop-inuse] [--raw]

[--blocksize size]

[--repair-sparse] image_file</td></tr>

ploop info</td>

[-s] [-d]

DiskDescriptor.xml </td></tr>

ploop list</td>

[-a]</td></tr>

</table>

ploop snapshot-merge </td>

[-u uuid [-U uuid2] | -A][-n new_delta]DiskDescriptor.xml ~~</td><td width="14%">~~</td></tr>

ploop snapshot-switch </td>

-u uuid

DiskDescriptor.xml ~~</td><td width="14%">~~</td></tr>

ploop snapshot-delete </td>

-u uuid

DiskDescriptor.xml ~~</td><td width="14%">~~</td></tr>

ploop snapshot-list </td>

</td></tr>

</table>

[-H]

[-u uuid] [-s]

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

DiskDescriptor.xml

<table width="100%" border="0" rules="none" frame="void"

cellspacing="0" cellpadding="0">

ploop copy</td>

-s device

[-F stop_command] {

[-d file] |

[-o output_fd]

[-f feedback_fd] }</td></tr>

ploop copy</td>

-d file

[-i input_fd]

[-f feedback_fd] </td></tr>

</table>

<table width="100%" border="0" rules="none" frame="void"

cellspacing="0" cellpadding="0">

ploop balloon discard <td width="45%"></td>

[--automount]

[--to-free size]

[--min-block min_size] [--defrag]

DiskDescriptor.xml </td>

</td></tr>

</table>

<table width="100%" border="0" rules="none" frame="void"

cellspacing="0" cellpadding="0">

ploop restore-descriptor <td width="49%"></td>

-f format

[-b blocksize] disk_dir

delta_file </td></tr>

</table>

== DESCRIPTION ==

the form with DiskDescriptor.xml.

==OPTIONS = ~~BASIC COMMANDS~~ = Runploop without any options to show a short synopsys,including a list of commands. Runploop command to show synopsys and a shortdescription for a particular command. === Basic commands ===

==== init ====

Create andinitalize a ploop image file and a correspondingDiskDescriptor.xml file.

<table width="100%" border="0" rules="none" frame="void"

[-t fstype]

[-b blocksize]

[-B fsblocksize] [--nolazy]delta_file</td></tr>

Image format. See ~~IMAGE FORMATS~~Image formats below.</td></tr>

Image version, can be 1 or 2. Default is

2, if supported by the kernel.</td></tr>

~~<tr valign="top" align="left"><td width="11%">~~</~~td><td width="15%"~~table>

<pstyle="margin-left:11%;">-tnone |<ib>~~fstype~~ext3</ib>|</pb>ext4</~~td><td width="2%"~~b></~~td><td width="72%"~~p>

<pstyle="margin-left:28%;">File system typeto create,default is ext4. ~~If this parameter~~ Unless none is specified, a

partition, a filesystem, and a balloon file will be created

inside the image~~. Currently supported types are ext3and ext4~~. Using ext3 is not recommended.</p~~></td></tr></table~~>

-b blocksize

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.

<table width="100%" border="0" rules="none" frame="void"

==== mount ====

Assemble aploop device from one or more delta images, start it, andoptionally mount the file system residing on the device.

Two forms ofthis command are provided. The first one accepts a list ofdelta images to be used for assembling the ploop device,while the second one is using information from aDiskDescriptor.xml file. Please note that not all mountoptions are applicable to both forms.

<table width="100%" border="0" rules="none" frame="void"

Ploop device to use, e.g.i, /dev/ploop0. If notspecified, ~~the first unused~~ a randomly numbered ploop device will be used.</td></tr>

</table>

==== umount ====

Unmount a ploopdevice. 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

Ploop device, e.g., /dev/ploop0~~. If notspecified, the first unused ploop device will be used~~.</td></tr>

</table>

</td></tr>

</table>

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

<table width="100%" border="0" rules="none" frame="void"

cellspacing="0" cellpadding="0">

ploop replace</td>

{ -u uuid |

-l level | -o cur_image_file }

[--keep-name] -i image_file

DiskDescriptor.xml </td></tr>

-u uuid</td>

A uuid of an image to be replaced.</td></tr>

-l level</td>

A level of image to be replaced. A level is a distance

of an image from the base delta.</td></tr>

</table>

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

<table width="100%" border="0" rules="none" frame="void"

cellspacing="0" cellpadding="0">

-i image_file</td>

A new replacement image.</td>

</td></tr>

</table>

DiskDescriptor.xml

Path to the DiskDescriptor.xml

file with information about images.

==== resize ====

Resize a ploopimage. Both~~image~~online (i.e. ~~Online~~ when ploop is mounted and used) and offlineresize is supported, and the tool can eithergrow or shrink both the ploop image and the underlying filesystem.

<table width="100%" border="0" rules="none" frame="void"

==== convert ====

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

<table width="100%" border="0" rules="none" frame="void"

Image format. See ~~IMAGE FORMATS~~Image formats below.</td></tr>

Image version, can be 1 or 2. ~~Only offline~~</td></tr></table> ==== check ==== Check the internal consistencyof (and possibly repair) a ploop image (or images). Notethat image (s) to be tested should not be in use. <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%"> ploop check</td><td width="1%"></td><td width="43%"> [-u uuid]DiskDescriptor.xml </td><td width="28%"></td></tr></table> Check all the images inDiskDescriptor.xml up to the one denoted by theuuid (or default top delta, if UUID is notspecified). Default built-in check options are used, and theones specified on the command line, if any, are ignored. <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%"> ploop check</td><td width="1%"></td><td width="71%"> [--force][--hard-force] [--check] [--ro][--silent] [--drop-inuse] [--raw][--blocksize size][--repair-sparse] DiskDescriptor.xml |image_file </td></tr><tr valign="top" align="left"><td width="11%"></td><td width="17%"> -f, --force</td><td width="1%"></td><td width="71%"> Force check even if image’s dirty flag is notset. </td></tr></table> -F,--hard-force Same as -f, plus try tofix even fatal errors (can be dangerous). <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%"> -c, --check</td><td width="1%"></td><td width="63%"> Check for duplicated blocks and holes.</td><td width="8%"></td></tr><tr valign="top" align="left"><td width="11%"></td><td width="17%"> -r, --ro</td><td width="1%"></td><td width="63%"> Read-only access, do not modify image(s).</td><td width="8%"></td></tr></table> -s, --silent Be more silent, only reporterrors. -d,--drop-inuse Drop image "in use"flag. <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%"> -R, --raw</td><td width="4%"></td><td width="71%"> Specifies that image_file is a raw ploopimage. </td></tr></table> -b, --blocksizesize Image cluster block size, insectors (for raw images). -S,--repair-sparse Repair sparse image(s). === 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%"> ploop info</td><td width="2%"></td><td width="27%"> DiskDescriptor.xml</td><td width="45%"></td></tr></table> When run without any options, show information aboutdisk space and inodes usage and limits on the inner ploopfilesystem, somewhat similar to [[Man/vzquota.8|vzquota(8)]]stat or show commands. <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%"> ploop info</td><td width="2%"></td><td width="43%"> [-s] [-d]DiskDescriptor.xml </td><td width="29%"></td></tr></table> Either one or both options can be used together. Option-s is used to show information about ploop devicesize, block size, and format version ~~conversion~~ . Option -d is ~~supported~~used to show a corresponding ploop block device, itavailable. file. ==== 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%"> ploop list</td><td width="2%"></td><td width="6%"> [-a]</td><td width="66%"></td></tr></table> Shows a list of running ploopdevices (first column) and their corresponding base images.With option -a it also shows a mount point (thirdcolumn). ==== restore-descriptor ==== Create DiskDescriptor.xml filesuitable for delta_file and put it intodisk_dir. <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%"> ploop restore-descriptor </td><td width="1%"></td><td width="51%"> -f format[-b blocksize] disk_dirdelta_file</td></tr>

</table>

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

<table width="100%" border="0" rules="none" frame="void"

==== snapshot-merge ====

Merge asnapshot with itsparent. That is, contents of the delta file corresponding tothe snapshot is merged to a parent delta, then the file isremoved. Parent snapshot UUID is lost (as it is replacedwith the uuid specified). All snapshots having thelost one as a parent are updated to have the uuid asits parent.

<table width="100%" border="0" rules="none" frame="void"

[-u uuid [-U uuid2] | -A][-n new_delta]

DiskDescriptor.xml </td></tr>

Specify a single snapshot uuid to merge. If this optionis not specified, the top delta will be used.</td></tr><tr valign="top" align="left"><td width="11%"></td><td width="31%"> -U uuid2</td><td width="1%"></td><td width="57%"> Together with -u uuid, specify that allsnapshots in the range uuid...uuid2 are to bemerged.</td></tr>

snapshots have more than a single child, they will be

impossible to merge.</td></tr>

-n new_delta</td>

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.</td></tr>

</table>

==== snapshot-switch ====

Switch to thespecified~~specified~~ snapshot. This operation can only be performedwhile ploop is not running (i.e. is unmounted). The currenttop delta image will be removed.

<table width="100%" border="0" rules="none" frame="void"

==== snapshot-delete ====

Delete thespecifed snapshot. This operation can only be performed ifthe specified snapshot is not active. In case snapshotdoesn’t have any children, it will simply be removed.In case snapshot has a single child, it will be merged tothat child. Deleting a snapshot that has multiple childrenis currently not supported (but can be performed manually inan iterative fashion).

<table width="100%" border="0" rules="none" frame="void"

==== snapshot-list ====

List availablesnapshots.

<table width="100%" border="0" rules="none" frame="void"

[-H]

[-u uuid] [-s]

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

DiskDescriptor.xml </td></tr>

Filter the output to a

specified uuid.

<table width="100%" border="0" rules="none" frame="void"

cellspacing="0" cellpadding="0">

-s, --snapshot</td>

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.</td></tr>

</table>

-o, --output

• fname - snapshot image file name.

=== ~~ADVANCED COMMANDS~~ Image copying === ploop copy is a mechanismof effective copying of a top ploop image with the help ofbuild-in ploop kernel driver feature called write tracker.Write tracker is a feature that lets ploop copy toiteratively obtain a list of modified image blocks from thekernel. Two ploop copy processes are required foriterative top delta transfer. These are used byvzmigrate(8).

==== ~~shapshot~~ copy (sending) ====

<table width="100%" border="0" rules="none" frame="void"

ploop ~~snapshot~~copy</td>

<td width="6672%"> -s device[-F stop_command] {[-d file] |[-o output_fd][-f feedback_fd] }</td></tr></table> This command enables thein-kernel write tracker for the specified ploopdevice, then sends all the data blocks from the topdelta image to a pipe specified by the output_fdargument (stdout, i.e. 1 by default),supposedly read by destination ploop copy, or afile. After that, it iteratively gets the list of themodified data blocks from the kernel and sends those blocksagain. After a number of iterations (or when the list isempty), it executes the stop_command (this could bevzctl stop or vzctl chkpnt) and does the lastiteration of sending the modified data blocks. Finally, itchecks that the data were not modified, error is returnedotherwise. If feedback_fd isspecified, it is used to read back from the ploop copyreceiving side. The feedback channel is currently used towait for fdatasync(2) completion. ==== copy (receiving) ====

<~~p style~~table width="~~margin-top: 1em~~100%" border="0" rules="none" frame="void"~~>[-F][-d device] image_file</td></tr~~ cellspacing="0" cellpadding="0">

<pstyle="margin-top: 1em">-Fploop copy</td>

<td width="6658%"> -d file[-i input_fd][-f feedback_fd] </td><td width="14%"></td></tr></table> Reads the data blocks (providedby the source ploop copy) from the file descriptorinput_fd (stdin, i.e. 0 by default) andwrites them to the file. If feedback_fd isspecified, it is used to send status back to the ploop copysending side. === Ballooning === Since there is no online shrinksupport in ext4 file system, ploop internally uses atechnique called "ballooning" as a work around toshrink its images. Ballooning operation consists ofinflating a special balloon file (invisible for ordinaryusers), loading fiemap info of the inflated balloon to thekernel, relocating blocks of the image file from the tail tothe space specified by fiemap info, and truncating the tailof the image file. Result is the image file of a smallersize. However, it is quite possiblethat inflated balloon file will only span blocks that werenever touched before. Those will look like "notallocated" space from the kernel ploop point of view.In this case nothing will be relocated and nothingtruncated. So, if balloon operationsucceeded, it’s only guaranteed that a user of ploopdevice won’t be able to consume more space than theinitial block device size minus the size of the inflatedballoon. On the other hand, if a user of block device used alot of space on it, then freed the significant part of usedspace, balloon operation will result in significant truncateof image file. All the ploop ballooning logicis hidden from the end user, so while a number of low-levelcommands exist for working with ploop ballooning, those arenot needed and therefore are not documented here, except fora single command.

~~Freeze filesystem before making a snapshot. If theoption is not given, the file system will not be frozen andsnapshot will have an inconsistent file system. If you needa quick snapshot, do not use this option. Journal will bereplayed when you mount the snapshot.</td></tr><tr valign~~=~~"top" align~~=~~"left"><td width~~=~~"11%"></td><td width~~=~~"21%">~~balloon discard ====

<pstyle="margin-top: 1em">In a situation when a lot ofdisk space were freed on an in-ploop filesystem, use-dploop balloon discard ~~device~~to optimize the ploop imagesize.</p~~></td><td width="2%"></td><td width="66%"~~>

<~~p>Ploop device, e.g., /dev/ploop0.</td></tr~~table width="100%" border="0" rules="none" frame="void" cellspacing="0" cellpadding="0">

<pstyle="margin-top: 1em"><ib>~~image_file~~ploop balloon discard</ib></td>

<pstyle="margin-top: 1em">~~Path~~ [--automount][--to ~~a file to write a new snapshot to. If this file~~-free size]~~already exists,~~ [~~ploop snapshot~~--min-block  ~~will exit with an~~min_size] [--defrag]~~error~~DiskDescriptor.xml </td><td width="5%"></td></tr>

</table>

Iteratively try to relocate anddiscard unused blocks from a ploop image, reducing itssize. Note that ploop device and itsinner file system should be mounted. If not, one can use--automount option to automatically mount ploop forthe duration of the operation. Option --defrag can beused to run a filesystem defragmentation utility (currentlye4defrag2 on ext4 only) before the main operation. Option --to-free can beused to specify a maximum disk space to be freed. In otherwords, stop the process once freed space exceeded requestedsize. Default is 0, meaning to try to free as muchspace as possible. Option --min-block can beused to specify a minimum size of an extent to free. Thesmallest possible extent is 1 cluster (currently 1 MB), onecan specify higher value to speed up the whole discardingoperation. Note that the same functionalityis available by means of vzctl compact command.

~~The~~ == Image formats ===followingimage formats are currently supported.

<table width="100%" border="0" rules="none" frame="void"

<td width="424%"> raw</td><td width="10%"></td><td width="55%"> Raw format, with 1:1 mapping between the image file andthe ploop device.</td></tr><tr valign="top" align="left"><td width="11%"></td><td width="24%"> ploop1, expanded</td><td width="10%"></td><td width="55%"> Expanded format. The image will grow according to theneeds of the underlying file system. This format is thedefault. Names ’ploop1’ and’expanded’ are aliases.</td></tr><tr valign="top" align="left"><td width="11%"></td><td width="24%">

~~raw~~preallocated</td><td width="710%"></td><td width="7855%">

~~Raw format~~This is the same as ’ploop1’ or’expanded’, ~~with 1:1 mapping~~the only difference is all~~between~~ the ~~image~~ file ~~and the ploop device~~blocks are allocated during creation.</td></tr>

</table>

== EXIT STATUS == ploopexits with status 0 in case of successful execution. Anystatus greater than 0 signifies an error. 1, SYSEXIT_CREAT Error creating a file. 2, SYSEXIT_DEVICE Error getting or opening aploop device. 3, SYSEXIT_DEVIOC Error doing ioctl(2) onploop device. 4, SYSEXIT_OPEN Error opening a file. 5, SYSEXIT_MALLOC Not enough memory (error frommalloc(3), realloc(3), calloc(3), orposix_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 imagedetected. 12, SYSEXIT_SYS Other system error. 13, SYSEXIT_PROTOCOL Broken protocol (unexpectedvalue received). 14, SYSEXIT_LOOP pcopy commandcan’t finalize copying (frozen filesystem ischanging). 15, SYSEXIT_FSTAT Error from stat(2),fstat(2), or statfs(2). 16, SYSEXIT_FSYNC Error from fsync(2) orsyncfs(2). 17, SYSEXIT_EBUSY Can’t continue, anotheroperation is in progress. 18, SYSEXIT_FLOCK Error from flock(2). 19, SYSEXIT_FTRUNCATE Error from ftruncate(2)or truncate(2). 20, SYSEXIT_FALLOCATE Error fromfallocate(2). 21, SYSEXIT_MOUNT Can’t mount ploop imageor file system. 22, SYSEXIT_UMOUNT Can’t unmount ploop imageor file system. 23, SYSEXIT_LOCK Locking failed (anotheroperation in progress?). 24, SYSEXIT_MKFS Can’t create filesystem. 26, SYSEXIT_RESIZE_FS Utility resizefsfailed. 27, SYSEXIT_MKDIR Error from mkdir(2). 28, SYSEXIT_RENAME Error fromrename(2). 29, SYSEXIT_ABORT Operation aborted. 30, SYSEXIT_RELOC Block relocation failed. 33, SYSEXIT_CHANGE_GPT Error resizing GPT partitiontable. 35, SYSEXIT_UNLINK Error fromunlink(2). ~~ploop1~~36, ~~expanded~~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.xmlfile.

~~Expanded format. The image willgrow according to the needs of the underlying file system.This format is the default. Names’~~~~ploop1~~40,&~~rsquo; and&rsquo~~nbsp;~~expanded~~SYSEXIT_DEV_NOT_MOUNTED~~’ are aliases.~~

~~preallocated~~Ploop image is not mounted.

~~This is the same as~~41,&~~rsquo~~nbsp;~~ploop1~~SYSEXIT_FSCK~~&rsquo~~ Error from fsck(8). 43,&~~rsquo~~nbsp;~~expanded~~SYSEXIT_NOSNAP Can’~~, the only difference is all~~t find specified~~the file blocks are allocated during creation~~snapshot UUID.

== SEE ALSO ==

[[Man/vzctl.8|vzctl(8)]],[[Man/vzmigrate.8|vzmigrate(8)]], http://openvz.org/Ploop.

Kir

Bureaucrats, Administrators

6,534

edits

Changes

Man/ploop.8

Navigation menu

Personal tools

Namespaces

Variants

Views

More

Search

Navigation

Services

Donate

Tools