Statistics
| Branch: | Tag: | Revision:

mininet / INSTALL @ ae2ede79

History | View | Annotate | Download (10.1 KB)

1 35341142 Bob Lantz
2 d2f9aea2 Bob Lantz
Mininet Installation/Configuration Notes
3 af8f0b61 Bob Lantz
4 d2f9aea2 Bob Lantz
Mininet 1.0.0
5 35341142 Bob Lantz
6 219f9de7 Bob Lantz
---
7 8125370d Bob Lantz
8 219f9de7 Bob Lantz
The supported installation methods for Mininet are 1) using
9 40beaabc Bob Lantz
a pre-built VM image, and 2) native installation on Ubuntu or Debian.
10
(Other distributions may be supported in the future - if you would
11
like to contribute an installation script, we would welcome it!)
12
13
1. Easiest "install" - use our pre-built VM image!
14
15 52c700ff Bob Lantz
The easiest way to get Mininet running is to start with one of our pre-built 
16 219f9de7 Bob Lantz
virtual machine images from http://openflow.org/mininet
17 40beaabc Bob Lantz
18
Boot up the VM image, log in, and follow the instructions on the wiki page.
19
20
An additional advantage of using the VM image is that it doesn't mess with
21 219f9de7 Bob Lantz
your native OS installation or damage it in any way.
22 40beaabc Bob Lantz
23 d2f9aea2 Bob Lantz
2. Native installation (experimental!) for Ubuntu 10.04 LTS
24 40beaabc Bob Lantz
25 d2f9aea2 Bob Lantz
If you are running Ubuntu 10.04 LTS (or possibly Debian 5), you may be
26
able to use our handy install.sh script, which is in mininet/util.
27 40beaabc Bob Lantz
28 219f9de7 Bob Lantz
WARNING: USE AT YOUR OWN RISK!
29
30 d2f9aea2 Bob Lantz
install.sh is a bit intrusive and may possibly damage your OS and/or
31
home directory, by creating/modifying several directories such as
32
mininet, openflow, openvswitch and noxcore. Although we hope it won't
33
do anything completely terrible, you may want to look at the script
34
before you run it, and you should make sure your system and home
35
directory are backed up just in case!
36 40beaabc Bob Lantz
37 d2f9aea2 Bob Lantz
To install ALL of the software which we use for OpenFlow tutorials,
38
you may use
39 40beaabc Bob Lantz
40
$ mininet/util/install.sh
41
42
This takes about 20-30 minutes.
43
44
Alternately, you can install just the pieces you need.
45
46
We recommend the following steps, in order:
47 8125370d Bob Lantz
48 d2f9aea2 Bob Lantz
[a) On Debian 5, first install a Mininet-compatible kernel:
49 40beaabc Bob Lantz
    $ mininet/util/install.sh -k
50 d2f9aea2 Bob Lantz
   Reboot and run 'uname -r' to make sure you're running the new kernel.]
51 ec226c9b Bob Lantz
52
b) Install mininet and its dependencies:
53
    $ mininet/util/install.sh -n
54
    
55
c) Install OpenFlow 1.0 and associated useful software
56 40beaabc Bob Lantz
    $ mininet/util/install.sh -f
57 8eae2550 Bob Lantz
58 ec226c9b Bob Lantz
d) Install Open vSwitch and its kernel module
59 ee7ee406 Bob Lantz
    $ mininet/util/install.sh -vm
60 8eae2550 Bob Lantz
61 ec226c9b Bob Lantz
e) If you wish to install the version of NOX we use in the tutorial:
62 40beaabc Bob Lantz
    $ mininet/util/install.sh -x
63 8eae2550 Bob Lantz
64 d2f9aea2 Bob Lantz
   Note: NOX development is progressing over time, so after you complete
65
   the tutorial you may wish to install the latest and greatest NOX from
66
   noxrepo.org.
67
68 40beaabc Bob Lantz
Good luck! Some additional installation notes are provided below, for
69
the brave and/or Linux-savvy, or those who are trying to understand what
70
is installed and why.
71 8eae2550 Bob Lantz
72 40beaabc Bob Lantz
p.s. Note that only one instance of Mininet is currently supported on a single
73
machine - that's one reason we recommend using a VM to run it.
74 8eae2550 Bob Lantz
75
---
76
77
Mininet Manual Installation Notes
78 c8fbd446 Bob Lantz
79 9a17de91 Bob Lantz
These installation notes assume you understand how to do things like
80
compile kernels, apply patches, configure networks, write code, etc.. If
81
this is unfamiliar territory, or if you run into trouble, we recommend
82
using one of our pre-built virtual machine images (see above.)
83 c8fbd446 Bob Lantz
84 52c700ff Bob Lantz
If you wish to try to create a VM to run Mininet, you may also wish
85
to look at the Wiki page:
86
87 a77e7a02 Bob Lantz
http://openflow.org/foswiki/bin/view/OpenFlow/MininetVMCreationNotes
88 52c700ff Bob Lantz
89
0. Obtaining Mininet
90
91
  If you're reading this, you've already done it, but the command to
92
  download mininet is:
93
   
94 a77e7a02 Bob Lantz
  git clone git://openflow.org/mininet.git
95 52c700ff Bob Lantz
     
96 c8fbd446 Bob Lantz
1. Core Mininet installation
97 3465c9ea Bob Lantz
98 8eae2550 Bob Lantz
  The core Mininet installation requires gcc, make, python,
99 52c700ff Bob Lantz
  and setuptools. On Ubuntu and Debian you may install them with:
100
  
101
  # aptitude install gcc make python setuptools
102 8eae2550 Bob Lantz
103 c8fbd446 Bob Lantz
  To install Mininet itself, with root privileges:
104 52c700ff Bob Lantz
  
105
  # cd mininet
106 cae423e5 Bob Lantz
  # make install
107 51270ce4 Brandon Heller
108 52c700ff Bob Lantz
  This places the mininet package in /usr/lib/python-*/site-packages/,
109 3465c9ea Bob Lantz
  so that 'import mininet' will work, and installs the primary mn
110
  script (mn) as well as its helper utility (mnexec.)
111 6555c929 Bob Lantz
  
112 2d48b463 Bob Lantz
  On Ubuntu and Debian, Mininet's dependencies and core files may also be 
113 6555c929 Bob Lantz
  installed using mininet/util/install.sh -n
114 af8f0b61 Bob Lantz
115 2d48b463 Bob Lantz
2. Installation script for Ubuntu/Debian Lenny
116 9a17de91 Bob Lantz
117 52c700ff Bob Lantz
  If you are running Ubuntu 10.04 or Debian Lenny, you may be able to use the
118 9a17de91 Bob Lantz
  util/install.sh script to install a compatible Linux kernel as well as
119
  other software including the OpenFlow reference implementation, the Open
120 f6149e4d Bob Lantz
  vSwitch switch implementation, and the NOX OpenFlow controller. 
121 9a17de91 Bob Lantz
122 f6149e4d Bob Lantz
  Many different installation options are possible by passing different
123
  options to install.sh; install.sh -h lists them all.
124
  
125
  Assuming the mininet source tree is installed in ~/mininet, the steps to run
126 2d48b463 Bob Lantz
  install.sh to install EVERYTHING we use for OpenFlow tutorials are:
127 f6149e4d Bob Lantz
  
128 9a17de91 Bob Lantz
  % cd
129 f6149e4d Bob Lantz
  % time ~/mininet/util/install.sh  # installs tons of stuff
130 9a17de91 Bob Lantz
  % sudo reboot  # to load new kernel
131
  % ~/mininet/util/install.sh -c  # to clean out unneeded kernel stuff
132
133 2d48b463 Bob Lantz
  This installs a lot of useful software, but it will take a while (30
134 52c700ff Bob Lantz
  minutes or more, depending on your network connection, computer, etc..)
135 6555c929 Bob Lantz
 
136 f6149e4d Bob Lantz
  Probably the minimal semi-useful configuration would be to install 
137
  Mininet itself, kernel support if necessary, and either the 
138
  reference OpenFlow switch or Open vSwitch. This could be installed 
139
  as follows:
140 6555c929 Bob Lantz
  
141
  % sudo ~/mininet/util/install.sh -knvm
142
  
143
  Respectively, this installs kernel support, core mininet dependencies,
144
  Open vSwitch, and the Open vSwitch kernel module. If a new kernel was
145
  installed, then a reboot may be required.
146 f6149e4d Bob Lantz
147 2d48b463 Bob Lantz
  If install.sh cannot be used for some reason (e.g. you're on Fedora
148
  or some other Linux - please don't say CentOS) or if you don't want to
149 f6149e4d Bob Lantz
  install all of these components (they're useful!), the kernel and
150
  OpenFlow software requirements are described in steps [3] and [4],
151
  which follow.
152
153 52c700ff Bob Lantz
  If you successfully used install.sh, congratulations! You're basically
154
  done. Proceed to step [6] for additional advice.
155
      
156 9a17de91 Bob Lantz
3. Linux Kernel requirements
157 c8fbd446 Bob Lantz
158
  Mininet requires a kernel built with network namespace support enabled,
159 52c700ff Bob Lantz
  i.e. with CONFIG_NET_NS=Y, such as the kernel shipped with
160
  Ubuntu 10.04 LTS, currently 2.6.32. On Ubuntu 10.04, you should not need
161
  to install or build a custom kernel, although 2.6.33+ is faster at
162
  tearing down virtual ethernet pairs.
163
164
  For Ubuntu and Debian, we provide a 2.6.33 kernel package which you may be
165 f6149e4d Bob Lantz
  able to install using "util/install.sh -k". Note our kernel package
166 52c700ff Bob Lantz
  requires an ext2 or ext3 root file system, so it won't work if you have
167
  a default Ubuntu install, which uses ext4.
168 ed097b3b Bob Lantz
  
169 52c700ff Bob Lantz
  If your kernel wasn't compiled with CONFIG_NET_NS=Y, you will need to 
170
  build and install a  kernel that does! >= 2.6.33 works better, but may 
171
  be harder to get working, depending on your Linux distribution.
172 f2eaeac7 Bob Lantz
  
173 8125370d Bob Lantz
  A script for building Debian packages for 2.6.33.1 is provided in
174
  mininet/util/kbuild. You may wish to read it, as it applies patches
175
  to enable 2.6.33.1 to build under debian-stable, and to enable the
176
  tun driver to work correctly with Mininet.
177
    
178 9a17de91 Bob Lantz
  Earlier kernels (e.g. 2.6.29) work with CONFIG_NET_NS enabled and no
179
  additional patches, but are much slower at removing veth interfaces,
180 8125370d Bob Lantz
  resulting in much slower switch shutdown.
181 5947e017 Bob Lantz
182 c8fbd446 Bob Lantz
  For scalable configurations, you might need to increase some of your
183 9a17de91 Bob Lantz
  kernel limits. Sample params are in util/sysctl_addon, which can be
184
  appended to /etc/sysctl.conf (and modified as necessary for your
185
  desired configuration):
186 af8f0b61 Bob Lantz
187 c8fbd446 Bob Lantz
    sudo su -c "cat sysctl_addon >> /etc/sysctl.conf"
188 af8f0b61 Bob Lantz
189 c8fbd446 Bob Lantz
  To save the config change, run:
190 af8f0b61 Bob Lantz
191 c8fbd446 Bob Lantz
    sudo sysctl -p
192 af8f0b61 Bob Lantz
    
193 9a17de91 Bob Lantz
4. OpenFlow software and configuration requirements
194 c8fbd446 Bob Lantz
195
  Mininet requires either the reference OpenFlow switch implementation
196 9a17de91 Bob Lantz
  (from openflowswitch.org) or Open vSwitch (openvswitch.org) to be
197 52c700ff Bob Lantz
  installed. "make test" requires the reference user space
198
  implementations as well as Open vSwitch. Note the reference kernel
199
  implementation is not currently included in OpenFlow 1.0.
200 3465c9ea Bob Lantz
  
201 52c700ff Bob Lantz
  On Ubuntu and  Debian, the install.sh script may be used with the '-f'
202
  option to install the OpenFlow reference implementation, the '-v' option
203
  to build Open vSwitch, and the '-m' option to install the Open vSwitch
204
  kernel module into /lib/modules (note: you must build Open vSwitch first!)
205 8125370d Bob Lantz
  
206 9a17de91 Bob Lantz
  Mininet will automatically load and remove kernel module dependencies
207
  for supported switch types, using modprobe and rmmod - but these
208 52c700ff Bob Lantz
  modules must be in a location where modprobe can find them (e.g.
209
  something like /lib/modules/`uname -r`/kernel/drivers/net/)
210 af8f0b61 Bob Lantz
211 c8fbd446 Bob Lantz
  The reference OpenFlow controller (controller(8)) only supports 16
212 55dd9368 Bob Lantz
  switches by default! If you wish to run a network with more than 16
213
  switches, please recompile controller(8) with larger limits, or use a
214 c8fbd446 Bob Lantz
  different controller such as nox. A patch to controller(8) is included
215 9a17de91 Bob Lantz
  as util/openflow-patches/controller.patch.
216 b3dd44d4 Bob Lantz
  
217 9a17de91 Bob Lantz
5. Other software dependencies
218 af8f0b61 Bob Lantz
219 52c700ff Bob Lantz
  On Ubuntu and Debian, other Mininet dependencies may be installed using
220
  the '-n' option of the install.sh script.
221
222 9a17de91 Bob Lantz
  To run the iperf test, you need to install iperf:
223 af8f0b61 Bob Lantz
224 c8fbd446 Bob Lantz
    sudo aptitude/yum install iperf
225 83086439 Brandon Heller
226 c8fbd446 Bob Lantz
  We assume you already have ping installed. ;-)
227
  
228 9a17de91 Bob Lantz
  To use xterm or sshd with Mininet, you need the following:
229 83086439 Brandon Heller
230 c8fbd446 Bob Lantz
    sudo aptitude/yum install sshd xterm screen
231
    
232 9a17de91 Bob Lantz
  Some examples may have additional requirements - consult the specific
233
  example file for details.
234 c8fbd446 Bob Lantz
  
235 52c700ff Bob Lantz
  The install.sh script has an '-x' option to install the version of
236
  NOX from the OpenFlow tutorial.
237
  
238 9a17de91 Bob Lantz
6. Other notes and recommendations
239 c8fbd446 Bob Lantz
240 6555c929 Bob Lantz
  If you did not install certain useful packages and you wish to later,
241
  it may be possible to install them using install.sh.
242
  
243 8125370d Bob Lantz
  Mininet should be run either on a machine with
244
  no other important processes, or on a virtual machine (recommended!)
245 c8fbd446 Bob Lantz
  
246
  Multiple concurrent Mininet instances are not supported!
247
248
Good luck!
249 8eae2550 Bob Lantz
250
---
251 52c700ff Bob Lantz
252
Historical information on OpenFlow 0.8.9 and the reference kernel module:
253
254
  The kernel reference implementation has been deprecated, but it may
255
  be possible to get it work with Mininet.
256
  
257
  To switch to the most recent OpenFlow 0.8.9 release branch (the most
258
  recent one with full NOX support and kernel datapath support) in your
259
  OpenFlow git tree:
260
261
   git checkout -b release/0.8.9 remotes/origin/release/0.8.9
262
  
263
  A patch to enable datapath.c to compile with recent kernels
264
  is included in util/openflow-patches/datapath.patch.
265
  
266
  In OpenFlow 1.0, switch port numbering starts at 1 (for better or for worse.)
267
  To run with previous versions of OpenFlow, it may be necessary
268
  to change SWITCH_PORT_BASE from 1 to 0 in node.py.
269
270
  
271
  
272
  
273