ia64/xen-unstable

view tools/vnet/doc/man/vn.pod.1 @ 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 6d7bba6443ef
children
line source
1 =head1 NAME
3 vn - Vnet (virtual networking) management utility.
5 =head1 SYNOPSIS
7 vn <command> [args]
9 =head1 DESCRIPTION
11 The B<vn> utility manages vnets, virtual networks for virtual machines.
12 Before using vnets, the vnet kernel module must be installed or
13 the user-space daemon vnetd must be running. Using the kernel module is recommended,
14 see the B<insmod> command below.
16 A vnet is a virtual network that behaves like a private LAN, transporting
17 Ethernet frames. Each vnet is identified by a 128-bit vnet id and
18 has a network device that interfaces to it. Ethernet packets written
19 to the device are encapsulated and sent to the network.
20 Received vnet packets are decapsulated and delivered from the device
21 corresponding to their vnet id. The default encapsulation uses UDP on port 1798.
23 Usually each vnet device is enslaved to a corresponding bridge, and virtual
24 machine interfaces are attached to vnets by enslaving them to the bridge.
25 Each vnet behaves like a private LAN: traffic on one vnet is not visible
26 on other vnets, and interfaces on a vnet cannot see traffic on the
27 physical network.
29 Vnets can be connected together into larger networks
30 by direct bridging or packet forwarding, or by using multihomed vms
31 with interfaces on several vnets, or vnets and the physical network.
32 As vnet interfaces are discovered dynamically, vnet connectivity is maintained
33 if a vm using a vnet is migrated from one physical machine to another.
35 In the commands vnet ids can be given in two forms. Long form, as 8 4-digit hex fields
36 separated by colons, for example 0000:0000:0000:0000:0000:0000:0000:0004, and
37 short form as a hex field, for example 0004 or 4. The short form is the same as the
38 long form with the first 7 fields zero. Vnet id 0000:0000:0000:0000:0000:0000:0000:0001
39 is reserved for the physical network and has no vnet device.
41 Vnets use multicast to discover the location of virtual interfaces, by default
42 using multicast group 224.10.0.1. If all the machines hosting vnets are on
43 the same subnet, or reachable by multicast, vnets will span all the machines
44 automatically. If some machines are not reachable by multicast you can configure
45 vnets to perform multicast forwarding using UDP.
47 The vnet devices are fully-functional network devices, so you can add IP addresses
48 to them and test connectivity without any vms running.
49 For example, using vnif0004 on machines A and B:
51 A> ifconfig vnif0004 192.0.2.11
52 B> ifconfig vnif0004 192.0.2.12
53 B> ping 192.0.2.11
55 If the vnet device is enslaved to a bridge you will have to add the IP address
56 to the bridge instead. Use C<brctl show> or C<vn vnets> to see if a vnet
57 device is on a bridge.
59 =over 4
61 =item B<insmod> I<[varp_mcaddr=ADDR]>
63 Insert the vnet kernel module, optionally supplying the multicast
64 address to use, default 224.10.0.1.
66 =item B<varp>
68 Print varp infrormation and varp cache.
70 =item B<vnets> [options]
72 Print the list of vnets (virtual networks). If a vnet device is on a bridge,
73 also shows the bridge and its bridged interfaces.
75 =over 4
77 =item B<-a | --all>
79 Also print the vifs on each vnet and varp information.
81 =item B<-l | --long>
83 Also print the ifconfig for the vnet devices.
85 =back
87 =item B<vnet-create> I<[options]> I<vnetid>
89 Create a vnet with the given id. The options are:
91 =over 4
93 =item B<-s | --security> I<level>
95 Security level, which can be one of I<none> for no security,
96 I<auth> for message authentication, and I<conf> for message
97 authentication and confidentiality. The default is no security.
98 Security is provided using IPSEC, but uses hard-wired keys.
100 =item B<-b | --bridge> I<bridgename>
102 Create a bridge for the vnet called I<bridgename> and enslave
103 the vnet device to it.
105 =item B<-v | --vnetif> I<vnetifname>
107 Use I<vnetifname> as the name for the vnet device. If this option
108 is not specified the default is to name the device vnifN where N
109 is the last field of the vnet id as 4 hex characters.
110 For example vnif0004. Network device names can be at
111 most 14 characters.
113 =back
115 =item B<vnet-delete> I<[options]> I<vnetid>
117 Delete the vnet with the given id. The vnet device goes away too.
119 =over 4
121 =item B<-b | --bridge>
123 If this option is specified, delete the bridge associated with the vnet.
125 =back
127 =item B<vifs>
129 Print the list of vifs (virtual interfaces).
131 =item B<vif-add> I<[-i|-interface]> I<vnet> I<vmac>
133 Add a vif to a vnet. Here I<vnet> is the vnet id and I<vmac>
134 is the vif's MAC address. Alternatively, I<vmac> can be the name of
135 a network device if the I<-i> or -I<--interface> flag is given.
137 It is not usually necessary to use B<vif-add> as vnets automatically
138 add vifs for the MAC addresses they see.
140 =item B<vif-delete> I<[-i|-interface]> I<vnet> I<vmac>
142 Delete a vif from a vnet. Here I<vnet> is the vnet id and I<vmac>
143 is the vif's MAC address. Alternatively, I<vmac> can be the name of
144 a network device if the I<-i> of -I<--interface> flag is given.
146 It is not usually necessary to use B<vif-delete> as vnets periodically
147 delete unused vifs.
149 =item B<peers>
151 Print the list of peer vnet machines to forward multicasts to, and accept
152 forwarded multicasts from.
154 =item B<peer-add> I<addr>
156 Add the peer with the given IP address or hostname.
158 =item B<peer-delete> I<addr>
160 Delete the peer with the given IP address or hostname.
162 =back
164 =head1 AUTHOR
166 The author of vn and vnets is Mike Wray of HP Labs. Please send problems, bugs,
167 enhancements requests etc. to mike.wray@hp.com.
169 =head1 COPYRIGHT AND LICENSE
171 Copyright (C) 2006 Mike Wray <mike.wray@hp.com>.
173 This library is free software; you can redistribute it and/or modify
174 it under the terms of the GNU Lesser General Public License as published by
175 the Free Software Foundation; either version 2.1 of the License, or
176 (at your option) any later version.