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>&lt;username or uid&gt;</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>&lt;IP for the tap interface&gt;</replaceable> netmask <replaceable>&lt;sub-subnet's netmask&gt;</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>&lt;host's physical interface&gt;</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>&lt;host's physical interface&gt;</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>
