doc update - added qemu-img manual page
git-svn-id: svn://svn.savannah.nongnu.org/qemu/trunk@1151 c046a42c-6fe2-441c-8c8c-71466251a162
diff --git a/.cvsignore b/.cvsignore
index bca4882..42bc1c7 100644
--- a/.cvsignore
+++ b/.cvsignore
@@ -10,6 +10,8 @@
qemu-tech.html
qemu.1
qemu.pod
+qemu-img.1
+qemu-img.pod
sparc-user
qemu-img
sparc-softmmu
diff --git a/Makefile b/Makefile
index c9c7e9b..e422228 100644
--- a/Makefile
+++ b/Makefile
@@ -14,7 +14,7 @@
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 @@
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 @@
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 @@
./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 @@
( 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 @@
$(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
diff --git a/qemu-doc.texi b/qemu-doc.texi
index c262ee7..732f40f 100644
--- a/qemu-doc.texi
+++ b/qemu-doc.texi
@@ -584,81 +584,34 @@
@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
diff --git a/qemu-img.texi b/qemu-img.texi
new file mode 100644
index 0000000..3afd320
--- /dev/null
+++ b/qemu-img.texi
@@ -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
diff --git a/qemu-mkcow.1 b/qemu-mkcow.1
deleted file mode 100644
index 5e1a681..0000000
--- a/qemu-mkcow.1
+++ /dev/null
@@ -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
