Date: Wed, 17 Dec 2008 16:26:21 GMT From: loader <loader@FreeBSD.org> To: murray@FreeBSD.org Cc: freebsd-doc@FreeBSD.org Subject: Re: docs/127923: Please mention qemu in the FreeBSD Handbook Message-ID: <200812171626.mBHGQL0K035212@freefall.freebsd.org> In-Reply-To: <20081215130236.B5E051D703EF@mail.freebsdmall.com> (loader@freebsdmall.com's message of "Mon\, 15 Dec 2008 05\:02\:36 -0800 \(PST\)") References: <200812150128.mBF1Sehd094548@freefall.freebsd.org> <20081215130236.B5E051D703EF@mail.freebsdmall.com>
next in thread | previous in thread | raw e-mail | index | archive | help
--=-=-= loader <loader@freebsdmall.com> wrote: >> http://www.freebsd.org/cgi/query-pr.cgi?pr=127923 And I reworded some parts of Juergen's patch with the help of murray@. --=-=-= Content-Type: text/x-diff Content-Disposition: inline; filename=virtualization.diff Index: chapter.sgml =================================================================== RCS file: /home/ncvs/doc/en_US.ISO8859-1/books/handbook/virtualization/chapter.sgml,v retrieving revision 1.17 diff -u -r1.17 chapter.sgml --- chapter.sgml 28 Jul 2008 14:33:51 -0000 1.17 +++ chapter.sgml 17 Dec 2008 16:13:40 -0000 @@ -54,6 +54,11 @@ virtualization.</para> </listitem> + <listitem> + <para>How to run FreeBSD as guest in <application>qemu</application> + and as a qemu host.</para> + </listitem> + </itemizedlist> <para>Before reading this chapter, you should:</para> @@ -969,6 +974,327 @@ Work is also ongoing in getting <application>&xen;</application> to work as a host environment on FreeBSD.</para> + <sect2 id="virtualization-host-qemu"> + <sect2info> + <authorgroup> + <author> + <firstname>Juergen</firstname> + <surname>Lock</surname> + <contrib>Contributed by </contrib> + </author> + </authorgroup> + </sect2info> + <title><application>QEMU</application> on &os; as Host</title> + + <para><ulink url="http://bellard.org/qemu/">QEMU</ulink>; + is a generic processor emulator using dynamic binary translation + to achieve a reasonable emulation speed.</para> + + <sect3 id="virtualization-host-qemu-installation"> + <title>Installation</title> + + <para>There are two <application>QEMU</application> ports in the &os; + Ports tree at the moment: + <filename role="package">emulators/qemu</filename> + is usually the latest release, and + <filename role="package">emulators/qemu-devel</filename>. + is an svn snapshot. For best results try the latest version + available as a &os; package, or alternatively try the + <filename role="package">emulators/qemu-devel</filename>.</para> + + <para>Install <filename role="package">emulators/qemu-devel</filename> + with the following commands:</para> + + <screen>&prompt.root; <userinput>cd /usr/ports/emulators/qemu-devel</userinput> +&prompt.root; <userinput>make install clean</userinput></screen> + + <para>If the <application>QEMU</application> port is built with the + kqemu knob enabled, load the kqemu kernel module:</para> + + <screen>&prompt.root; <userinput>kldload kqemu</userinput></screen> + + <para>And kqemu can be loaded automatically at boot by adding + the following line to <filename>/etc/rc.conf</filename>:</para> + + <programlisting>kqemu_enable="YES"</programlisting> + + <para>Please make sure the <filename>kqemu.ko</filename> is always in sync + with the kernel like with any kld installed outside of the base. Rebuild + the port <filename role="package">emulators/kqemu-kmod</filename> or + <filename role="package">emulators/kqemu-kmod-devel</filename> + whenever you update the kernel.</para> + + <para><application>QEMU</application> now uses &man.aio.4; at least + for IDE DMA, otherwise <application>QEMU</application> crashes + with <quote>Invalid system call</quote>:</para> + + <screen>&prompt.root; <userinput>kldload aio</userinput></screen> + + <note> + <para>If you want to run <application>QEMU</application> with + <option>-m</option> 512 or larger on &os; 6.3 i386 hosts, + <varname>kern.maxdsiz</varname> needs to be increased in + <filename>/boot/loader.conf</filename> since the default + value is 512 MB, and <application>QEMU</application> needs + memory for itself also. &os; 7.0 and up use jemalloc which uses + &man.mmap.2; and isn't affected by + <varname>kern.maxdsiz</varname> anymore.</para> + </note> + </sect3> + + <sect3 id="virtualization-host-qemu-fbsdguest"> + <title>An example of installing &os; 7.0 as a + <application>QEMU</application> guest</title> + + <para>First, create an empty raw 5 GB image:</para> + + <screen>&prompt.user; <userinput>qemu-img create 7.0.img 5G</userinput></screen> + + <note> + <para>qcow2 is the <application>QEMU</application> image format, + use the <option>-f</option> qcow2 option to avoid sparse files + on the host. Some backup applications like &man.bsdtar.1; don't + support them properly, others like <application>gtar</application> + or <application>star</application> do if passed appropriate flags, + qcow2 format might be slower than raw format.</para> + </note> + + <para>Next, boot sysinstall with the image:</para> + + <screen>&prompt.user; <userinput>qemu -m 256 -cdrom 7.0-RELEASE-i386-disc1.iso -hda 7.0.img -boot d -monitor stdio</userinput></screen> + + <note> + <para>You need to run <command>qemu-system-x86_64</command> + if you want to emulate a amd64 guest.</para> + </note> + + <para>Now follow the instructions in <xref linkend="install"> like + as if you would install a real machine using CD media. + Click into the guest window to access the guest mouse pointer + and hit <keycombo action="simul"><keycap>Alt</keycap> + <keycap>Ctrl</keycap></keycombo> to leave the guest window + mouse grab. If you use the default usermode networking (aka slirp) + like in the above example the guest should have network if you + configure it to use DHCP, so if you want you could probably + also use a bootonly iso instead of disc1 and do a network install. + (&man.ping.8; doesn't work with slirp though.)</para> + + <para>When finished, select <quote>exit install</quote> in sysinstall to reboot, + and when the guest booting the ISO again, type + <command>q</command> in <application>QEMU</application>'s monitor or + <command>killall</command> qemu on another host shell if you are + using <option>-curses</option>, like when you have no X11 on the + host.</para> + + <para>Now, boot the installed image:</para> + + <screen>&prompt.user; <userinput>qemu -m 256 -cdrom 7.0-RELEASE-i386-disc1.iso -hda 7.0.img -boot c -monitor stdio</userinput></screen> + + <para>Now you should see a normal boot like on a freshly installed + box, all the way up to your first login prompt. If you plan to + use this guest with <option>-nographic</option> later on, + now is the time to configure it for a serial console in the guest:</para> + + <screen>&prompt.root; <userinput>echo console=\"comconsole\" >>/boot/loader.conf</userinput> +&prompt.root; <userinput>sed -i -e '/^ttyu0/s/off/on/' /etc/ttys</userinput></screen> + + <para>As always with virtualization, lowering <varname>kern.hz</varname> + helps performance also with <application>QEMU</application>:</para> + + <screen>&prompt.root; <userinput>echo kern.hz=100 >>/boot/loader.conf</userinput></screen> + + <para>When you are finished with the guest, shut it down, this should + make <application>QEMU</application> quit gracefully:</para> + + <screen>&prompt.root; <userinput>shutdown -p now</userinput></screen> + + <para>If the serial console is configured, now you can boot the + guest with <option>-nographic</option>:</para> + + <screen>&prompt.user; <userinput>qemu -m 256 -hda 7.0.img -boot c -nographic</userinput></screen> + + <para>With <option>-nographic</option>, the guest console and + <application>QEMU</application>'s monitor are multiplexed on + <application>QEMU</application>'s tty, hit + <keycombo action="simul"><keycap>Ctrl</keycap> + <keycap>a</keycap></keycombo> and then + <keycap>h</keycap> to show a small help.</para> + + <note> + <para>Qemu can emulate several different mode of network card, + try <option>pcnet</option>, <option>i82557b</option> + or <option>e1000</option>, they should be faster + and use less guest <acronym>CPU</acronym> than the + default <option>ne2kpci</option>.</para> + + <para>With the <option>-vnc</option> <replaceable>display</replaceable> + option, <application>QEMU</application> will listen on + <acronym>VNC</acronym> display <replaceable>display</replaceable> + and redirect the <acronym>VGA</acronym> display over the + <acronym>VNC</acronym> session. If the host or + <application>QEMU</application> build lacks X11 and + <option>-nographic</option> or <option>-curses</option> + is not an available option. <option>-vnc</option> works best with + an en-us keymap on the host. + Use the port <filename role="package">net/tightvnc</filename> + with <application>QEMU</application>. The X keymap on the host + can be changed temporarily using <command>setxkbmap</command>, + see the manual pages for more information.</para> + </note> + </sect3> + + <sect3 id="virtualization-host-qemu-linuxguest"> + <title>&linux; guest examples</title> + + <para>As an example, we run the well known <ulink + url="http://knoppix.net">Knoppix</ulink>; &linux; live-CD/DVD in qemu:</para> + + <screen>&prompt.user; <userinput>qemu -m 256 -cdrom KNOPPIX_V5.3.1DVD-2008-03-26-EN.iso -boot d -monitor stdio -soundhw es1370</userinput></screen> + + <para>In this example we launched <application>QEMU</application> + with an ES1370 sound card enabled for the guest OS.</para> + + <para>Click into the guest window to access the guest + mouse pointer and hit <keycombo action="simul"><keycap>Alt</keycap> + <keycap>Ctrl</keycap></keycombo> to leave the guest window + mouse grab.</para> + + <note> + <para>Debian/Ubuntu (and their offsprings) have a record of + shipping partially broken <application>QEMU</application> + bioses, so if you have problems using a packaged + <application>QEMU</application> these distros also try + using the bios found in that <application>QEMU</application> + version's source tarball (<filename>pc-bios/bios.bin</filename> + in there) instead of the one installed by your distro + package.</para> + </note> + </sect3> + + <sect3 id="virtualization-host-qemu-tuntap"> + <title>Simple Example for using <application>QEMU</application> + tuntap networking on &os; Hosts</title> + + <para>In cases where you want a <application>QEMU</application> + guest to appear as a seperate (virtual) host on your network, + or when you are on an amd64 host where the default usermode + networking doesn't quite work, or when you are simply concerned + about virtual network performance, you may want to use tuntap + networking.</para> + + <para>The idea here is to have <application>QEMU</application> + talk to a &man.tap.4; interface, which bridge with your host's + physical interface, and that <application>QEMU</application> + then passes the traffic of the emulated NIC that the guest + uses on. Since you don't want to run <application>QEMU</application> + as root you first need to setup permissions on the tap device in + &man.devfs.conf.5; so that <application>QEMU</application> + running as your user can acess it. For example add:</para> + + <programlisting>own tap0 <replaceable><username or uid></replaceable></programlisting> + + <para>Next figure out two IPs in an unused sub-subnet of your + host's network, one for the tap interface and the other for the + guest (this is important so the host itself can talk to the guest's + emulated nic properly), and then edit qemu's tuntap setup script + that gets executed after qemu opens a tap device, + <filename>/usr/local/etc/qemu-ifup</filename> to read something + like this:</para> + + <programlisting>#!/bin/sh +sudo /sbin/ifconfig $1 <replaceable><IP for the tap interface></replaceable> netmask <replaceable><sub-subnet's netmask></replaceable> +case "`/sbin/ifconfig bridge0`" in + *" $1 "*) ;; # already in the bridge + *) sudo /sbin/ifconfig bridge0 addm $1 ;; +esac</programlisting> + + <para>sudo is in ports as + <filename role="package">security/sudo</filename>, if your user + is in the wheel group you can add the following line to + <filename>/usr/local/etc/sudoers</filename>:</para> + + <programlisting>%wheel ALL=/sbin/ifconfig</programlisting> + + <para>Then load the kernel modules <filename>if_tap.ko</filename> and + <filename>if_bridge.ko</filename>, restart devfs, set the + <varname>net.link.tap.user_open</varname> sysctl, create + the bridge and add your host's physical interface to it:</para> + + <screen>&prompt.root; <userinput>kldload if_tap if_bridge</userinput> +&prompt.root; <userinput>/etc/rc.d/devfs restart</userinput> +&prompt.root; <userinput>sysctl net.link.tap.user_open=1</userinput> +&prompt.root; <userinput>ifconfig bridge0 create</userinput> +&prompt.root; <userinput>ifconfig bridge0 addm <replaceable><host's physical interface></replaceable> up</userinput></screen> + + <para>Now start the <application>QEMU</application>:</para> + + <screen>&prompt.user; <userinput>qemu -m 256 -hda guest.img -boot c -net nic -net tap,ifname=tap0</userinput></screen> + + <para>Then configure the NIC in the guest like + other hosts on your physical network.</para> + + <note> + <para>If you have more than one <application>QEMU</application> + guest on a network you need to make sure they use different + MAC addresses, the MAC address can be set via + <option>-net nic,macaddr</option>.</para> + </note> + + <para>To make the settings permanent, add the following lines + in <filename>/boot/loader.conf</filename>:</para> + + <programlisting>if_tap_load="YES" +if_bridge_load="YES"</programlisting> + + <para>Add the following line in <filename>/etc/sysctl.conf</filename>:</para> + + <programlisting>net.link.tap.user_open=1</programlisting> + + <para>And add the bridge configuration in <filename>/etc/rc.conf</filename>:</para> + + <programlisting>cloned_interfaces="bridge0" +ifconfig_bridge0="addm <replaceable><host's physical interface></replaceable> up"</programlisting> + </sect3> + + <sect3 id="virtualization-host-qemu-help"> + <title>User Documentation and Resources</title> + + <para>The <application>QEMU</application> package + includes qemu(1) man page and the following locally installed html + documents:</para> + + <itemizedlist> + <listitem><para><filename>/usr/local/share/doc/qemu/qemu-doc.html</filename></para></listitem> + <listitem><para><filename>/usr/local/share/doc/qemu/qemu-tech.html</filename></para></listitem> + </itemizedlist> + + <para>Places to check other than the official documentation:</para> + + <itemizedlist> + <listitem> + <para><filename role="package">emulators/qemu-devel</filename> + <ulink url="http://www.freebsd.org/cgi/cvsweb.cgi/ports/emulators/qemu-devel/pkg-message">; + pkg-message</ulink></para> + </listitem> + <listitem> + <para>The <ulink + url="http://lists.freebsd.org/pipermail/freebsd-emulation/">; + freebsd-emulation mailing list archive</ulink>.</para> + </listitem> + <listitem> + <para>The <ulink + url="http://qemu-forum.ipi.fi/">; + qemu forum</ulink> + has howtos, patches, and code snapshots. Note, however + that the qemu sources won't build on &os; without some changes.</para> + </listitem> + <listitem> + <para>The <ulink + url="http://lists.gnu.org/archive/html/qemu-devel/">; + qemu-devel mailing list archive</ulink>.</para> + </listitem> + </itemizedlist> + </sect2> </sect1> </chapter> --=-=-=--
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200812171626.mBHGQL0K035212>