Archipelago » qemu

\input texinfo @c -*- texinfo -*-

@c %**start of header

@setfilename qemu-doc.info

@documentlanguage en

@documentencoding UTF-8

@settitle QEMU Emulator User Documentation

@exampleindent 0

@paragraphindent 0

@c %**end of header

@ifinfo

@direntry

* QEMU: (qemu-doc).    The QEMU Emulator User Documentation.

@end direntry

@end ifinfo

@iftex

@titlepage

@sp 7

@center @titlefont{QEMU Emulator}

@sp 1

@center @titlefont{User Documentation}

@sp 3

@end titlepage

@end iftex

@ifnottex

@node Top

@top

@menu

* Introduction::

* Installation::

* QEMU PC System emulator::

* QEMU System emulator for non PC targets::

* QEMU User space emulator::

* compilation:: Compilation from the sources

* License::

* Index::

@end menu

@end ifnottex

@contents

@node Introduction

@chapter Introduction

@menu

* intro_features:: Features

@end menu

@node intro_features

@section Features

QEMU is a FAST! processor emulator using dynamic translation to

achieve good emulation speed.

QEMU has two operating modes:

@itemize

@cindex operating modes

@item

@cindex system emulation

Full system emulation. In this mode, QEMU emulates a full system (for

example a PC), including one or several processors and various

peripherals. It can be used to launch different Operating Systems

without rebooting the PC or to debug system code.

@item

@cindex user mode emulation

User mode emulation. In this mode, QEMU can launch

processes compiled for one CPU on another CPU. It can be used to

launch the Wine Windows API emulator (@url{http://www.winehq.org}) or

to ease cross-compilation and cross-debugging.

@end itemize

QEMU can run without a host kernel driver and yet gives acceptable

performance.

For system emulation, the following hardware targets are supported:

@itemize

@cindex emulated target systems

@cindex supported target systems

@item PC (x86 or x86_64 processor)

@item ISA PC (old style PC without PCI bus)

@item PREP (PowerPC processor)

@item G3 Beige PowerMac (PowerPC processor)

@item Mac99 PowerMac (PowerPC processor, in progress)

@item Sun4m/Sun4c/Sun4d (32-bit Sparc processor)

@item Sun4u/Sun4v (64-bit Sparc processor, in progress)

@item Malta board (32-bit and 64-bit MIPS processors)

@item MIPS Magnum (64-bit MIPS processor)

@item ARM Integrator/CP (ARM)

@item ARM Versatile baseboard (ARM)

@item ARM RealView Emulation/Platform baseboard (ARM)

@item Spitz, Akita, Borzoi, Terrier and Tosa PDAs (PXA270 processor)

@item Luminary Micro LM3S811EVB (ARM Cortex-M3)

@item Luminary Micro LM3S6965EVB (ARM Cortex-M3)

@item Freescale MCF5208EVB (ColdFire V2).

@item Arnewsh MCF5206 evaluation board (ColdFire V2).

@item Palm Tungsten|E PDA (OMAP310 processor)

@item N800 and N810 tablets (OMAP2420 processor)

@item MusicPal (MV88W8618 ARM processor)

@item Gumstix "Connex" and "Verdex" motherboards (PXA255/270).

@item Siemens SX1 smartphone (OMAP310 processor)

@item AXIS-Devboard88 (CRISv32 ETRAX-FS).

@item Petalogix Spartan 3aDSP1800 MMU ref design (MicroBlaze).

@item Avnet LX60/LX110/LX200 boards (Xtensa)

@end itemize

@cindex supported user mode targets

For user emulation, x86 (32 and 64 bit), PowerPC (32 and 64 bit),

ARM, MIPS (32 bit only), Sparc (32 and 64 bit),

Alpha, ColdFire(m68k), CRISv32 and MicroBlaze CPUs are supported.

@node Installation

@chapter Installation

If you want to compile QEMU yourself, see @ref{compilation}.

@menu

* install_linux::   Linux

* install_windows:: Windows

* install_mac::     Macintosh

@end menu

@node install_linux

@section Linux

@cindex installation (Linux)

If a precompiled package is available for your distribution - you just

have to install it. Otherwise, see @ref{compilation}.

@node install_windows

@section Windows

@cindex installation (Windows)

Download the experimental binary installer at

@url{http://www.free.oszoo.org/@/download.html}.

TODO (no longer available)

@node install_mac

@section Mac OS X

Download the experimental binary installer at

@url{http://www.free.oszoo.org/@/download.html}.

TODO (no longer available)

@node QEMU PC System emulator

@chapter QEMU PC System emulator

@cindex system emulation (PC)

@menu

* pcsys_introduction:: Introduction

* pcsys_quickstart::   Quick Start

* sec_invocation::     Invocation

* pcsys_keys::         Keys

* pcsys_monitor::      QEMU Monitor

* disk_images::        Disk Images

* pcsys_network::      Network emulation

* pcsys_other_devs::   Other Devices

* direct_linux_boot::  Direct Linux Boot

* pcsys_usb::          USB emulation

* vnc_security::       VNC security

* gdb_usage::          GDB usage

* pcsys_os_specific::  Target OS specific information

@end menu

@node pcsys_introduction

@section Introduction

@c man begin DESCRIPTION

The QEMU PC System emulator simulates the

following peripherals:

@itemize @minus

@item

i440FX host PCI bridge and PIIX3 PCI to ISA bridge

@item

Cirrus CLGD 5446 PCI VGA card or dummy VGA card with Bochs VESA

extensions (hardware level, including all non standard modes).

@item

PS/2 mouse and keyboard

@item

2 PCI IDE interfaces with hard disk and CD-ROM support

@item

Floppy disk

@item

PCI and ISA network adapters

@item

Serial ports

@item

Creative SoundBlaster 16 sound card

@item

ENSONIQ AudioPCI ES1370 sound card

@item

Intel 82801AA AC97 Audio compatible sound card

@item

Intel HD Audio Controller and HDA codec

@item

Adlib (OPL2) - Yamaha YM3812 compatible chip

@item

Gravis Ultrasound GF1 sound card

@item

CS4231A compatible sound card

@item

PCI UHCI USB controller and a virtual USB hub.

@end itemize

SMP is supported with up to 255 CPUs.

QEMU uses the PC BIOS from the Seabios project and the Plex86/Bochs LGPL

VGA BIOS.

QEMU uses YM3812 emulation by Tatsuyuki Satoh.

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.

@example

qemu-system-i386 dos.img -soundhw gus -parallel none

@end example

Alternatively:

@example

qemu-system-i386 dos.img -device gus,irq=5

@end example

Or some other unclaimed IRQ.

CS4231A is the chip used in Windows Sound System and GUSMAX products

@c man end

@node pcsys_quickstart

@section Quick Start

@cindex quick start

Download and uncompress the linux image (@file{linux.img}) and type:

@example

qemu-system-i386 linux.img

@end example

Linux should boot and give you a prompt.

@node sec_invocation

@section Invocation

@example

@c man begin SYNOPSIS

usage: qemu-system-i386 [options] [@var{disk_image}]

@c man end

@end example

@c man begin OPTIONS

@var{disk_image} is a raw hard disk image for IDE hard disk 0. Some

targets do not need a disk image.

@include qemu-options.texi

@c man end

@node pcsys_keys

@section Keys

@c man begin OPTIONS

During the graphical emulation, you can use special key combinations to change

modes. The default key mappings are shown below, but if you use @code{-alt-grab}

then the modifier is Ctrl-Alt-Shift (instead of Ctrl-Alt) and if you use

@code{-ctrl-grab} then the modifier is the right Ctrl key (instead of Ctrl-Alt):

@table @key

@item Ctrl-Alt-f

@kindex Ctrl-Alt-f

Toggle full screen

@item Ctrl-Alt-+

@kindex Ctrl-Alt-+

Enlarge the screen

@item Ctrl-Alt--

@kindex Ctrl-Alt--

Shrink the screen

@item Ctrl-Alt-u

@kindex Ctrl-Alt-u

Restore the screen's un-scaled dimensions

@item Ctrl-Alt-n

@kindex Ctrl-Alt-n

Switch to virtual console 'n'. Standard console mappings are:

@table @emph

@item 1

Target system display

@item 2

Monitor

@item 3

Serial port

@end table

@item Ctrl-Alt

@kindex Ctrl-Alt

Toggle mouse and keyboard grab.

@end table

@kindex Ctrl-Up

@kindex Ctrl-Down

@kindex Ctrl-PageUp

@kindex Ctrl-PageDown

In the virtual consoles, you can use @key{Ctrl-Up}, @key{Ctrl-Down},

@key{Ctrl-PageUp} and @key{Ctrl-PageDown} to move in the back log.

@kindex Ctrl-a h

During emulation, if you are using the @option{-nographic} option, use

@key{Ctrl-a h} to get terminal commands:

@table @key

@item Ctrl-a h

@kindex Ctrl-a h

@item Ctrl-a ?

@kindex Ctrl-a ?

Print this help

@item Ctrl-a x

@kindex Ctrl-a x

Exit emulator

@item Ctrl-a s

@kindex Ctrl-a s

Save disk data back to file (if -snapshot)

@item Ctrl-a t

@kindex Ctrl-a t

Toggle console timestamps

@item Ctrl-a b

@kindex Ctrl-a b

Send break (magic sysrq in Linux)

@item Ctrl-a c

@kindex Ctrl-a c

Switch between console and monitor

@item Ctrl-a Ctrl-a

@kindex Ctrl-a a

Send Ctrl-a

@end table

@c man end

@ignore

@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

@node pcsys_monitor

@section QEMU Monitor

@cindex QEMU monitor

The QEMU monitor is used to give complex commands to the QEMU

emulator. You can use it to:

@itemize @minus

@item

Remove or insert removable media images

(such as CD-ROM or floppies).

@item

Freeze/unfreeze the Virtual Machine (VM) and save or restore its state

from a disk file.

@item Inspect the VM state without an external debugger.

@end itemize

@subsection Commands

The following commands are available:

@include qemu-monitor.texi

@subsection Integer expressions

The monitor understands integers expressions for every integer

argument. You can use register names to get the value of specifics

CPU registers by prefixing them with @emph{$}.

@node disk_images

@section 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. Version 0.8.3 added

the new qcow2 disk image format which is essential to support VM

snapshots.

@menu

* disk_images_quickstart::    Quick start for disk image creation

* disk_images_snapshot_mode:: Snapshot mode

* vm_snapshots::              VM snapshots

* qemu_img_invocation::       qemu-img Invocation

* qemu_nbd_invocation::       qemu-nbd Invocation

* disk_images_formats::       Disk image file formats

* host_drives::               Using host drives

* disk_images_fat_images::    Virtual FAT disk images

* disk_images_nbd::           NBD access

* disk_images_sheepdog::      Sheepdog disk images

* disk_images_iscsi::         iSCSI LUNs

* disk_images_gluster::       GlusterFS disk images

* disk_images_ssh::           Secure Shell (ssh) disk images

@end menu

@node disk_images_quickstart

@subsection Quick start for disk image creation

You can create a disk image with the command:

@example

qemu-img create myimage.img mysize

@end example

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.

See @ref{qemu_img_invocation} for more information.

@node disk_images_snapshot_mode

@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 using the @code{commit} monitor

command (or @key{C-a s} in the serial console).

@node vm_snapshots

@subsection VM snapshots

VM snapshots are snapshots of the complete virtual machine including

CPU state, RAM, device state and the content of all the writable

disks. In order to use VM snapshots, you must have at least one non

removable and writable block device using the @code{qcow2} disk image

format. Normally this device is the first virtual hard drive.

Use the monitor command @code{savevm} to create a new VM snapshot or

replace an existing one. A human readable name can be assigned to each

snapshot in addition to its numerical ID.

Use @code{loadvm} to restore a VM snapshot and @code{delvm} to remove

a VM snapshot. @code{info snapshots} lists the available snapshots

with their associated information:

@example

(qemu) info snapshots

Snapshot devices: hda

Snapshot list (from hda):

ID        TAG                 VM SIZE                DATE       VM CLOCK

1         start                   41M 2006-08-06 12:38:02   00:00:14.954

2                                 40M 2006-08-06 12:43:29   00:00:18.633

3         msys                    40M 2006-08-06 12:44:04   00:00:23.514

@end example

A VM snapshot is made of a VM state info (its size is shown in

@code{info snapshots}) and a snapshot of every writable disk image.

The VM state info is stored in the first @code{qcow2} non removable

and writable block device. The disk image snapshots are stored in

every disk image. The size of a snapshot in a disk image is difficult

to evaluate and is not shown by @code{info snapshots} because the

associated disk sectors are shared among all the snapshots to save

disk space (otherwise each snapshot would need a full copy of all the

disk images).

When using the (unrelated) @code{-snapshot} option

(@ref{disk_images_snapshot_mode}), you can always make VM snapshots,

but they are deleted as soon as you exit QEMU.

VM snapshots currently have the following known limitations:

@itemize

@item

They cannot cope with removable devices if they are removed or

inserted after a snapshot is done.

@item

A few device drivers still have incomplete snapshot support so their

state is not saved or restored properly (in particular USB).

@end itemize

@node qemu_img_invocation

@subsection @code{qemu-img} Invocation

@include qemu-img.texi

@node qemu_nbd_invocation

@subsection @code{qemu-nbd} Invocation

@include qemu-nbd.texi

@node disk_images_formats

@subsection Disk image file formats

QEMU supports many image file formats that can be used with VMs as well as with

any of the tools (like @code{qemu-img}). This includes the preferred formats

raw and qcow2 as well as formats that are supported for compatibility with

older QEMU versions or other hypervisors.

Depending on the image format, different options can be passed to

@code{qemu-img create} and @code{qemu-img convert} using the @code{-o} option.

This section describes each format and the options that are supported for it.

@table @option

@item raw

Raw disk image format. 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 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.

@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

on Windows), optional AES encryption, zlib based compression and

support of multiple VM snapshots.

Supported options:

@table @code

@item compat

Determines the qcow2 version to use. @code{compat=0.10} uses the

traditional image format that can be read by any QEMU since 0.10.

@code{compat=1.1} enables image format extensions that only QEMU 1.1 and

newer understand (this is the default). Amongst others, this includes

zero clusters, which allow efficient copy-on-read for sparse images.

@item backing_file

File name of a base image (see @option{create} subcommand)

@item backing_fmt

Image format of the base image

@item encryption

If this option is set to @code{on}, the image is encrypted.

Encryption uses the AES format which is very secure (128 bit keys). Use

a long password (16 characters) to get maximum protection.

@item cluster_size

Changes the qcow2 cluster size (must be between 512 and 2M). Smaller cluster

sizes can improve the image file size whereas larger cluster sizes generally

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.

@item lazy_refcounts

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

the goal of avoiding metadata I/O and improving performance. This is

particularly interesting with @option{cache=writethrough} which doesn't batch

metadata updates. The tradeoff is that after a host crash, the reference count

tables must be rebuilt, i.e. on the next open an (automatic) @code{qemu-img

check -r all} is required, which may take some time.

This option can only be enabled if @code{compat=1.1} is specified.

@end table

@item qed

Old QEMU image format with support for backing files and compact image files

(when your filesystem or transport medium does not support holes).

When converting QED images to qcow2, you might want to consider using the

@code{lazy_refcounts=on} option to get a more QED-like behaviour.

Supported options:

@table @code

@item backing_file

File name of a base image (see @option{create} subcommand).

@item backing_fmt

Image file format of backing file (optional).  Useful if the format cannot be

autodetected because it has no header, like some vhd/vpc files.

@item cluster_size

Changes the cluster size (must be power-of-2 between 4K and 64K). Smaller

cluster sizes can improve the image file size whereas larger cluster sizes

generally provide better performance.

@item table_size

Changes the number of clusters per L1/L2 table (must be power-of-2 between 1

and 16).  There is normally no need to change this value but this option can be

used for performance benchmarking.

@end table

@item qcow

Old QEMU image format with support for backing files, compact image files,

encryption and compression.

Supported options:

@table @code

@item backing_file

File name of a base image (see @option{create} subcommand)

@item encryption

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:

@table @code

@item static

If this option is set to @code{on}, the image is created with metadata

preallocation.

@end table

@item vmdk

VMware 3 and 4 compatible image format.

Supported options:

@table @code

@item backing_file

File name of a base image (see @option{create} subcommand).

@item compat6

Create a VMDK version 6 image (instead of version 4)

@item subformat

Specifies which VMDK subformat to use. Valid options are

@code{monolithicSparse} (default),

@code{monolithicFlat},

@code{twoGbMaxExtentSparse},

@code{twoGbMaxExtentFlat} and

@code{streamOptimized}.

@end table

@item vpc

VirtualPC compatible image format (VHD).

Supported options:

@table @code

@item subformat

Specifies which VHD subformat to use. Valid options are

@code{dynamic} (default) and @code{fixed}.

@end table

@item VHDX

Hyper-V compatible image format (VHDX).

Supported options:

@table @code

@item subformat

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'.

@item block_size

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

@item log_size

Log size; min 1 MB.

@end table

@end table

@subsubsection Read-only formats

More disk image file formats are supported in a read-only mode.

@table @option

@item bochs

Bochs images of @code{growing} type.

@item cloop

Linux Compressed Loop image, useful only to reuse directly compressed

CD-ROM images present for example in the Knoppix CD-ROMs.

@item dmg

Apple disk image.

@item parallels

Parallels disk image format.

@end table

@node host_drives

@subsection Using host drives

In addition to disk image files, QEMU can directly access host

devices. We describe here the usage for QEMU version >= 0.8.3.

@subsubsection Linux

On Linux, you can directly use the host device filename instead of a

disk image filename provided you have enough privileges to access

it. For example, use @file{/dev/cdrom} to access to the CDROM or

@file{/dev/fd0} for the floppy.

@table @code

@item CD

You can specify a CDROM device even if no CDROM is loaded. QEMU has

specific code to detect CDROM insertion or removal. CDROM ejection by

the guest OS is supported. Currently only data CDs are supported.

@item Floppy

You can specify a floppy device even if no floppy is loaded. Floppy

removal is currently not detected accurately (if you change floppy

without doing floppy access while the floppy is not loaded, the guest

OS will think that the same floppy is loaded).

@item Hard disks

Hard disks can be used. Normally you must specify the whole disk

(@file{/dev/hdb} instead of @file{/dev/hdb1}) so that the guest OS can

see it as a partitioned disk. WARNING: unless you know what you do, it

is better to only make READ-ONLY accesses to the hard disk otherwise

you may corrupt your host data (use the @option{-snapshot} command

line option or modify the device permissions accordingly).

@end table

@subsubsection Windows

@table @code

@item CD

The preferred syntax is the drive letter (e.g. @file{d:}). The

alternate syntax @file{\\.\d:} is supported. @file{/dev/cdrom} is

supported as an alias to the first CDROM drive.

Currently there is no specific code to handle removable media, so it

is better to use the @code{change} or @code{eject} monitor commands to

change or eject media.

@item Hard disks

Hard disks can be used with the syntax: @file{\\.\PhysicalDrive@var{N}}

where @var{N} is the drive number (0 is the first hard disk).

WARNING: unless you know what you do, it is better to only make

READ-ONLY accesses to the hard disk otherwise you may corrupt your

host data (use the @option{-snapshot} command line so that the

modifications are written in a temporary file).

@end table

@subsubsection Mac OS X

@file{/dev/cdrom} is an alias to the first CDROM.

Currently there is no specific code to handle removable media, so it

is better to use the @code{change} or @code{eject} monitor commands to

change or eject media.

@node disk_images_fat_images

@subsection Virtual FAT disk images

QEMU can automatically create a virtual FAT disk image from a

directory tree. In order to use it, just type:

@example

qemu-system-i386 linux.img -hdb fat:/my_directory

@end example

Then you access access to all the files in the @file{/my_directory}

directory without having to copy them in a disk image or to export

them via SAMBA or NFS. The default access is @emph{read-only}.

Floppies can be emulated with the @code{:floppy:} option:

@example

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-system-i386 linux.img -fda fat:floppy:rw:/my_directory

@end example

What you should @emph{never} do:

@itemize

@item use non-ASCII filenames ;

@item use "-snapshot" together with ":rw:" ;

@item expect it to work when loadvm'ing ;

@item write to the FAT directory on the host system while accessing it with the guest system.

@end itemize

@node disk_images_nbd

@subsection NBD access

QEMU can access directly to block device exported using the Network Block Device

protocol.

@example

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-system-i386 linux.img -hdb nbd+unix://?socket=/tmp/my_socket

@end example

In this case, the block device must be exported using qemu-nbd:

@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:

@example

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

@end example

@noindent

and then you can use it with two guests:

@example

qemu-system-i386 linux1.img -hdb nbd+unix://?socket=/tmp/my_socket

qemu-system-i386 linux2.img -hdb nbd+unix://?socket=/tmp/my_socket

@end example

If the nbd-server uses named exports (supported since NBD 2.9.18, or with QEMU's

own embedded NBD server), you must specify an export name in the URI:

@example

qemu-system-i386 -cdrom nbd://localhost/debian-500-ppc-netinst

qemu-system-i386 -cdrom nbd://localhost/openSUSE-11.1-ppc-netinst

@end example

The URI syntax for NBD is supported since QEMU 1.3.  An alternative syntax is

also available.  Here are some example of the older syntax:

@example

qemu-system-i386 linux.img -hdb nbd:my_nbd_server.mydomain.org:1024

qemu-system-i386 linux2.img -hdb nbd:unix:/tmp/my_socket

qemu-system-i386 -cdrom nbd:localhost:10809:exportname=debian-500-ppc-netinst

@end example

@node disk_images_sheepdog

@subsection Sheepdog disk images

Sheepdog is a distributed storage system for QEMU.  It provides highly

available block level storage volumes that can be attached to

QEMU-based virtual machines.

You can create a Sheepdog disk image with the command:

@example

qemu-img create sheepdog:///@var{image} @var{size}

@end example

where @var{image} is the Sheepdog image name and @var{size} is its

size.

To import the existing @var{filename} to Sheepdog, you can use a

convert command.

@example

qemu-img convert @var{filename} sheepdog:///@var{image}

@end example

You can boot from the Sheepdog disk image with the command:

@example

qemu-system-i386 sheepdog:///@var{image}

@end example

You can also create a snapshot of the Sheepdog image like qcow2.

@example

qemu-img snapshot -c @var{tag} sheepdog:///@var{image}

@end example

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-system-i386 sheepdog:///@var{image}#@var{tag}

@end example

You can create a cloned image from the existing snapshot.

@example

qemu-img create -b sheepdog:///@var{base}#@var{tag} sheepdog:///@var{image}

@end example

where @var{base} is a image name of the source snapshot and @var{tag}

is its tag name.

You can use an unix socket instead of an inet socket:

@example

qemu-system-i386 sheepdog+unix:///@var{image}?socket=@var{path}

@end example

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-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://[<username>[%<password>]@@]<host>[:<port>]/<target-iqn-name>/<lun>

@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=<username>

export LIBISCSI_CHAP_PASSWORD=<password>

iscsi://<host>/<target-iqn-name>/<lun>

@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[:<name>'] where <name> 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 <<EOF

[iscsi]

  user = "me"

  password = "my password"

  initiator-name = "iqn.qemu.test:my-initiator"

  header-digest = "CRC32C"

EOF

qemu-system-i386 -drive file=iscsi://127.0.0.1/iqn.qemu.test/1 \

    -readconfig iscsi.conf

@end example

Howto set up a simple iSCSI target on loopback and accessing it via QEMU:

@example

This example shows how to set up an iSCSI target with one CDROM and one DISK

using the Linux STGT software target. This target is available on Red Hat based

systems as the package 'scsi-target-utils'.

tgtd --iscsi portal=127.0.0.1:3260

tgtadm --lld iscsi --op new --mode target --tid 1 -T iqn.qemu.test