Mariusz: Add basic usage description and how to use containerised guestfish for editing instance disks

2020-01-09T10:47:36Z

Add basic usage description and how to use containerised guestfish for editing instance disks

New page

== Basic usage ==

The basic command for
<nowiki>
docker run --rm -it --entrypoint /bin/bash -v <your-image>:/image:rw registry.vscaler.com:5000/docker-guestfish:latest
</nowiki>
Then, when inside the container, run:

<nowiki>
guestfish --rw -a /image
run
list-filesystems
... (mount the filesystem as /, view and edit files, etc.)
</nowiki>
Replace <code>rw</code> in the below commands with <code>ro</code> if you only want to view the content of the image without editing files inside.

Aside from guestfish, this Docker image contains <code>qemu-img</code>, <code>virt-customize</code> and <code>virt-v2v</code> (for converting VMware images to QCOW, see: http://docs.vscaler.com/vscaler-docs/user-guide/_build/html/useful-tips/import-vmdk-from-vmware.html).

== Editing instance disks ==
Containerised guestfish may come in handy when you want to edit files inside an instance but don't have SSH access to the instance (so, for example, when you need to edit <code>/etc/shadow</code> to set/change the root password).

Find out on which hypervisor your instance lives (<code>openstack server show <instance-name-or-uuid> | grep hyper</code>) and locate its disk file. For example <code>/var/lib/docker/volumes/nova_compute/_data/instances/5893ad03-42d5-43fb-b9a1-349f97d49e2b/disk</code> is the disk file of instance with UUID <code>5893ad03-42d5-43fb-b9a1-349f97d49e2b</code> (Glance is using the file backend here).
TODO: Describe how to retrieve disk files from Ceph RBD.

BEFORE PROCEEDING SHUT DOWN YOUR INSTANCE AND CREATE A BACKUP OF ITS DISK FILE!

First, mount the disk file as described in the "Basic usage" section and run <code>qemu-img info /image</code>. Here is an example of the output:

<nowiki>
# qemu-img info /image
image: /image
file format: qcow2
virtual size: 80G (85899345920 bytes)
disk size: 30G
cluster_size: 65536
backing file: /var/lib/nova/instances/_base/3c09392e65a56cc2c6ba5db1bd91601ae5a355c1
Format specific information:
compat: 1.1
lazy refcounts: false
</nowiki>
As your image also has the "backing file" property, you'll need to locate it in <code>/var/lib/docker/volumes/nova_compute/_data/instances/_base/</code> and then mount it in the container in the location specified by the property (Feel free to also backup the backing file, just in case). Here are commands for mounting this sample image in a (temporary) guestfish container:

<nowiki>
export IMAGE=/var/lib/docker/volumes/nova_compute/_data/instances/5893ad03-42d5-43fb-b9a1-349f97d49e2b/disk
export IMAGE_BASE=/var/lib/docker/volumes/nova_compute/_data/instances/_base/3c09392e65a56cc2c6ba5db1bd91601ae5a355c1
export IMAGE_LOC=/var/lib/nova/instances/_base/3c09392e65a56cc2c6ba5db1bd91601ae5a355c1
docker run --rm -it --entrypoint /bin/bash -v ${IMAGE}:/image:rw -v ${IMAGE_BASE}:${IMAGE_LOC}:ro registry.vscaler.com:5000/docker-guestfish:latest
</nowiki>

Again, BACKUP THE DISK FILE (cp -a, rsync -avz, etc.) BEFORE DOING ANYTHING WITH IT.

When inside, run <code>guestfish --rw -a /image</code>, then <code>run</code>, mount the filesystem, view and edit files, etc.

=== Merging images ===
Alternatively, you can merge your backing file with the main image to create a snapshot of the disk file.

First of all, copy your main disk file.

MERGING IS A DESTRUCTIVE OPERATION, SO DON'T DO IT DIRECTLY ON THE ORIGINAL DISK FILE!

Then mount this copy and the backing file in a container:

<nowiki>
export IMAGE=<copy-of-your-main-disk-file>
export IMAGE_BASE=<backing-file-of-the-main-disk-file>
export IMAGE_LOC=<backing-image-location-from-the-backing-image-property>
docker run --rm -it --entrypoint /bin/bash -v ${IMAGE}:/image:rw -v ${IMAGE_BASE}:${IMAGE_LOC}:ro -e IMAGE_LOC=${IMAGE_LOC} registry.vscaler.com:5000/docker-guestfish:latest
</nowiki>
Inside the container run the following commands to merge the images (this will take a while):

<nowiki>
qemu-img rebase -b ${IMAGE_LOC} /image
qemu-img commit /image
qemu-img info /image
</nowiki>

Exit the container, add the resulting image to Glance and launch an instance off of this snapshot.

== References ==

# http://libguestfs.org/guestfish.1.html
# http://openstack.10931.n7.nabble.com/Migrating-KVM-VM-to-Openstack-td8004.html
# https://stackoverflow.com/questions/22913384/transforming-qcows2-snapshot-plus-backing-file-into-standalone-image-file

Containerised guestfish - Revision history

Mariusz: Add basic usage description and how to use containerised guestfish for editing instance disks