Statistics
| Branch: | Tag: | Revision:

mininet / INSTALL @ 40beaabc

History | View | Annotate | Download (9.81 KB)

1

    
2
Preliminary Mininet Installation/Configuration Notes
3

    
4
Pre-Beta version, August 2010
5
---
6

    
7
(Disclaimer: we're still pre-beta - things may be broken!)
8

    
9
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
The easiest way to get Mininet running is to start with one of our pre-built 
17
virtual machine images from:
18

    
19
 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

    
47
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
   
51
b) Install OpenFlow 1.0 and associated useful software
52
    $ mininet/util/install.sh -f
53

    
54
c) Install Open vSwitch
55
    $ mininet/util/install.sh -f
56

    
57
d) If you wish to install the version of NOX we use in the tutorial:
58
    $ mininet/util/install.sh -x
59

    
60
Good luck! Some additional installation notes are provided below, for
61
the brave and/or Linux-savvy, or those who are trying to understand what
62
is installed and why.
63

    
64
p.s. Note that only one instance of Mininet is currently supported on a single
65
machine - that's one reason we recommend using a VM to run it.
66

    
67
---
68

    
69
Mininet Manual Installation Notes
70

    
71
These installation notes assume you understand how to do things like
72
compile kernels, apply patches, configure networks, write code, etc.. If
73
this is unfamiliar territory, or if you run into trouble, we recommend
74
using one of our pre-built virtual machine images (see above.)
75

    
76
If you wish to try to create a VM to run Mininet, you may also wish
77
to look at the Wiki page:
78

    
79
http://openflow.org/foswiki/bin/view/OpenFlow/MininetVMCreationNotes
80

    
81
0. Obtaining Mininet
82

    
83
  If you're reading this, you've already done it, but the command to
84
  download mininet is:
85
   
86
  git clone git://openflow.org/mininet.git
87
     
88
1. Core Mininet installation
89

    
90
  The core Mininet installation requires gcc, make, python,
91
  and setuptools. On Ubuntu and Debian you may install them with:
92
  
93
  # aptitude install gcc make python setuptools
94

    
95
  To install Mininet itself, with root privileges:
96
  
97
  # cd mininet
98
  # make install
99

    
100
  This places the mininet package in /usr/lib/python-*/site-packages/,
101
  so that 'import mininet' will work, and installs the primary mn
102
  script (mn) as well as its helper utility (mnexec.)
103
  
104
  On Ubuntu and Debian, Mininet's dependencies and core files may also be 
105
  installed using mininet/util/install.sh -n
106

    
107
2. Installation script for Ubuntu/Debian Lenny
108

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

    
114
  Many different installation options are possible by passing different
115
  options to install.sh; install.sh -h lists them all.
116
  
117
  Assuming the mininet source tree is installed in ~/mininet, the steps to run
118
  install.sh to install EVERYTHING we use for OpenFlow tutorials are:
119
  
120
  % cd
121
  % time ~/mininet/util/install.sh  # installs tons of stuff
122
  % sudo reboot  # to load new kernel
123
  % ~/mininet/util/install.sh -c  # to clean out unneeded kernel stuff
124

    
125
  This installs a lot of useful software, but it will take a while (30
126
  minutes or more, depending on your network connection, computer, etc..)
127
 
128
  Probably the minimal semi-useful configuration would be to install 
129
  Mininet itself, kernel support if necessary, and either the 
130
  reference OpenFlow switch or Open vSwitch. This could be installed 
131
  as follows:
132
  
133
  % sudo ~/mininet/util/install.sh -knvm
134
  
135
  Respectively, this installs kernel support, core mininet dependencies,
136
  Open vSwitch, and the Open vSwitch kernel module. If a new kernel was
137
  installed, then a reboot may be required.
138

    
139
  If install.sh cannot be used for some reason (e.g. you're on Fedora
140
  or some other Linux - please don't say CentOS) or if you don't want to
141
  install all of these components (they're useful!), the kernel and
142
  OpenFlow software requirements are described in steps [3] and [4],
143
  which follow.
144

    
145
  If you successfully used install.sh, congratulations! You're basically
146
  done. Proceed to step [6] for additional advice.
147
      
148
3. Linux Kernel requirements
149

    
150
  Mininet requires a kernel built with network namespace support enabled,
151
  i.e. with CONFIG_NET_NS=Y, such as the kernel shipped with
152
  Ubuntu 10.04 LTS, currently 2.6.32. On Ubuntu 10.04, you should not need
153
  to install or build a custom kernel, although 2.6.33+ is faster at
154
  tearing down virtual ethernet pairs.
155

    
156
  For Ubuntu and Debian, we provide a 2.6.33 kernel package which you may be
157
  able to install using "util/install.sh -k". Note our kernel package
158
  requires an ext2 or ext3 root file system, so it won't work if you have
159
  a default Ubuntu install, which uses ext4.
160
  
161
  If your kernel wasn't compiled with CONFIG_NET_NS=Y, you will need to 
162
  build and install a  kernel that does! >= 2.6.33 works better, but may 
163
  be harder to get working, depending on your Linux distribution.
164
  
165
  A script for building Debian packages for 2.6.33.1 is provided in
166
  mininet/util/kbuild. You may wish to read it, as it applies patches
167
  to enable 2.6.33.1 to build under debian-stable, and to enable the
168
  tun driver to work correctly with Mininet.
169
    
170
  Earlier kernels (e.g. 2.6.29) work with CONFIG_NET_NS enabled and no
171
  additional patches, but are much slower at removing veth interfaces,
172
  resulting in much slower switch shutdown.
173

    
174
  For scalable configurations, you might need to increase some of your
175
  kernel limits. Sample params are in util/sysctl_addon, which can be
176
  appended to /etc/sysctl.conf (and modified as necessary for your
177
  desired configuration):
178

    
179
    sudo su -c "cat sysctl_addon >> /etc/sysctl.conf"
180

    
181
  To save the config change, run:
182

    
183
    sudo sysctl -p
184
    
185
4. OpenFlow software and configuration requirements
186

    
187
  Mininet requires either the reference OpenFlow switch implementation
188
  (from openflowswitch.org) or Open vSwitch (openvswitch.org) to be
189
  installed. "make test" requires the reference user space
190
  implementations as well as Open vSwitch. Note the reference kernel
191
  implementation is not currently included in OpenFlow 1.0.
192
  
193
  On Ubuntu and  Debian, the install.sh script may be used with the '-f'
194
  option to install the OpenFlow reference implementation, the '-v' option
195
  to build Open vSwitch, and the '-m' option to install the Open vSwitch
196
  kernel module into /lib/modules (note: you must build Open vSwitch first!)
197
  
198
  Mininet will automatically load and remove kernel module dependencies
199
  for supported switch types, using modprobe and rmmod - but these
200
  modules must be in a location where modprobe can find them (e.g.
201
  something like /lib/modules/`uname -r`/kernel/drivers/net/)
202

    
203
  The reference OpenFlow controller (controller(8)) only supports 16
204
  switches by default! If you wish to run a network with more than 16
205
  switches, please recompile controller(8) with larger limits, or use a
206
  different controller such as nox. A patch to controller(8) is included
207
  as util/openflow-patches/controller.patch.
208
  
209
5. Other software dependencies
210

    
211
  On Ubuntu and Debian, other Mininet dependencies may be installed using
212
  the '-n' option of the install.sh script.
213

    
214
  To run the iperf test, you need to install iperf:
215

    
216
    sudo aptitude/yum install iperf
217

    
218
  We assume you already have ping installed. ;-)
219
  
220
  To use xterm or sshd with Mininet, you need the following:
221

    
222
    sudo aptitude/yum install sshd xterm screen
223
    
224
  Some examples may have additional requirements - consult the specific
225
  example file for details.
226
  
227
  The install.sh script has an '-x' option to install the version of
228
  NOX from the OpenFlow tutorial.
229
  
230
6. Other notes and recommendations
231

    
232
  If you did not install certain useful packages and you wish to later,
233
  it may be possible to install them using install.sh.
234
  
235
  Mininet should be run either on a machine with
236
  no other important processes, or on a virtual machine (recommended!)
237
  
238
  Multiple concurrent Mininet instances are not supported!
239

    
240
Good luck!
241

    
242
---
243

    
244
Historical information on OpenFlow 0.8.9 and the reference kernel module:
245

    
246
  The kernel reference implementation has been deprecated, but it may
247
  be possible to get it work with Mininet.
248
  
249
  To switch to the most recent OpenFlow 0.8.9 release branch (the most
250
  recent one with full NOX support and kernel datapath support) in your
251
  OpenFlow git tree:
252

    
253
   git checkout -b release/0.8.9 remotes/origin/release/0.8.9
254
  
255
  A patch to enable datapath.c to compile with recent kernels
256
  is included in util/openflow-patches/datapath.patch.
257
  
258
  In OpenFlow 1.0, switch port numbering starts at 1 (for better or for worse.)
259
  To run with previous versions of OpenFlow, it may be necessary
260
  to change SWITCH_PORT_BASE from 1 to 0 in node.py.
261

    
262
  
263
  
264
  
265