-
Notifications
You must be signed in to change notification settings - Fork 4
/
Copy pathREADME
128 lines (92 loc) · 5 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
README - PyMatryoshka v0.1
Overview
=========
PyMatryoshka is a VXLAN-over-UDP agent, an implementation of VXLAN in
userspace, using Python. It targets the case of large-scale, isolated, virtual
networking in virtualized infrastructure.
Here are some more information on VXLAN and its advantages:
https://tools.ietf.org/html/draft-mahalingam-dutt-dcops-vxlan-02
http://www.cisco.com/en/US/prod/collateral/switches/ps9441/ps9902/white_paper_c11-685115.html
http://linux-network-plumber.blogspot.com/2012/09/just-published-linux-kernel.html
VXLAN support has recently been merged into the Linux 3.7 kernel.
PyMatryoshka is a userspace implementation of VXLAN, which is independent of any
kernel-based support.
PyMatryoshka accepts Ethernet frames from virtual networks and encapsulates
them in VXLAN packets, over UDP. A special "Virtual Network ID" (VNI) header
allows incoming packets to be distributed to distinct virtual networks.
This allows virtual networks to be implemented completely independently from
physical VLANs, and removes the limitations imposed by the use of physical
VLANs; the VNI is 24-bit long and removes the limitation of at most 4096
physical VLANs.
The end result is virtual networks run in isolation, over standard IPv4/IPv6
infrastructure. VMs running on hosts produce Ethernet frames, which are
encapsulated in UDP packets and are exchanged between PyMatryoshka daemons on
different physical hosts.
Every PyMatryoshka daemon maintains a MAC learning table, which maps every MAC
address to a physical host. Whenever an outgoing frame is being encapsulated
into a UDP packet the procedure is:
* if the destination host can be determined based on this table, the daemon
uses unicast UDP to send a packet to the target physical host.
* Otherwise, if the physical host of the destination VM is not yet known, the
daemon uses IP multicast to reach every physical host on which the virtual
network extends.
Usage
=========
The PyMatryoshka server matryoshka/server.py runs on every physical node and
can be controlled by manipulating files under its state directory,
/var/lib/matryoshka by default. Creation of a new file instructs the daemon to
join a new virtual network, removal of an existing file instructs the daemon to
leave a virtual network. A virtual network is joined by joining a corresponding
IPv4 or IPv6 multicast group.
The file being created in the state directory must define values for the
following environment variables:
* TAPNAME: The name of the virtual tap interface to be joined in to the new
network
* VNI: The Virtual Network Identifier of the network to join
* MACTTL: The Time-to-live for the MAC learning table for this network
* TARGETIP: The [multicast] target IP for contacting all physical nodes which
have interfaces joined to this virtual network. Matryoshka will join the
associated multicast group. Both IPv4 and IPv6 multicast groups are supported.
* TARGETPORT: The target UDP port to use for VXLAN UDP packets
Please see scripts/join_vnet.sh for a quick-n-dirty script to create network
files under /var/lib/matryoshka. The script chooses a unique IPv4 multicast
group in the 239.0.0.0/8 range based on the virtual network id (VNI) of the
network being joined.
Once the daemon has joined a tap interface into a virtual network, you may use
standard Linux bridging tools (e.g., brctl addif) to add new VMs onto the VXLAN
segment. Example:
Use the following command to join virtual interface tap4 into VXLAN with VNI=5,
over the 239.0.0.5 IPv4 multicast group:
# join_vnet.sh tap4 5
Then create a bridge for the virtual network and add two VMs with NICs at tap5,
tap6 to it:
# brctl addbr br0
# brctl addif br0 tap4
# brctl addif br0 tap5
# brctl addif br0 tap6
The server also responds to signals SIGUSR1, SIGUSR2, e.g.:
# kill -USR1 <matryoshka-server-pid>
* SIGUSR1: Print current server state, including all joined networks and the
MAC learning table for each virtual network.
* SIGUSR2: Turn verbose debugging messages on and off.
Misc
========
For any bugs, patches or suggestions for improvement please contact
Vangelis Koukis <[email protected]>.
What's in a name? See https://en.wikipedia.org/wiki/Matryoshka_doll on why
PyMatryoshka was named that way.
License
========
PyMatryoshka: A VXLAN-over-UDP agent
Copyright (c) 2012 Vangelis Koukis <[email protected]>.
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License along
with this program; if not, write to the Free Software Foundation, Inc.,
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.