1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
|
<?xml version="1.0" encoding="UTF-8"?>
<!--
manpage, user manual, usage: vboximg-mount
-->
<!--
Copyright (C) 2006-2023 Oracle and/or its affiliates.
This file is part of VirtualBox base platform packages, as
available from https://www.virtualbox.org.
This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation, in version 3 of the
License.
This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program; if not, see <https://www.gnu.org/licenses>.
SPDX-License-Identifier: GPL-3.0-only
-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
<!ENTITY % all.entities SYSTEM "all-entities.ent">
%all.entities;
]>
<refentry id="man_vboximg-mount" lang="en">
<refentryinfo>
<pubdate>November 2019</pubdate>
<title>vboximg-mount</title>
</refentryinfo>
<refmeta>
<refentrytitle>vboximg-mount</refentrytitle>
<manvolnum>1</manvolnum>
</refmeta>
<refnamediv>
<refname>vboximg-mount</refname>
<refpurpose>FUSE mount a virtual disk image for Mac OS and Linux hosts</refpurpose>
<refclass>Oracle VM VirtualBox</refclass>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis id="synopsis-vboximg-mount-help">
<!-- The 'id' is mandatory and must start with 'synopsis-'. -->
<command>vboximg-mount</command>
<group choice="req">
<arg choice="plain">-?</arg>
<arg choice="plain">-h</arg>
<arg choice="plain">--help</arg>
</group>
</cmdsynopsis>
<cmdsynopsis id="synopsis-vboximg-mount-mount">
<command>vboximg-mount</command>
<arg choice="req">--image=<replaceable>image-UUID</replaceable></arg>
<arg>--guest-filesystem</arg>
<arg>-o=<replaceable>FUSE-option</replaceable>[,<replaceable>FUSE-option</replaceable>]</arg>
<arg>--root</arg>
<arg>--rw</arg>
<arg choice="req"><replaceable>mountpoint</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis id="synopsis-vboximg-mount-list">
<command>vboximg-mount</command>
<arg choice="req">--list</arg>
<arg>--image=<replaceable>image-UUID</replaceable></arg>
<arg>--guest-filesystem</arg>
<arg>--verbose</arg>
<arg>--vm=<replaceable>vm-UUID</replaceable></arg>
<arg>--wide</arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1 id="vboximg-mount-intro">
<title>Description</title>
<para>
The <command>vboximg-mount</command> 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).
</para>
<para>
This command uses the Filesystem in Userspace (FUSE) technology to
provide raw access to an &product-name; virtual disk image.
</para>
<para>
When you use the <option>--image</option> option to specify a base
image identifier, only the base image is mounted. Any related
snapshots are disregarded. Alternatively, if you use the
<option>--image</option> 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.
</para>
<para>
The <command>vboximg-mount</command> 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. &product-name; supports the
FAT, NTFS, <filename>ext2</filename>, <filename>ext3</filename>,
and <filename>ext4</filename> file systems.
</para>
<para>
The virtual disk is exposed as a device node within a FUSE-based
file system that overlays the specified mount point.
</para>
<para>
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
<command>basename</command>(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:
</para>
<itemizedlist>
<listitem><para>
<filename>vhdd</filename> provides access to the raw disk
image data as a flat image
</para></listitem>
<listitem><para>
<literal>vol<replaceable>ID</replaceable></literal> provides
access to an individual volume on the specified disk image
</para></listitem>
<listitem><para>
<literal>fs<replaceable>ID</replaceable></literal> provides
access to a supported file system without requiring a host
file system driver
</para></listitem>
</itemizedlist>
<refsect2 id="vboximg-mount-help">
<title>General Command Options</title>
<remark role="help-copy-synopsis"/>
<para>
Use the following options to obtain information about the
<command>vboximg-mount</command> command and its options.
</para>
<variablelist>
<varlistentry>
<term><option>--help</option>, <option>--h</option>, or<option>--?</option></term>
<listitem><para>
Shows usage information.
</para></listitem>
</varlistentry>
</variablelist>
</refsect2>
<refsect2 id="vboximg-mount-mount">
<title>Mounting an &product-name; Disk Image</title>
<remark role="help-copy-synopsis"/>
<para>
Use the <command>vboximg-mount</command> 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.
</para>
<para>
You can use the <command>vboximg-mount</command> command to
restrict FUSE-based access to a subsection of the virtual disk.
</para>
<variablelist>
<varlistentry>
<term><option>--image=<replaceable>disk-image</replaceable></option></term>
<listitem><para>
Specifies the Universally Unique Identifier (UUID), name,
or path of the &product-name; disk image.
</para><para>
The short form of the <option>--image</option> option is
<option>-i</option>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--guest-filesystem</option></term>
<listitem><para>
Enables experimental read-only support for guest file
systems. When you specify this option, all known file
systems are made available to access.
</para><para>
The short form of the <option>--guest-filesystem</option>
option is <option>-g</option>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-o=<replaceable>FUSE-option</replaceable>[,<replaceable>FUSE-option</replaceable>...]</option></term>
<listitem><para>
Specifies FUSE mount options.
</para><para>
The <command>vboximg-mount</command> command enables you
to use the FUSE mount options that are described in the
<command>mount.fuse</command>(8) man page.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--root</option></term>
<listitem><para>
Overrides the security measure that restricts file access
to the file system owner by also granting file access to
the <literal>root</literal> user.
</para><para>
Same as the <option>-o allow_root</option> option. See the
<option>-o</option> option description.
</para><para>
This option is incompatible with the <option>-o
allow_other</option> option.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--rw</option></term>
<listitem><para>
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.
</para></listitem>
</varlistentry>
<varlistentry>
<term><replaceable>mount-point</replaceable></term>
<listitem><para>
Specifies the path name of a directory on which to mount
the &product-name; disk image.
</para></listitem>
</varlistentry>
</variablelist>
</refsect2>
<refsect2 id="vboximg-mount-list">
<title>Viewing &product-name; Disk Image Information</title>
<remark role="help-copy-synopsis"/>
<para>
Use the <command>vboximg-mount</command> command to view
information about registered VMs or an &product-name; virtual
disk image.
</para>
<variablelist>
<varlistentry>
<term><option>--image=<replaceable>disk-image</replaceable></option></term>
<listitem><para>
Specifies the UUID, name, or path of the &product-name;
disk image.
</para><para>
The short form of the <option>--image</option> option is
<option>-i</option>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--guest-filesystem</option></term>
<listitem><para>
Enables experimental read-only support for guest file
systems. When you specify this option, all known file
systems are made available to access.
</para><para>
The short form of the <option>--guest-filesystem</option>
option is <option>-g</option>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--list</option></term>
<listitem><para>
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.
</para><para>
When you specify the <option>--verbose</option> option,
the output includes detailed information about the VMs and
media, including snapshot images and file paths.
</para><para>
The short form of the <option>--list</option> option is
<option>-l</option>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--verbose</option></term>
<listitem><para>
Shows or logs detailed information.
</para><para>
The short form of the <option>--verbose</option> option is
<option>-v</option>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--vm=<replaceable>vm-UUID</replaceable></option></term>
<listitem><para>
Outputs information about the VM that is associated with
the specified UUID.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--wide</option></term>
<listitem><para>
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 <literal>created</literal>.
</para><para>
The wide output uses a tree-like structure in the VM
column to show the relationship between a VM base image
and its snapshots.
</para></listitem>
</varlistentry>
</variablelist>
</refsect2>
</refsect1>
<refsect1>
<title>Examples</title>
<remark role="help-scope" condition="MOUNT-MOUNT,MOUNT-LIST"/>
<para>
The following example shows how to mount a virtual disk image on
the host operating system (OS).
</para>
<screen>$ 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</screen>
<para>
The <command>mkdir</command> command creates a mount point called
<filename>fuse_mount_point</filename> on the host OS. The
<command>vboximg-mount</command> command is then used to mount the
specified disk image on the <filename>fuse_mount_point</filename>
mount point. The mount includes all snapshots for the disk image.
</para>
<para>
The <command>ls</command> command shows the contents of
<filename>fuse_mount_point</filename>. The
<command>mount</command> command is then used to mount the
FUSE-mounted device node, <command>vhdd</command>, on the
<filename>/mnt</filename> mount point. The <command>vhdd</command>
device node represents the virtual disk image.
</para>
<para>
The following example shows how to make the known file systems of
the <literal>b490e578-08be-4f7d-98e9-4c0ef0952377</literal> disk
image accessible when the image is mounted on the
<filename>fuse_mount_point</filename> mount point:
</para>
<screen>$ vboximg-mount --image=b490e578-08be-4f7d-98e9-4c0ef0952377 \
--guest-filesystem fuse_mount_point
</screen>
<para>
The following command outputs detailed information about all
registered VMs and their snapshots:
</para>
<screen>$ vboximg-mount --list --verbose</screen>
<para>
The following command shows an excerpt of the list output in wide
format.
</para>
<screen>$ 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
</screen>
<para>
The output shows that the Proxy VM is running the fourth snapshot
of the <command>Proxy.vdi</command> virtual disk image. The
running state is indicated by the <command>wlock</command> value
in the State column.
</para>
<para>
The Oracle Linux 7 VM is not running. It has two images:
<command>Oracle Linux 7.vdi</command> and
<command>kernel.vdi</command>. The <command>Oracle Linux
7.vdi</command> image has a snapshot.
</para>
<para>
The following command shows information about the VM with the
specified UUID:
</para>
<screen>
$ 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</screen>
</refsect1>
</refentry>
|
