glfs/postlfs/virtualization/qemu.xml

<?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 "http://download.qemu-project.org/qemu-&qemu-version;.tar.xz">
  <!ENTITY qemu-download-ftp  " ">
  <!ENTITY qemu-md5sum        "cdf2b5ca52b9abac9bacb5842fa420f8">
  <!ENTITY qemu-size          "52 MB">
  <!ENTITY qemu-buildsize     "1.2 G (add 414 MB for tests)">
  <!ENTITY qemu-time          "1.0 SBU (using parallelism=4; add 2.4 SBU for tests)">
]>

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

  <sect1info>
    <othername>$LastChangedBy$</othername>
    <date>$Date$</date>
  </sect1info>

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

    &lfs90_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"/>, and
      <xref linkend="x-window-system"/>
    </para>

    <bridgehead renderas="sect4">Recommended</bridgehead>
    <para role="recommended">
      <xref linkend="alsa-lib"/> 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="python2"/>,
      <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 linkend="sdl"/>,
      <xref linkend="vte"/> or <xref linkend="vte2"/>, and
<!-- libcacard has been a standalone project since qemu-2.5.-->
      <ulink url="https://www.spice-space.org/page/Libcacard">libcacard</ulink>
    </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">User 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>egrep '^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 enabing, 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>

<screen><literal>[*] Virtualization:  ---&gt;                            [CONFIG_VIRTUALIZATION]
  &lt;*/M&gt;   Kernel-based Virtual Machine (KVM) support [CONFIG_KVM]
  &lt;*/M&gt;     KVM for Intel processors support         [CONFIG_KVM_INTEL]
  &lt;*/M&gt;     KVM for AMD processors support           [CONFIG_KVM_AMD]</literal></screen>

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

<screen><literal>[*] Networking support  ---&gt;                         [CONFIG_NET]
  Networking options  ---&gt;
    &lt;*/M&gt; 802.1d Ethernet Bridging                   [CONFIG_BRIDGE]
Device Drivers  ---&gt;
  [*] Network device support  ---&gt;                   [CONFIG_NETDEVICES]
    &lt;*/M&gt;    Universal TUN/TAP device driver support [CONFIG_TUN]</literal></screen>

  </sect2>

  <sect2 role="installation">
    <title>Installation of qemu</title>

    <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>
      Add any users that might use the KVM device to that 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           \
             --target-list=$QEMU_ARCH    \
             --python=python3            \
             --audio-drv-list=alsa       \
             --docdir=/usr/share/doc/qemu-&qemu-version; &amp;&amp;

unset QEMU_ARCH &amp;&amp;

make</userinput></screen>

    <para>
      To run the built in tests, run <command>make V=1 -k check</command>.
    </para>

    <para>
      Now, as the <systemitem class="username">root</systemitem> user:
    </para>

<screen role="root"><userinput>make install</userinput></screen>

    <para>
      You will also need to add an Udev rule so that the KVM device gets correct
      permissions:
    </para>

<screen role="root"><userinput>cat > /lib/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):
    </para>

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

<!-- Not used anymore
    <para>
      <command>sed ... util/memfd.c</command>: This command fixes a conflict
      introduced with glibc-2.27.
    </para>
-->
    <para>
      <parameter>--python=python3</parameter>: This switch ensures that the
      build and test machinery uses <application>Python 3</application>.
    </para>

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

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

    <para>
      <option>--with-gtkabi=3.0</option>: builds with GTK+-3 if both GTK+-2
      and GTK+-3 are installed.
    </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> must be run from an X Window System based
        terminal (either locally or over ssh).
      </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 ajusted 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            \
     -soundhw 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 formated 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.
    </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>

    <bridgehead renderas="sect3">Controlling the Emulated Display</bridgehead>
    <para>
      It may happen that the guest window displayed by qemu does not correspond
      to the full capability of the emulated vga card. For example, the vmware
      card is 1600x900 capable, but only 1024x768 is displayed by default.
      A suitable Xorg configuration on the guest allows to use the full size
      (Note that the Xorg video driver to use is <xref
      linkend="xorg-vmware-driver"/>):
    </para>

<screen role="root"><userinput>cat &gt; /usr/share/X11/xorg.conf.d/20-vmware.conf &lt;&lt; "EOF"
<literal>Section         "Monitor"
  Identifier    "Monitor0"
  # cvt 1600 900
  # 1600x900 59.95 Hz (CVT 1.44M9) hsync: 55.99 kHz; pclk: 118.25 MHz
  Modeline      "1600x900"  118.25  1600 1696 1856 2112  900 903 908 934 -hsync +vsync
  Option        "PreferredMode" "1600x900"
  HorizSync     1-200
  VertRefresh   1-200
EndSection

Section         "Device"
  Identifier    "VMware SVGA II Adapter"
  Option        "Monitor" "default"
  Driver        "vmware"
EndSection

Section         "Screen"
  Identifier    "Default Screen"
  Device        "VMware SVGA II Adapter"
  Monitor       "Monitor0"

  SubSection    "Display"
    Depth       24
    Modes       "1600x900" "1440x900" "1366x768" "1280x720" "800x480"
  EndSubSection

EndSection</literal>
EOF</userinput></screen>

    <para>
      New sizes will be available besides the native ones. You need to
      restart X in order to have the new sizes available.
    </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>
<!-- Place holder for systemd: bridgeutils page does not have configuration
     information for systemd:
    <para revision="systemd">
      TODO
    </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 command above, replace the switch <parameter>-netdev user,...
      </parameter> with <parameter>-netdev bridge,id=net0</parameter>.
    </para>

  </sect2>

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

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

      <seglistitem>
        <seg>
          ivshmem-client,
          ivshmem-server,
          qemu (symlink),
          qemu-ga,
          qemu-img,
          qemu-io,
          qemu-nbd,
          qemu-system-&lt;arch&gt;, and
          virtfs-proxy-helper
        </seg>
        <seg>None</seg>
        <seg>
          /usr/share/qemu and
          /usr/share/doc/qemu-&qemu-version;
        </seg>
      </seglistitem>
    </segmentedlist>

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

      <varlistentry id="ivshmem-client">
        <term><command>ivshmem-client</command></term>
        <listitem>
          <para>is a standalone client for using the ivshmem device.</para>
          <indexterm zone="qemu ivshmem-client">
            <primary sortas="b-ivshmem-client">ivshmem-client</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="ivshmem-server">
        <term><command>ivshmem-server</command></term>
        <listitem>
          <para>is an example server for the ivshmem device.</para>
          <indexterm zone="qemu ivshmem-server">
            <primary sortas="b-ivshmem-server">ivshmem-server</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-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-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>

      <varlistentry id="virtfs-proxy-helper">
        <term><command>virtfs-proxy-helper</command></term>
        <listitem>
          <para>creates a socket pair or a named socket. QEMU and proxy helper
           communicate using this socket. QEMU proxy fs driver sends
           filesystem request to proxy helper and receives the response
           from it.</para>
          <indexterm zone="qemu virtfs-proxy-helper">
            <primary sortas="b-virtfs-proxy-helper">virtfs-proxy-helper</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>