====
QEMU
====

QEMU is a versatile piece of software that has lots of different use cases. Here are some common configurations to (manually...) check.

Emulation mode:
 * throw-away, user-mode/non-accelerated emulation -- `here are some images <https://people.debian.org/~gio/dqib/>`_
 * KVM guest (incompatible with Xen)
 * Xen HVM guest

User interfaces:
 * virt-manager/libvirt
 * gnome-boxes
 * ProxMox is Debian-based and would be a good test case, but they ship their own modified qemu version
 * Xen *xl* CLI

Guest systems:
 * GNU/Linux
 * Windows: trial versions of Windows Server ISOs are easily available; pre-installed VMs are also available through modern.ie,
   with a `conversion script <https://github.com/lentinj/ie-vm>`_; 2012R2 is known to crash with Xen HVM on first boot (Jessie)

Networking card:
 * basic Ethernet emulation
 * VirtIO networking (accelerated)

Networking attachment:
 * slirp user-mode networking (NAT)
 * bridge
 * ...

Disk types:
 * IDE, SCSI emulation (non-accelerated)
 * VirtIO disk (accelerated, may require `drivers ISO <https://www.linux-kvm.org/page/WindowsGuestDrivers/Download_Drivers>`_)
 * iSCSI client/initiator (you can install `tgt <https://packages.debian.org/tgt>`_ on a separate box for a test server/target, and *qemu-block-extra*
 * `VirtIO crypto <https://wiki.qemu.org/Features/VirtioCrypto#Testing>`_

Graphic access:
 * SDL (direct window)
 * VNC (e.g. with vncviewer)
 * Spice (e.g. with virt-manager)

----------------------------
Network Block Device support
----------------------------

QEMU ships a server that makes it possible to export a QEMU disk via NBD.

.. code:: sh

  modprobe nbd
  qemu-nbd -v -f qcow2 <image.qcow2>
  nbd-client localhost

Then mount and test the export.

NBD also support TLS:


.. code:: sh

    mkdir -p $HOME/.pki/qemu

    certtool --generate-privkey >  $HOME/.pki/qemu/ca-key.pem

    cat > $HOME/.pki/qemu/ca.info <<EOF
    cn = Debian
    ca
    cert_signing_key
    EOF

    certtool --generate-self-signed \
           --load-privkey $HOME/.pki/qemu/ca-key.pem \
           --template $HOME/.pki/qemu/ca.info \
           --outfile $HOME/.pki/qemu/ca-cert.pem


Create a certificate that can be used by a server and a client:

.. code:: sh

    cd $HOME/.pki/qemu

    cat > both-host.info <<EOF
    country = GB
    state = London
    locality = City Of London
    organization = Name of your organization
    cn = host.foo.example.com
    dns_name = host
    dns_name = host.foo.example.com
    ip_address = 127.0.0.1
    ip_address = 192.168.122.1
    ip_address = 2001:db8:cafe::2
    tls_www_server
    tls_www_client
    encryption_key
    signing_key
    EOF

    certtool --generate-privkey > both-host-key.pem

    certtool --generate-certificate \
               --load-ca-certificate ca-cert.pem \
               --load-ca-privkey ca-key.pem \
               --load-privkey both-host-key.pem \
               --template both-host.info \
               --outfile both-host-cert.pem

    ln -s both-host-cert.pem server-cert.pem
    ln -s both-host-key.pem server-key.pem

    ln -s both-host-cert.pem client-cert.pem
    ln -s both-host-key.pem client-key.pem

Start the server:

.. code:: sh

    qemu-nbd \
      --object tls-creds-x509,id=tls0,endpoint=server,dir=$HOME/.pki/qemu/ \
      --object 'authz-simple,id=auth0,identity=CN=host.foo.example.com,,O=Name of your organization,,L=City Of London,,ST=London,,C=GB' \
      --tls-creds tls0 --tls-authz auth0 \
      -t -p 10810 -v \
      -f qcow2 <image.qcow2>

    nbd-client localhost 10810 /dev/nbd0 -cacertfile $HOME/.pki/qemu/ca-cert.pem -certfile $HOME/.pki/qemu/client-cert.pem -keyfile $HOME/.pki/qemu/client-key.pem

The disk should be available on `/dev/nbd0pX`

-------------------
QEMU User Emulation
-------------------

QEMU makes it possible to run packages for incompatible architectures. QEMU
User Emulation is documented at the Debian
`QemuUserEmulation <https://wiki.debian.org/QemuUserEmulation>`_ wiki page.

-------------
Common issues
-------------

Make sure you reserve enough memory (``-m``). QEMU's default is 128M
but running the Debian Installer ISO plain panics with that amount
(512M only gets you buster's "low-memory" mode).

----------
ASAN build
----------

:doc:`ASan <../../howtos/lts-Development-Asan>` doesn't support static builds, so in addition to the *DEB_*FLAGS_APPEND* drop qemu-user/qemu-user-static from *debian/control* and *debian/control-in* before building.


| Copyright (C) 2019, 2020, 2021, 2022, 2023  Sylvain Beucler