Statistics
| Branch: | Tag: | Revision:

mininet / INSTALL @ 8a130dea

History | View | Annotate | Download (9.9 KB)

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