Provided by: ploop_1.14.1-1_amd64 bug

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

       43, SYSEXIT_NOSNAP
              Can't find specified snapshot UUID.

SEE ALSO

       vzctl(8), vzmigrate(8), http://openvz.org/Ploop.