November 2019

vboximg-mount

vboximg-mount 1
vboximg-mount FUSE mount a virtual disk image for Mac OS and Linux hosts &product-name;
`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 --verbose --vm=vm-UUID --wide

## Description

The `vboximg-mount` command enables you to make &product-name; 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 &product-name; 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 &product-name; 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 features 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. &product-name; 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

### General Command Options

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

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

  Shows usage information.

### Mounting an &product-name; Disk Image

Use the `vboximg-mount` command to mount an &product-name; 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 &product-name; disk image.

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

`--guest-filesystem`

  Enables 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 &product-name; disk image.

### Viewing &product-name; Disk Image Information

Use the `vboximg-mount` command to view information about registered VMs or an &product-name; virtual disk image.

`--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`.

`--image=disk-image`

  Specifies the UUID, name, or path of the &product-name; disk image.

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

`--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.

## 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