VirtualBox

source: vbox/trunk/doc/manual/en_US/man_vboximg-mount.xml@ 105298

Last change on this file since 105298 was 104688, checked in by vboxsync, 7 months ago

FE/Qt. bugref:10691. Replacing hard coded product name(s) with corresponding entities in manual docbook files.

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

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette