ia64/xen-unstable

view tools/vnet/doc/vnet-xend.txt @ 16739:33dcf04d7715

tools/docs: Fix example and default IP addresses.

In various places in documentation and code, IP addresses are provided
as examples, defaults, or dummy configuration. In general the
specific IP addresses used in Xen are not always appropriate. (For
example, 1.2.3.4 is used in a few places!)

The following addresses should be used:
* For examples and documentation, 192.0.2.0/24. (See RFC3330.)
* For defaults for private networks, a random network from RFC1918.
I have randomly selected 172.30.206.0/24 for this purpose and
documented this in at the only registry I know of,
www.ucam.org/cam-grin. This network should henceforth be used for
default configurations of local bridges, test networks, etc. in
Xen tools.

The following addresses should NOT be used:
* 10.0.*.*, 10.1.*.*, 192.168.0.*, 192.168.1.*, etc. Using these
addresses gives greatly increased likelihood of collision, as
ignorant network administrators and reckless middlebox vendors
often pick networks from the bottom of 10/8 and 192.168/16.
* 169.254.*.*. These are reserved for zeroconf (ad-hoc networking)
and should not be used for Xen private networks, bridges, etc.,
etc. Use of these addresses by Xen scripts causes trouble on hosts
(eg laptops) which find themselves in ad-hoc networking
environments. I think this is not hypothetical (!) since at least
one Linux distribution have specific code to detect this case and
cause Xen startup to fail iff the host already has an external
zeroconf address.
* 1.2.3.4. WTF !?

I have also used 127.0.255.255 in one place where apparently a dummy
address is needed (some Linux kernels won't accept a lack of an NFS
server address). If 127.0.255.255 is mistakenly used it is unlikely
to do any damage to real traffic even if it does escape into the
network at large.

Signed-off-by: Ian Jackson <ian.jackson@eu.citrix.com>
author Keir Fraser <keir.fraser@citrix.com>
date Thu Jan 17 15:13:40 2008 +0000 (2008-01-17)
parents 71b0f00f6344
children
line source
2 Vnets: Virtual Networks for Virtual Machines
4 Mike Wray <mike.wray@hp.com>
6 2005/12/13
8 0) Introduction
9 ---------------
11 Vnets provide virtual private LANs for virtual machines.
12 This is done using bridging and multipoint tunneling. A virtual interface
13 on a vnet can only see other interfaces on the same vnet - it cannot
14 see the real network, and the real network cannot see it either.
16 Virtual interfaces on the same vnet can be on the same machine
17 or on different machines, they can still talk. The hosting machines
18 can even be on different subnets if you configure vnet forwarding,
19 or have multicast routing enabled.
22 1) Installing vnet support
23 --------------------------
25 Assuming the code has been installed (make install in the parent directory),
26 configure xend to use 'network-vnet' instead of the default 'network' to
27 start up networking. This just loads the vnet module when networking starts.
29 In /etc/xend/xend-config.sxp:
31 Configure the network script:
33 (network-script network-vnet)
35 Restart xend.
37 Alternatively insert the vnet module using 'vn insmod',
38 preferably before xend starts.
40 2) Creating vnets
41 -----------------
43 Xend already implements commands to add/remove vnets and
44 bridge to them. To add a vnet use
46 xm vnet-create <vnet config file>
48 For example, if vnet97.sxp contains:
50 (vnet (id 97) (bridge vnet97) (vnetif vnif97) (security none))
52 do
54 xm vnet-create vnet97.sxp
56 This will define a vnet with id 97 and no security. The bridge for the
57 vnet is called vnet97 and the virtual interface for it is vnif97.
58 To add an interface on a vm to this vnet simply set its bridge to vnet97
59 in its configuration.
61 In Python:
63 vif="bridge=vnet97"
65 In sxp:
67 (dev (vif (mac aa:00:00:01:02:03) (bridge vnet97)))
69 By default vnets use udp encapsulation, but if you use etherip encapsulation
70 you will also have to reduce the MTU of the corresponding
71 device in the domain (because of the tunneling). Reducing the MTU may improve
72 performance for udp encapsulation, but is not necessary.
74 For example, for eth0 (in the domain, not dom0) use
76 ifconfig eth0 mtu 1400
78 or, better, put
80 MTU=1400
82 in /etc/sysconfig/network-scripts/ifcfg-eth0. You may also have to change or remove
83 cached config files for eth0 under /etc/sysconfig/networking.
85 Once configured, vnets are persistent in the xend database.
86 To remove a vnet use
88 xm vnet-delete <vnet id>
90 To list vnets use
92 xm vnet-list
94 To get information on one or more vnet ids use
96 xm vnet-list <vnet id>...
98 You can also manage vnets using the vn utility which talks
99 directly to the vnet implementation. The source is in ../scripts/vn
100 and is installed in /usr/sbin/vn.
102 3) Troubleshooting
103 ------------------
105 The vnet module should appear in 'lsmod'.
106 If a vnet has been configured it should appear in the output of 'xm vnet-list'.
107 Its bridge and interface should appear in 'ifconfig'.
108 It should also show in 'brctl show', with its attached interfaces.
110 You can 'see into' a vnet from dom0 if you put an IP address on the bridge.
111 For example, if you have vnet97 and a vm with ip addr 192.0.2.12 connected to it,
112 then
114 ifconfig vnet97 192.0.2.20 up
116 should let you ping 192.0.2.12 via the vnet97 bridge.
118 4) Examples
119 -----------
121 These assume a vnet with a bridge 'vnet97' has been created.
123 Here's the full config for a vm on vnet 97, using ip addr 192.0.2.12:
125 (vm
126 (name dom12)
127 (memory '64')
128 (cpu '1')
129 (console '8502')
130 (image
131 (linux
132 (kernel /boot/vmlinuz-2.6-xenU)
133 (ip 192.0.2.12:192.0.2.4::::eth0:off)
134 (root /dev/sda1)
135 (args 'rw fastboot 4')
136 )
137 )
138 (device (vbd (uname phy:hda2) (dev sda1) (mode w)))
139 (device (vif (mac aa:00:00:11:00:12) (bridge vnet97)))
140 )
142 If you run another vm on the same vnet:
144 (vm
145 (name dom11)
146 (memory '64')
147 (cpu '1')
148 (console '8501')
149 (image
150 (linux
151 (kernel /boot/vmlinuz-2.6-xenU)
152 (ip 192.0.2.11:192.0.2.4::::eth0:off)
153 (root /dev/sda1)
154 (args 'rw fastboot 4')
155 )
156 )
157 (device (vbd (uname phy:hda3) (dev sda1) (mode w)))
158 (device (vif (mac aa:00:00:11:00:11) (bridge vnet97)))
159 )
161 the vms should be able to talk over the vnet. Check with ping.
162 If they are both on the same machine the connection will simply
163 be the vnet97 bridge, if they are on separate machines their
164 packets will be tunneled in udp (or etherip). They should be able to
165 see each other, but not the real network.