network setup mods to Xen HOWTO

["Johnny C. Lam" <jlam%pkgsrc.org@localhost>]

I'd like to change the Xen 2.0 HOWTO on the NetBSD website to describe
how to configure guest domains in a bridged-network configuration
instead of a routed-network configuration.  There are several reasons
for this:

(1) The existing instructions in the HOWTO are a bit confusing because
    it constantly refers to scripts with "bridge" in there name and
    parameters named "bridge", and yet it isn't setting up a
    bridged-network configuration.

(2) The bridged-network configuration is simpler to understand and
    set up for a novice because the guest domains are essentially
    "peers" on the same network as domain0.

(3) This also avoids needing any special routing or NAT configuration
    in domain0.

I've also made some minor changes by improving the documentation in
the comments of the example domain configuration file, showing how to
specify a file to be used for a file-backed domain, and by including
the vif-bridge script from the latest PKGREVISION of the
sysutils/xentools20 package.

I'll likely be making additions and other modifications to the HOWTO
as I prepare for an upcoming talk I'm giving about Xen for NYCBUG,
and I'll post my proposed changes here in the coming weeks -- I would
like eventually to fold the HOWTO into the NetBSD Guide.

        Cheers,

        -- Johnny Lam <jlam%pkgsrc.org@localhost>

Index: howto.xml
===================================================================
RCS file: /cvsroot/htdocs/Ports/xen/howto.xml,v
retrieving revision 1.21
diff -u -r1.21 howto.xml
--- howto.xml   28 Aug 2005 23:25:33 -0000      1.21
+++ howto.xml   8 Nov 2005 01:05:07 -0000
@@ -244,44 +244,64 @@
 memory = 128
 
 # A handy name for your new domain. This will appear in 'xm list',
-# and you can use this as parameters for xm in place of the domain number.
+# and you can use this as parameters for xm in place of the domain
+# number. All domains must have different names.
+#
 name = "nbsd"
 
-# Which CPU to start domain on (only relevant for SMP hardware)
+# Which CPU to start domain on (only relevant for SMP hardware).  CPUs
+# numbered starting from ``0''.
+#
 cpu = -1   # leave to Xen to pick
 
 #----------------------------------------------------------------------------
 # Define network interfaces for the new domain.
 
-# Number of network interfaces. Default is 1.
+# Number of network interfaces (must be at least 1). Default is 1.
 nics=1
 
-# Optionally define mac and/or bridge for the network interfaces.
-# Random MACs are assigned if not given.
-# The MAC address specified is the one used for the interface in the new
-# domain. The interface in domain0 will use this address xor'd with
-# 00:00:00:01:00:00 (i.e. aa:00:00:51:02:f0 in our example)
-# bridge is a required parameter, which will be passed to the vif script
-# called by xend when a new domain is created to configure the new
-# xvif interface in domain0. We can pass any information here.
-# In our example, the xvif won't be added to a bridge, but configured with a
-# private address. Pass the ifconfig line which will be used by the script
-# here instead.
-vif = [ 'mac=aa:00:00:50:02:f0, bridge=10.0.0.254 netmask 255.255.255.0' ]
+# Define MAC and/or bridge for the network interfaces.
+#
+# The MAC address specified in ``mac'' is the one used for the interface
+# in the new domain. The interface in domain0 will use this address XOR'd
+# with 00:00:00:01:00:00 (i.e. aa:00:00:51:02:f0 in our example). Random
+# MACs are assigned if not given.
+#
+# ``bridge'' is a required parameter, which will be passed to the
+# vif-script called by xend(8) when a new domain is created to configure
+# the new xvif interface in domain0.
+#
+# In this example, the xvif is added to bridge0, which should have been
+# set up prior to the new domain being created -- either in the
+# ``network'' script or using a /etc/ifconfig.bridge0 file.
+#
+vif = [ 'mac=aa:00:00:50:02:f0, bridge=bridge0' ]
 
 #----------------------------------------------------------------------------
 # Define the disk devices you want the domain to have access to, and
 # what you want them accessible as.
-# Each disk entry is of the form phy:DEV,VDEV,MODE
+#
+# Each disk entry is of the form:
+#
+#      phy:DEV,VDEV,MODE
+#
 # where DEV is the device, VDEV is the device name the domain will see,
-# and MODE is r for read-only, w for read-write.
-# VDEV doesn't really matter for NetBSD guest OS, but does for Linux.
+# and MODE is r for read-only, w for read-write.  You can also create
+# file-backed domains using disk entries of the form:
+#
+#      file:PATH,VDEV,MODE
+#
+# where PATH is the path to the file used as the virtual disk, and VDEV
+# and MODE have the same meaning as for ``phy'' devices.
+#
+# VDEV doesn't really matter for a NetBSD guest OS, but it does for Linux.
 # Worse, the device has to exists in /dev/ of domain0, because xm will
 # try to stat() it. This means that in order to load a Linux guest OS
 # from a NetBSD domain0, you'll have to create /dev/hda1, /dev/hda2, ...
 # on domain0, with the major/minor from Linux :(
 
 disk = [ 'phy:/dev/wd0e,wd0d,w' ]
+#disk = [ 'file:/var/xen/nbsd-disk,wd0d,w' ]
 
 #----------------------------------------------------------------------------
 # Set the kernel command line for the new domain.
@@ -304,47 +324,48 @@
       for each virtual network interface created in
       <emphasis>domain0</emphasis>. This
       can be used to configure automatically the xvif?.? interfaces
-      in <emphasis>domain0</emphasis>. In our example, these will get an IP 
(<emphasis>domain0</emphasis>
-      then provide routing and NAT for Internet access via
-      IPF).</para>
+      in <emphasis>domain0</emphasis>. In our example, these will be bridged
+      with the bridge0 device created in (<emphasis>domain0</emphasis>.</para>
       <para>Here is a suitable 
       <filename>/usr/pkg/etc/xen/vif-bridge</filename>
       for this:</para>
 <programlisting>
 #!/bin/sh
 #============================================================================
+# $NetBSD$
+#
 # /usr/pkg/etc/xen/vif-bridge
 #
-# Script for configuring a vif.
-# Xend calls a vif script when configuring a vif up or down.
-# This script is the default - but it can be configured for each vif.
+# Script for configuring a vif in bridged mode with a dom0 interface.
+# The xend(8) daemon calls a vif script when bringing a vif up or down.
+# The script name to use is defined in /usr/pkg/etc/xen/xend-config.sxp
+# in the ``vif-script'' field.
 #
-# Example invocation:
+# Usage: vif-bridge up|down [var=value ...]
 #
-# vif-bridge up domain=VM1 vif=vif1.0 bridge=xen-br0 mac=aa:00:00:50:02:f0
+# Actions:
+#    up                Adds the vif interface to the bridge.
+#    down      Removes the vif interface from the bridge.
 #
+# Variables:
+#    domain    name of the domain the interface is on (required).
+#    vifq      vif interface name (required).
+#    mac       vif MAC address (required).
+#    bridge    bridge to add the vif to (required).
 #
-# Usage:
-# vif-bridge (up|down) {VAR=VAL}*
-#
-# Vars:
+# Example invocation:
 #
-# domain  name of the domain the interface is on (required).
-# vif     vif interface name (required).
-# mac     vif MAC address (required).
-# bridge  bridge to add the vif to (required).
+# vif-bridge up domain=VM1 vif=xvif1.0 mac="ee:14:01:d0:ec:af" bridge=bridge0
 #
 #============================================================================
 
 # Exit if anything goes wrong
 set -e 
 
-#this will be logged in xend-debug.log
 echo "vif-bridge $*"
 
 # Operation name.
-OP=$1
-shift
+OP=$1; shift
 
 # Pull variables in args into environment
 for arg ; do export "${arg}" ; done
@@ -355,28 +376,33 @@
 mac=${mac:?}
 bridge=${bridge:?}
 
+# Optional parameters. Set defaults.
+ip=${ip:-''}   # default to null (do nothing)
+
 # Are we going up or down?
 case $OP in
-    up)
-       # ${bridge} contains ifconfig parameters in our case.
-        # It could also be parameters to brctl, or anything else we
-        # want.
-       # xend gives us vif?.? as interface name, but on NetBSD
-       # they're called xvif?.?
-       ifconfig x${vif} ${bridge}
-       exit 0
-
-       ;;
-    down)
-       exit 0
-       ;;
-    *)
+up)    brcmd='add' ;;
+down)  brcmd='delete' ;;
+*)
        echo 'Invalid command: ' $OP
        echo 'Valid commands are: up, down'
        exit 1
        ;;
 esac
-#end of /usr/pkg/etc/xen/vif-bridge
+
+# Don't do anything if the bridge is "null".
+if [ "${bridge}" = "null" ] ; then
+       exit
+fi
+
+# Don't do anything if the bridge doesn't exist.
+if ! ifconfig -l | grep "${bridge}" >/dev/null; then
+       exit
+fi
+
+# Add/remove vif to/from bridge.
+ifconfig x${vif} $OP
+brconfig ${bridge} ${brcmd} x${vif}
 </programlisting>
       <para>Now, running</para>
       <programlisting>xm create -c /usr/pkg/etc/xen/nbsd</programlisting>