Statistics
| Branch: | Tag: | Revision:

mininet / INSTALL @ ae2ede79

History | View | Annotate | Download (10.1 KB)

1

    
2
Mininet Installation/Configuration Notes
3

    
4
Mininet 1.0.0
5

    
6
---
7

    
8
The supported installation methods for Mininet are 1) using
9
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
The easiest way to get Mininet running is to start with one of our pre-built 
16
virtual machine images from http://openflow.org/mininet
17

    
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
your native OS installation or damage it in any way.
22

    
23
2. Native installation (experimental!) for Ubuntu 10.04 LTS
24

    
25
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

    
28
WARNING: USE AT YOUR OWN RISK!
29

    
30
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

    
37
To install ALL of the software which we use for OpenFlow tutorials,
38
you may use
39

    
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

    
48
[a) On Debian 5, first install a Mininet-compatible kernel:
49
    $ mininet/util/install.sh -k
50
   Reboot and run 'uname -r' to make sure you're running the new kernel.]
51

    
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
    $ mininet/util/install.sh -f
57

    
58
d) Install Open vSwitch and its kernel module
59
    $ mininet/util/install.sh -vm
60

    
61
e) If you wish to install the version of NOX we use in the tutorial:
62
    $ mininet/util/install.sh -x
63

    
64
   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
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

    
72
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

    
75
---
76

    
77
Mininet Manual Installation Notes
78

    
79
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

    
84
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
http://openflow.org/foswiki/bin/view/OpenFlow/MininetVMCreationNotes
88

    
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
  git clone git://openflow.org/mininet.git
95
     
96
1. Core Mininet installation
97

    
98
  The core Mininet installation requires gcc, make, python,
99
  and setuptools. On Ubuntu and Debian you may install them with:
100
  
101
  # aptitude install gcc make python setuptools
102

    
103
  To install Mininet itself, with root privileges:
104
  
105
  # cd mininet
106
  # make install
107

    
108
  This places the mininet package in /usr/lib/python-*/site-packages/,
109
  so that 'import mininet' will work, and installs the primary mn
110
  script (mn) as well as its helper utility (mnexec.)
111
  
112
  On Ubuntu and Debian, Mininet's dependencies and core files may also be 
113
  installed using mininet/util/install.sh -n
114

    
115
2. Installation script for Ubuntu/Debian Lenny
116

    
117
  If you are running Ubuntu 10.04 or Debian Lenny, you may be able to use the
118
  util/install.sh script to install a compatible Linux kernel as well as
119
  other software including the OpenFlow reference implementation, the Open
120
  vSwitch switch implementation, and the NOX OpenFlow controller. 
121

    
122
  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
  install.sh to install EVERYTHING we use for OpenFlow tutorials are:
127
  
128
  % cd
129
  % time ~/mininet/util/install.sh  # installs tons of stuff
130
  % sudo reboot  # to load new kernel
131
  % ~/mininet/util/install.sh -c  # to clean out unneeded kernel stuff
132

    
133
  This installs a lot of useful software, but it will take a while (30
134
  minutes or more, depending on your network connection, computer, etc..)
135
 
136
  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
  
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

    
147
  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
  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
  If you successfully used install.sh, congratulations! You're basically
154
  done. Proceed to step [6] for additional advice.
155
      
156
3. Linux Kernel requirements
157

    
158
  Mininet requires a kernel built with network namespace support enabled,
159
  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
  able to install using "util/install.sh -k". Note our kernel package
166
  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
  
169
  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
  
173
  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
  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
  resulting in much slower switch shutdown.
181

    
182
  For scalable configurations, you might need to increase some of your
183
  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

    
187
    sudo su -c "cat sysctl_addon >> /etc/sysctl.conf"
188

    
189
  To save the config change, run:
190

    
191
    sudo sysctl -p
192
    
193
4. OpenFlow software and configuration requirements
194

    
195
  Mininet requires either the reference OpenFlow switch implementation
196
  (from openflowswitch.org) or Open vSwitch (openvswitch.org) to be
197
  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
  
201
  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
  
206
  Mininet will automatically load and remove kernel module dependencies
207
  for supported switch types, using modprobe and rmmod - but these
208
  modules must be in a location where modprobe can find them (e.g.
209
  something like /lib/modules/`uname -r`/kernel/drivers/net/)
210

    
211
  The reference OpenFlow controller (controller(8)) only supports 16
212
  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
  different controller such as nox. A patch to controller(8) is included
215
  as util/openflow-patches/controller.patch.
216
  
217
5. Other software dependencies
218

    
219
  On Ubuntu and Debian, other Mininet dependencies may be installed using
220
  the '-n' option of the install.sh script.
221

    
222
  To run the iperf test, you need to install iperf:
223

    
224
    sudo aptitude/yum install iperf
225

    
226
  We assume you already have ping installed. ;-)
227
  
228
  To use xterm or sshd with Mininet, you need the following:
229

    
230
    sudo aptitude/yum install sshd xterm screen
231
    
232
  Some examples may have additional requirements - consult the specific
233
  example file for details.
234
  
235
  The install.sh script has an '-x' option to install the version of
236
  NOX from the OpenFlow tutorial.
237
  
238
6. Other notes and recommendations
239

    
240
  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
  Mininet should be run either on a machine with
244
  no other important processes, or on a virtual machine (recommended!)
245
  
246
  Multiple concurrent Mininet instances are not supported!
247

    
248
Good luck!
249

    
250
---
251

    
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