Add a vnet chapter to the user manual.

Signed-off-by: Mike Wray <mike.wray@hp.com>

docs/src/user.tex

@@ -2099,6 +2099,155 @@ If you are running in the X environment after creating a VMX guest, an X window
 \subsection{Save/Restore and Migration}
 VMX guests currently cannot be saved and restored, nor migrated. These features are currently under active development.
 
+\chapter{Vnets - Domain Virtual Networking}
+
+Xen optionally supports virtual networking for domains using {\em vnets}.
+These emulate private LANs that domains can use. Domains on the same
+vnet can be hosted on the same machine or on separate machines, and the
+vnets remain connected if domains are migrated. Ethernet traffic 
+on a vnet is tunneled inside IP packets on the physical network. A vnet is a virtual
+network and addressing within it need have no relation to addressing on 
+the underlying physical network. Separate vnets, or vnets and the physical network,
+can be connected using domains with more than one network interface and
+enabling IP forwarding or bridging in the usual way.
+
+Vnet support is included in \texttt{xm} and \xend:
+\begin{verbatim}
+# xm vnet-create <config>
+\end{verbatim}
+creates a vnet using the configuration in the file \verb|<config>|.
+When a vnet is created its configuration is stored by \xend and the vnet persists until it is
+deleted using
+\begin{verbatim}
+# xm vnet-delete <vnetid>
+\end{verbatim}
+The vnets \xend knows about are listed by
+\begin{verbatim}
+# xm vnet-list
+\end{verbatim}
+More vnet management commands are available using the
+\texttt{vn} tool included in the vnet distribution.
+
+The format of a vnet configuration file is
+\begin{verbatim}
+(vnet (id       <vnetid>)
+      (bridge   <bridge>)
+      (vnetif   <vnet interface>)
+      (security <level>))
+\end{verbatim}
+White space is not significant. The parameters are:
+\begin{itemize}
+  \item \verb|<vnetid>|: vnet id, the 128-bit vnet identifier. This can be given
+    as 8 4-digit hex numbers separated by colons, or in short form as a single 4-digit hex number.
+    The short form is the same as the long form with the first 7 fields zero.
+    Vnet ids must be non-zero and id 1 is reserved.
+
+  \item \verb|<bridge>|: the name of a bridge interface to create for the vnet. Domains
+    are connected to the vnet by connecting their virtual interfaces to the bridge.
+    Bridge names are limited to 14 characters by the kernel.
+
+  \item \verb|<vnetif>|: the name of the virtual interface onto the vnet (optional). The
+    interface encapsulates and decapsulates vnet traffic for the network and is attached
+    to the vnet bridge. Interface names are limited to 14 characters by the kernel.
+
+  \item \verb|<level>|: security level for the vnet (optional). The level may be one of 
+      \begin{itemize}
+        \item \verb|none|: no security (default). Vnet traffic is in clear on the network.
+        \item \verb|auth|: authentication. Vnet traffic is authenticated using IPSEC
+           ESP with hmac96.
+        \item \verb|conf|: confidentiality. Vnet traffic is authenticated and encrypted
+           using IPSEC ESP with hmac96 and AES-128.
+      \end{itemize}
+      Authentication and confidentiality are experimental and use hard-wired keys at present.
+\end{itemize}
+When a vnet is created its configuration is stored by \xend and the vnet persists until it is
+deleted using \texttt{xm vnet-delete <vnetid>}. The interfaces and bridges used by vnets
+are visible in the output of \texttt{ifconfig} and \texttt{brctl show}.
+
+\section{Example}
+If the file \path{vnet97.sxp} contains
+\begin{verbatim}
+(vnet (id 97) (bridge vnet97) (vnetif vnif97)
+      (security none))
+\end{verbatim}
+Then \texttt{xm vnet-create vnet97.sxp} will define a vnet with id 97 and no security.
+The bridge for the vnet is called vnet97 and the virtual interface for it is vnif97.
+To add an interface on a domain to this vnet set its bridge to vnet97
+in its configuration. In Python:
+\begin{verbatim}
+vif="bridge=vnet97"
+\end{verbatim}
+In sxp:
+\begin{verbatim}
+(dev (vif (mac aa:00:00:01:02:03) (bridge vnet97)))
+\end{verbatim}
+Once the domain is started you should see its interface in the output of \texttt{brctl show}
+under the ports for \texttt{vnet97}.
+
+To get best performance it is a good idea to reduce the MTU of a domain's interface
+onto a vnet to 1400. For example using \texttt{ifconfig eth0 mtu 1400} or putting
+\texttt{MTU=1400} in \texttt{ifcfg-eth0}.
+You may also have to change or remove cached config files for eth0 under
+\texttt{/etc/sysconfig/networking}. Vnets work anyway, but performance can be reduced
+by IP fragmentation caused by the vnet encapsulation exceeding the hardware MTU.
+
+\section{Installing vnet support}
+Vnets are implemented using a kernel module, which needs to be loaded before
+they can be used. You can either do this manually before starting \xend, using the
+command \texttt{vn insmod}, or configure \xend to use the \path{network-vnet}
+script in the xend configuration file \texttt{/etc/xend/xend-config.sxp}:
+\begin{verbatim}
+(network-script        network-vnet)
+\end{verbatim}
+This script insmods the module and calls the \path{network-bridge} script.
+
+The vnet code is not compiled and installed by default.
+To compile the code and install on the current system
+use \texttt{make install} in the root of the vnet source tree,
+\path{tools/vnet}. It is also possible to install to an installation
+directory using \texttt{make dist}. See the \path{Makefile} in
+the source for details.
+
+The vnet module creates vnet interfaces \texttt{vnif0002},
+\texttt{vnif0003} and \texttt{vnif0004} by default. You can test that
+vnets are working by configuring IP addresses on these interfaces
+and trying to ping them across the network. For example, using machines
+hostA and hostB:
+\begin{verbatim}
+hostA# ifconfig vnif0004 10.0.0.100 up
+hostB# ifconfig vnif0004 10.0.0.101 up
+hostB# ping 10.0.0.100
+\end{verbatim}
+
+The vnet implementation uses IP multicast to discover vnet interfaces, so
+all machines hosting vnets must be reachable by multicast. Network switches
+are often configured not to forward multicast packets, so this often
+means that all machines using a vnet must be on the same LAN segment,
+unless you configure vnet forwarding.
+
+You can test multicast coverage by pinging the vnet multicast address:
+\begin{verbatim}
+# ping -b 224.10.0.1
+\end{verbatim}
+You should see replies from all machines with the vnet module running.
+You can see if vnet packets are being sent or received by dumping traffic
+on the vnet UDP port:
+\begin{verbatim}
+# tcpdump udp port 1798
+\end{verbatim}
+
+If multicast is not being forwaded between machines you can configure
+multicast forwarding using vn. Suppose we have machines hostA on 10.10.0.100
+and hostB on 10.11.0.100 and that multicast is not forwarded between them.
+We use vn to configure each machine to forward to the other:
+\begin{verbatim}
+hostA# vn peer-add hostB
+hostB# vn peer-add hostA
+\end{verbatim}
+Multicast forwarding needs to be used carefully - you must avoid creating forwarding
+loops. Typically only one machine on a subnet needs to be configured to forward,
+as it will forward multicasts received from other machines on the subnet.
+
 %% Chapter Glossary of Terms moved to glossary.tex
 \chapter{Glossary of Terms}