man_vboximg-mount.xml

Last change on this file was 108564, checked in by vboxsync, 7 weeks ago
manual/man_vboximg-mount: Remove experimental state of read-only filesystem access and clean up the --list documentation.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 16.1 KB

Line
1	<?xml version="1.0" encoding="UTF-8"?>
2	<!--
3	manpage, user manual, usage: vboximg-mount
4	-->
5	<!--
6	Copyright (C) 2006-2024 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>--verbose</arg>
74	<arg>--vm=<replaceable>vm-UUID</replaceable></arg>
75	<arg>--wide</arg>
76	</cmdsynopsis>
77	</refsynopsisdiv>
78
79	<refsect1 id="vboximg-mount-description">
80	<title>Description</title>
81	<para>
82	The <command>vboximg-mount</command> command enables you to make
83	&product-name; disk images available to a Mac OS or Linux host
84	operating system (OS) for privileged or non-priviliged access. You
85	can mount any version of the disk from its available history of
86	snapshots. Use this command to mount, view, and optionally modify
87	the contents of an &product-name; virtual disk image, and you can
88	also use this command to view information about registered virtual
89	machines (VMs).
90	</para>
91	<para>
92	This command uses the Filesystem in Userspace (FUSE) technology to
93	provide raw access to an &product-name; virtual disk image.
94	</para>
95	<para>
96	When you use the <option>--image</option> option to specify a base
97	image identifier, only the base image is mounted. Any related
98	snapshots are disregarded. Alternatively, if you use the
99	<option>--image</option> option to specify a snapshot, the state
100	of the FUSE-mounted virtual disk is synthesized from the implied
101	chain of snapshots, including the base image.
102	</para>
103	<para>
104	The <command>vboximg-mount</command> command features
105	read-only access to file systems inside a VM disk image. This
106	feature enables you to extract some files from the VM disk image
107	without starting the VM and without requiring third-party file
108	system drivers on the host system. &product-name; supports the
109	FAT, NTFS, <filename>ext2</filename>, <filename>ext3</filename>,
110	and <filename>ext4</filename> file systems.
111	</para>
112	<para>
113	The virtual disk is exposed as a device node within a FUSE-based
114	file system that overlays the specified mount point.
115	</para>
116	<para>
117	The FUSE file system includes a directory that contains a number
118	of files. The file system can also contain a directory that
119	includes a symbolic link that has the same base name (see the
120	<command>basename</command>(1) man page) as the virtual disk base
121	image and points to the location of the virtual disk base image.
122	The directory can be of the following types:
123	</para>
124	<itemizedlist>
125	<listitem><para>
126	<filename>vhdd</filename> provides access to the raw disk
127	image data as a flat image
128	</para></listitem>
129	<listitem><para>
130	<literal>vol<replaceable>ID</replaceable></literal> provides
131	access to an individual volume on the specified disk image
132	</para></listitem>
133	<listitem><para>
134	<literal>fs<replaceable>ID</replaceable></literal> provides
135	access to a supported file system without requiring a host
136	file system driver
137	</para></listitem>
138	</itemizedlist>
139	<refsect2 id="vboximg-mount-help">
140	<title>General Command Options</title>
141	<remark role="help-copy-synopsis"/>
142	<para>
143	Use the following options to obtain information about the
144	<command>vboximg-mount</command> command and its options.
145	</para>
146	<variablelist>
147	<varlistentry>
148	<term><option>--help</option>, <option>--h</option>, or<option>--?</option></term>
149	<listitem><para>
150	Shows usage information.
151	</para></listitem>
152	</varlistentry>
153	</variablelist>
154	</refsect2>
155	<refsect2 id="vboximg-mount-mount">
156	<title>Mounting an &product-name; Disk Image</title>
157	<remark role="help-copy-synopsis"/>
158	<para>
159	Use the <command>vboximg-mount</command> command to mount an
160	&product-name; virtual disk image on a Mac OS or Linux host
161	system. When mounted, you can view the contents of the disk
162	image or modify the contents of the disk image.
163	</para>
164	<para>
165	You can use the <command>vboximg-mount</command> command to
166	restrict FUSE-based access to a subsection of the virtual disk.
167	</para>
168	<variablelist>
169	<varlistentry>
170	<term><option>--image=<replaceable>disk-image</replaceable></option></term>
171	<listitem><para>
172	Specifies the Universally Unique Identifier (UUID), name,
173	or path of the &product-name; disk image.
174	</para><para>
175	The short form of the <option>--image</option> option is
176	<option>-i</option>.
177	</para></listitem>
178	</varlistentry>
179	<varlistentry>
180	<term><option>--guest-filesystem</option></term>
181	<listitem><para>
182	Enables read-only support for guest file
183	systems. When you specify this option, all known file
184	systems are made available to access.
185	</para><para>
186	The short form of the <option>--guest-filesystem</option>
187	option is <option>-g</option>.
188	</para></listitem>
189	</varlistentry>
190	<varlistentry>
191	<term><option>-o=<replaceable>FUSE-option</replaceable>[,<replaceable>FUSE-option</replaceable>...]</option></term>
192	<listitem><para>
193	Specifies FUSE mount options.
194	</para><para>
195	The <command>vboximg-mount</command> command enables you
196	to use the FUSE mount options that are described in the
197	<command>mount.fuse</command>(8) man page.
198	</para></listitem>
199	</varlistentry>
200	<varlistentry>
201	<term><option>--root</option></term>
202	<listitem><para>
203	Overrides the security measure that restricts file access
204	to the file system owner by also granting file access to
205	the <literal>root</literal> user.
206	</para><para>
207	Same as the <option>-o allow_root</option> option. See the
208	<option>-o</option> option description.
209	</para><para>
210	This option is incompatible with the <option>-o
211	allow_other</option> option.
212	</para></listitem>
213	</varlistentry>
214	<varlistentry>
215	<term><option>--rw</option></term>
216	<listitem><para>
217	Mounts the specified image as read-write, which is
218	required if you want to modify its contents. By default,
219	images are mounted as read-only.
220	</para></listitem>
221	</varlistentry>
222	<varlistentry>
223	<term><replaceable>mount-point</replaceable></term>
224	<listitem><para>
225	Specifies the path name of a directory on which to mount
226	the &product-name; disk image.
227	</para></listitem>
228	</varlistentry>
229	</variablelist>
230	</refsect2>
231	<refsect2 id="vboximg-mount-list">
232	<title>Viewing &product-name; Disk Image Information</title>
233	<remark role="help-copy-synopsis"/>
234	<para>
235	Use the <command>vboximg-mount</command> command to view
236	information about registered VMs or an &product-name; virtual
237	disk image.
238	</para>
239	<variablelist>
240	<varlistentry>
241	<term><option>--list</option></term>
242	<listitem><para>
243	Shows information about the disks that are associated with
244	the registered VMs. If you specify a disk image, this
245	option shows information about the partitions of the
246	specified image.
247	</para><para>
248	When you specify the <option>--verbose</option> option,
249	the output includes detailed information about the VMs and
250	media, including snapshot images and file paths.
251	</para><para>
252	The short form of the <option>--list</option> option is
253	<option>-l</option>.
254	</para></listitem>
255	</varlistentry>
256	<varlistentry>
257	<term><option>--image=<replaceable>disk-image</replaceable></option></term>
258	<listitem><para>
259	Specifies the UUID, name, or path of the &product-name;
260	disk image.
261	</para><para>
262	The short form of the <option>--image</option> option is
263	<option>-i</option>.
264	</para></listitem>
265	</varlistentry>
266	<varlistentry>
267	<term><option>--verbose</option></term>
268	<listitem><para>
269	Shows or logs detailed information.
270	</para><para>
271	The short form of the <option>--verbose</option> option is
272	<option>-v</option>.
273	</para></listitem>
274	</varlistentry>
275	<varlistentry>
276	<term><option>--vm=<replaceable>vm-UUID</replaceable></option></term>
277	<listitem><para>
278	Outputs information about the VM that is associated with
279	the specified UUID.
280	</para></listitem>
281	</varlistentry>
282	<varlistentry>
283	<term><option>--wide</option></term>
284	<listitem><para>
285	Outputs information in a wide format. This output includes
286	the lock state information of running VMs. For VMs that
287	are not running, the state is <literal>created</literal>.
288	</para><para>
289	The wide output uses a tree-like structure in the VM
290	column to show the relationship between a VM base image
291	and its snapshots.
292	</para></listitem>
293	</varlistentry>
294	</variablelist>
295	</refsect2>
296	</refsect1>
297
298	<refsect1 id="vboximg-mount-examples">
299	<title>Examples</title>
300	<remark role="help-scope" condition="MOUNT-MOUNT,MOUNT-LIST"/>
301	<para>
302	The following example shows how to mount a virtual disk image on
303	the host operating system (OS).
304	</para>
305	<screen>$ mkdir fuse_mount_point
306	$ vboximg-mount --image=b490e578-08be-4f7d-98e9-4c0ef0952377 fuse_mount_point
307	$ ls fuse_mount_point
308	ubu.vdi[32256:2053029880] vhdd
309	$ sudo mount fuse_mount_point/vhdd /mnt</screen>
310	<para>
311	The <command>mkdir</command> command creates a mount point called
312	<filename>fuse_mount_point</filename> on the host OS. The
313	<command>vboximg-mount</command> command is then used to mount the
314	specified disk image on the <filename>fuse_mount_point</filename>
315	mount point. The mount includes all snapshots for the disk image.
316	</para>
317	<para>
318	The <command>ls</command> command shows the contents of
319	<filename>fuse_mount_point</filename>. The
320	<command>mount</command> command is then used to mount the
321	FUSE-mounted device node, <command>vhdd</command>, on the
322	<filename>/mnt</filename> mount point. The <command>vhdd</command>
323	device node represents the virtual disk image.
324	</para>
325	<para>
326	The following example shows how to make the known file systems of
327	the <literal>b490e578-08be-4f7d-98e9-4c0ef0952377</literal> disk
328	image accessible when the image is mounted on the
329	<filename>fuse_mount_point</filename> mount point:
330	</para>
331	<screen>$ vboximg-mount --image=b490e578-08be-4f7d-98e9-4c0ef0952377 \
332	--guest-filesystem fuse_mount_point
333	</screen>
334	<para>
335	The following command outputs detailed information about all
336	registered VMs and their snapshots:
337	</para>
338	<screen>$ vboximg-mount --list --verbose</screen>
339	<para>
340	The following command shows an excerpt of the list output in wide
341	format.
342	</para>
343	<screen>$ vboximg-mount --list --wide
344
345	VM Image Size Type State UUID (hierarchy)
346	------------------------------------------ ------------------------------------
347	Proxy 0833f5bc-6304-42e1-b799-cdc81c576c60
348	\|
349	+- Proxy.vdi 4.8G VDI rlock d5f84afb-0794-4952-ab71-6bbcbee07737
350	\| +- <snapshot> 12.3G VDI rlock dffc67aa-3023-477f-8033-b27e3daf4f54
351	\| +- <snapshot> 8.8G VDI rlock 3b2755bd-5f2a-4171-98fe-647d510b6274
352	\| +- <snapshot> 14.6G VDI rlock e2ccdb5f-49e8-4123-8623-c61f363cc5cf
353	\| +- <snapshot> 7.4G VDI wlock 3c1e6794-9091-4be3-9e80-11aba40c2649
354
355	------------------------------------------ ------------------------------------
356	Oracle Linux 7 5365ab5f-470d-44c0-9863-dad532ee5905
357	\|
358	+- Oracle Linux 7.vdi 7.0G VDI created 96d2e92e-0d4e-46ab-a0f1-008fdbf997e7
359	\| +- <snapshot> 15.9G VDI created f9cc866a-9166-42e9-a503-bbfe9b7312e8
360	\|
361	+- kernel.vdi 11.1G VDI created 79a370bd-0c4f-480a-30bb-10cdea68423f
362	</screen>
363	<para>
364	The output shows that the Proxy VM is running the fourth snapshot
365	of the <command>Proxy.vdi</command> virtual disk image. The
366	running state is indicated by the <command>wlock</command> value
367	in the State column.
368	</para>
369	<para>
370	The Oracle Linux 7 VM is not running. It has two images:
371	<command>Oracle Linux 7.vdi</command> and
372	<command>kernel.vdi</command>. The <command>Oracle Linux
373	7.vdi</command> image has a snapshot.
374	</para>
375	<para>
376	The following command shows information about the VM with the
377	specified UUID:
378	</para>
379	<screen>
380	$ vboximg-mount --list --vm=b1d5563b-2a5b-4013-89f1-26c81d6bbfa0
381	-----------------------------------------------------------------
382	VM: ubu
383	UUID: b1d5563b-2a5b-4013-89f1-26c81d6bbfa0
384
385	Image: ubu.vdi
386	UUID: b490e578-08be-4f7d-98e9-4c0ef0952377
387
388	Snapshot: 35afe1e0-0a51-44f3-a228-caf172f3306f
389	Size: 12.1G
390
391	Snapshot: 874279c1-4425-4282-ada8-a9c07c00bbf9
392	Size: 13.6G
393
394	Image: kernel.vdi
395	UUID: 79a370bd-6eb7-4dbf-8bc6-d29118f127e0</screen>
396	</refsect1>
397	</refentry>

Note: See TracBrowser for help on using the repository browser.

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

Download in other formats: