source: postlfs/virtualization/qemu.xml@ f48a2a2a

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
  <!ENTITY % general-entities SYSTEM "../../general.ent">
  %general-entities;

  <!ENTITY qemu-download-http "https://download.qemu.org/qemu-&qemu-version;.tar.xz">
  <!ENTITY qemu-download-ftp  " ">
  <!ENTITY qemu-md5sum        "d41853bffb18878dd1ff7afc2eb41f1a">
  <!ENTITY qemu-size          "121 MB">
  <!ENTITY qemu-buildsize     "2.5 GB (365 MB installed)">
  <!ENTITY qemu-time          "1.6 SBU (add 2.4 SBU for tests, both using parallelism=4)">
]>

<sect1 id="qemu" xreflabel="qemu-&qemu-version;">
  <?dbhtml filename="qemu.html"?>


  <title>qemu-&qemu-version;</title>

  <indexterm zone="qemu">
    <primary sortas="a-qemu">qemu</primary>
  </indexterm>

  <sect2 role="package">
    <title>Introduction to qemu</title>

    <para>
      <application>qemu</application> is a full virtualization solution for
      Linux on x86 hardware containing virtualization extensions (Intel VT or
      AMD-V).
    </para>

    &lfs113_checked;

    <bridgehead renderas="sect3">Package Information</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>
          Download (HTTP): <ulink url="&qemu-download-http;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download (FTP): <ulink url="&qemu-download-ftp;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download MD5 sum: &qemu-md5sum;
        </para>
      </listitem>
      <listitem>
        <para>
          Download size: &qemu-size;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated disk space required: &qemu-buildsize;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated build time: &qemu-time;
        </para>
      </listitem>
    </itemizedlist>

    <bridgehead renderas="sect3">Qemu Dependencies</bridgehead>

    <bridgehead renderas="sect4">Required</bridgehead>
    <para role="required">
      <xref linkend="glib2"/>
    </para>

    <bridgehead renderas="sect4">Recommended</bridgehead>
    <para role="recommended">
      <xref linkend="alsa-lib"/>,
      <xref linkend="libslirp"/>, and
      <xref linkend="sdl2"/>
    </para>

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional">
      Depending on the sound system, various packages in <xref linkend="alsa"/>,
      <xref linkend="python3"/>,
      <xref linkend="pulseaudio"/>,
      <xref linkend="bluez"/>,
      <xref linkend="curl"/>,
      <xref linkend="cyrus-sasl"/>,
      <xref linkend="gnutls"/>,
      <xref linkend="gtk2"/>,
      <xref linkend="gtk3"/>,
      <xref linkend="libusb"/>,
      <xref linkend="libgcrypt"/>,
      <xref linkend="libssh2"/>,
      <xref linkend="lzo"/>,
      <xref linkend="nettle"/>,
      <xref linkend="mesa"/>,
      <xref role="nodep" linkend="vte"/> or <xref linkend="vte2"/>, and
<!-- libcacard has been a standalone project since qemu-2.5.-->
      <ulink url="https://gitlab.freedesktop.org/spice/libcacard">libcacard</ulink>
    </para>

    <bridgehead renderas="sect4">Optional (Runtime)</bridgehead>
    <para role="runtime">
      &logind;
    </para>

    <bridgehead renderas="sect4">Optional (for building the documentation)</bridgehead>
    <para role="optional">
      <xref linkend="sphinx_rtd_theme"/>
    </para>

    <note>
      <para>
        This optional dependencies list is not comprehensive. See the output of
        <command>./configure --help</command> for a more complete list.
      </para>
    </note>

    <para condition="html" role="usernotes">Editor Notes:
    <ulink url="&blfs-wiki;/qemu"/></para>

  </sect2>

  <sect2 id='qemu-prereq'>
    <title>KVM Prerequisites</title>

    <para>
      Before building <application>qemu</application>, check to see if
      your processor supports Virtualization Technology (VT):
    </para>

    <screen><userinput>grep -E '^flags.*(vmx|svm)' /proc/cpuinfo</userinput></screen>

    <para>
      If you get any output, you have VT technology (vmx for Intel
      processors and svm for AMD processors).  You then need to go into your
      system BIOS and ensure it is enabled.  After enabling, reboot back to your
      LFS instance.
    </para>

  </sect2>

  <sect2 role="kernel" id='qemu-kernel'>
    <title>Kernel Configuration</title>

    <para>
      Enable the following options in the kernel configuration and
      recompile the kernel if necessary:
    </para>

    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
      href="qemu-kvm-kernel.xml"/>

    <indexterm zone="qemu qemu-kernel">
      <primary sortas="d-qemu">qemu</primary>
    </indexterm>

    <para>
      The Intel or AMD settings are not both required, but the one matching
      your system processor is required.
    </para>

    <para>
      To use the <quote>bridge</quote> network device, as explained below,
      check that <xref linkend='bridgeutils'/> is installed
      and the following options in the kernel configuration are enabled:
    </para>

    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
      href="qemu-bridge-kernel.xml"/>

  </sect2>

  <sect2 role="installation">
    <title>Installation of qemu</title>
<!-- group kvm is created in lfs chapter 7 even for sysv
    <para revision="sysv">
      You will need a dedicated group that will contain users (other than root)
      allowed to access the KVM device.  Create this group by running the
      following command as the
      <systemitem class="username">root</systemitem> user:
    </para>

<screen role="root" revision="sysv"><userinput>groupadd -g 61 kvm</userinput></screen>
-->
    <para>
      The udev rule of LFS only allows the &root; user, the users owning
      a local login session supported by the optional runtime dependency
      &logind;, or the users in the
      <systemitem class="groupname">kvm</systemitem> group to use the KVM
      device.  As the &root; user, add any non-&root; users that might use
      the KVM device either without &logind; installed or remotely (via a
      SSH connection) to the
      <systemitem class="groupname">kvm</systemitem> group:
    </para>

<screen role="root"><userinput>usermod -a -G kvm <replaceable>&lt;username&gt;</replaceable></userinput></screen>

    <para>
      Install <application>qemu</application> by running the following
      commands:
    </para>

    <note>
      <para>
        Qemu is capable of running many targets.  The build process
        is also capable of building multiple targets at one time in a
        comma delimited list assigned to <option>--target-list</option>. Run
        <command>./configure --help</command> to get a complete list of
        available targets.
      </para>
    </note>


<screen><userinput>if [ $(uname -m) = i686 ]; then
   QEMU_ARCH=i386-softmmu
else
   QEMU_ARCH=x86_64-softmmu
fi


mkdir -vp build &amp;&amp;
cd        build &amp;&amp;

../configure --prefix=/usr               \
             --sysconfdir=/etc           \
             --localstatedir=/var        \
             --target-list=$QEMU_ARCH    \
             --audio-drv-list=alsa       \
             --disable-pa                \
             --enable-slirp              \
             --docdir=/usr/share/doc/qemu-&qemu-version; &amp;&amp;

unset QEMU_ARCH &amp;&amp;

make</userinput></screen>

    <para>
      <application>qemu</application> uses <command>ninja</command> as
      a subprocess when building.  To run the tests, issue:
      <command>ninja test</command>. Two migration tests are known to fail.
    </para>

    <para>
      Now, as the &root; user:
    </para>

<screen role="root"><userinput>make install</userinput></screen>
<!-- now in LFS
    <para>
      You will also need to add an Udev rule so that the KVM device gets correct
      permissions. As the &root; user, issue:
    </para>

<screen role="root"><userinput>cat > /etc/udev/rules.d/65-kvm.rules &lt;&lt; "EOF"
<literal>KERNEL=="kvm", GROUP="kvm", MODE="0660"</literal>
EOF</userinput></screen>
-->
    <para>
      Change the permissions and ownership of a helper script, which is needed
      when using the <quote>bridge</quote> network device (see below). Again
      as the &root; user, issue:
    </para>

    <note>
      <para>
        You need to add any users who might use the <quote>bridge</quote>
        network device into the
        <systemitem class="groupname">kvm</systemitem> group even if
        &logind; is installed.
      </para>
    </note>

<screen role="root"><userinput>chgrp kvm  /usr/libexec/qemu-bridge-helper &amp;&amp;
chmod 4750 /usr/libexec/qemu-bridge-helper</userinput></screen>

    <note>
      <para>
        For convenience you may want to create a symbolic link to run
        the installed program. For instance (as the &root; user):
      </para>

<screen role="root"><userinput>ln -sv qemu-system-`uname -m` /usr/bin/qemu</userinput></screen>
    </note>

  </sect2>

  <sect2 role="commands">
    <title>Command Explanations</title>

    <para>
      <parameter>--audio-drv-list=alsa --disable-pa</parameter>: This switch
      sets the audio driver to ALSA. See below for enabling other audio drivers.
    </para>

    <para>
      <parameter>--enable-slirp</parameter>: This switch forces the building
      system to check for <xref linkend='libslirp'/>.  Remove it if you
      don't need the <option>-netdev user</option> support.
    </para>

    <para>
      <option>--audio-drv-list=pa --disable-alsa</option>: This switch sets
      the audio driver to pulseaudio. For other drivers see the
      --audio-drv-list choices in the output of
      <command>./configure --help</command>. The default audio driver is OSS.
      To enable support for both alsa and pulseaudio, use
      <option>--audio-drv-list=alsa,pa</option>.
    </para>

  </sect2>

  <sect2 role="using">
    <title>Using Qemu</title>

    <para>
      Since using qemu means using a virtual computer, the steps to set up
      the virtual machine are in close analogy with those to set up a real
      computer. You'll need to decide about CPU, memory, disk, USB devices,
      network card(s), screen size, etc. Once the <quote>hardware</quote> is
      decided, you'll have for example to choose how to connect the machine
      to internet, and/or to install an OS. In the following, we show basic
      ways of performing those steps. But qemu is much more than this, and it
      is strongly advised to read the qemu documentation in
      <filename>/usr/share/doc/qemu-&qemu-version;/qemu-doc.html</filename>.
    </para>

    <note>
      <para>
        It is standard practice to name the computer running qemu
        <quote>host</quote> and the emulated machine running under qemu the
        <quote>guest</quote>. We'll use those notations in the following.
      </para>
    </note>

    <note>
      <para>
        The following instructions assume the optional symbolic link,
        <filename>qemu</filename>, has been created. Additionally,
        <command>qemu</command> should be run in a graphical environment.
        But it is possible to use qemu <quote>headless</quote> or through
        SSH. See the documentation for the various possibilities.
      </para>
    </note>

    <bridgehead renderas="sect3">Disk</bridgehead>
    <para>
      A virtual disk may be set up in the following way:
    </para>

<screen><userinput>VDISK_SIZE=<replaceable>50G</replaceable>
VDISK_FILENAME=<replaceable>vdisk.img</replaceable>
qemu-img create -f qcow2 $VDISK_FILENAME $VDISK_SIZE</userinput></screen>

    <para>
      The virtual disk size and filename should be adjusted as desired. The
      actual size of the file will be less than specified, but will expand as
      needed, so it is safe to put a high value.
    </para>

    <bridgehead renderas="sect3">Operating System</bridgehead>
    <para>
      To install an operating system, download an iso image from your preferred
      Linux distribution. For the purposes of this example, we'll use
      <filename>Fedora-16-x86_64-Live-LXDE.iso</filename> in the current
      directory. Run the following:
    </para>

<screen><userinput>qemu -enable-kvm                           \
     -drive file=$VDISK_FILENAME           \
     -cdrom Fedora-16-x86_64-Live-LXDE.iso \
     -boot d                               \
     -m <replaceable>1G</replaceable></userinput></screen>

    <para>
      Follow the normal installation procedures for the chosen distribution.
      The <parameter>-boot</parameter> option specifies the boot order of
      drives as a string of drive letters. Valid drive letters are: a, b
      (floppy 1 and 2), c (first hard disk), d (first CD-ROM). The
      <parameter>-m</parameter> option is the amount of memory to use for the
      virtual machine. The choice depends on the load of the host. Modern
      distributions should be comfortable with 1GB.
      The <parameter>-enable-kvm</parameter> option allows hardware
      acceleration. Without this switch, the emulation is much slower.
    </para>

    <bridgehead renderas="sect3">Defining the virtual hardware</bridgehead>
    <para>
      The virtual machine hardware is defined by the qemu command line.
      An example command is given below:
    </para>

<screen><userinput>qemu -enable-kvm                     \
     -smp 4                          \
     -cpu host                       \
     -m 1G                           \
     -drive file=$VDISK_FILENAME     \
     -cdrom grub-img.iso             \
     -boot order=c,once=d,menu=on    \
     -net nic,netdev=net0            \
     -netdev user,id=net0            \
     -device ac97                    \
     -vga std                        \
     -serial mon:stdio               \
     -name "fedora-16"</userinput></screen>

    <bridgehead renderas="sect3">Meaning of the command line options</bridgehead>
    <para>
      <parameter>-enable-kvm</parameter>: enable full KVM virtualization
      support. On some hardware, it may be necessary to add the undocumented
      <option>-machine smm=off</option> option in order to enable KVM.
    </para>

    <para>
      <parameter>-smp &lt;N&gt;</parameter>: enable symmetric multiprocessing
      with &lt;N&gt; CPUs.
    </para>

    <para>
      <parameter>-cpu &lt;model&gt;</parameter>: simulate CPU &lt;model&gt;.
      the list of supported models can be obtained with <option>-cpu
      help</option>.
    </para>

    <para>
      <parameter>-drive file=&lt;filename&gt;</parameter>: defines a virtual
      disk whose image is stored in <filename>&lt;filename&gt;</filename>.
    </para>

    <para>
      <parameter>-cdrom grub-img.iso</parameter>: defines an iso formatted file
      to use as a cdrom. Here we use a grub rescue disk, which may turn handy
      when something goes wrong at boot time.
    </para>

    <para>
      <parameter>-boot order=c,once=d,menu=on</parameter>: defines the boot
      order for the virtual BIOS.
    </para>

    <para>
      <parameter>-net nic,netdev=&lt;netid&gt;</parameter>: defines a network
      card connected to the network device with id &lt;netid&gt;.
    </para>

    <para>
      <parameter>-netdev user,id=&lt;netid&gt;</parameter>: defines the
      network <quote>user</quote> device. This is a virtual local network
      with addresses 10.0.2.0/24, where the host has address 10.0.2.2 and
      acts as a gateway to internet, and with a name server at address
      10.0.2.3, and an smb server at address 10.0.2.4. A builtin DHCP server
      can allocate addresses between 10.0.2.15 and 10.0.2.31.
    </para>

    <para>
      <parameter>-soundhw &lt;model&gt;</parameter>: defines the soundcard
      model. The list may be obtained with <option>-soundhw help</option>.
    </para>

    <para>
      <parameter>-vga &lt;type&gt;</parameter>: defines the type of VGA card
      to emulate.  For <parameter>-vga std</parameter>, if you are building
      a Linux kernel for the guest, it's recommended to enable
      <option>CONFIG_DRM_BOCHS</option> (as a part of the kernel or a kernel
      module) to drive all the features of the emulated VGA card, and
      <option>CONFIG_FB</option> to display the Linux console on it.  The
      other <option>&lt;type&gt;</option> values are not tested by the
      editors and may require additional dependencies.
    </para>

    <para>
      <parameter>-serial mon:stdio</parameter>: sends the serial port of the
      guest (<filename>/dev/ttyS0</filename> on linux guests), multiplexed with
      the qemu monitor, to the standard input and output of the qemu
      process.
    </para>

    <para>
      <parameter>-name &lt;name&gt;</parameter>: sets the name of the guest.
      This name is displayed in the guest window caption. It may be useful
      if you run several guests at the same time.
    </para>

    <para>
      <option>-drive if=pflash,format=raw,readonly=on,file=/usr/share/qemu/edk2-x86_64-code.fd</option>: Load a
      pre-built EDK2 UEFI firmware, instead of the default PC BIOS.  Use
      this option if you want to boot the guest OS with UEFI.
    </para>

    <para>
      <option>-drive file=&lt;filename&gt;,if=virtio</option>: Provide
      Virtio interface to the guest kernel for accessing the disk image,
      instead of simulating a real disk hardware.  This can improve disk I/O
      performance, but it requires a Virtio driver in guest kernel.  Use
      it instead of a plain <option>-drive</option> if the guest kernel
      supports Virtio.  To build a Linux kernel with Virtio support for the
      guest, use
      <command>make defconfig &amp;&amp; make kvm_guest.config</command> to
      create an initial kernel configuration with the Virtio drives enabled,
      then make your customization.  And, if the guest kernel is Linux, the
      virtual disks using Virtio interface will be named
      <filename>vdx</filename> in the devtmpfs, instead of
      <filename>sdx</filename>.
    </para>

    <para>
      <option>-net nic,netdev=net0,model=virtio-net-pci</option>: Provide
      Virtio interface to the guest kernel for accessing the network
      interface, instead of simulating a real network interface card.  This
      can improve network I/O performance, but it requires a Virtio driver
      in guest kernel.  Use it instead of a plain <option>-net</option> if
      the guest kernel supports Virtio.
    </para>

    <bridgehead renderas="sect3">Controlling the Emulated Display</bridgehead>
    <para>
      To set the resolution of the emulated display for a Xorg server
      running in the guest Linux system, read <xref linkend='xdisplay'/>.
    </para>

    <bridgehead renderas="sect3">Networking</bridgehead>
    <para>
      The above solution for networking allows the guest to access the local
      network through the host (and possibly to access internet through the
      local routers), but the converse is not true. Not even the host can
      access the guest, unless port forwarding is enabled. And in the case
      several guests are running, they cannot communicate with each other.
      Other network devices can be used for this purpose. For example, there
      is the <quote>socket</quote> device, which allows several guests to
      share a common virtual network. In the following, we describe in more
      details how to set up the <quote>bridge</quote> device, which allows
      the guests to appear as if connected to the local network. All the
      commands below should be run as the <systemitem
      class="username">root</systemitem> user.
    </para>

    <para revision="sysv">
      Set up bridging with <xref linkend="bridgeutils"/>. Only the physical
      interface(s) should be set up at boot. The virtual interface(s) will be
      added as needed when qemu is started.
    </para>

    <para revision="systemd">
      <!-- On SYS-V, IP_FORWARD is enabled by the bridge script. -->
      Allow the host to forward IP packets:
    </para>

<screen role="root"
        revision="systemd"><userinput>sysctl -w net.ipv4.ip_forward=1</userinput></screen>

    <para revision="systemd">
      To make this permanent, add the command to
      <filename>/etc/sysctl.d/60-net-forward.conf:</filename>
    </para>

<screen role="root"
        revision="systemd"><userinput>cat &gt;&gt; /etc/sysctl.d/60-net-forward.conf &lt;&lt; EOF
<literal>net.ipv4.ip_forward=1</literal>
EOF</userinput></screen>

    <para>
      Set up a required configuration file:
    </para>

<!-- /etc/qemu has not been installed by "make install" since version 2.4 -->
<screen role="root"><userinput>install -vdm 755 /etc/qemu &amp;&amp;
echo allow br0 &gt; /etc/qemu/bridge.conf</userinput></screen>

    <para>
      In the qemu command line above, replace the switch
      <parameter>-netdev user,...</parameter> with
      <parameter>-netdev bridge,...</parameter>.
    </para>

  </sect2>

  <sect2 role="content">
    <title>Contents</title>

    <segmentedlist>
      <segtitle>Installed Programs</segtitle>
      <segtitle>Installed Library</segtitle>
      <segtitle>Installed Directories</segtitle>

      <seglistitem>
        <seg>
          elf2dmp,
          qemu (symlink),
          qemu-edid,
          qemu-ga,
          qemu-img,
          qemu-io,
          qemu-keymap,
          qemu-nbd,
          qemu-pr-helper,
          qemu-storage-daemon, and
          qemu-system-&lt;arch&gt;
        </seg>
        <seg>None</seg>
        <seg>
          /usr/share/qemu and
          /usr/share/doc/qemu-&qemu-version; (optional)
        </seg>
      </seglistitem>
    </segmentedlist>

    <variablelist>
      <bridgehead renderas="sect3">Short Description</bridgehead>
      <?dbfo list-presentation="list"?>
      <?dbhtml list-presentation="table"?>

      <varlistentry id="elf2dmp">
        <term><command>elf2dmp</command></term>
        <listitem>
          <para>
            Converts files from elf to dmp format
          </para>
          <indexterm zone="qemu elf2dmp">
            <primary sortas="b-elf2dmp">elf2dmp</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="qemu-edid">
        <term><command>qemu-edid</command></term>
        <listitem>
          <para>
            is a test tool for the qemu EDID generator
          </para>
          <indexterm zone="qemu qemu-edid">
            <primary sortas="b-qemu-edid">qemu-edid</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="qemu-ga">
        <term><command>qemu-ga</command></term>
        <listitem>
          <para>
            implements support for QMP (QEMU Monitor Protocol) commands and
            events that terminate and originate respectively within the guest
            using an agent built as part of QEMU
          </para>
          <indexterm zone="qemu qemu-ga">
            <primary sortas="b-qemu-ga">qemu-ga</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="qemu-img">
        <term><command>qemu-img</command></term>
        <listitem>
          <para>
            provides commands to manage QEMU disk images
          </para>
          <indexterm zone="qemu qemu-img">
            <primary sortas="b-qemu-img">qemu-img</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="qemu-io">
        <term><command>qemu-io</command></term>
        <listitem>
          <para>
            is a diagnostic and manipulation program for (virtual) memory
            media. It is still at an early stage of development
          </para>
          <indexterm zone="qemu qemu-io">
            <primary sortas="b-qemu-io">qemu-io</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="qemu-keymap">
        <term><command>qemu-keymap</command></term>
        <listitem>
          <para>
            generates qemu reverse keymaps from xkb keymaps,
            which can be used with the qemu "-k" command line switch
          </para>
          <indexterm zone="qemu qemu-keymap">
            <primary sortas="b-qemu-keymap">qemu-keymap</primary>
          </indexterm>
        </listitem>
      </varlistentry>


      <varlistentry id="qemu-nbd">
        <term><command>qemu-nbd</command></term>
        <listitem>
          <para>
            exports Qemu disk images using the QEMU Disk Network Block
            Device (NBD) protocol
          </para>
          <indexterm zone="qemu qemu-nbd">
            <primary sortas="b-qemu-nbd">qemu-nbd</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="qemu-pr-helper">
        <term><command>qemu-pr-helper</command></term>
        <listitem>
          <para>
            Implements the persistent reservation helper for QEMU
          </para>
          <indexterm zone="qemu qemu-pr-helper">
            <primary sortas="b-qemu-pr-helper">qemu-pr-helper</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="qemu-storage-daemon">
        <term><command>qemu-storage-daemon</command></term>
        <listitem>
          <para>
            allows to modify disk images using the QEMU Monitor Protocol (QMP)
            without running a VM
          </para>
          <indexterm zone="qemu qemu-storage-daemon">
            <primary sortas="b-qemu-storage-daemon">qemu-storage-daemon</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="qemu-system">
        <term><command>qemu-system-x86_64</command></term>
        <listitem>
          <para>
            is the QEMU PC System emulator
          </para>
          <indexterm zone="qemu qemu-system">
            <primary sortas="b-qemu-system">qemu-system-x86_64</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>