README for OpenBSD users
------------------------

==> Quick Start

1. get a bootable floppy image
2. qemu-img create -f qcow2 virtual.hd 10G
3. qemu -m 32 -fda floppy.fs -boot a -monitor stdio virtual.hd
     (initial install to hard drive)
4. qemu-img convert -c -O qcow2 virtual.hd tmp && mv tmp virtual.hd
     (compress hard drive while qemu is not running)
5. qemu -m 32 -monitor stdio virtual.hd
     (normal boot from hard drive)


==> Networking

1.  Default Settings

  By default, qemu sets up the equivalent of the following networking:

	-net nic,vlan=0,model=ne2k_pci,macaddr=52:54:00:12:34:56
	-net user,vlan=0

  Also, inside this virtual usermode network, it uses the 10.0.2.0/24 and
  serves dhcp from inside this virtual network.  Static address can be used
  if one cannot or does not want to do dhcp in the guest os:

	Guest OS IP     : 10.0.2.15
	Default Gateway : 10.0.2.2
	Nameserver      : 10.0.2.3

  It is sufficient for most operations, qemu itself performs NAT and then
  makes userland network calls for tcp/udp operations. icmp and other things
  are not possible in this mode.

  It is recommended to use this if at all possible, because other options
  involve running qemu as root.

  Note: If you use one '-net' cmdline argument, qemu assumes you know what you
  want and clears defaults for the rest of the -net defaults.

  Note: The guest mode networking does not currently support IPv6, and
  qemu will complain that it cannot find a dns server if /etc/resolv.conf
  contains only IPv6 dns servers.


2.  tap mode

  Sometimes it is desirable to configure qemu to access a network via layer2
  directly.  This has the side effect that currently it requires root
  privileges to open and configure /dev/tunN.  There is no way to drop from
  root privileges at this point.

  %SYSCONFDIR%/qemu-ifup contains some default settings that permit one to do
  the following:

	# qemu -net nic -net tap virtual.hd

  It presumes you have a 'trunk0' interface you wish the tun(4) interface to
  talk to.  It presumes you want 'bridge0' to be used to bridge the two.

  If you wish to over-ride these settings, setting the environment variables
  ETHER and BRIDGE will over-ride these settings, respectively.

  When starting qemu, the script attempts to output useful information, but
  there are also error messages that occur as well.  On my laptop, I want to
  route / nat natively using pf and also have layer2 access to the qemu
  networks.  I thus have this as /etc/hostname.trunk101:

	inet6 fe80::1c 64 lladdr 00:03:25:0d:7a:2c
	inet 10.7.255.1 255.255.255.0
	inet6 alias 2001:240:58a:45::1c

  I have dhcpd configured to run on trunk101, and also run rtadvd.  For qemu,
  the startup looks like this:

   # export ETHER=trunk101
   # export BRIDGE=bridge101
   # qemu -net nic,vlan=0,model=rtl8139,macaddr=52:54:00:12:35:00 \
	-net tap,vlan=0 -vnc :0 -localtime -usb -usbdevice tablet \
	-m 256 -hda virtual.hd -monitor stdio
   {tun0 (bridge101 <-> trunk101)brconfig: bridge101: No such process
   brconfig: bridge101: No such process
   }
   (qemu)

  The errors are normal and should be ignored.  One can verify the networking
  is properly configured by verifying the bridge interface:

   $ brconfig bridge101
   bridge101: flags=41<UP,RUNNING>
        priority 32768 hellotime 2 fwddelay 15 maxage 20 holdcnt 6 proto rstp
        designated: id 00:00:00:00:00:00 priority 0
        tun0 flags=3<LEARNING,DISCOVER>
                port 16 ifpriority 0 ifcost 0
        trunk101 flags=3<LEARNING,DISCOVER>
                port 6 ifpriority 0 ifcost 0
        Addresses (max cache: 100, timeout: 240):

  Note: when running multiple qemu sessions simultaneously on the same bridge,
  care must be taken because the network mac address defaults
  to 52:54:00:12:34:56 for every qemu instance.  To change this, observe
  the macaddr= syntax in the above example.

==> Mice

  Note: Certain m$ os's work so much better with the tablet usb device than
  the normal ps2 mouse handling.  See the above example for usage.

==> Serial Console

  1. Installing OpenBSD via serial console is sometimes desirable.  X may not
     be available, and so on.  There are two ways to accomplish this, both in
     effect the same solution:

    a. qemu -vnc :0 -serial stdio .. virtual.hd -cdrom install43.iso -boot d

	- this option permits you to use vnc from some system to connect to
	  the qemu instance and 'set tty com0' at the 'boot>' prompt.
	- you may then disconnect vnc and use the terminal from which you
	  started qemu to do the install

    b. qemu -nographic .. virtual.hd -fda floppy43.fs -boot a

	- this maps both the serial port and the (qemu) monitor prompt to
	  the terminal qemu was started on
        - to flip between them, Ctrl-a c; see the qemu man page for other
          commands that work in -nographic mode.
	- preparation of the floppy image to force serial console mode is
	  straightforward:

		vnconfig svnd0 floppy43.fs
		mount /dev/svnd0c /mnt
		mkdir /mnt/etc
		echo set tty com0 > /mnt/etc/boot.conf
		umount /mnt
		vnconfig -u svnd0

     .. be sure to choose 'yes' for setting com0 to be the serial console.

   Note: OpenBSD poweroff does work with qemu, which actually causes qemu
   itself to exit.  This is a good thing, as it is currently not possible to
   set what block device is booted from at runtime from qemu.  So if you start
   an installation booting from a cdrom, you will always boot off a cdrom
   every time you reboot that qemu session until you exit and start qemu
   again booting off the virtual hard drive.

==> daemonized qemu

   Sometimes you want qemu to start as part of a system script.

   Adding to some of the above, the -daemonize option comes in handy,
   as well as the telnet: designator for -serial and monitor.  This
   is a complete example that may be cut-and-pasted into rc.local:

    hddir=/var/vm
    if [ -x /usr/local/bin/qemu ]; then
        echo -n 'Qemu: vmi386'
        (
            export ETHER=trunk101
            export BRIDGE=bridge101

            /usr/local/bin/qemu \
                -daemonize \
                -nographic \
                -net nic,vlan=0,model=rtl8139,macaddr=52:54:00:4e:62:8f \
                -net tap,vlan=0 \
                -m 128 \
                -hda $hddir/vmi386.hd \
                -serial telnet:127.0.0.1:1010,server,nowait \
                -monitor telnet:127.0.0.1:1011,server,nowait
        )
        echo "."
    fi

