qemu-nbd: Use blk_new_open() in main()

[qemu.git] / qemu-doc.texi

diff --git a/qemu-doc.texi b/qemu-doc.texi
index ad31f2d2d0d8047ceb578eb8dca5517ba7cea47d..aabe8df2f34da3dffdc1a1773ebab0a85f33c944 100644 (file)
--- a/qemu-doc.texi
+++ b/qemu-doc.texi
@@ -527,6 +527,15 @@ Linux or NTFS on Windows), 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.
 
 space. Use @code{qemu-img info} to know the real size used by the
 image or @code{ls -ls} on Unix/Linux.
 

+Supported options:
+@table @code
+@item preallocation
+Preallocation mode (allowed values: @code{off}, @code{falloc}, @code{full}).
+@code{falloc} mode preallocates space for image by calling posix_fallocate().
+@code{full} mode preallocates space for image by writing zeros to underlying
+storage.
+@end table
+

 @item qcow2
 QEMU image format, the most versatile format. Use it to have smaller
 images (useful if your filesystem does not supports holes, for example
 @item qcow2
 QEMU image format, the most versatile format. Use it to have smaller
 images (useful if your filesystem does not supports holes, for example


@@ -575,9 +584,11 @@ sizes can improve the image file size whereas larger cluster sizes generally
 provide better performance.
 
 @item preallocation
 provide better performance.
 
 @item preallocation

-Preallocation mode (allowed values: off, metadata). An image with preallocated
-metadata is initially larger but can improve performance when the image needs
-to grow.
+Preallocation mode (allowed values: @code{off}, @code{metadata}, @code{falloc},
+@code{full}). An image with preallocated metadata is initially larger but can
+improve performance when the image needs to grow. @code{falloc} and @code{full}
+preallocations are like the same options of @code{raw} format, but sets up
+metadata also.

 
 @item lazy_refcounts
 If this option is set to @code{on}, reference count updates are postponed with
 
 @item lazy_refcounts
 If this option is set to @code{on}, reference count updates are postponed with


@@ -589,6 +600,22 @@ check -r all} is required, which may take some time.
 
 This option can only be enabled if @code{compat=1.1} is specified.
 
 
 This option can only be enabled if @code{compat=1.1} is specified.
 

+@item nocow
+If this option is set to @code{on}, it will turn off COW of the file. It's only
+valid on btrfs, no effect on other file systems.
+
+Btrfs has low performance when hosting a VM image file, even more when the guest
+on the VM also using btrfs as file system. Turning off COW is a way to mitigate
+this bad performance. Generally there are two ways to turn off COW on btrfs:
+a) Disable it by mounting with nodatacow, then all newly created files will be
+NOCOW. b) For an empty file, add the NOCOW file attribute. That's what this option
+does.
+
+Note: this option is only valid to new or empty files. If there is an existing
+file which is COW and has data blocks already, it couldn't be changed to NOCOW
+by setting @code{nocow=on}. One can issue @code{lsattr filename} to check if
+the NOCOW flag is set or not (Capital 'C' is NOCOW flag).
+

 @end table
 
 @item qed
 @end table
 
 @item qed


@@ -627,15 +654,6 @@ File name of a base image (see @option{create} subcommand)
 If this option is set to @code{on}, the image is encrypted.
 @end table
 
 If this option is set to @code{on}, the image is encrypted.
 @end table
 

-@item cow
-User Mode Linux Copy On Write image format. It is supported only for
-compatibility with previous versions.
-Supported options:
-@table @code
-@item backing_file
-File name of a base image (see @option{create} subcommand)
-@end table
-

 @item vdi
 VirtualBox 1.1 compatible image format.
 Supported options:
 @item vdi
 VirtualBox 1.1 compatible image format.
 Supported options:


@@ -680,7 +698,11 @@ Supported options:
 Specifies which VHDX subformat to use. Valid options are
 @code{dynamic} (default) and @code{fixed}.
 @item block_state_zero
 Specifies which VHDX subformat to use. Valid options are
 @code{dynamic} (default) and @code{fixed}.
 @item block_state_zero

-Force use of payload blocks of type 'ZERO'.
+Force use of payload blocks of type 'ZERO'.  Can be set to @code{on} (default)
+or @code{off}.  When set to @code{off}, new blocks will be created as
+@code{PAYLOAD_BLOCK_NOT_PRESENT}, which means parsers are free to return
+arbitrary data for those blocks.  Do not set to @code{off} when using
+@code{qemu-img convert} with @code{subformat=dynamic}.

 @item block_size
 Block size; min 1 MB, max 256 MB.  0 means auto-calculate based on image size.
 @item log_size
 @item block_size
 Block size; min 1 MB, max 256 MB.  0 means auto-calculate based on image size.
 @item log_size


@@ -823,7 +845,7 @@ In this case, the block device must be exported using qemu-nbd:
 qemu-nbd --socket=/tmp/my_socket my_disk.qcow2
 @end example
 
 qemu-nbd --socket=/tmp/my_socket my_disk.qcow2
 @end example
 

-The use of qemu-nbd allows to share a disk between several guests:
+The use of qemu-nbd allows sharing of a disk between several guests:

 @example
 qemu-nbd --socket=/tmp/my_socket --share=2 my_disk.qcow2
 @end example
 @example
 qemu-nbd --socket=/tmp/my_socket --share=2 my_disk.qcow2
 @end example


@@ -1189,9 +1211,16 @@ In order to check that the user mode network is working, you can ping
 the address 10.0.2.2 and verify that you got an address in the range
 10.0.2.x from the QEMU virtual DHCP server.
 
 the address 10.0.2.2 and verify that you got an address in the range
 10.0.2.x from the QEMU virtual DHCP server.
 

-Note that @code{ping} is not supported reliably to the internet as it
-would require root privileges. It means you can only ping the local
-router (10.0.2.2).
+Note that ICMP traffic in general does not work with user mode networking.
+@code{ping}, aka. ICMP echo, to the local router (10.0.2.2) shall work,
+however. If you're using QEMU on Linux >= 3.0, it can use unprivileged ICMP
+ping sockets to allow @code{ping} to the Internet. The host admin has to set
+the ping_group_range in order to grant access to those sockets. To allow ping
+for GID 100 (usually users group):
+
+@example
+echo 100 100 > /proc/sys/net/ipv4/ping_group_range
+@end example

 
 When using the built-in TFTP server, the router is also the TFTP
 server.
 
 When using the built-in TFTP server, the router is also the TFTP
 server.


@@ -1606,7 +1635,7 @@ EOF
 # certtool --generate-certificate \
            --load-ca-certificate ca-cert.pem \
            --load-ca-privkey ca-key.pem \
 # certtool --generate-certificate \
            --load-ca-certificate ca-cert.pem \
            --load-ca-privkey ca-key.pem \

-           --load-privkey server server-key.pem \
+           --load-privkey server-key.pem \

            --template server.info \
            --outfile server-cert.pem
 @end example
            --template server.info \
            --outfile server-cert.pem
 @end example


@@ -1629,7 +1658,7 @@ the secure CA private key:
 country = GB
 state = London
 locality = London
 country = GB
 state = London
 locality = London

-organiazation = Name of your organization
+organization = Name of your organization

 cn = client.foo.example.com
 tls_www_client
 encryption_key
 cn = client.foo.example.com
 tls_www_client
 encryption_key


@@ -1938,7 +1967,7 @@ The following options are specific to the PowerPC emulation:
 
 @item -g @var{W}x@var{H}[x@var{DEPTH}]
 
 
 @item -g @var{W}x@var{H}[x@var{DEPTH}]
 

-Set the initial VGA graphic mode. The default is 800x600x15.
+Set the initial VGA graphic mode. The default is 800x600x32.

 
 @item -prom-env @var{string}
 
 
 @item -prom-env @var{string}
 


@@ -1996,7 +2025,7 @@ QEMU emulates the following sun4m peripherals:
 @item
 IOMMU
 @item
 @item
 IOMMU
 @item

-TCX Frame buffer
+TCX or cgthree Frame buffer

 @item
 Lance (Am7990) Ethernet
 @item
 @item
 Lance (Am7990) Ethernet
 @item


@@ -2023,7 +2052,7 @@ firmware implementation. The goal is to implement a 100% IEEE
 
 A sample Linux 2.6 series kernel and ram disk image are available on
 the QEMU web site. There are still issues with NetBSD and OpenBSD, but
 
 A sample Linux 2.6 series kernel and ram disk image are available on
 the QEMU web site. There are still issues with NetBSD and OpenBSD, but

-some kernel versions work. Please note that currently Solaris kernels
+some kernel versions work. Please note that currently older Solaris kernels

 don't work probably due to interface issues between OpenBIOS and
 Solaris.
 
 don't work probably due to interface issues between OpenBIOS and
 Solaris.
 


@@ -2035,8 +2064,9 @@ The following options are specific to the Sparc32 emulation:
 
 @item -g @var{W}x@var{H}x[x@var{DEPTH}]
 
 
 @item -g @var{W}x@var{H}x[x@var{DEPTH}]
 

-Set the initial TCX graphic mode. The default is 1024x768x8, currently
-the only other possible mode is 1024x768x24.
+Set the initial graphics mode. For TCX, the default is 1024x768x8 with the
+option of 1024x768x24. For cgthree, the default is 1024x768x8 with the option
+of 1152x900x8 for people who wish to use OBP.

 
 @item -prom-env @var{string}
 
 
 @item -prom-env @var{string}