summaryrefslogtreecommitdiffstats
path: root/doc/manual/en_US/man_vboximg-mount.xml
blob: 981ed9cce71e8457dedfec36484ba2ac00f9fd3d (plain)
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
 |  +- &lt;snapshot>        12.3G VDI  rlock     dffc67aa-3023-477f-8033-b27e3daf4f54
 |  +- &lt;snapshot>         8.8G VDI  rlock       3b2755bd-5f2a-4171-98fe-647d510b6274
 |  +- &lt;snapshot>        14.6G VDI  rlock         e2ccdb5f-49e8-4123-8623-c61f363cc5cf
 |  +- &lt;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
 | +- &lt;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>