Changes

Man/ploop.8

16,478 bytes added, 19:44, 17 December 2013

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

{ -f format |

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

ploop check</td>

</td></tr>

</table>

[--force]

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

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

[--blocksize size]

[--repair-sparse] DiskDescriptor.xml |

image_file

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

cellspacing="0" cellpadding="0">

ploop info</td>

[-s]

DiskDescriptor.xml </td>

</td></tr>

ploop list</td>

[-a]</td>

</td></tr>

</table>

ploop snapshot-merge </td>

[-u uuid | -A]

DiskDescriptor.xml </td>

</td></tr>

ploop snapshot-switch </td>

-u uuid

DiskDescriptor.xml </td>

</td></tr>

ploop snapshot-delete </td>

-u uuid

DiskDescriptor.xml </td>

</td></tr>

ploop snapshot-list </td>

</td></tr>

</table>

[-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] </td>

</td></tr>

ploop copy</td>

-d file</td>

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

DiskDescriptor.xml </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"

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

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

==== 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. IfDiskDescriptor.xml is supplied, all the images one byone are checked. <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 ~~version conversion~~ ’s dirty flag is ~~supported~~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, --blocksize

size

Image cluster block size, in

sectors (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">

ploop info</td>

DiskDescriptor.xml</td>

</td></tr>

</table>

Show information about disk space and inodes usage and

limits on the inner ploop filesystem, 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">

ploop info</td>

-s

DiskDescriptor.xml </td>

</td></tr>

</table>

Show information about ploop device size, block size,

and format version.

==== list ====

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

cellspacing="0" cellpadding="0">

ploop list</td>

[-a]</td>

</td></tr>

</table>

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

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

==== snapshot-merge ====

Merge asnapshot with its parent.

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

[-u uuid | -A]

DiskDescriptor.xml </td></tr>

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

• 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="6657%"> -s device[-F stop_command][-d file] </td><td width="15%"></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 stdout (supposedly read by destinationploop copy) or a file. After that, ititeratively gets the list of the modified data blocks fromthe kernel and sends those blocks again. After a number ofiterations (or when the list is empty), it executes thestop_command (this could be vzctl stop orvzctl chkpnt) and does the last iteration of sendingthe modified data blocks. Finally, it checks that the datawere not modified, error is returned otherwise. ==== 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="6610%"> -d file</td><td width="62%"></td></tr></table> Reads the data block (providedby the source ploop copy) from the stdin andwrites them to the file. === 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]~~error~~DiskDescriptor.xml </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 --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. The smallest 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. === Image formats ===followingimage formats are currently supported.

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

raw</td><td width="710%"></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="7824%">

ploop1, expanded</td><td width="10%"></td><td width="~~margin-top: 1em~~55%">~~Raw~~ Expanded format~~, with 1:1 mapping~~. The image will grow according to the~~between~~ needs of the ~~image~~ 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%"> preallocated</td><td width="10%"></td><td width="55%"> This is the ~~ploop device~~same as ’ploop1’ or’expanded’, the only difference is allthe file 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. ~~ploop1~~2, ~~expanded~~SYSEXIT_DEVICE Error getting or opening aploop device. 3, SYSEXIT_DEVIOC Error doing ioctl(2) onploop device. 4, SYSEXIT_OPEN Error opening a file.

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

Not enough memory (error from~~preallocated~~malloc(3), realloc(3), calloc(3), orposix_memalign(3)).

6, SYSEXIT_READ Error during read. 7, SYSEXIT_WRITE ~~This~~ 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 is ~~the same as~~changing). 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. ~~ploop1~~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 imageorfile system. 22, SYSEXIT_UMOUNT Can’t unmount ploop imageor file system. 23, SYSEXIT_LOCK Locking failed (anotheroperation in progress?). ~~expanded~~24, SYSEXIT_MKFS Can’t create filesystem. 26, ~~the only difference~~  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). 36, SYSEXIT_MKNOD Error from mknod(2). 37, SYSEXIT_PLOOPINUSE Image is ~~all~~already in use. 38, SYSEXIT_PARAM Invalid parameter. 39, SYSEXIT_DISKDESCR Problem with DiskDescriptor.xml~~the~~ file ~~blocks are allocated during creation~~. 40, SYSEXIT_DEV_NOT_MOUNTED Ploop image is not mounted. 41, SYSEXIT_FSCK Error from fsck(8).

== SEE ALSO ==

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

Botinki Kira

Bots

2,253

edits

Changes

Man/ploop.8

Navigation menu

Personal tools

Namespaces

Variants

Views

More

Search

Navigation

Services

Donate

Tools