7.48. vboximg-mount

FUSE mount a virtual disk image for Mac OS and Linux hosts.

7.48.1. Synopsis

vboximg-mount { -? | -h | --help }

vboximg-mount {--image=image-UUID} [--guest-filesystem] [-o=FUSE-option[,FUSE-option]] [--root] [--rw] { mountpoint }

vboximg-mount {--list} [--image=image-UUID] [--guest-filesystem] [--verbose] [--vm=vm-UUID] [--wide]

7.48.2. Description

The vboximg-mount command enables you to make Oracle VM VirtualBox disk images available to a Mac OS or Linux host operating system (OS) for privileged or non-priviliged access. You can mount any version of the disk from its available history of snapshots. Use this command to mount, view, and optionally modify the contents of an Oracle VM VirtualBox virtual disk image, and you can also use this command to view information about registered virtual machines (VMs).

This command uses the Filesystem in Userspace (FUSE) technology to provide raw access to an Oracle VM VirtualBox virtual disk image.

When you use the --image option to specify a base image identifier, only the base image is mounted. Any related snapshots are disregarded. Alternatively, if you use the --image option to specify a snapshot, the state of the FUSE-mounted virtual disk is synthesized from the implied chain of snapshots, including the base image.

The vboximg-mount command includes experimental read-only access to file systems inside a VM disk image. This feature enables you to extract some files from the VM disk image without starting the VM and without requiring third-party file system drivers on the host system. Oracle VM VirtualBox supports the FAT, NTFS, ext2, ext3, and ext4 file systems.

The virtual disk is exposed as a device node within a FUSE-based file system that overlays the specified mount point.

The FUSE file system includes a directory that contains a number of files. The file system can also contain a directory that includes a symbolic link that has the same base name (see the basename(1) man page) as the virtual disk base image and points to the location of the virtual disk base image. The directory can be of the following types:

  • vhdd provides access to the raw disk image data as a flat image

  • volID provides access to an individual volume on the specified disk image

  • fsID provides access to a supported file system without requiring a host file system driver

7.48.2.1. General Command Options

vboximg-mount { -? | -h | --help }

Use the following options to obtain information about the vboximg-mount command and its options.

--help, --h, or--?

Shows usage information.

7.48.2.2. Mounting an Oracle VM VirtualBox Disk Image

vboximg-mount {--image=image-UUID} [--guest-filesystem] [-o=FUSE-option[,FUSE-option]] [--root] [--rw] { mountpoint }

Use the vboximg-mount command to mount an Oracle VM VirtualBox virtual disk image on a Mac OS or Linux host system. When mounted, you can view the contents of the disk image or modify the contents of the disk image.

You can use the vboximg-mount command to restrict FUSE-based access to a subsection of the virtual disk.

--image=disk-image

Specifies the Universally Unique Identifier (UUID), name, or path of the Oracle VM VirtualBox disk image.

The short form of the --image option is -i.

--guest-filesystem

Enables experimental read-only support for guest file systems. When you specify this option, all known file systems are made available to access.

The short form of the --guest-filesystem option is -g.

-o=FUSE-option[,FUSE-option...]

Specifies FUSE mount options.

The vboximg-mount command enables you to use the FUSE mount options that are described in the mount.fuse(8) man page.

--root

Overrides the security measure that restricts file access to the file system owner by also granting file access to the root user.

Same as the -o allow_root option. See the -o option description.

This option is incompatible with the -o allow_other option.

--rw

Mounts the specified image as read-write, which is required if you want to modify its contents. By default, images are mounted as read-only.

mount-point

Specifies the path name of a directory on which to mount the Oracle VM VirtualBox disk image.

7.48.2.3. Viewing Oracle VM VirtualBox Disk Image Information

vboximg-mount {--list} [--image=image-UUID] [--guest-filesystem] [--verbose] [--vm=vm-UUID] [--wide]

Use the vboximg-mount command to view information about registered VMs or an Oracle VM VirtualBox virtual disk image.

--image=disk-image

Specifies the UUID, name, or path of the Oracle VM VirtualBox disk image.

The short form of the --image option is -i.

--guest-filesystem

Enables experimental read-only support for guest file systems. When you specify this option, all known file systems are made available to access.

The short form of the --guest-filesystem option is -g.

--list

Shows information about the disks that are associated with the registered VMs. If you specify a disk image, this option shows information about the partitions of the specified image.

When you specify the --verbose option, the output includes detailed information about the VMs and media, including snapshot images and file paths.

The short form of the --list option is -l.

--verbose

Shows or logs detailed information.

The short form of the --verbose option is -v.

--vm=vm-UUID

Outputs information about the VM that is associated with the specified UUID.

--wide

Outputs information in a wide format. This output includes the lock state information of running VMs. For VMs that are not running, the state is created.

The wide output uses a tree-like structure in the VM column to show the relationship between a VM base image and its snapshots.

7.48.3. Examples

The following example shows how to mount a virtual disk image on the host operating system (OS).

$ mkdir fuse_mount_point
$ vboximg-mount --image=b490e578-08be-4f7d-98e9-4c0ef0952377 fuse_mount_point
$ ls fuse_mount_point
ubu.vdi[32256:2053029880]   vhdd
$ sudo mount fuse_mount_point/vhdd /mnt

The mkdir command creates a mount point called fuse_mount_point on the host OS. The vboximg-mount command is then used to mount the specified disk image on the fuse_mount_point mount point. The mount includes all snapshots for the disk image.

The ls command shows the contents of fuse_mount_point. The mount command is then used to mount the FUSE-mounted device node, vhdd, on the /mnt mount point. The vhdd device node represents the virtual disk image.

The following example shows how to make the known file systems of the b490e578-08be-4f7d-98e9-4c0ef0952377 disk image accessible when the image is mounted on the fuse_mount_point mount point:

$ vboximg-mount --image=b490e578-08be-4f7d-98e9-4c0ef0952377 \
--guest-filesystem fuse_mount_point

The following command outputs detailed information about all registered VMs and their snapshots:

$ vboximg-mount --list --verbose

The following command shows an excerpt of the list output in wide format.

$ vboximg-mount --list --wide

VM  Image                 Size Type State   UUID (hierarchy)
------------------------------------------  ------------------------------------
Proxy                                       0833f5bc-6304-42e1-b799-cdc81c576c60
 |
 +- Proxy.vdi             4.8G VDI  rlock   d5f84afb-0794-4952-ab71-6bbcbee07737
 |  +- <snapshot>        12.3G VDI  rlock     dffc67aa-3023-477f-8033-b27e3daf4f54
 |  +- <snapshot>         8.8G VDI  rlock       3b2755bd-5f2a-4171-98fe-647d510b6274
 |  +- <snapshot>        14.6G VDI  rlock         e2ccdb5f-49e8-4123-8623-c61f363cc5cf
 |  +- <snapshot>         7.4G VDI  wlock           3c1e6794-9091-4be3-9e80-11aba40c2649

------------------------------------------  ------------------------------------
Oracle Linux 7                              5365ab5f-470d-44c0-9863-dad532ee5905
 |
 +- Oracle Linux 7.vdi     7.0G VDI created 96d2e92e-0d4e-46ab-a0f1-008fdbf997e7
 | +- <snapshot>          15.9G VDI created   f9cc866a-9166-42e9-a503-bbfe9b7312e8
 |
 +- kernel.vdi            11.1G VDI created 79a370bd-0c4f-480a-30bb-10cdea68423f

The output shows that the Proxy VM is running the fourth snapshot of the Proxy.vdi virtual disk image. The running state is indicated by the wlock value in the State column.

The Oracle Linux 7 VM is not running. It has two images: Oracle Linux 7.vdi and kernel.vdi. The Oracle Linux 7.vdi image has a snapshot.

The following command shows information about the VM with the specified UUID:

$ vboximg-mount --list --vm=b1d5563b-2a5b-4013-89f1-26c81d6bbfa0
-----------------------------------------------------------------
VM:   ubu
UUID: b1d5563b-2a5b-4013-89f1-26c81d6bbfa0

  Image:   ubu.vdi
  UUID:    b490e578-08be-4f7d-98e9-4c0ef0952377

       Snapshot: 35afe1e0-0a51-44f3-a228-caf172f3306f
       Size:     12.1G

       Snapshot: 874279c1-4425-4282-ada8-a9c07c00bbf9
       Size:     13.6G

  Image:   kernel.vdi
  UUID:    79a370bd-6eb7-4dbf-8bc6-d29118f127e0