1.1 --- a/docs/src/user.tex	Thu Feb 09 16:12:11 2006 +0100
     1.2 +++ b/docs/src/user.tex	Thu Feb 09 16:12:48 2006 +0100
     1.3 @@ -2099,6 +2099,155 @@ If you are running in the X environment 
     1.4  \subsection{Save/Restore and Migration}
     1.5  VMX guests currently cannot be saved and restored, nor migrated. These features are currently under active development.
     1.6  
     1.7 +\chapter{Vnets - Domain Virtual Networking}
     1.8 +
     1.9 +Xen optionally supports virtual networking for domains using {\em vnets}.
    1.10 +These emulate private LANs that domains can use. Domains on the same
    1.11 +vnet can be hosted on the same machine or on separate machines, and the
    1.12 +vnets remain connected if domains are migrated. Ethernet traffic 
    1.13 +on a vnet is tunneled inside IP packets on the physical network. A vnet is a virtual
    1.14 +network and addressing within it need have no relation to addressing on 
    1.15 +the underlying physical network. Separate vnets, or vnets and the physical network,
    1.16 +can be connected using domains with more than one network interface and
    1.17 +enabling IP forwarding or bridging in the usual way.
    1.18 +
    1.19 +Vnet support is included in \texttt{xm} and \xend:
    1.20 +\begin{verbatim}
    1.21 +# xm vnet-create <config>
    1.22 +\end{verbatim}
    1.23 +creates a vnet using the configuration in the file \verb|<config>|.
    1.24 +When a vnet is created its configuration is stored by \xend and the vnet persists until it is
    1.25 +deleted using
    1.26 +\begin{verbatim}
    1.27 +# xm vnet-delete <vnetid>
    1.28 +\end{verbatim}
    1.29 +The vnets \xend knows about are listed by
    1.30 +\begin{verbatim}
    1.31 +# xm vnet-list
    1.32 +\end{verbatim}
    1.33 +More vnet management commands are available using the
    1.34 +\texttt{vn} tool included in the vnet distribution.
    1.35 +
    1.36 +The format of a vnet configuration file is
    1.37 +\begin{verbatim}
    1.38 +(vnet (id       <vnetid>)
    1.39 +      (bridge   <bridge>)
    1.40 +      (vnetif   <vnet interface>)
    1.41 +      (security <level>))
    1.42 +\end{verbatim}
    1.43 +White space is not significant. The parameters are:
    1.44 +\begin{itemize}
    1.45 +  \item \verb|<vnetid>|: vnet id, the 128-bit vnet identifier. This can be given
    1.46 +    as 8 4-digit hex numbers separated by colons, or in short form as a single 4-digit hex number.
    1.47 +    The short form is the same as the long form with the first 7 fields zero.
    1.48 +    Vnet ids must be non-zero and id 1 is reserved.
    1.49 +
    1.50 +  \item \verb|<bridge>|: the name of a bridge interface to create for the vnet. Domains
    1.51 +    are connected to the vnet by connecting their virtual interfaces to the bridge.
    1.52 +    Bridge names are limited to 14 characters by the kernel.
    1.53 +
    1.54 +  \item \verb|<vnetif>|: the name of the virtual interface onto the vnet (optional). The
    1.55 +    interface encapsulates and decapsulates vnet traffic for the network and is attached
    1.56 +    to the vnet bridge. Interface names are limited to 14 characters by the kernel.
    1.57 +
    1.58 +  \item \verb|<level>|: security level for the vnet (optional). The level may be one of 
    1.59 +      \begin{itemize}
    1.60 +        \item \verb|none|: no security (default). Vnet traffic is in clear on the network.
    1.61 +        \item \verb|auth|: authentication. Vnet traffic is authenticated using IPSEC
    1.62 +           ESP with hmac96.
    1.63 +        \item \verb|conf|: confidentiality. Vnet traffic is authenticated and encrypted
    1.64 +           using IPSEC ESP with hmac96 and AES-128.
    1.65 +      \end{itemize}
    1.66 +      Authentication and confidentiality are experimental and use hard-wired keys at present.
    1.67 +\end{itemize}
    1.68 +When a vnet is created its configuration is stored by \xend and the vnet persists until it is
    1.69 +deleted using \texttt{xm vnet-delete <vnetid>}. The interfaces and bridges used by vnets
    1.70 +are visible in the output of \texttt{ifconfig} and \texttt{brctl show}.
    1.71 +
    1.72 +\section{Example}
    1.73 +If the file \path{vnet97.sxp} contains
    1.74 +\begin{verbatim}
    1.75 +(vnet (id 97) (bridge vnet97) (vnetif vnif97)
    1.76 +      (security none))
    1.77 +\end{verbatim}
    1.78 +Then \texttt{xm vnet-create vnet97.sxp} will define a vnet with id 97 and no security.
    1.79 +The bridge for the vnet is called vnet97 and the virtual interface for it is vnif97.
    1.80 +To add an interface on a domain to this vnet set its bridge to vnet97
    1.81 +in its configuration. In Python:
    1.82 +\begin{verbatim}
    1.83 +vif="bridge=vnet97"
    1.84 +\end{verbatim}
    1.85 +In sxp:
    1.86 +\begin{verbatim}
    1.87 +(dev (vif (mac aa:00:00:01:02:03) (bridge vnet97)))
    1.88 +\end{verbatim}
    1.89 +Once the domain is started you should see its interface in the output of \texttt{brctl show}
    1.90 +under the ports for \texttt{vnet97}.
    1.91 +
    1.92 +To get best performance it is a good idea to reduce the MTU of a domain's interface
    1.93 +onto a vnet to 1400. For example using \texttt{ifconfig eth0 mtu 1400} or putting
    1.94 +\texttt{MTU=1400} in \texttt{ifcfg-eth0}.
    1.95 +You may also have to change or remove cached config files for eth0 under
    1.96 +\texttt{/etc/sysconfig/networking}. Vnets work anyway, but performance can be reduced
    1.97 +by IP fragmentation caused by the vnet encapsulation exceeding the hardware MTU.
    1.98 +
    1.99 +\section{Installing vnet support}
   1.100 +Vnets are implemented using a kernel module, which needs to be loaded before
   1.101 +they can be used. You can either do this manually before starting \xend, using the
   1.102 +command \texttt{vn insmod}, or configure \xend to use the \path{network-vnet}
   1.103 +script in the xend configuration file \texttt{/etc/xend/xend-config.sxp}:
   1.104 +\begin{verbatim}
   1.105 +(network-script        network-vnet)
   1.106 +\end{verbatim}
   1.107 +This script insmods the module and calls the \path{network-bridge} script.
   1.108 +
   1.109 +The vnet code is not compiled and installed by default.
   1.110 +To compile the code and install on the current system
   1.111 +use \texttt{make install} in the root of the vnet source tree,
   1.112 +\path{tools/vnet}. It is also possible to install to an installation
   1.113 +directory using \texttt{make dist}. See the \path{Makefile} in
   1.114 +the source for details.
   1.115 +
   1.116 +The vnet module creates vnet interfaces \texttt{vnif0002},
   1.117 +\texttt{vnif0003} and \texttt{vnif0004} by default. You can test that
   1.118 +vnets are working by configuring IP addresses on these interfaces
   1.119 +and trying to ping them across the network. For example, using machines
   1.120 +hostA and hostB:
   1.121 +\begin{verbatim}
   1.122 +hostA# ifconfig vnif0004 10.0.0.100 up
   1.123 +hostB# ifconfig vnif0004 10.0.0.101 up
   1.124 +hostB# ping 10.0.0.100
   1.125 +\end{verbatim}
   1.126 +
   1.127 +The vnet implementation uses IP multicast to discover vnet interfaces, so
   1.128 +all machines hosting vnets must be reachable by multicast. Network switches
   1.129 +are often configured not to forward multicast packets, so this often
   1.130 +means that all machines using a vnet must be on the same LAN segment,
   1.131 +unless you configure vnet forwarding.
   1.132 +
   1.133 +You can test multicast coverage by pinging the vnet multicast address:
   1.134 +\begin{verbatim}
   1.135 +# ping -b 224.10.0.1
   1.136 +\end{verbatim}
   1.137 +You should see replies from all machines with the vnet module running.
   1.138 +You can see if vnet packets are being sent or received by dumping traffic
   1.139 +on the vnet UDP port:
   1.140 +\begin{verbatim}
   1.141 +# tcpdump udp port 1798
   1.142 +\end{verbatim}
   1.143 +
   1.144 +If multicast is not being forwaded between machines you can configure
   1.145 +multicast forwarding using vn. Suppose we have machines hostA on 10.10.0.100
   1.146 +and hostB on 10.11.0.100 and that multicast is not forwarded between them.
   1.147 +We use vn to configure each machine to forward to the other:
   1.148 +\begin{verbatim}
   1.149 +hostA# vn peer-add hostB
   1.150 +hostB# vn peer-add hostA
   1.151 +\end{verbatim}
   1.152 +Multicast forwarding needs to be used carefully - you must avoid creating forwarding
   1.153 +loops. Typically only one machine on a subnet needs to be configured to forward,
   1.154 +as it will forward multicasts received from other machines on the subnet.
   1.155 +
   1.156  %% Chapter Glossary of Terms moved to glossary.tex
   1.157  \chapter{Glossary of Terms}
   1.158