ploop

8

ploop

control ploop device

    ploop
    init

    ploop
    mount

    ploop
    umount

    ploop
    snapshot

    ploop
    merge

    ploop
    shrink

    ploop
    replace

    ploop
    fsck

Advanced commands:

    ploop
    add

    ploop
    delete

    ploop
    start

    ploop
    stop

    ploop
    clear

    ploop
    stat

## DESCRIPTION

### ploop init

Create and initialize image file.

    ploop
    init
    -f
    -s

````

- Path where delta image file is to be created. If the file already exists `ploop init` exits with an error.

`-s ```

- Size of block device. ``

`-f ```

- ``

#### ploop init -s 32g /tmp/delta0

to create ``

### ploop mount

Compose ploop device from one or more delta images and start it.

    ploop
    mount
    -d
    -r
    -b
    -f

````

- List of image files. ``

`-r`

- Compose read-only device. All the image files will be open read-only.

`-b ```

- Specify IO engine to be used for delta files. ``

  Neither tools nor ploop driver try to guess valid IO engine.

  If IO engine is different for different deltas, `ploop add` should be used.

`-f ```

- Specify format of base delta. ``

This operation is aggragate for sequence of `, followed by `.``

#### ploop mount -d /dev/ploop0 /tmp/delta0

to mount `/tmp/delta0` on `/dev/ploop0`.

### ploop umount

Unmount ploop device.

    ploop
    umount
    -d

`-d ```

- Specifies ploop device. F.e. `/dev/ploop0`

This operation is aggragate for `, followed by `.``

### ploop snapshot

Create snapshot.

    ploop
    snapshot
    -d
    -F
    -b

````

- Path where delta image file is to be created. If the file already exists `ploop snapshot` exits with an error.

`-d ```

- Specifies ploop device. F.e. `/dev/ploop0`

`-F`

- Freeze filesystem before doing snapshot. If the option is not given, file system is not frozen and snapshot contains inconsistent file system. If you need quick snapshot, do not use this option, replaying journal will be made when you mount the snapshot. Use this option, is are going to shrink the device (see `ploop shrink`) or you are going to mount this snapshot read-only for backup or something like this.

`-b ```

- Specify IO engine to be used for delta file. ``

#### ploop snapshot -F -d /dev/ploop0 /tmp/delta1

to synchronize file system and to snapshot `/dev/ploop0`. New data will be written out to `/tmp/delta1`.

### ploop merge

Merge delta(s) to previous one and delete them.

    ploop
    merge
    -d
    -l

The second form is used to merge unmounted deltas.

    ploop
    merge
    -f

`-d ```

- Specifies ploop device. F.e. `/dev/ploop0`

`-l ```

- ``

`-f ```

- Specify format of delta. ``

````

- Data from this image transferred to ``

````

- This data collects all data from ``

If ``merges top delta to previous one.``

#### ploop merge -d /dev/ploop0

to merge top level data to previous and one and to remove it.

### ploop shrink

Delete unused clusters and shrink image file.

    ploop
    shrink
    -d
    -l
    -o
    -m

The second form works on unmounted deltas:

    ploop
    shrink
    -o
    -m

`-d ```

- Specifies ploop device. F.e. `/dev/ploop0`

`-l ```

- ``

`-o ```

- If this option is not given, shrinking is made in place. Otherwise, `creates new delta image.`

`-m`

- Merge deltas before shrinking. This option is invalid when shrkinking is made in place.

````

- Image file to shrink.

````

- Additional deltas, if they are required in addition to ``

### ploop fsck

Check structure of ploop image. This procedure is required after crash, when image was not unmounted.

    ploop
    fsck
    -fcr

````

- Image file to check.

`-f`

- Force checking even if image file is not dirty.

`-r`

- Check the image, but do not touch it.

`-c`

- Turn on more expensive checks, which are not required while regular fsck after crash.

Normally this command is used as recovery from crash, when images were not cleanly unmounted. Also it is necessary after abort of ploop device, which can happen f.e. when volume with delta runs out of space. But it can be used even on mounted (read-only) images to recover after crashed merge.

### ploop add

Advanced command. Add delta to ploop device.

    ploop
    add
    -d
    -w
    -b
    -f

````

- Image file to add.

`-w`

- This delta is writable. After adding writable delta new deltas cannot be added.

`-b ```

- Specify IO engine to be used for this delta. ``

  Neither tools nor ploop driver try to guess valid IO engine.

`-f ```

- Specify format of delta. ``

### ploop start

Start ploop device. Before this it must be composed using `.`

    ploop
    start
    -d

`-d ```

- Specifies ploop device. F.e. `/dev/ploop0`

### ploop stop

Stop ploop device. Do not destroy it, it can be restarted with `.`

    ploop
    stop
    -d

`-d ```

- Specifies ploop device. F.e. `/dev/ploop0`

### ploop clear

Decompose ploop device. It must be already stopped (or never started).

    ploop
    clear
    -d

`-d ```

- Specifies ploop device. F.e. `/dev/ploop0`

### ploop delete

Delete delta.

    ploop
    delete
    -d
    -l

`-d ```

- Specifies ploop device. F.e. `/dev/ploop0`

`-l ```

- Level of delta to delete.

The operation is dangerous. Unless deleted delta is covered by higher delta or backed by lower delta, it can change content of the disk and corrupt or even destroy file system.

### ploop replace

Replace delta. The option is advanced, replacing deltas is safe only provided image is correctly prepared using ``

    ploop
    replace
    -d
    -l
    -b
    -f

````

- Image to insert instead of existing one.

`-d ```

- Specifies ploop device. F.e. `/dev/ploop0`

`-l ```

- Level of delta to replace.

`-b ```

- Specify IO engine to be used for this delta. ``

  Neither tools nor ploop driver try to guess valid IO engine.

`-f ```

- Specify format of delta. ``

The operation is dangerous. Unless delta is equivalent to replaced one, it can change content of the disk and corrupt or even destroy file system.

### ploop stat

Print some statistics about ploop device. The command is advanced, statistics counters are used only for debugging and diagnostics.

    ploop
    stat
    -cl
    -d

`-d ```

- Specifies ploop device. F.e. `/dev/ploop0`

`-l`

- Load counters. This option is to be used, when we want to inherit counters after some device is decomposed and recomposed again.

`-c`

- Clear counters.

Semantics of counters is undefined and depends on version of ploop device driver. Statistic counters are used only for debugging and diagnostics.

## PLOOP DEVICE

``

1. Provide performance of file systems based on ``

2. Preserve the properties of real block devices, which provide reliability of existing journaling file systems.

These goals seriously limit space for manoeuvre, both from viewpoint of image file format and properties of backing file system.

Raw linear image, implemented by module ``

Current version of ``

Also, it is possible to use ``

It is important to emphasize that ``

Differences between ``

1. ``

## EXAMPLES

### Migration on shared storage

Virtual machine based on device ``

    src> ploop snapshot -F -d /dev/ploop0 tmp_delta_src

Virtual machine is suspened, so that logically snapshot is not required, however base images must be moved to read-only state to sync shared storage and we should protect base image of modifications which are possible while killing virtual machine, which is possible if virtual machine is actually a container. Now it is possible to compose the device on target host:

    dst> ploop mount -r -d /dev/ploop0 delta1 delta0
    dst> ploop snapshot -d /dev/ploop0 tmp_delta_dst

Now we can kill virtual machine at source host and to resume it at destination host. After this we can destroy ``

    src> ploop umount -d /dev/ploop0
    src> rm tmp_delta_src
    dst> ploop merge -d /dev/ploop0
    dst> rm tmp_delta_dst