Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision		 Previous revision
docs:guide-user:virtualization:qemu_host [2018/06/03 15:45] – [Running a guest] added link to basic-networking sebastiandocs:guide-user:virtualization:qemu_host [2022/05/30 09:04] (current) – [Download installer files] use https sebastian
Line 1: Line 1:
-====== Running QEMU guests on OpenWrt ======+====== OpenWrt as QEMU/KVM host server ======
  
 ===== Introduction ===== ===== Introduction =====
-It's possible to use OpenWrt as a QEMU host and run guests on it. If you want to run OpenWrt as a QEMU guest, see [[docs:guide-user:virtualization:qemu|OpenWrt in QEMU]]. +It's possible to use OpenWrt as a QEMU host and run guests on it. If you want to run OpenWrt as a QEMU guest itself, see [[docs:guide-user:virtualization:qemu|OpenWrt in QEMU]].
- +
-OpenWrt provides QEMU packages for ARM and x86 platforms. This article focuses on the x86 target, the networking is done via ''qemu-bridge-helper''+
  
 +OpenWrt provides QEMU packages for ARM and x86 platforms. This article focuses on the x86 target, the networking is done via [[https://wiki.qemu.org/Features/HelperNetworking|qemu-bridge-helper]].
 ===== Installing QEMU ===== ===== Installing QEMU =====
-You need the following packages on your device: ''kmod-tun qemu-bridge-helper qemu-x86_64-softmmu''. If your hardware supports it, also install ''kmod-kvm-amd'' or ''kmod-kvm-intel'' for better performance.+You need the following packages on your device: [[packages:pkgdata:kmod-tun|kmod-tun]], [[packages:pkgdata:qemu-bridge-helper|qemu-bridge-helper]]. Depending on the guest architecture, install [[packages:pkgdata:qemu-x86_64-softmmu|qemu-x86_64-softmmu]] or [[packages:pkgdata:qemu-arm-softmmu|qemu-arm-softmmu]]. If your hardware supports it, also install [[packages:pkgdata:kmod-kvm-amd|kmod-kvm-amd]] or [[packages:pkgdata:kmod-kvm-intel|kmod-kvm-intel]] for better performance.
  
-Example for an Intel system:+Example for an Intel system and a x86_64 guest:
 <code> <code>
 opkg install kmod-tun qemu-bridge-helper qemu-x86_64-softmmu kmod-kvm-intel opkg install kmod-tun qemu-bridge-helper qemu-x86_64-softmmu kmod-kvm-intel
Line 16: Line 15:
  
 ===== Running a guest ===== ===== Running a guest =====
-For the guest operation system, use a distribution that comes with virtio drivers by default (Debian or Fedora for example). There are several guides available on how to install a Linux distribution inside a QEMU image: [[https://wiki.debian.org/QEMU#Setting_up_a_stable_system|Debian]]+For the guest OS, use a distribution that comes with virtio drivers by default (Debian or Fedora for example).
  
-The following QEMU command uses a physical disk, but you can use a qcow2 image as well. Below are explanations of the networking options.+The following QEMU command uses a physical disk, but you can use a disk image as well. Below are explanations of the networking options.
 <code bash> <code bash>
 qemu-system-x86_64 -enable-kvm -cpu host -smp 2 -m 2G \ qemu-system-x86_64 -enable-kvm -cpu host -smp 2 -m 2G \
Line 26: Line 25:
 </code> </code>
  
-**Line 3** creates a virtio net device with a fixed MAC address and is told to use the network backend with ''id=br0'', which gets created in **line 4**. The network backend is of type ''bridge'' and ''br=br-lan'' tells QEMU to connect to the bridge network ''br-lan'' of the OpenWrt host. For that ''qemu-bridge-helper'' will automatically create the needed TUN/TAP interfaces.+**Line 3** creates a virtio net device with a fixed MAC address that is told to use the network backend with ''id=br0'', which gets created in **line 4**. The network backend is of type ''bridge'' and ''br=br-lan'' tells QEMU to connect to the bridge network ''br-lan'' of the OpenWrt host. For that ''qemu-bridge-helper'' will automatically create the needed TUN/TAP interfaces.
 If your guest uses DHCP it should now receive an address by the server running in ''br-lan''. If your guest uses DHCP it should now receive an address by the server running in ''br-lan''.
  
 You can choose any other bridge interface available on your OpenWrt host as well. See [[docs:guide-user:base-system:basic-networking|Network basics]] on how to configure networking interfaces. You can choose any other bridge interface available on your OpenWrt host as well. See [[docs:guide-user:base-system:basic-networking|Network basics]] on how to configure networking interfaces.
 +If you want to change which networks QEMU is allowed to connect to, you can do so via ''/etc/qemu/bridge.conf''.
  
-===== Init script =====+===== Installing Debian as guest OS ===== 
 +If you don't have a prepared disk image, you can install a guest OS directly on your OpenWrt device. There are several guides available on how to install a Linux distribution on a QEMU image: [[https://wiki.debian.org/QEMU#Setting_up_a_stable_system|Debian]] for example. 
 + A quick way is to install Debian using the kernel and initrd of a Debian netboot installer. 
 +==== Create a disk image ==== 
 +<code bash> 
 +qemu-img create -f qcow2 debian.img 4G 
 +</code> 
 +More details on disk images: [[https://en.wikibooks.org/wiki/QEMU/Images]]
  
-To automatically start the VM at boot and shut it down cleanly using [[https://wiki.qemu.org/Documentation/QMP|QMP]], create an [[docs:techref:initscripts|init script]] like the following:+==== Download installer files ==== 
 +<code bash> 
 +wget https://ftp.debian.org/debian/dists/stable/main/installer-amd64/current/images/netboot/debian-installer/amd64/linux 
 +wget https://ftp.debian.org/debian/dists/stable/main/installer-amd64/current/images/netboot/debian-installer/amd64/initrd.gz 
 +</code> 
 +Both files can be savely removed after finishing the installation. 
 + 
 +==== Run the installer ==== 
 +The following command will launch the Debian installer inside QEMU, ''debian.img'' will appear as ''/dev/vda'' 
 +<code bash> 
 +qemu-system-x86_64 -enable-kvm -cpu host -smp 2 -m 2G \ 
 + -initrd initrd.gz \ 
 + -kernel linux \ 
 + -append "root=/dev/ram console=ttyS0" \ 
 + -drive file=debian.img,if=virtio \ 
 + -device virtio-net-pci,mac=E2:F2:6A:01:9D:C9,netdev=br0 \ 
 + -netdev bridge,br=br-lan,id=br0 \ 
 + -nographic 
 +</code> 
 +Follow the installation instructions and install GRUB on ''/dev/vda''. It's also useful to install sshd (enabled by default). 
 + 
 +==== Run the new guest ==== 
 +After finishing the installation, you can launch the new installation with QEMU: 
 +<code bash> 
 +qemu-system-x86_64 -enable-kvm -cpu host -smp 2 -m 2G \ 
 + -drive file=debian.img,if=virtio \ 
 + -device virtio-net-pci,mac=E2:F2:6A:01:9D:C9,netdev=br0 \ 
 + -netdev bridge,br=br-lan,id=br0 \ 
 + -nographic 
 +</code> 
 +You should now be able to reach the VM via SSH from within ''br-lan''. 
 +If you want to control the VM using the command line, you have to enable a serial console. To do this, edit the GRUB entry during boot and add ''console=ttyS0'' to the kernel command line. After the VM finished booting, edit ''/etc/default/grub'' and add ''console=ttyS0'' to ''GRUB_CMDLINE_LINUX_DEFAULT'' as well. After that run ''update-grub''. 
 + 
 +===== Init script ===== 
 +To automatically start the VM at boot and shut it down cleanly using [[https://wiki.qemu.org/Documentation/QMP|QMP]], create an [[docs:techref:initscripts|init script]] like the one below. 
 +<WRAP center round important 60%> 
 +Be careful with copying the heredoc part. This code block is left unindented on purpose to avoid problems with whitespaces. If you want, you can indent the lines with tabs and use ''%%<<-%%QMP'' instead of ''%%<<%%QMP'', but since tabs are printed as whitespaces in dokuwiki code blocks, this example is used without indentation. You can read more about here documents in the [[http://tldp.org/LDP/abs/html/here-docs.html|advanced bash-scripting guide]] 
 +</WRAP>
  
 <code bash /etc/init.d/qemu> <code bash /etc/init.d/qemu>
Line 40: Line 84:
 START=99 START=99
 STOP=1 STOP=1
 +
 +qemu_pidfile="/var/run/qemu.pid"
  
 start() { start() {
 qemu-system-x86_64 -enable-kvm -cpu host -smp 2 -m 2G \ qemu-system-x86_64 -enable-kvm -cpu host -smp 2 -m 2G \
-    -drive file=/dev/sda,cache=none,if=virtio,format=raw \ + -drive file=/dev/sda,cache=none,if=virtio,format=raw \ 
-    -device virtio-net-pci,mac=E2:F2:6A:01:9D:C9,netdev=br0 \ + -device virtio-net-pci,mac=E2:F2:6A:01:9D:C9,netdev=br0 \ 
-    -netdev bridge,br=br-lan,id=br0 \ + -netdev bridge,br=br-lan,id=br0 \ 
-    -qmp tcp:127.0.0.1:4444,server,nowait \ + -qmp tcp:127.0.0.1:4444,server,nowait \ 
-    -daemonize &> /var/log/qemu.log+ -daemonize &> /var/log/qemu.log 
 + 
 +/usr/bin/pgrep qemu-system-x86_64 > $qemu_pidfile 
 +echo "QEMU: Started VM with PID $(cat $qemu_pidfile)."
 } }
  
 stop() { stop() {
 +echo "QEMU: Sending 'system_powerdown' to VM with PID $(cat $qemu_pidfile)."
 nc localhost 4444 <<QMP  nc localhost 4444 <<QMP 
-{ "execute": "qmp_capabilities" } +{ "execute": "qmp_capabilities" }  
-{ "execute": "system_powerdown" }+{ "execute": "system_powerdown" } 
 QMP QMP
  
-sleep 10s+if [ -e $qemu_pidfile ]; then 
 + if [ -e /proc/$(cat $qemu_pidfile) ]; then 
 + echo "QEMU: Waiting for VM shutdown." 
 + while [ -e /proc/$(cat $qemu_pidfile) ]; do sleep 1s; done 
 + echo "QEMU: VM Process $(cat $qemu_pidfile) finished." 
 + else 
 + echo "QEMU: Error: No VM with PID $(cat $qemu_pidfile) running." 
 + fi 
 + 
 + rm -f $qemu_pidfile 
 +else 
 + echo "QEMU: Error: $qemu_pidfile doesn't exist." 
 +fi
 } }
 </code> </code>
-FIXME This script currently uses a fixed time of 10 seconds to wait for the VM shutdown. Provide a better way to wait for the qemu process to finish 
  
 Test the the script by running ''/etc/init.d/qemu start'' and look for errors in ''/var/log/qemu.log''. Test the the script by running ''/etc/init.d/qemu start'' and look for errors in ''/var/log/qemu.log''.
 If the script works as desired, enable it for every boot: ''/etc/init.d/qemu enable'' If the script works as desired, enable it for every boot: ''/etc/init.d/qemu enable''
 +
 +FIXME This script needs to be ported to [[:docs:guide-developer:procd-init-scripts|procd]]. Problem: [[:docs:guide-developer:procd-init-scripts#stopping_services|stop_service() is called after procd killed the service]], but we must run it beforehand to let the VM shut down.
  • Last modified: 2018/06/03 15:45
  • by sebastian