doc update - added qemu-img manual page
git-svn-id: svn://svn.savannah.nongnu.org/qemu/trunk@1151 c046a42c-6fe2-441c-8c8c-71466251a162
This commit is contained in:
bellard
parent
c9c0eae84e
commit
acd935ef62
|
|
@ -10,6 +10,8 @@ qemu-doc.html
|
|||
qemu-tech.html
|
||||
qemu.1
|
||||
qemu.pod
|
||||
qemu-img.1
|
||||
qemu-img.pod
|
||||
sparc-user
|
||||
qemu-img
|
||||
sparc-softmmu
|
||||
|
|
|
|||
13
Makefile
13
Makefile
|
|
@ -14,7 +14,7 @@ TOOLS=qemu-img
|
|||
ifdef CONFIG_STATIC
|
||||
LDFLAGS+=-static
|
||||
endif
|
||||
DOCS=qemu-doc.html qemu-tech.html qemu.1
|
||||
DOCS=qemu-doc.html qemu-tech.html qemu.1 qemu-img.1
|
||||
|
||||
all: dyngen$(EXESUF) $(TOOLS) $(DOCS)
|
||||
for d in $(TARGET_DIRS); do \
|
||||
|
|
@ -30,7 +30,7 @@ dyngen$(EXESUF): dyngen.c
|
|||
clean:
|
||||
# avoid old build problems by removing potentially incorrect old files
|
||||
rm -f config.mak config.h op-i386.h opc-i386.h gen-op-i386.h op-arm.h opc-arm.h gen-op-arm.h
|
||||
rm -f *.o *.a $(TOOLS) dyngen$(EXESUF) TAGS qemu.pod *~ */*~
|
||||
rm -f *.o *.a $(TOOLS) dyngen$(EXESUF) TAGS *.pod *~ */*~
|
||||
$(MAKE) -C tests clean
|
||||
for d in $(TARGET_DIRS); do \
|
||||
$(MAKE) -C $$d $@ || exit 1 ; \
|
||||
|
|
@ -57,7 +57,7 @@ endif
|
|||
install -m 644 qemu-doc.html qemu-tech.html "$(docdir)"
|
||||
ifndef CONFIG_WIN32
|
||||
mkdir -p "$(mandir)/man1"
|
||||
install qemu.1 qemu-mkcow.1 "$(mandir)/man1"
|
||||
install qemu.1 qemu-img.1 "$(mandir)/man1"
|
||||
endif
|
||||
for d in $(TARGET_DIRS); do \
|
||||
$(MAKE) -C $$d $@ || exit 1 ; \
|
||||
|
|
@ -78,6 +78,10 @@ qemu.1: qemu-doc.texi
|
|||
./texi2pod.pl $< qemu.pod
|
||||
pod2man --section=1 --center=" " --release=" " qemu.pod > $@
|
||||
|
||||
qemu-img.1: qemu-img.texi
|
||||
./texi2pod.pl $< qemu-img.pod
|
||||
pod2man --section=1 --center=" " --release=" " qemu-img.pod > $@
|
||||
|
||||
FILE=qemu-$(shell cat VERSION)
|
||||
|
||||
# tar release (use 'make -k tar' on a checkouted tree)
|
||||
|
|
@ -92,6 +96,7 @@ tarbin:
|
|||
( cd / ; tar zcvf ~/qemu-$(VERSION)-i386.tar.gz \
|
||||
$(bindir)/qemu $(bindir)/qemu-fast \
|
||||
$(bindir)/qemu-system-ppc \
|
||||
$(bindir)/qemu-system-sparc \
|
||||
$(bindir)/qemu-i386 \
|
||||
$(bindir)/qemu-arm \
|
||||
$(bindir)/qemu-sparc \
|
||||
|
|
@ -105,7 +110,7 @@ tarbin:
|
|||
$(datadir)/linux_boot.bin \
|
||||
$(docdir)/qemu-doc.html \
|
||||
$(docdir)/qemu-tech.html \
|
||||
$(mandir)/man1/qemu.1 $(mandir)/man1/qemu-mkcow.1 )
|
||||
$(mandir)/man1/qemu.1 $(mandir)/man1/qemu-img.1 )
|
||||
|
||||
ifneq ($(wildcard .depend),)
|
||||
include .depend
|
||||
|
|
|
|||
|
|
@ -584,81 +584,34 @@ CPU registers by prefixing them with @emph{$}.
|
|||
@node disk_images
|
||||
@section Disk Images
|
||||
|
||||
@subsection Raw disk images
|
||||
Since version 0.6.1, QEMU supports many disk image formats, including
|
||||
growable disk images (their size increase as non empty sectors are
|
||||
written), compressed and encrypted disk images.
|
||||
|
||||
The disk images can simply be raw images of the hard disk. You can
|
||||
create them with the command:
|
||||
@subsection Quick start for disk image creation
|
||||
|
||||
You can create a disk image with the command:
|
||||
@example
|
||||
dd of=myimage bs=1024 seek=mysize count=0
|
||||
qemu-img create myimage.img mysize
|
||||
@end example
|
||||
where @var{myimage} is the image filename and @var{mysize} is its size
|
||||
in kilobytes.
|
||||
where @var{myimage.img} is the disk image filename and @var{mysize} is its
|
||||
size in kilobytes. You can add an @code{M} suffix to give the size in
|
||||
megabytes and a @code{G} suffix for gigabytes.
|
||||
|
||||
@xref{qemu_img_invocation} for more information.
|
||||
|
||||
@subsection Snapshot mode
|
||||
|
||||
If you use the option @option{-snapshot}, all disk images are
|
||||
considered as read only. When sectors in written, they are written in
|
||||
a temporary file created in @file{/tmp}. You can however force the
|
||||
write back to the raw disk images by pressing @key{C-a s}.
|
||||
write back to the raw disk images by using the @code{commit} monitor
|
||||
command (or @key{C-a s} in the serial console).
|
||||
|
||||
NOTE: The snapshot mode only works with raw disk images.
|
||||
@node qemu_img_invocation
|
||||
@subsection @code{qemu-img} Invocation
|
||||
|
||||
@subsection Copy On Write disk images
|
||||
|
||||
QEMU also supports user mode Linux
|
||||
(@url{http://user-mode-linux.sourceforge.net/}) Copy On Write (COW)
|
||||
disk images. The COW disk images are much smaller than normal images
|
||||
as they store only modified sectors. They also permit the use of the
|
||||
same disk image template for many users.
|
||||
|
||||
To create a COW disk images, use the command:
|
||||
|
||||
@example
|
||||
qemu-mkcow -f myrawimage.bin mycowimage.cow
|
||||
@end example
|
||||
|
||||
@file{myrawimage.bin} is a raw image you want to use as original disk
|
||||
image. It will never be written to.
|
||||
|
||||
@file{mycowimage.cow} is the COW disk image which is created by
|
||||
@code{qemu-mkcow}. You can use it directly with the @option{-hdx}
|
||||
options. You must not modify the original raw disk image if you use
|
||||
COW images, as COW images only store the modified sectors from the raw
|
||||
disk image. QEMU stores the original raw disk image name and its
|
||||
modified time in the COW disk image so that chances of mistakes are
|
||||
reduced.
|
||||
|
||||
If the raw disk image is not read-only, by pressing @key{C-a s} you
|
||||
can flush the COW disk image back into the raw disk image, as in
|
||||
snapshot mode.
|
||||
|
||||
COW disk images can also be created without a corresponding raw disk
|
||||
image. It is useful to have a big initial virtual disk image without
|
||||
using much disk space. Use:
|
||||
|
||||
@example
|
||||
qemu-mkcow mycowimage.cow 1024
|
||||
@end example
|
||||
|
||||
to create a 1 gigabyte empty COW disk image.
|
||||
|
||||
NOTES:
|
||||
@enumerate
|
||||
@item
|
||||
COW disk images must be created on file systems supporting
|
||||
@emph{holes} such as ext2 or ext3.
|
||||
@item
|
||||
Since holes are used, the displayed size of the COW disk image is not
|
||||
the real one. To know it, use the @code{ls -ls} command.
|
||||
@end enumerate
|
||||
|
||||
@subsection Convert VMware disk images to raw disk images
|
||||
|
||||
You can use the tool @file{vmdk2raw} to convert VMware disk images to
|
||||
raw disk images directly usable by QEMU. The syntax is:
|
||||
@example
|
||||
vmdk2raw vmware_image output_image
|
||||
@end example
|
||||
@include qemu-img.texi
|
||||
|
||||
@section Network emulation
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,127 @@
|
|||
@example
|
||||
@c man begin SYNOPSIS
|
||||
usage: qemu-img command [command options]
|
||||
@c man end
|
||||
@end example
|
||||
|
||||
@c man begin OPTIONS
|
||||
|
||||
The following commands are supported:
|
||||
@table @option
|
||||
@item create [-e] [-b @var{base_image}] [-f @var{fmt}] @var{filename} [@var{size}]
|
||||
@item commit [-f @var{fmt}] @var{filename}
|
||||
@item convert [-c] [-e] [-f @var{fmt}] @var{filename} [-O @var{output_fmt}] @var{output_filename}
|
||||
@item info [-f @var{fmt}] @var{filename}
|
||||
@end table
|
||||
|
||||
Command parameters:
|
||||
@table @var
|
||||
@item filename
|
||||
is a disk image filename
|
||||
@item base_image
|
||||
is the read-only disk image which is used as base for a copy on
|
||||
write image; the copy on write image only stores the modified data
|
||||
|
||||
@item fmt
|
||||
is the disk image format. It is guessed automatically in most cases. The following formats are supported:
|
||||
|
||||
@table @code
|
||||
@item raw
|
||||
|
||||
Raw disk image format (default). This format has the advantage of
|
||||
being simple and easily exportable to all other emulators. If your file
|
||||
system supports @emph{holes} (for example in ext2 or ext3 on Linux),
|
||||
then only the written sectors will reserve space. Use @code{qemu-img
|
||||
info} to know the real size used by the image or @code{ls -ls} on
|
||||
Unix/Linux.
|
||||
|
||||
@item qcow
|
||||
QEMU image format, the most versatile format. Use it to have smaller
|
||||
images (useful if your filesystem does not supports holes, for example
|
||||
on Windows), optional AES encryption and zlib based compression.
|
||||
@item cow
|
||||
User Mode Linux Copy On Write image format. Used to be the only growable
|
||||
image format in QEMU. It is supported only for compatibility with
|
||||
previous versions. It does not work on win32.
|
||||
@item vmdk
|
||||
VMware 3 and 4 compatible image format. Currently only supported as
|
||||
read-only.
|
||||
@item cloop
|
||||
Linux Compressed Loop image, useful only to reuse directly compressed
|
||||
CD-ROM images present for example in the Knoppix CD-ROMs.
|
||||
@end table
|
||||
|
||||
@item size
|
||||
is the disk image size in kilobytes. Optional suffixes @code{M}
|
||||
(megabyte) and @code{G} (gigabyte) are supported
|
||||
|
||||
@item output_filename
|
||||
is the destination disk image filename
|
||||
|
||||
@item output_fmt
|
||||
is the destination format
|
||||
|
||||
@item -c
|
||||
indicates that target image must be compressed (qcow format only)
|
||||
@item -e
|
||||
indicates that the target image must be encrypted (qcow format only)
|
||||
@end table
|
||||
|
||||
Command description:
|
||||
|
||||
@table @option
|
||||
@item create [-e] [-b @var{base_image}] [-f @var{fmt}] @var{filename} [@var{size}]
|
||||
|
||||
Create the new disk image @var{filename} of size @var{size} and format
|
||||
@var{fmt}.
|
||||
|
||||
If @var{base_image} is specified, then the image will record only the
|
||||
differences from @var{base_image}. No size needs to be specified in
|
||||
this case. @var{base_image} will never be modified unless you use the
|
||||
@code{commit} monitor command.
|
||||
|
||||
@item commit [-f @var{fmt}] @var{filename}
|
||||
|
||||
Commit the changes recorded in @var{filename} in its base image.
|
||||
|
||||
@item convert [-c] [-e] [-f @var{fmt}] @var{filename} [-O @var{output_fmt}] @var{output_filename}
|
||||
|
||||
Convert the disk image @var{filename} to disk image @var{output_filename}
|
||||
using format @var{output_fmt}. It can be optionnaly encrypted
|
||||
(@code{-e} option) or compressed (@code{-c} option).
|
||||
|
||||
Only the format @code{qcow} supports encryption or compression. The
|
||||
compression is read-only. It means that if a compressed sector is
|
||||
rewritten, then it is rewritten as uncompressed data.
|
||||
|
||||
Encryption uses the AES format which is very secure (128 bit keys). Use
|
||||
a long password (16 characters) to get maximum protection.
|
||||
|
||||
Image conversion is also useful to get smaller image when using a
|
||||
growable format such as @code{qcow} or @code{cow}: the empty sectors
|
||||
are detected and suppressed from the destination image.
|
||||
|
||||
@item info [-f @var{fmt}] @var{filename}
|
||||
|
||||
Give information about the disk image @var{filename}. Use it in
|
||||
particular to know the size reserved on disk which can be different
|
||||
from the displayed size.
|
||||
@end table
|
||||
|
||||
@c man end
|
||||
|
||||
@ignore
|
||||
|
||||
@setfilename qemu-img
|
||||
@settitle QEMU disk image utility
|
||||
|
||||
@c man begin SEEALSO
|
||||
The HTML documentation of QEMU for more precise information and Linux
|
||||
user mode emulator invocation.
|
||||
@c man end
|
||||
|
||||
@c man begin AUTHOR
|
||||
Fabrice Bellard
|
||||
@c man end
|
||||
|
||||
@end ignore
|
||||
105
qemu-mkcow.1
105
qemu-mkcow.1
|
|
@ -1,105 +0,0 @@
|
|||
.\" $Header: /home/paul/qemu/svnmerge/qemu-cvs/qemu/qemu-mkcow.1,v 1.1 2004-03-26 22:42:54 bellard Exp $
|
||||
.\"
|
||||
.\" transcript compatibility for postscript use.
|
||||
.\"
|
||||
.\" synopsis: .P! <file.ps>
|
||||
.\"
|
||||
.de P!
|
||||
.fl
|
||||
\!!1 setgray
|
||||
.fl
|
||||
\\&.\"
|
||||
.fl
|
||||
\!!0 setgray
|
||||
.fl \" force out current output buffer
|
||||
\!!save /psv exch def currentpoint translate 0 0 moveto
|
||||
\!!/showpage{}def
|
||||
.fl \" prolog
|
||||
.sy sed -e 's/^/!/' \\$1\" bring in postscript file
|
||||
\!!psv restore
|
||||
.
|
||||
.de pF
|
||||
.ie \\*(f1 .ds f1 \\n(.f
|
||||
.el .ie \\*(f2 .ds f2 \\n(.f
|
||||
.el .ie \\*(f3 .ds f3 \\n(.f
|
||||
.el .ie \\*(f4 .ds f4 \\n(.f
|
||||
.el .tm ? font overflow
|
||||
.ft \\$1
|
||||
..
|
||||
.de fP
|
||||
.ie !\\*(f4 \{\
|
||||
. ft \\*(f4
|
||||
. ds f4\"
|
||||
' br \}
|
||||
.el .ie !\\*(f3 \{\
|
||||
. ft \\*(f3
|
||||
. ds f3\"
|
||||
' br \}
|
||||
.el .ie !\\*(f2 \{\
|
||||
. ft \\*(f2
|
||||
. ds f2\"
|
||||
' br \}
|
||||
.el .ie !\\*(f1 \{\
|
||||
. ft \\*(f1
|
||||
. ds f1\"
|
||||
' br \}
|
||||
.el .tm ? font underflow
|
||||
..
|
||||
.ds f1\"
|
||||
.ds f2\"
|
||||
.ds f3\"
|
||||
.ds f4\"
|
||||
'\" t
|
||||
.ta 8n 16n 24n 32n 40n 48n 56n 64n 72n
|
||||
.TH "QEMU" "8"
|
||||
.SH "NAME"
|
||||
qemu-mkcow \(em create a copy-on-write file for qemu
|
||||
.SH "SYNOPSIS"
|
||||
.PP
|
||||
\fBqemu-mkcow\fR [\fB-h\fP] [\fB-f \fImaster_disk_image\fR\fP] [\fIcow_image\fR] [\fB\fIcow_size\fR\fP]
|
||||
.SH "DESCRIPTION"
|
||||
.PP
|
||||
The \fBqemu-mkcow\fR command creates a
|
||||
persistent copy-on-write file for \fBqemu\fR.
|
||||
|
||||
.PP
|
||||
\fBqemu\fR can be used in a "copy-on-write" mode,
|
||||
where changes made by \fBqemu\fR do not actually
|
||||
change the disk image file. One way is to invoke
|
||||
\fBqemu\fR with -snapshot: these changes
|
||||
are stored in a temporary file, which is discarded when
|
||||
\fBqemu\fR exits.
|
||||
|
||||
.PP
|
||||
\fBqemu-mkcow\fR creates an explicit copy-on-write
|
||||
file where changes are to be stored: this way, changes made
|
||||
inside \fBqemu\fR will still be there next time you
|
||||
run it, although the master disk image isn't ever changed.
|
||||
|
||||
.PP
|
||||
The usual method is to create the master image, then create a
|
||||
copy-on-write file using \fBqemu-mkcow\fR with
|
||||
\fB-f\fP. The filename of the master image is stored
|
||||
inside the generated copy-on-write file: it must not be modified
|
||||
after this is run!
|
||||
|
||||
.PP
|
||||
If no master file is specified, the effect is that of a
|
||||
blank master of size \fIcow_size\fR.
|
||||
|
||||
.SH "SEE ALSO"
|
||||
.PP
|
||||
qemu(1), qemu-fast(1).
|
||||
.SH "AUTHOR"
|
||||
.PP
|
||||
This manual page was written by Paul Russell prussell@debian.org for
|
||||
the \fBDebian\fP system (but may be used by others). Permission is
|
||||
granted to copy, distribute and/or modify this document under
|
||||
the terms of the GNU General Public License, Version 2 any
|
||||
later version published by the Free Software Foundation.
|
||||
|
||||
.PP
|
||||
On Debian systems, the complete text of the GNU General Public
|
||||
License can be found in /usr/share/common-licenses/GPL.
|
||||
|
||||
.\" created by instant / docbook-to-man, Fri 12 Mar 2004, 05:58
|
||||
Loading…
Reference in New Issue