Editing Ploop/readme
Warning: You are not logged in. Your IP address will be publicly visible if you make any edits. If you log in or create an account, your edits will be attributed to your username, along with other benefits.
The edit can be undone.
Please check the comparison below to verify that this is what you want to do, and then save the changes below to finish undoing the edit.
Latest revision | Your text | ||
Line 1: | Line 1: | ||
− | This document explains how to use user-space | + | This document explains how to use user-space ploop utility for typical |
use-cases. | use-cases. | ||
− | |||
− | |||
== Getting help == | == Getting help == | ||
− | All user-space ploop management operations are available via " | + | All user-space ploop management operations are available via "ploop" |
utility. Run it w/o args to get help: | utility. Run it w/o args to get help: | ||
Line 14: | Line 12: | ||
# ploop init | # ploop init | ||
+ | |||
+ | == Initialize image file == | ||
+ | |||
+ | In-kernel ploop operates on image files of "raw" or "ploop1" format. | ||
+ | An image file should be created and initialized (entirely in user-space) | ||
+ | before asking in-kernel ploop to start using it. | ||
+ | |||
+ | To create and initialize image file of "ploop1" format: | ||
+ | |||
+ | # ploop init -s 1g -f ploop1 /ploop.image | ||
+ | |||
+ | the same for "raw" format: | ||
+ | |||
+ | # ploop init -s 1g -f raw /ploop.image | ||
+ | |||
+ | where /ploop.image is full path to new image file and 1g is block-device size | ||
+ | equal to 1GB. These commands succeed only if the file /ploop.image didn't | ||
+ | exist at the time of running "ploop init". | ||
== Load modules == | == Load modules == | ||
− | |||
Further ploop commands assume that all necessary modules are loaded: | Further ploop commands assume that all necessary modules are loaded: | ||
Line 25: | Line 40: | ||
# modprobe pio_direct | # modprobe pio_direct | ||
+ | It's not always required to load both pfmt_ploop1 (support of ploop1 format) and | ||
+ | pfmt_raw (support of raw format). If we're going to use ploop1 image file, | ||
+ | loading pfmt_raw can be omitted. If we're going to use raw image file and have no | ||
+ | plans to snapshot it, pfmt_ploop1 can be omitted. | ||
− | + | == Create device file == | |
− | |||
− | |||
− | |||
− | + | # mknod /dev/ploop0 b 182 0 | |
+ | This example above uses 0 as minor number. In practice, it can be any multiple | ||
+ | of 16 in 0..1048575 range: 0, 16, 32, 48, etc. | ||
− | + | Other minors (not multiple of 16) are reserved for partitions. E.g. if primary | |
− | + | partition number 1 is created on /dev/ploop0, /dev/ploop0p1 will have minor | |
− | + | equal to 1. | |
− | + | == Bind ploop to image file == | |
− | + | Assuming that steps 2-4 were done, the following commands are used to "mount" | |
+ | ploop device over image file. | ||
− | + | For ploop1 format: | |
− | |||
− | |||
− | + | # ploop mount -f ploop1 -d /dev/ploop0 /ploop.image | |
− | + | For raw format: | |
− | |||
− | # ploop mount /ploop.image | + | # ploop mount -f raw -d /dev/ploop0 /ploop.image |
− | Since this point, | + | Since this point, /dev/ploop0 is operable. One can read/write any data from/to |
− | it (e.g. with "dd"), manipulate partition table on it (with | + | it (e.g. with "dd"), manipulate partition table on it (with "fdisk"), format |
− | now | + | it with mkfs.ext4 and mount it on some mount-point. In the other words, since |
+ | now /dev/ploop0 can be used as any other ordinary block device. | ||
== Snapshot == | == Snapshot == | ||
− | Let | + | Let /dev/ploop0 be a ploop device running over /ploop.image (i.e. step 4 was |
− | done) and | + | done) and /ploop-delta.image - some full path to non-existent file. Then the |
command: | command: | ||
Line 66: | Line 83: | ||
will create empty "ploop1" image file and register it in kernel ploop | will create empty "ploop1" image file and register it in kernel ploop | ||
− | forming "snapshotted" configuration | + | forming "snapshotted" configuration top_delta-->base_delta where base_delta |
− | is | + | is /ploop.image and top_delta is /ploop-delta.image. |
− | Since now, all i/o targeted at | + | Since now, all i/o targeted at /dev/ploop0 will change only top_delta. |
Actually, while performing snapshot operation in kernel, ploop re-open | Actually, while performing snapshot operation in kernel, ploop re-open | ||
− | + | base_delta "read-only". So, when "ploop snapshot" completed, it's quite safe, | |
− | for example, to backup | + | for example, to backup base_delta. |
It's allowable to snapshot snapshotted configuration. Following example above, | It's allowable to snapshot snapshotted configuration. Following example above, | ||
Line 79: | Line 96: | ||
# ploop snapshot -d /dev/ploop0 /ploop-delta1.image | # ploop snapshot -d /dev/ploop0 /ploop-delta1.image | ||
− | will form | + | will form top_delta-->delta-->base_delta configuration where: |
top_delta := /ploop-delta1.image | top_delta := /ploop-delta1.image | ||
Line 86: | Line 103: | ||
All deltas in snapshotted configuration are enumerated in kernel ploop in | All deltas in snapshotted configuration are enumerated in kernel ploop in | ||
− | the natural order starting from 0 for | + | the natural order starting from 0 for base_delta: |
base_delta' number is 0 | base_delta' number is 0 | ||
Line 109: | Line 126: | ||
=== Offline merge === | === Offline merge === | ||
− | ploop has no | + | ploop has no heruistic about determining raw/ploop1 format of image file. So, |
in case of offline merge, user should specify the format of base_delta | in case of offline merge, user should specify the format of base_delta | ||
explicitly. If it's ploop1, merge command looks like: | explicitly. If it's ploop1, merge command looks like: | ||
Line 119: | Line 136: | ||
# ploop merge /ploop-d2.image /ploop-d1.image /ploop-d.image /ploop.image | # ploop merge /ploop-d2.image /ploop-d1.image /ploop-d.image /ploop.image | ||
− | |||
This will merge /ploop-d2.image, /ploop-d1.image and /ploop-d.image into | This will merge /ploop-d2.image, /ploop-d1.image and /ploop-d.image into | ||
/ploop.image. | /ploop.image. | ||
− | |||
When merge completed, source deltas can be deleted because all data that | When merge completed, source deltas can be deleted because all data that | ||
was present in them has been copied to destination delta. | was present in them has been copied to destination delta. | ||
− | |||
For raw format, "-f raw" should be added as option. E.g.: | For raw format, "-f raw" should be added as option. E.g.: | ||
Line 194: | Line 208: | ||
In this case "ploop copy" on node02 will write data to standard output | In this case "ploop copy" on node02 will write data to standard output | ||
in some special binary format and "ploop copy" on node01 will read data | in some special binary format and "ploop copy" on node01 will read data | ||
− | from | + | from stndard input, parse that special format and store data in |
/home/ploop1.image ("-s" stands for "source", "-d" stands for "destination"). | /home/ploop1.image ("-s" stands for "source", "-d" stands for "destination"). | ||
This should work if standard output of node02 and standard input of node01 | This should work if standard output of node02 and standard input of node01 | ||
Line 201: | Line 215: | ||
== Grow ploop device == | == Grow ploop device == | ||
− | "ploop grow" command is to extend image file as | + | "ploop grow" command is to extend image file as neccessary (offline or online) |
− | and | + | and propogate new block-device size to linux kernel (in online case). |
=== Offline grow === | === Offline grow === | ||
Line 221: | Line 235: | ||
=== Online grow === | === Online grow === | ||
− | Assuming that /dev/ploop0 is | + | Assuming that /dev/ploop0 is runnung ploop device, the command: |
# ploop grow -s 32g -d /dev/ploop0 | # ploop grow -s 32g -d /dev/ploop0 | ||
will re-arrange underlying image file, update internal kernel ploop structures | will re-arrange underlying image file, update internal kernel ploop structures | ||
− | and | + | and propogate changes to linux kernel making ploop device 32GB size long. |
If user had ext4 formatted and mounted on /dev/ploop0, ext4 fs can be extended | If user had ext4 formatted and mounted on /dev/ploop0, ext4 fs can be extended | ||
Line 263: | Line 277: | ||
someone mounted ext4 on ploop device w/o balloon_ino option, then created | someone mounted ext4 on ploop device w/o balloon_ino option, then created | ||
empty balloon file there, found out its inode number and saved it for the | empty balloon file there, found out its inode number and saved it for the | ||
− | future use) | + | future use) |
Currently, only online ballooning is supported. The following command performs | Currently, only online ballooning is supported. The following command performs | ||
Line 274: | Line 288: | ||
mounted to. | mounted to. | ||
− | If balloon file was empty, the command above simply | + | If balloon file was empty, the command above simply iflates it to become |
1GB size. If it was non-empty but smaller than 1GB, that command extends it | 1GB size. If it was non-empty but smaller than 1GB, that command extends it | ||
to given size (1GB). If it was non-empty but larger that 1GB, that | to given size (1GB). If it was non-empty but larger that 1GB, that | ||
Line 288: | Line 302: | ||
# ploop balloon status -d /dev/ploop0 -m /mnt_ploop | # ploop balloon status -d /dev/ploop0 -m /mnt_ploop | ||
− | will report current in-kernel status of | + | will report current in-kernel status of maintainance like "merge in progress", |
"grow in progress", "ballooning started", etc. This is useful because on the | "grow in progress", "ballooning started", etc. This is useful because on the | ||
one hand balloon operation can't be performed while merge or grow is in | one hand balloon operation can't be performed while merge or grow is in | ||
Line 296: | Line 310: | ||
# ploop balloon clear -d /dev/ploop0 -m /mnt_ploop | # ploop balloon clear -d /dev/ploop0 -m /mnt_ploop | ||
− | will flush stale in-kernel "BALLOON" state of | + | will flush stale in-kernel "BALLOON" state of maintainance. This is useful if |
previous "ploop balloon" died early leaving in-kernel ploop locked. | previous "ploop balloon" died early leaving in-kernel ploop locked. | ||
Line 304: | Line 318: | ||
user monitors exit status of ploop commands he/she runs in some way. If | user monitors exit status of ploop commands he/she runs in some way. If | ||
user issued "ploop balloon change" and it was killed in the middle, the user | user issued "ploop balloon change" and it was killed in the middle, the user | ||
− | knows that it didn't complete with zero exit status. Then user | + | knows that it didn't complete with zero exit status. Then user shoud inquire |
− | current | + | current maintainance state with "ploop balloon status" command, and, if it |
reported "FBLOAD" or "RELOC", the user should use "ploop balloon complete" | reported "FBLOAD" or "RELOC", the user should use "ploop balloon complete" | ||
− | before proceeding with any other | + | before proceeding with any other maintainance operations (shanphsot, merge, |
grow, balloon). | grow, balloon). | ||
Line 314: | Line 328: | ||
will check whether existent balloon file was properly processed. This is useful | will check whether existent balloon file was properly processed. This is useful | ||
if previous "ploop balloon" was interrupted, but "ploop balloon status" | if previous "ploop balloon" was interrupted, but "ploop balloon status" | ||
− | reports "OFF" or "BALLOON" | + | reports "OFF" or "BALLOON" maintainance state. In this case it's possible |
that balloon file was inflated but no further processing happened. | that balloon file was inflated but no further processing happened. | ||
Line 325: | Line 339: | ||
This command does essentially the same as "ploop balloon change" but w/o | This command does essentially the same as "ploop balloon change" but w/o | ||
inflating balloon. | inflating balloon. | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− |