Statistics
| Branch: | Tag: | Revision:

mininet / INSTALL @ ee7ee406

History | View | Annotate | Download (9.9 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 and its kernel module
55
    $ mininet/util/install.sh -vm
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
e) Install mininet and its dependencies:
61
    $ mininet/util/install.sh -n
62

    
63
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

    
67
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

    
70
---
71

    
72
Mininet Manual Installation Notes
73

    
74
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

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

    
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
  git clone git://openflow.org/mininet.git
90
     
91
1. Core Mininet installation
92

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

    
98
  To install Mininet itself, with root privileges:
99
  
100
  # cd mininet
101
  # make install
102

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

    
110
2. Installation script for Ubuntu/Debian Lenny
111

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

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

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

    
142
  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
  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
  If you successfully used install.sh, congratulations! You're basically
149
  done. Proceed to step [6] for additional advice.
150
      
151
3. Linux Kernel requirements
152

    
153
  Mininet requires a kernel built with network namespace support enabled,
154
  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
  able to install using "util/install.sh -k". Note our kernel package
161
  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
  
164
  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
  
168
  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
  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
  resulting in much slower switch shutdown.
176

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

    
182
    sudo su -c "cat sysctl_addon >> /etc/sysctl.conf"
183

    
184
  To save the config change, run:
185

    
186
    sudo sysctl -p
187
    
188
4. OpenFlow software and configuration requirements
189

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

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

    
214
  On Ubuntu and Debian, other Mininet dependencies may be installed using
215
  the '-n' option of the install.sh script.
216

    
217
  To run the iperf test, you need to install iperf:
218

    
219
    sudo aptitude/yum install iperf
220

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

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

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

    
243
Good luck!
244

    
245
---
246

    
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