guestfish is an interactive CLI tool that allows you to access guest virtual machine file systems. It provides a set of utilities useful in the VM image managment including tasks like inspection of the filesystem, and editing files without needing to boot the VM.

This quick guide is featured in Mastering KVM Virtualization. Explore deeper with the full eBook from CloudSpinx. Read it here.

Don’t perform any modifications in a live instance but it must be stopped.

sudo virsh shutdown <instance-name>

Locate VM image path using the following command

virsh dumpxml <vm-name> | egrep "source file"

guestfish common options:

• -a or --add – Used to specify the virtual machine disk image you want to interact with.
• -d – Access a guest virtual machine by name. List VMs using virsh list --all
• -r or --ro – Opens guest disk image in read-only mode. With this no changes are made to the image during the session.
• -w or --rw – Opens guest disk image in read-write mode, allowing you to make modifications to the file system.
• -i or --init – This initialized the guest image and automatically mounts all partitions in the image.
• -m or --mount – Counts a specific partition or device inside the guest image. The argument passed is dev[:mnt[:opts[:fstype]]].

1 – Open VM Image as read-only

The guest image will be opened in read-only, which is a more safe mode that doesn’t allow write access. There are two ways in which you can access virtual machine:

# Using direct VM image path
sudo guestfish --ro -i -a /path/to/disk/image

# Or using VM name
sudo guestfish --ro -i -d <vm-name>

2 – Open VM image as read-write

The disk image will be opened in read-write mode, allowing you to make changes to the file system.

# Using direct VM image path
sudo guestfish --rw -i -a /path/to/disk/image

# Or using VM name
sudo guestfish --rw -i -d <vm-name>

Where /path/to/disk/image is the actual path to the disk image. It can ve a file, a host physical machine logical volume (such as /dev/VG/LV), or a SAN LUN (/dev/sdf3).

After starting guestfish shell, it will display this prompt:

Welcome to guestfish, the guest filesystem shell for
editing virtual machine filesystems and disk images.

Type: ‘help’ for help on commands
‘man’ to read the manual
‘quit’ to quit the shell

Operating system: 12.8
/dev/sda1 mounted on /

><fs> man

List all available commands in the shell by running:

help --list

It’s also possible to add network block devices using a URI-style format:

guestfish -a ssh://[email protected]/vmdisk.qcow2

The equivalent command using the API directly is:

><fs> add /vmdisk.qcow2 protocol:ssh server:tcp:192.168.1.12 username:root

3 – List all block devices

Get a list of block devices attached to the VM using list-devices command. This will return full block device names.

><fs> list-devices
/dev/sda
/dev/sdb

4 – List file systems found by libguestfs

Get a list of filesystems and their type using list_filesystems command. It will look for filesystems on partitions, block devices and logical volumes and map to the filesystem type.

><fs> list_filesystems

/dev/sdb: iso9660
/dev/sda1: ext4
/dev/sda14: unknown
/dev/sda15: vfat

5 – List LVM devices

List LVM physical volumes, volumes groups, and logical volumes detected

pvs
vgs
lvs

6 – Get command usage help

Get more information and help on a specific command using help:

help <command>
# Example
help lvs

7 – List directory contents

List contents in a directory using lsand ll commands:

ls /etc
ll /var

Unlike standard shells, there is no concept of current working directory. You cannot use commands like cd to navigate between directories. All paths must be fully qualified, starting from the root with a forward slash (/). You can use the Tab key for path auto-completion.

8 – List the contents of a file

Display the contents of a file, for example /etc/os-release

><fs> cat /etc/os-release

PRETTY_NAME="Debian GNU/Linux 12 (bookworm)"
NAME="Debian GNU/Linux"
VERSION_ID="12"
VERSION="12 (bookworm)"
VERSION_CODENAME=bookworm
ID=debian
HOME_URL="https://www.debian.org/"
SUPPORT_URL="https://www.debian.org/support"
BUG_REPORT_URL="https://bugs.debian.org/"

9 – Download file / directories and store locally

Download a file to the local machine using downloadand directories using copy-out

• Copy file to local directory

download remotefilename filename

# Example
download /etc/os-release os-release.txt

• Copying out whole directories from a disk image:

><fs> copy-out /home /tmp/home

10 – Pack directory contents using tar and download

Pack the contents of a directory and download as tarfile to the local machine. This example packs contents of /etc directory and save as etc.tar:

tar-out /etc etc.tar

The optional compress flag controls compression:

tar-out /var/log /tmp/guest-logs.gz compress:gzip

If you exit guestfish shell, the tarfile can be uncompressed using tar -xvf:

><fs> exit
><fs> ls /tmp/guest-logs.gz

$ tar xvf /tmp/guest-logs.gz
./
./unattended-upgrades/
./unattended-upgrades/unattended-upgrades-shutdown.log
./runit/
./runit/ssh/
./private/
./README
./journal/

11 – Mount guest disk

You can mount a guest disk at a position in the filesystem

><fs> list-filesystems

/dev/sda1: ext4
/dev/vg_guest/lv_root: ext4
/dev/vg_guest/lv_swap: swap

><fs> mount /dev/vg_guest/lv_root /

><fs> cat /etc/fstab
><fs> exit

12 – Upload file from local machine

Use the upload command to push local file to the guest filesystem. The synopsis for this is:

upload <local-filename> <remote-filename>

In the following example we are uploading a file in current host working directory to guest instance under /root.

><fs> upload teamviewer_amd64.deb /root/teamviewer_amd64.deb

13 – Edit files

Use edit command to edit a file. It downloads the file, edits it locally using your editor, then uploads the result.

><fs> edit /etc/fstab

To edit files, you can use commands like edit, vi, or emacs. For creating files and directories, commands such as write, mkdir, upload, and tar-in are available.

14 – Create / delete directories

Use mkdir command to create a directory

><fs> mkdir /tmp/files

To delete a directory use

><fs> rmdir /tmp/files

15 – Unpack tarfile to directory

The following command uploads and unpacks local file tar file backups.tar.gz into directory /tmp

tar-in backups.tar.gz /tmp compress:gzip

16 – Partitions / Filesystems management

You can perform advanced disk operations like formatting filesystems, creating partitions, and managing LVM logical volumes, using commands such as

• mkfs
• part-add
• lvresize
• lvcreate
• vgcreate
• pvcreate
• Exit fom the guestfish shell

exit
# OR
Ctrl+d

Get the complete Mastering KVM Virtualization eBook to learn more about KVM.