X-Git-Url: https://repo.jachan.dev/qemu.git/blobdiff_plain/3a069ff11b9178a84f560435b2fd22294d839018..b6e9f63711ea19b110574e384477bad4ea74f4a2:/qemu-doc.texi diff --git a/qemu-doc.texi b/qemu-doc.texi index 149e9bd28b..35cabbcb9e 100644 --- a/qemu-doc.texi +++ b/qemu-doc.texi @@ -78,7 +78,7 @@ to ease cross-compilation and cross-debugging. @end itemize -QEMU can run without an host kernel driver and yet gives acceptable +QEMU can run without a host kernel driver and yet gives acceptable performance. For system emulation, the following hardware targets are supported: @@ -107,7 +107,6 @@ For system emulation, the following hardware targets are supported: @item MusicPal (MV88W8618 ARM processor) @item Gumstix "Connex" and "Verdex" motherboards (PXA255/270). @item Siemens SX1 smartphone (OMAP310 processor) -@item Syborg SVP base model (ARM Cortex-A8). @item AXIS-Devboard88 (CRISv32 ETRAX-FS). @item Petalogix Spartan 3aDSP1800 MMU ref design (MicroBlaze). @item Avnet LX60/LX110/LX200 boards (Xtensa) @@ -228,15 +227,15 @@ QEMU uses GUS emulation (GUSEMU32 @url{http://www.deinmeister.de/gusemu/}) by Tibor "TS" Schütz. Note that, by default, GUS shares IRQ(7) with parallel ports and so -qemu must be told to not have parallel ports to have working GUS +QEMU must be told to not have parallel ports to have working GUS. @example -qemu dos.img -soundhw gus -parallel none +qemu-system-i386 dos.img -soundhw gus -parallel none @end example Alternatively: @example -qemu dos.img -device gus,irq=5 +qemu-system-i386 dos.img -device gus,irq=5 @end example Or some other unclaimed IRQ. @@ -252,7 +251,7 @@ CS4231A is the chip used in Windows Sound System and GUSMAX products Download and uncompress the linux image (@file{linux.img}) and type: @example -qemu linux.img +qemu-system-i386 linux.img @end example Linux should boot and give you a prompt. @@ -262,7 +261,7 @@ Linux should boot and give you a prompt. @example @c man begin SYNOPSIS -usage: qemu [options] [@var{disk_image}] +usage: qemu-system-i386 [options] [@var{disk_image}] @c man end @end example @@ -421,6 +420,7 @@ snapshots. * disk_images_fat_images:: Virtual FAT disk images * disk_images_nbd:: NBD access * disk_images_sheepdog:: Sheepdog disk images +* disk_images_iscsi:: iSCSI LUNs @end menu @node disk_images_quickstart @@ -575,7 +575,7 @@ QEMU can automatically create a virtual FAT disk image from a directory tree. In order to use it, just type: @example -qemu linux.img -hdb fat:/my_directory +qemu-system-i386 linux.img -hdb fat:/my_directory @end example Then you access access to all the files in the @file{/my_directory} @@ -585,14 +585,14 @@ them via SAMBA or NFS. The default access is @emph{read-only}. Floppies can be emulated with the @code{:floppy:} option: @example -qemu linux.img -fda fat:floppy:/my_directory +qemu-system-i386 linux.img -fda fat:floppy:/my_directory @end example A read/write support is available for testing (beta stage) with the @code{:rw:} option: @example -qemu linux.img -fda fat:floppy:rw:/my_directory +qemu-system-i386 linux.img -fda fat:floppy:rw:/my_directory @end example What you should @emph{never} do: @@ -610,14 +610,14 @@ QEMU can access directly to block device exported using the Network Block Device protocol. @example -qemu linux.img -hdb nbd:my_nbd_server.mydomain.org:1024 +qemu-system-i386 linux.img -hdb nbd:my_nbd_server.mydomain.org:1024 @end example If the NBD server is located on the same host, you can use an unix socket instead of an inet socket: @example -qemu linux.img -hdb nbd:unix:/tmp/my_socket +qemu-system-i386 linux.img -hdb nbd:unix:/tmp/my_socket @end example In this case, the block device must be exported using qemu-nbd: @@ -633,15 +633,15 @@ qemu-nbd --socket=/tmp/my_socket --share=2 my_disk.qcow2 and then you can use it with two guests: @example -qemu linux1.img -hdb nbd:unix:/tmp/my_socket -qemu linux2.img -hdb nbd:unix:/tmp/my_socket +qemu-system-i386 linux1.img -hdb nbd:unix:/tmp/my_socket +qemu-system-i386 linux2.img -hdb nbd:unix:/tmp/my_socket @end example If the nbd-server uses named exports (since NBD 2.9.18), you must use the "exportname" option: @example -qemu -cdrom nbd:localhost:exportname=debian-500-ppc-netinst -qemu -cdrom nbd:localhost:exportname=openSUSE-11.1-ppc-netinst +qemu-system-i386 -cdrom nbd:localhost:exportname=debian-500-ppc-netinst +qemu-system-i386 -cdrom nbd:localhost:exportname=openSUSE-11.1-ppc-netinst @end example @node disk_images_sheepdog @@ -666,7 +666,7 @@ qemu-img convert @var{filename} sheepdog:@var{image} You can boot from the Sheepdog disk image with the command: @example -qemu sheepdog:@var{image} +qemu-system-i386 sheepdog:@var{image} @end example You can also create a snapshot of the Sheepdog image like qcow2. @@ -678,7 +678,7 @@ where @var{tag} is a tag name of the newly created snapshot. To boot from the Sheepdog snapshot, specify the tag name of the snapshot. @example -qemu sheepdog:@var{image}:@var{tag} +qemu-system-i386 sheepdog:@var{image}:@var{tag} @end example You can create a cloned image from the existing snapshot. @@ -692,9 +692,121 @@ If the Sheepdog daemon doesn't run on the local host, you need to specify one of the Sheepdog servers to connect to. @example qemu-img create sheepdog:@var{hostname}:@var{port}:@var{image} @var{size} -qemu sheepdog:@var{hostname}:@var{port}:@var{image} +qemu-system-i386 sheepdog:@var{hostname}:@var{port}:@var{image} @end example +@node disk_images_iscsi +@subsection iSCSI LUNs + +iSCSI is a popular protocol used to access SCSI devices across a computer +network. + +There are two different ways iSCSI devices can be used by QEMU. + +The first method is to mount the iSCSI LUN on the host, and make it appear as +any other ordinary SCSI device on the host and then to access this device as a +/dev/sd device from QEMU. How to do this differs between host OSes. + +The second method involves using the iSCSI initiator that is built into +QEMU. This provides a mechanism that works the same way regardless of which +host OS you are running QEMU on. This section will describe this second method +of using iSCSI together with QEMU. + +In QEMU, iSCSI devices are described using special iSCSI URLs + +@example +URL syntax: +iscsi://[[%]@@][:]// +@end example + +Username and password are optional and only used if your target is set up +using CHAP authentication for access control. +Alternatively the username and password can also be set via environment +variables to have these not show up in the process list + +@example +export LIBISCSI_CHAP_USERNAME= +export LIBISCSI_CHAP_PASSWORD= +iscsi://// +@end example + +Various session related parameters can be set via special options, either +in a configuration file provided via '-readconfig' or directly on the +command line. + +If the initiator-name is not specified qemu will use a default name +of 'iqn.2008-11.org.linux-kvm[:'] where is the name of the +virtual machine. + + +@example +Setting a specific initiator name to use when logging in to the target +-iscsi initiator-name=iqn.qemu.test:my-initiator +@end example + +@example +Controlling which type of header digest to negotiate with the target +-iscsi header-digest=CRC32C|CRC32C-NONE|NONE-CRC32C|NONE +@end example + +These can also be set via a configuration file +@example +[iscsi] + user = "CHAP username" + password = "CHAP password" + initiator-name = "iqn.qemu.test:my-initiator" + # header digest is one of CRC32C|CRC32C-NONE|NONE-CRC32C|NONE + header-digest = "CRC32C" +@end example + + +Setting the target name allows different options for different targets +@example +[iscsi "iqn.target.name"] + user = "CHAP username" + password = "CHAP password" + initiator-name = "iqn.qemu.test:my-initiator" + # header digest is one of CRC32C|CRC32C-NONE|NONE-CRC32C|NONE + header-digest = "CRC32C" +@end example + + +Howto use a configuration file to set iSCSI configuration options: +@example +cat >iscsi.conf <[,shm=] +qemu-system-i386 -device ivshmem,size=[,shm=] @end example If desired, interrupts can be sent between guest VMs accessing the same shared @@ -802,9 +914,9 @@ is qemu.git/contrib/ivshmem-server. An example syntax when using the shared memory server is: @example -qemu -device ivshmem,size=[,chardev=] - [,msi=on][,ioeventfd=on][,vectors=n][,role=peer|master] -qemu -chardev socket,path=,id= +qemu-system-i386 -device ivshmem,size=[,chardev=] + [,msi=on][,ioeventfd=on][,vectors=n][,role=peer|master] +qemu-system-i386 -chardev socket,path=,id= @end example When using the server, the guest will be assigned a VM ID (>=0) that allows guests @@ -834,7 +946,7 @@ kernel testing. The syntax is: @example -qemu -kernel arch/i386/boot/bzImage -hda root-2.4.20.img -append "root=/dev/hda" +qemu-system-i386 -kernel arch/i386/boot/bzImage -hda root-2.4.20.img -append "root=/dev/hda" @end example Use @option{-kernel} to provide the Linux kernel image and @@ -849,8 +961,8 @@ If you do not need graphical output, you can disable it and redirect the virtual serial port and the QEMU monitor to the console with the @option{-nographic} option. The typical command line is: @example -qemu -kernel arch/i386/boot/bzImage -hda root-2.4.20.img \ - -append "root=/dev/hda console=ttyS0" -nographic +qemu-system-i386 -kernel arch/i386/boot/bzImage -hda root-2.4.20.img \ + -append "root=/dev/hda console=ttyS0" -nographic @end example Use @key{Ctrl-a c} to switch between the serial console and the @@ -861,7 +973,7 @@ monitor (@pxref{pcsys_keys}). QEMU emulates a PCI UHCI USB controller. You can virtually plug virtual USB devices or real host USB devices (experimental, works only -on Linux hosts). Qemu will automatically create and connect virtual USB hubs +on Linux hosts). QEMU will automatically create and connect virtual USB hubs as necessary to connect multiple USB devices. @menu @@ -879,7 +991,7 @@ or the @code{usb_add} monitor command. Available devices are: Virtual Mouse. This will override the PS/2 mouse emulation when activated. @item tablet Pointer device that uses absolute coordinates (like a touchscreen). -This means qemu is able to report the mouse position without having +This means QEMU is able to report the mouse position without having to grab the mouse. Also overrides the PS/2 mouse emulation when activated. @item disk:@var{file} Mass storage device based on @var{file} (@pxref{disk_images}) @@ -913,7 +1025,7 @@ Network adapter that supports CDC ethernet and RNDIS protocols. @var{options} specifies NIC options as with @code{-net nic,}@var{options} (see description). For instance, user-mode networking can be used with @example -qemu [...OPTIONS...] -net user,vlan=0 -usbdevice net:vlan=0 +qemu-system-i386 [...OPTIONS...] -net user,vlan=0 -usbdevice net:vlan=0 @end example Currently this cannot be used in machines that support PCI NICs. @item bt[:@var{hci-type}] @@ -923,7 +1035,7 @@ no type is given, the HCI logic corresponds to @code{-bt hci,vlan=0}. This USB device implements the USB Transport Layer of HCI. Example usage: @example -qemu [...OPTIONS...] -usbdevice bt:hci,vlan=3 -bt device:keyboard,vlan=3 +qemu-system-i386 [...OPTIONS...] -usbdevice bt:hci,vlan=3 -bt device:keyboard,vlan=3 @end example @end table @@ -1001,7 +1113,7 @@ For this setup it is recommended to restrict it to listen on a UNIX domain socket only. For example @example -qemu [...OPTIONS...] -vnc unix:/home/joebloggs/.qemu-myvm-vnc +qemu-system-i386 [...OPTIONS...] -vnc unix:/home/joebloggs/.qemu-myvm-vnc @end example This ensures that only users on local box with read/write access to that @@ -1017,12 +1129,14 @@ the protocol limits passwords to 8 characters it should not be considered to provide high security. The password can be fairly easily brute-forced by a client making repeat connections. For this reason, a VNC server using password authentication should be restricted to only listen on the loopback interface -or UNIX domain sockets. Password authentication is requested with the @code{password} -option, and then once QEMU is running the password is set with the monitor. Until -the monitor is used to set the password all clients will be rejected. +or UNIX domain sockets. Password authentication is not supported when operating +in FIPS 140-2 compliance mode as it requires the use of the DES cipher. Password +authentication is requested with the @code{password} option, and then once QEMU +is running the password is set with the monitor. Until the monitor is used to +set the password all clients will be rejected. @example -qemu [...OPTIONS...] -vnc :1,password -monitor stdio +qemu-system-i386 [...OPTIONS...] -vnc :1,password -monitor stdio (qemu) change vnc password Password: ******** (qemu) @@ -1039,7 +1153,7 @@ support provides a secure session, but no authentication. This allows any client to connect, and provides an encrypted session. @example -qemu [...OPTIONS...] -vnc :1,tls,x509=/etc/pki/qemu -monitor stdio +qemu-system-i386 [...OPTIONS...] -vnc :1,tls,x509=/etc/pki/qemu -monitor stdio @end example In the above example @code{/etc/pki/qemu} should contain at least three files, @@ -1057,7 +1171,7 @@ then validate against the CA certificate. This is a good choice if deploying in an environment with a private internal certificate authority. @example -qemu [...OPTIONS...] -vnc :1,tls,x509verify=/etc/pki/qemu -monitor stdio +qemu-system-i386 [...OPTIONS...] -vnc :1,tls,x509verify=/etc/pki/qemu -monitor stdio @end example @@ -1068,7 +1182,7 @@ Finally, the previous method can be combined with VNC password authentication to provide two layers of authentication for clients. @example -qemu [...OPTIONS...] -vnc :1,password,tls,x509verify=/etc/pki/qemu -monitor stdio +qemu-system-i386 [...OPTIONS...] -vnc :1,password,tls,x509verify=/etc/pki/qemu -monitor stdio (qemu) change vnc password Password: ******** (qemu) @@ -1091,7 +1205,7 @@ used for authentication, but assuming use of one supporting SSF, then QEMU can be launched with: @example -qemu [...OPTIONS...] -vnc :1,sasl -monitor stdio +qemu-system-i386 [...OPTIONS...] -vnc :1,sasl -monitor stdio @end example @node vnc_sec_certificate_sasl @@ -1105,7 +1219,7 @@ credentials. This can be enabled, by combining the 'sasl' option with the aforementioned TLS + x509 options: @example -qemu [...OPTIONS...] -vnc :1,tls,x509,sasl -monitor stdio +qemu-system-i386 [...OPTIONS...] -vnc :1,tls,x509,sasl -monitor stdio @end example @@ -1270,11 +1384,11 @@ use TLS and x509 certificates to protect security credentials from snooping. QEMU has a primitive support to work with gdb, so that you can do 'Ctrl-C' while the virtual machine is running and inspect its state. -In order to use gdb, launch qemu with the '-s' option. It will wait for a +In order to use gdb, launch QEMU with the '-s' option. It will wait for a gdb connection: @example -> qemu -s -kernel arch/i386/boot/bzImage -hda root-2.4.20.img \ - -append "root=/dev/hda" +qemu-system-i386 -s -kernel arch/i386/boot/bzImage -hda root-2.4.20.img \ + -append "root=/dev/hda" Connected to host network interface: tun0 Waiting gdb connection on port 1234 @end example @@ -1749,7 +1863,7 @@ PC Keyboard IDE controller @end itemize -The mipssim pseudo board emulation provides an environment similiar +The mipssim pseudo board emulation provides an environment similar to what the proprietary MIPS emulator uses for running Linux. It supports: @@ -2023,28 +2137,6 @@ Secure Digital card connected to OMAP MMC/SD host Three on-chip UARTs @end itemize -The "Syborg" Symbian Virtual Platform base model includes the following -elements: - -@itemize @minus -@item -ARM Cortex-A8 CPU -@item -Interrupt controller -@item -Timer -@item -Real Time Clock -@item -Keyboard -@item -Framebuffer -@item -Touchscreen -@item -UARTs -@end itemize - A Linux 2.6 test image is available on the QEMU web site. More information is available in the QEMU mailing-list archive. @@ -2141,7 +2233,7 @@ Xtensa emulator pseudo board "sim" Avnet LX60/LX110/LX200 board @end itemize -The sim pseudo board emulation provides an environment similiar +The sim pseudo board emulation provides an environment similar to one provided by the proprietary Tensilica ISS. It supports: @@ -2185,7 +2277,6 @@ so should only be used with trusted guest OS. @menu * Supported Operating Systems :: * Linux User space emulator:: -* Mac OS X/Darwin User space emulator :: * BSD User space emulator :: @end menu @@ -2198,8 +2289,6 @@ The following OS are supported in user space emulation: @item Linux (referred as qemu-linux-user) @item -Mac OS X/Darwin (referred as qemu-darwin-user) -@item BSD (referred as qemu-bsd-user) @end itemize @@ -2231,8 +2320,8 @@ qemu-i386 -L / /bin/ls @code{-L /} tells that the x86 dynamic linker must be searched with a @file{/} prefix. -@item Since QEMU is also a linux process, you can launch qemu with -qemu (NOTE: you can only do that if you compiled QEMU from the sources): +@item Since QEMU is also a linux process, you can launch QEMU with +QEMU (NOTE: you can only do that if you compiled QEMU from the sources): @example qemu-i386 -L / qemu-i386 -L / /bin/ls @@ -2308,7 +2397,7 @@ Set the x86 elf interpreter prefix (default=/usr/local/qemu-i386) @item -s size Set the x86 stack size in bytes (default=524288) @item -cpu model -Select CPU model (-cpu ? for list and additional feature selection) +Select CPU model (-cpu help for list and additional feature selection) @item -ignore-environment Start with an empty environment. Without this option, the initial environment is a copy of the caller's environment. @@ -2404,93 +2493,6 @@ The binary format is detected automatically. @command{qemu-sparc64} can execute some Sparc64 (Sparc64 CPU, 64 bit ABI) and SPARC32PLUS binaries (Sparc64 CPU, 32 bit ABI). -@node Mac OS X/Darwin User space emulator -@section Mac OS X/Darwin User space emulator - -@menu -* Mac OS X/Darwin Status:: -* Mac OS X/Darwin Quick Start:: -* Mac OS X/Darwin Command line options:: -@end menu - -@node Mac OS X/Darwin Status -@subsection Mac OS X/Darwin Status - -@itemize @minus -@item -target x86 on x86: Most apps (Cocoa and Carbon too) works. [1] -@item -target PowerPC on x86: Not working as the ppc commpage can't be mapped (yet!) -@item -target PowerPC on PowerPC: Most apps (Cocoa and Carbon too) works. [1] -@item -target x86 on PowerPC: most utilities work. Cocoa and Carbon apps are not yet supported. -@end itemize - -[1] If you're host commpage can be executed by qemu. - -@node Mac OS X/Darwin Quick Start -@subsection Quick Start - -In order to launch a Mac OS X/Darwin process, QEMU needs the process executable -itself and all the target dynamic libraries used by it. If you don't have the FAT -libraries (you're running Mac OS X/ppc) you'll need to obtain it from a Mac OS X -CD or compile them by hand. - -@itemize - -@item On x86, you can just try to launch any process by using the native -libraries: - -@example -qemu-i386 /bin/ls -@end example - -or to run the ppc version of the executable: - -@example -qemu-ppc /bin/ls -@end example - -@item On ppc, you'll have to tell qemu where your x86 libraries (and dynamic linker) -are installed: - -@example -qemu-i386 -L /opt/x86_root/ /bin/ls -@end example - -@code{-L /opt/x86_root/} tells that the dynamic linker (dyld) path is in -@file{/opt/x86_root/usr/bin/dyld}. - -@end itemize - -@node Mac OS X/Darwin Command line options -@subsection Command line options - -@example -usage: qemu-i386 [-h] [-d] [-L path] [-s size] program [arguments...] -@end example - -@table @option -@item -h -Print the help -@item -L path -Set the library root path (default=/) -@item -s size -Set the stack size in bytes (default=524288) -@end table - -Debug options: - -@table @option -@item -d -Activate log (logfile=/tmp/qemu.log) -@item -p pagesize -Act as if the host page size was 'pagesize' bytes -@item -singlestep -Run the emulation in single step mode. -@end table - @node BSD User space emulator @section BSD User space emulator @@ -2624,9 +2626,9 @@ MinGW's default header and linker search paths. @file{make}. If you have problems using SDL, verify that @file{sdl-config} can be launched from the MSYS command line. -@item You can install QEMU in @file{Program Files/Qemu} by typing +@item You can install QEMU in @file{Program Files/QEMU} by typing @file{make install}. Don't forget to copy @file{SDL.dll} in -@file{Program Files/Qemu}. +@file{Program Files/QEMU}. @end itemize @@ -2660,7 +2662,7 @@ The example assumes @file{sdl-config} is installed under @file{/usr/i686-pc-ming MinGW cross compilation tools have names like @file{i686-pc-mingw32-gcc} and @file{i686-pc-mingw32-strip}. We set the @code{PATH} environment variable to ensure the MinGW version of @file{sdl-config} is used and use --cross-prefix to specify the name of the cross compiler. -You can also use --prefix to set the Win32 install path which defaults to @file{c:/Program Files/Qemu}. +You can also use --prefix to set the Win32 install path which defaults to @file{c:/Program Files/QEMU}. Under Fedora Linux, you can run: @example @@ -2674,7 +2676,8 @@ installation directory. @end itemize -Wine can be used to launch the resulting qemu.exe compiled for Win32. +Wine can be used to launch the resulting qemu-system-i386.exe +and all other qemu-system-@var{target}.exe compiled for Win32. @node Mac OS X @section Mac OS X