Revision acd935ef

b/.cvsignore
10 10
qemu-tech.html
11 11
qemu.1
12 12
qemu.pod
13
qemu-img.1
14
qemu-img.pod
13 15
sparc-user
14 16
qemu-img
15 17
sparc-softmmu
b/Makefile
14 14
ifdef CONFIG_STATIC
15 15
LDFLAGS+=-static
16 16
endif
17
DOCS=qemu-doc.html qemu-tech.html qemu.1
17
DOCS=qemu-doc.html qemu-tech.html qemu.1 qemu-img.1
18 18

  
19 19
all: dyngen$(EXESUF) $(TOOLS) $(DOCS)
20 20
	for d in $(TARGET_DIRS); do \
......
30 30
clean:
31 31
# avoid old build problems by removing potentially incorrect old files
32 32
	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 
33
	rm -f *.o *.a $(TOOLS) dyngen$(EXESUF) TAGS qemu.pod *~ */*~
33
	rm -f *.o *.a $(TOOLS) dyngen$(EXESUF) TAGS *.pod *~ */*~
34 34
	$(MAKE) -C tests clean
35 35
	for d in $(TARGET_DIRS); do \
36 36
	$(MAKE) -C $$d $@ || exit 1 ; \
......
57 57
	install -m 644 qemu-doc.html  qemu-tech.html "$(docdir)"
58 58
ifndef CONFIG_WIN32
59 59
	mkdir -p "$(mandir)/man1"
60
	install qemu.1 qemu-mkcow.1 "$(mandir)/man1"
60
	install qemu.1 qemu-img.1 "$(mandir)/man1"
61 61
endif
62 62
	for d in $(TARGET_DIRS); do \
63 63
	$(MAKE) -C $$d $@ || exit 1 ; \
......
78 78
	./texi2pod.pl $< qemu.pod
79 79
	pod2man --section=1 --center=" " --release=" " qemu.pod > $@
80 80

  
81
qemu-img.1: qemu-img.texi
82
	./texi2pod.pl $< qemu-img.pod
83
	pod2man --section=1 --center=" " --release=" " qemu-img.pod > $@
84

  
81 85
FILE=qemu-$(shell cat VERSION)
82 86

  
83 87
# tar release (use 'make -k tar' on a checkouted tree)
......
92 96
	( cd / ; tar zcvf ~/qemu-$(VERSION)-i386.tar.gz \
93 97
	$(bindir)/qemu $(bindir)/qemu-fast \
94 98
	$(bindir)/qemu-system-ppc \
99
	$(bindir)/qemu-system-sparc \
95 100
	$(bindir)/qemu-i386 \
96 101
        $(bindir)/qemu-arm \
97 102
        $(bindir)/qemu-sparc \
......
105 110
	$(datadir)/linux_boot.bin \
106 111
	$(docdir)/qemu-doc.html \
107 112
	$(docdir)/qemu-tech.html \
108
	$(mandir)/man1/qemu.1 $(mandir)/man1/qemu-mkcow.1 )
113
	$(mandir)/man1/qemu.1 $(mandir)/man1/qemu-img.1 )
109 114

  
110 115
ifneq ($(wildcard .depend),)
111 116
include .depend
b/qemu-doc.texi
584 584
@node disk_images
585 585
@section Disk Images
586 586

  
587
@subsection Raw disk images
587
Since version 0.6.1, QEMU supports many disk image formats, including
588
growable disk images (their size increase as non empty sectors are
589
written), compressed and encrypted disk images.
588 590

  
589
The disk images can simply be raw images of the hard disk. You can
590
create them with the command:
591
@subsection Quick start for disk image creation
592

  
593
You can create a disk image with the command:
591 594
@example
592
dd of=myimage bs=1024 seek=mysize count=0
595
qemu-img create myimage.img mysize
593 596
@end example
594
where @var{myimage} is the image filename and @var{mysize} is its size
595
in kilobytes.
597
where @var{myimage.img} is the disk image filename and @var{mysize} is its
598
size in kilobytes. You can add an @code{M} suffix to give the size in
599
megabytes and a @code{G} suffix for gigabytes.
600

  
601
@xref{qemu_img_invocation} for more information.
596 602

  
597 603
@subsection Snapshot mode
598 604

  
599 605
If you use the option @option{-snapshot}, all disk images are
600 606
considered as read only. When sectors in written, they are written in
601 607
a temporary file created in @file{/tmp}. You can however force the
602
write back to the raw disk images by pressing @key{C-a s}.
603

  
604
NOTE: The snapshot mode only works with raw disk images.
605

  
606
@subsection Copy On Write disk images
607

  
608
QEMU also supports user mode Linux
609
(@url{http://user-mode-linux.sourceforge.net/}) Copy On Write (COW)
610
disk images. The COW disk images are much smaller than normal images
611
as they store only modified sectors. They also permit the use of the
612
same disk image template for many users.
613

  
614
To create a COW disk images, use the command:
615

  
616
@example
617
qemu-mkcow -f myrawimage.bin mycowimage.cow
618
@end example
619

  
620
@file{myrawimage.bin} is a raw image you want to use as original disk
621
image. It will never be written to.
622

  
623
@file{mycowimage.cow} is the COW disk image which is created by
624
@code{qemu-mkcow}. You can use it directly with the @option{-hdx}
625
options. You must not modify the original raw disk image if you use
626
COW images, as COW images only store the modified sectors from the raw
627
disk image. QEMU stores the original raw disk image name and its
628
modified time in the COW disk image so that chances of mistakes are
629
reduced.
630

  
631
If the raw disk image is not read-only, by pressing @key{C-a s} you
632
can flush the COW disk image back into the raw disk image, as in
633
snapshot mode.
608
write back to the raw disk images by using the @code{commit} monitor
609
command (or @key{C-a s} in the serial console).
634 610

  
635
COW disk images can also be created without a corresponding raw disk
636
image. It is useful to have a big initial virtual disk image without
637
using much disk space. Use:
611
@node qemu_img_invocation
612
@subsection @code{qemu-img} Invocation
638 613

  
639
@example
640
qemu-mkcow mycowimage.cow 1024
641
@end example
642

  
643
to create a 1 gigabyte empty COW disk image.
644

  
645
NOTES: 
646
@enumerate
647
@item
648
COW disk images must be created on file systems supporting
649
@emph{holes} such as ext2 or ext3.
650
@item 
651
Since holes are used, the displayed size of the COW disk image is not
652
the real one. To know it, use the @code{ls -ls} command.
653
@end enumerate
654

  
655
@subsection Convert VMware disk images to raw disk images
656

  
657
You can use the tool @file{vmdk2raw} to convert VMware disk images to
658
raw disk images directly usable by QEMU. The syntax is:
659
@example
660
vmdk2raw vmware_image output_image
661
@end example
614
@include qemu-img.texi
662 615

  
663 616
@section Network emulation
664 617

  
b/qemu-img.texi
1
@example
2
@c man begin SYNOPSIS
3
usage: qemu-img command [command options]
4
@c man end
5
@end example
6

  
7
@c man begin OPTIONS
8

  
9
The following commands are supported:
10
@table @option
11
@item create [-e] [-b @var{base_image}] [-f @var{fmt}] @var{filename} [@var{size}]
12
@item commit [-f @var{fmt}] @var{filename}
13
@item convert [-c] [-e] [-f @var{fmt}] @var{filename} [-O @var{output_fmt}] @var{output_filename}
14
@item info [-f @var{fmt}] @var{filename}
15
@end table
16

  
17
Command parameters:
18
@table @var
19
@item filename
20
 is a disk image filename
21
@item base_image 
22
is the read-only disk image which is used as base for a copy on
23
    write image; the copy on write image only stores the modified data
24

  
25
@item fmt 
26
is the disk image format. It is guessed automatically in most cases. The following formats are supported:
27

  
28
@table @code
29
@item raw
30

  
31
Raw disk image format (default). This format has the advantage of
32
being simple and easily exportable to all other emulators. If your file
33
system supports @emph{holes} (for example in ext2 or ext3 on Linux),
34
then only the written sectors will reserve space. Use @code{qemu-img
35
info} to know the real size used by the image or @code{ls -ls} on
36
Unix/Linux.
37

  
38
@item qcow
39
QEMU image format, the most versatile format. Use it to have smaller
40
images (useful if your filesystem does not supports holes, for example
41
on Windows), optional AES encryption and zlib based compression.
42
@item cow
43
User Mode Linux Copy On Write image format. Used to be the only growable
44
image format in QEMU. It is supported only for compatibility with
45
previous versions. It does not work on win32.
46
@item vmdk
47
VMware 3 and 4 compatible image format. Currently only supported as
48
read-only.
49
@item cloop
50
Linux Compressed Loop image, useful only to reuse directly compressed
51
CD-ROM images present for example in the Knoppix CD-ROMs.
52
@end table
53

  
54
@item size 
55
is the disk image size in kilobytes. Optional suffixes @code{M}
56
(megabyte) and @code{G} (gigabyte) are supported 
57

  
58
@item output_filename
59
is the destination disk image filename 
60

  
61
@item output_fmt
62
 is the destination format
63

  
64
@item -c
65
indicates that target image must be compressed (qcow format only)
66
@item -e 
67
indicates that the target image must be encrypted (qcow format only)
68
@end table
69

  
70
Command description:
71

  
72
@table @option
73
@item create [-e] [-b @var{base_image}] [-f @var{fmt}] @var{filename} [@var{size}]
74

  
75
Create the new disk image @var{filename} of size @var{size} and format
76
@var{fmt}. 
77

  
78
If @var{base_image} is specified, then the image will record only the
79
differences from @var{base_image}. No size needs to be specified in
80
this case. @var{base_image} will never be modified unless you use the
81
@code{commit} monitor command.
82

  
83
@item commit [-f @var{fmt}] @var{filename}
84

  
85
Commit the changes recorded in @var{filename} in its base image.
86

  
87
@item convert [-c] [-e] [-f @var{fmt}] @var{filename} [-O @var{output_fmt}] @var{output_filename}
88

  
89
Convert the disk image @var{filename} to disk image @var{output_filename}
90
using format @var{output_fmt}. It can be optionnaly encrypted
91
(@code{-e} option) or compressed (@code{-c} option).
92

  
93
Only the format @code{qcow} supports encryption or compression. The
94
compression is read-only. It means that if a compressed sector is
95
rewritten, then it is rewritten as uncompressed data.
96

  
97
Encryption uses the AES format which is very secure (128 bit keys). Use
98
a long password (16 characters) to get maximum protection.
99

  
100
Image conversion is also useful to get smaller image when using a
101
growable format such as @code{qcow} or @code{cow}: the empty sectors
102
are detected and suppressed from the destination image.
103

  
104
@item info [-f @var{fmt}] @var{filename}
105

  
106
Give information about the disk image @var{filename}. Use it in
107
particular to know the size reserved on disk which can be different
108
from the displayed size.
109
@end table
110

  
111
@c man end
112

  
113
@ignore
114

  
115
@setfilename qemu-img
116
@settitle QEMU disk image utility
117

  
118
@c man begin SEEALSO
119
The HTML documentation of QEMU for more precise information and Linux
120
user mode emulator invocation.
121
@c man end
122

  
123
@c man begin AUTHOR
124
Fabrice Bellard
125
@c man end
126

  
127
@end ignore
/dev/null
1
.\" $Header: /home/paul/qemu/svnmerge/qemu-cvs/qemu/qemu-mkcow.1,v 1.1 2004-03-26 22:42:54 bellard Exp $
2
.\"
3
.\"	transcript compatibility for postscript use.
4
.\"
5
.\"	synopsis:  .P! <file.ps>
6
.\"
7
.de P!
8
.fl
9
\!!1 setgray
10
.fl
11
\\&.\"
12
.fl
13
\!!0 setgray
14
.fl			\" force out current output buffer
15
\!!save /psv exch def currentpoint translate 0 0 moveto
16
\!!/showpage{}def
17
.fl			\" prolog
18
.sy sed -e 's/^/!/' \\$1\" bring in postscript file
19
\!!psv restore
20
.
21
.de pF
22
.ie     \\*(f1 .ds f1 \\n(.f
23
.el .ie \\*(f2 .ds f2 \\n(.f
24
.el .ie \\*(f3 .ds f3 \\n(.f
25
.el .ie \\*(f4 .ds f4 \\n(.f
26
.el .tm ? font overflow
27
.ft \\$1
28
..
29
.de fP
30
.ie     !\\*(f4 \{\
31
.	ft \\*(f4
32
.	ds f4\"
33
'	br \}
34
.el .ie !\\*(f3 \{\
35
.	ft \\*(f3
36
.	ds f3\"
37
'	br \}
38
.el .ie !\\*(f2 \{\
39
.	ft \\*(f2
40
.	ds f2\"
41
'	br \}
42
.el .ie !\\*(f1 \{\
43
.	ft \\*(f1
44
.	ds f1\"
45
'	br \}
46
.el .tm ? font underflow
47
..
48
.ds f1\"
49
.ds f2\"
50
.ds f3\"
51
.ds f4\"
52
'\" t 
53
.ta 8n 16n 24n 32n 40n 48n 56n 64n 72n  
54
.TH "QEMU" "8" 
55
.SH "NAME" 
56
qemu-mkcow \(em create a copy-on-write file for qemu 
57
.SH "SYNOPSIS" 
58
.PP 
59
\fBqemu-mkcow\fR [\fB-h\fP]  [\fB-f \fImaster_disk_image\fR\fP]  [\fIcow_image\fR]  [\fB\fIcow_size\fR\fP]  
60
.SH "DESCRIPTION" 
61
.PP 
62
The \fBqemu-mkcow\fR command creates a 
63
persistent copy-on-write file for \fBqemu\fR. 
64
 
65
.PP 
66
\fBqemu\fR can be used in a "copy-on-write" mode, 
67
where changes made by \fBqemu\fR do not actually 
68
change the disk image file.  One way is to invoke 
69
\fBqemu\fR with -snapshot: these changes 
70
are stored in a temporary file, which is discarded when  
71
\fBqemu\fR exits. 
72
 
73
.PP 
74
\fBqemu-mkcow\fR creates an explicit copy-on-write 
75
file where changes are to be stored: this way, changes made 
76
inside \fBqemu\fR will still be there next time you 
77
run it, although the master disk image isn't ever changed. 
78
 
79
.PP 
80
The usual method is to create the master image, then create a 
81
copy-on-write file using \fBqemu-mkcow\fR with 
82
\fB-f\fP.  The filename of the master image is stored 
83
inside the generated copy-on-write file: it must not be modified 
84
after this is run! 
85
 
86
.PP 
87
If no master file is specified, the effect is that of a 
88
blank master of size \fIcow_size\fR. 
89
 
90
.SH "SEE ALSO" 
91
.PP 
92
qemu(1), qemu-fast(1). 
93
.SH "AUTHOR" 
94
.PP 
95
This manual page was written by Paul Russell prussell@debian.org for 
96
the \fBDebian\fP system (but may be used by others).  Permission is 
97
granted to copy, distribute and/or modify this document under 
98
the terms of the GNU General Public License, Version 2 any  
99
later version published by the Free Software Foundation. 
100
 
101
.PP 
102
On Debian systems, the complete text of the GNU General Public 
103
License can be found in /usr/share/common-licenses/GPL. 
104
 
105
.\" created by instant / docbook-to-man, Fri 12 Mar 2004, 05:58 

Also available in: Unified diff