Getting Started: Ubuntu 16.10 and later

The following instructions assume that we are currently logged in as a regular user.

Install the required packages:
   $ sudo apt install qemu-system-s390x libvirt-bin
Next up, we define a sample guest. We will install Ubuntu 16.10, and use a virtual disk backed by an image file in our host's filesystem. Note that connectivity is required, as the Ubuntu installer needs to download packages from remote.
To do so, create a file ubuntu.xml with the following content:
   <domain type='kvm'>
     <memory unit='GiB'>4</memory>
       <type arch='s390x' machine='s390-ccw-virtio'>hvm</type>
       <disk type='file' device='disk'>
         <driver name='qemu' type='qcow2' io='native' cache='none' iothread='1'/>
         <source file='/var/lib/libvirt/images/ubuntu.img'/>
         <target dev='vda' bus='virtio'/>
       <disk type='file' device='cdrom'>
         <source file='/var/lib/libvirt/images/ubuntu-16.10-server-s390x.iso'/>
         <target dev='sda' bus='scsi'/>
         <boot order='1'/>
       <interface type='bridge'>
         <source bridge='virbr0'/>
         <model type='virtio'/>
       <console type='pty'>
         <target type='sclp'/>
       <memballoon model='none'/> 
Modify the highlighted parts as follows (in sequence):
  • image file: Image file backing your virtual disk. Note that this file is defined in the next step, might grow, and sufficient free space should be available.
  • ISO file: ISO image of the Linux distribution to install in the guest. Could be any Linux distribution supported by the host distro as a guest.
  • Network link: Name of the host's bridge device, which was automatically setup when the add'l packets required for KVM were installed in the first step above.
Create the image file as indicated above:
   $ sudo qemu-img create -f qcow2 /var/lib/libvirt/images/ubuntu.img 8G
   Formatting '/var/lib/libvirt/images/ubuntu.img', fmt=qcow2 size=8589934592
   encryption=off cluster_size=65536 lazy_refcounts=off refcount_bits=16
Add your user to group libvirt:
   $ sudo usermod -a -G libvirt <your_user>
This is required for domain management. Otherwise we would have to run all virsh comands as root using sudo.
Logoff and logon to have the change take effect.
Define the guest and start it (which will boot the ISO image), connecting to the console:
   $ virsh define ubuntu.xml
   $ virsh start --console ubuntu
This will bring up the installer. Make sure to select virtio as the network  interface type on the first screen:
Otherwise, configure to your liking, and complete the guest installation.
Once done, Ubuntu will reboot - and start the whole installation process again from the beginning, as it still tries to boot from the install ISO first.
Therefore, we need to modify the guest definition to boot from its virtual disk rather than the ISO image - or we would be prompted to re-install the guest on each restart.
To do so, stop the guest and bring up its configuration in an editor by running
   $ virsh shutdown ubuntu
   $ virsh edit ubuntu
and either remove the entire <disk> element, or the indicated <boot> element only:
   <disk type='file' device='cdrom'>
     <source file='/var/lib/libvirt/images/ubuntu-16.10-server-s390x.iso'/>
     <target dev='sda' bus='scsi'/>
     <boot order='1'>
Finally, restart the guest: 
   $ virsh start --console ubuntu

For a more detailed explanation of the various options to run KVM on Ubuntu, see here.


  1. Hi, I am working on PCIe SR-IOV. It looks like we are allowed to add a new PCIe device to a running domain in GUI. How do we do this in command line?

    1. Forget to mention, I am using Ubuntu16.04 as host OS. The GuestOS is running Ubuntu18.04.

    2. If you're running on IBM Z, then the host is definitely too old for proper PCI support. You will need at least 18.04 in the host, too. But depending on the GUI you are using, you might still be out of luck, as libvirt support is not present in 18.04.

  2. Hi, Stefan, thanks for your quick response. I am running on a X99 Broadwell Xeon D server. It looks like GUI allow me to add a function to a running VM without any issue. I am wondering if I can do the same thing through command line. Thanks.

    1. Yeah, you could use libvirt (that's what we strictly recommend anyway), or, if you're adventurous, even QEMU directly.
      However, the focus of this blog is strictly IBM Z, so I'd have to refer you to elsewhere for specifics on PCI support for x86, sorry!