view tools/vnet/doc/man/vn.pod.1 @ 0:7d21f7218375

Exact replica of unstable on 051908 + README-this
author Mukesh Rathor
date Mon May 19 15:34:57 2008 -0700 (2008-05-19)
line source
1 =head1 NAME
3 vn - Vnet (virtual networking) management utility.
5 =head1 SYNOPSIS
7 vn <command> [args]
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 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
52 B> ifconfig vnif0004
53 B> ping
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
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
171 Copyright (C) 2006 Mike Wray <>.
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.