
Mininet Installation/Configuration Notes
----------------------------------------

Mininet 2.3.0
---

The supported installation methods for Mininet are 1) using a
pre-built VM image, and 2) native installation on Ubuntu. You can also
easily create your own Mininet VM image (4).

(Other distributions may be supported in the future - if you would
like to contribute an installation script, we would welcome it!)

1. Easiest "installation" - use our pre-built VM image!

   The easiest way to get Mininet running is to start with one of our
   pre-built virtual machine images from <http://mininet.org/>

   Boot up the VM image, log in, and follow the instructions on the
   Mininet web site.

   One advantage of using the VM image is that it doesn't mess with
   your native OS installation or damage it in any way.

   Although a single Mininet instance can simulate multiple networks
   with multiple controllers, only one Mininet instance may currently
   be run at a time, and Mininet requires root access in the machine
   it's running on.  Therefore, if you have a multiuser system, you
   may wish to consider running Mininet in a VM.

2. Next-easiest option: use our Ubuntu package!

   To install Mininet itself (i.e. `mn` and the Python API) on Ubuntu
   16.04+:

        sudo apt-get install mininet

   Note: this may install an older version of Mininet which may not
   support Python 3. If you would like the latest version of Mininet,
   consider installing from source as described in the next section.

3. Native installation from source

   If you are running Ubuntu, Debian, or Fedora, you may be able to use
   our handy `install.sh` script, which is in `util/`. Please read the
   following sections first.

3.1. Obtaining the Mininet source code

   If you're reading this, you've probably already done so, but the
   command to download the Mininet source code is:

        git clone git://github.com/mininet/mininet.git

   Note that the above git command will check out the latest and greatest
   Mininet (which we recommend!) If you want to run the last
   tagged/released version of Mininet, you can look at the release tags
   using

        cd mininet
        git tag

    and then

        git checkout <release tag>

   where <release tag> is the release you want to check out.

3.1.1 *CAUTION: USE AT YOUR OWN RISK!*

   `install.sh` can be a bit intrusive and may possibly damage your OS
   and/or home directory, by creating/modifying several directories
   such as `mininet`, `openflow`, `oftest`, `pox`, etc.. We recommend
   trying it in a VM before trying it on a system you use from day to
   day.

   Although we hope it won't do anything completely terrible, you may
   want to look at the script before you run it, and you should make
   sure your system and home directory are backed up just in case!

   You can change the directory where the dependencies are installed
   using the -s <directory> flag.

        util/install.sh -s <directory> ...

3.1.2 Running `install.sh`

   Installing a "minimal" version of Mininet with Open vSwitch should
   be reasonably non-perturbing since it should not create directories
   for other tools:

       util/install.sh -nv

   Note this will not install a controller, so you will have to either
   install your own controller, or use a switch such OVSBridge that does
   not require a controller:

       sudo mn --switch ovsbr --test pingall

   To install Mininet itself, the OpenFlow reference controller, and
   Open vSwitch, you may use:

        util/install.sh -fnv

   This should be reasonably quick, and the following command should
   work after the installation:

        sudo mn --test pingall

3.1.3 Python 3 and Python 2 support

   Mininet supports Python 3 and Python 2. By default, `install.sh`
   will use whatever `python` is on your system.  To specify a
   specific version of Pythonm, you can set the PYTHON environment
   variable:

       PYTHON=python3 util/install.sh -fnv

   You can install Mininet for both Python 3 and Python 2:

       PYTHON=python2 util/install.sh -fnv
       PYTHON=python3 util/install.sh -n

   Whichever version was installed last will be the default for `mn`.
   As long as Mininet is installed for the appropriate version of
   Python, you can run it using that versinon of Python:

       python3 `which mn`
       python2 `which mn`

   To install ALL of the software which we use for OpenFlow tutorials,
   including POX, the OpenFlow WireShark dissector, the `oftest`
   framework, and other potentially useful software, you may use:

        util/install.sh -a

   This takes about 4 minutes on our test system.

3.2. (Experimental) Native installation from source on Fedora:

   As root execute the following operations:

    * install git

        yum install git

    * clone the Mininet repository

        git clone git://github.com/mininet/mininet.git

    * install Mininet, the OpenFlow reference implementation, and
      Open vSwitch

        util/install.sh -fnv

    * enable and start openvswitch

        sudo systemctl enable openvswitch
        sudo systemctl start openvswitch

    * test the mininet installation

        sudo mn --test pingall

    Note that `install.sh -fnv `may not install all dependencies on Fedora,
    and many tests may still fail.
    
4. Creating your own Mininet/OpenFlow tutorial VM on Ubuntu/Debian

   Creating your own Ubuntu Mininet VM for use with the OpenFlow tutorial
   is easy! First, create a new Ubuntu VM. Next, run two commands in it:

        wget https://raw.github.com/mininet/mininet/master/util/vm/install-mininet-vm.sh
        time install-mininet-vm.sh

   Finally, verify that Mininet is installed and working in the VM:

        sudo mn --test pingall

5. Installation on other Linux distributions

   Although we don't support other Linux distributions directly, it
   should be possible to install and run Mininet with some degree of
   manual effort. People have even gotten `mn --switch user` to run
   in a ChromeOS container.

   In general, you must have:

   * A Linux kernel compiled with network namespace support enabled

   * An compatible software switch such as Open vSwitch or
     the Linux bridge.

   * Python, `bash`, `ping`, `iperf`, etc.

   * Root privileges (required for network device access)

   We encourage contribution of patches to the `install.sh` script to
   support other Linux distributions.


As always, please feel free to submit issues or pull requests for
installation-related features.

Good luck, and have fun!

Mininet Developers

---
