From acd935ef62283a2469333db0975b7d55c42fd997 Mon Sep 17 00:00:00 2001 From: bellard Date: Mon, 15 Nov 2004 22:57:26 +0000 Subject: [PATCH] doc update - added qemu-img manual page git-svn-id: svn://svn.savannah.nongnu.org/qemu/trunk@1151 c046a42c-6fe2-441c-8c8c-71466251a162 --- .cvsignore | 2 + Makefile | 13 ++++-- qemu-doc.texi | 81 +++++++------------------------- qemu-img.texi | 127 ++++++++++++++++++++++++++++++++++++++++++++++++++ qemu-mkcow.1 | 105 ----------------------------------------- 5 files changed, 155 insertions(+), 173 deletions(-) create mode 100644 qemu-img.texi delete mode 100644 qemu-mkcow.1 diff --git a/.cvsignore b/.cvsignore index bca4882388..42bc1c7544 100644 --- a/.cvsignore +++ b/.cvsignore @@ -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 diff --git a/Makefile b/Makefile index c9c7e9bc8a..e422228729 100644 --- a/Makefile +++ b/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 diff --git a/qemu-doc.texi b/qemu-doc.texi index c262ee7e9c..732f40f367 100644 --- a/qemu-doc.texi +++ b/qemu-doc.texi @@ -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 diff --git a/qemu-img.texi b/qemu-img.texi new file mode 100644 index 0000000000..3afd320851 --- /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 5e1a6812be..0000000000 --- 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! -.\" -.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