Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Getting Started with MidoNet
This guide intends to easily get you started with using MidoNet.
Try MidoNet with Quickstart
For the impatient users; we have a fast path to get started. This is not intended for production environments.
MidoNet Quickstart enables you to start an all-in-one node OpenStack + MidoNet environment with a single command. It installs MidoNet and OpenStack from packages and configures/runs OpenStack to use MidoNet as the Neutron plugin.
Use the following command on a 64-bit Ubuntu 14.04 environment to run the MidoNet Quickstart:
$ curl -sL https://quickstart.midonet.org | sudo bash
This command will install MidoNet with OpenStack. Once finished, you will be told how to log into Horizon.
Get familiar with MidoNet
In order to install MidoNet you will need to be familiar with the basic concepts of MidoNet.
We recommend you read the following:
Before you start
As any software, MidoNet has prerequisites that must be carefully reviewed before the install.
There are two ways to install MidoNet: building from source or downloading packages.
In addition of the nightly builds, packages of community supported versions will be available soon.
See the Release Schedule for details.
Install from sources
The install from sources is only recommended if you want to install MidoNet on an unsupported distribution.
Follow the Install from sources guide.
Install from packages
This is the recommended way to install MidoNet for production, pre-production or lab environments.
To install MidoNet on Ubuntu, refer to the Quick Start Guides.
Those who would like to try out MidoNet on operating systems derived from RHEL or Fedora, such as CentOS, Scientific Linux and others may use the same procedure as that for RHEL, above, with the exceptions outlined here: guide on RDO wiki.
Building Packages Quickstart
This quick start guide will install the necessary prerequisites and build dependencies needed for MidoNet, then build the project and all its modules. On an Ubuntu 14.04.2 LTS with 4 CPUs, 8Gb RAM and 40Gb Disk space, the time needed to build the Debian and RPM packages is roughly 7 minutes without tests. Note that the quality of internet connection and availability of resources needed from the internet can effect this value. To install protobuf takes roughly 5 minutes.
~$ sudo apt-get install git -y ~$ git clone https://github.com/midonet/midonet ~$ echo | sudo add-apt-repository ppa:openjdk-r/ppa ~$ sudo apt-get update ~$ sudo apt-get install openjdk-8-jdk -y ~$ sudo apt-get install ruby-dev build-essential -y ~$ sudo apt-get install -y ruby rpm ruby-ronn && sudo gem install fpm ~$ wget https://github.com/google/protobuf/releases/download/v2.6.1/protobuf-2.6.1.tar.gz ~$ tar -xzf protobuf-2.6.1.tar.gz ~$ cd protobuf-2.6.1 ~$ ./configure ~$ make ~$ sudo make install ~$ sudo ldconfig ~$ cd - ~$ rm -rf protobuf-2.6.1 ~$ rm protobuf-2.6.1.tar.gz ~$ cd midonet ~/midonet$ ./gradlew debian -x test ~/midonet$ ./gradlew rpm -x test
The resulting packages can be found in the following locations:
./midolman/build/packages/midolman***.deb ./midonet-cluster/build/packages/midonet-cluster***.deb ./python-midonetclient/python-midonetclient***.deb ./midonet-util/build/packages/midonet-tools***.deb ./midolman/build/packages/midolman-5.0-0.0.***.el7.noarch.rpm ./cluster/midonet-cluster/build/packages/midonet-cluster-5.0-0.0.***.el7.noarch.rpm ./python-midonetclient/python-midonetclient-5.0-0.0.***.el7.noarch.rpm
Getting up to speed with MidoNet
Before you can start playing around with MidoNet, log in to the OpenStack dashboard (Horizon) as a cloud administrative user, and create a MidoNet project with these pieces in place:
- admin user
- security group with some rules
- private network
- external network
- tenant router
- VM with an associated floating IP address
For detailed procedures refer to the OPENSTACK ADMIN USER GUIDE:
Note: All the examples provided here require access to the MidoNet CLI.
Launching the MidoNet CLI
In the terminal of the host running the MidoNet CLI enter the command:
The second line (midonet>) is the familiar MidoNet CLI prompt where you can type in commands. It will accompany you throughout this tutorial.
MidoNet Provider Router
The MidoNet Provider Router is created automatically. It connects your tenant router(s) with an external network. The connection between the MidoNet Provider Router and the external network is also created automatically. The Provider Router does not have any tenant (project) associated that's why you can view it directly after you log it to the MidoNet CLI:
midonet> list router
router router1 name MidoNet Provider Router state up
Listing the Provider Router's ports
To list the port on the MidoNet Provider Router, enter the command:
midonet> router router1 list port
port port0 device router1 state up mac 02:fb:21:dc:49:62 address 169.254.255.1 net 169.254.255.0/30 peer router0:port0
port port1 device router1 state up mac 02:f3:fa:89:34:c6 address 198.51.100.1 net 198.51.100.0/24 peer bridge0:port0
The above output reveals the following information:
- port0 is peered with router0 (tenant-router) via the 169.254.255.1 link-local address.
- port1 is peered with port0 on bridge0.
Selecting your project
To select the project (tenant) that you created in OpenStack issue this command:
midonet> pusht <your-project-id>
where <your-project-id> is your project's ID in OpenStack. For example:
midonet> pusht 031ac72f54ee434a9079c1fc0baddacf
Listing tenant bridges
To display the list of bridges (networks) for the selected tenant, enter the command:
midonet> bridge list
bridge bridge0 name my-private-network state up
The output shows:
- The alias (bridge0) for the private network you created in OpenStack (my-private-network).
- The bridge's state is up.
Listing tenant routers
To obtain the information about the router(s) for the current tenant, enter the command:
midonet> router list
router router0 name tenant-router state up infilter chain0 outfilter chain1
The output reveals the following information:
- There is just one router, alias (router0). This is the tenant router that you created in OpenStack, named tenant-router.
- The tenant-router's state is up.
- Two rule chains are associated with the router: an infilter (pre-routing) and outfilter (post-routing) chain. They were created automatically.
Viewing pre-routing rule information
To display information about the router's pre-routing rule chain, enter the command:
midonet> chain chain0 list rule
rule rule0 dst 198.51.100.3 proto 0 tos 0 in-ports router0:port0 pos 1 type dnat action accept target 172.16.3.3
rule rule1 dst 198.51.100.2 proto 0 tos 0 in-ports router0:port0 pos 2 type rev_snat action accept
Viewing post-routing rule information
To display information about the post-routing rule chain, enter the command:
midonet> chain chain1 list rule
rule rule0 src 172.16.3.3 proto 0 tos 0 out-ports router1:port0 pos 1 type snat action accept target 198.51.100.3
rule rule1 proto 0 tos 0 out-ports router1:port0 pos 2 type snat action accept target 198.51.100.2:1
Getting router port information
To view information about the ports on the tenant-router (router0), enter the command:
midonet> router router0 list port
port port0 device router0 state up mac 02:77:ae:ff:d8:20 address 169.254.255.2 net 169.254.255.0/30 peer router1:port0
port port1 device router0 state up mac 02:4c:f1:ed:6b:df address 172.16.3.1 net 172.16.3.0/24 peer bridge0:port0
The output shows the following information about the two ports on router0:
- Both ports are up, and their MAC addresses and assigned IP and network addresses are listed.
- port0 is connected to port 0 on router1. 169.254.255.2 is a link-local address and the 169.254.255.0/30 network is an address in the link-local address block. This is one of the interfaces that are automatically created to connect virtual routers.
- port1 is connected to port0 on bridge0. This is the network:router_interface for the private network you configured on OpenStack, demo-private-net (bridge0).
Viewing route information
Routes are set up automatically for you when you configure your network in OpenStack, so you probably won't need to modify them. If you need to view the information about the routes configured on the tenant router, run this command:
midonet> router router0 list route
route route0 type normal src 0.0.0.0/0 dst router0:port0 weight 0
route route1 type normal src 0.0.0.0/0 dst weight 100
route route2 type normal src 0.0.0.0/0 dst router0:port1 weight 100
route route3 type normal src 172.16.3.0/24 172.16.3.2 port router0:port1 weight 100
route route4 type normal src 0.0.0.0/0 dst router0:port1 weight 0
A tunnel zone is an isolation zone for hosts. Physical hosts in the same tunnel zone, can communicate directly with one another. MidoNet supports two types of tunnel zones for separating physical hosts in the underlay, GRE (default) and VXLAN.
To create a tunnel zone use the command:
create tunnel-zone name <tz-name> type <tz-type>
where tz-type is tunnel zone type, gre or vxlan. For example:
midonet> create tunnel-zone name gre-tunnel-zone type gre
Getting a list of hosts
To admit a host into a tunnel zone first get the list of all the available hosts. For example:
midonet> list host
host host0 name compute-1 alive true
host host1 name compute-2 alive true
Admitting a host to tunnel zone
To admit a host into a tunnel zone you need to add one of its interfaces to it.
First get the list of all the host's interfaces by using the command:
host <host-alias> list interface
where <host-alias> is the host alias obtained earlier by issuing the
host list command. For example:
midonet> host host0 list interface
iface lo host_id host0 status 3 addresses [u'127.0.0.1', u'0:0:0:0:0:0:0:1'] /
mac 00:00:00:00:00:00 mtu 65536 type Virtual endpoint LOCALHOST
iface eth0 host_id host0 status 3 addresses [u'10.1.2.200', u'fe80:0:0:0:250:56ff:fe93:c9a4'] /
mac 00:50:56:93:c9:a4 mtu 1500 type Physical endpoint PHYSICAL
Take note of the IP address of the interface that you want to add to the tunnel zone.
Add host0 as a new member of the tunnel zone tzone0 using this command:
midonet> tunnel-zone tzone0 add member host host0
Specify the IP of the interface on host0 that you want to add to tzone0:
midonet> tunnel-zone tzone0 add member host host0 address 10.1.2.200
In the above command:
- tzone0 = the tunnel zone you want to add the member (host) to
- host0 = the alias of the host you want to add
- 10.1.2.200 = the IP address of the host you want to add
Getting tunnel zone information
To display information about a tunnel zone, issue this command:
midonet> tunnel-zone tzone0 list member
zone tzone0 host host0 address 10.1.2.200
The command output shows the following information:
- The name of the tunnel zone in question (tzone0)
- The alias of the host(s) in the tunnel zone (for now, there's just one host in it, host0)
- The IP address assigned to the host(s)
Go further with MidoNet
See the MidoNet operations guide and API reference in the Documentation site.
In particular, you will find in the operations guide instructions to setup the gateway nodes using BGP.