mirror of
https://github.com/opennetworkinglab/onos.git
synced 2025-10-15 09:21:06 +02:00
126 lines
5.4 KiB
Markdown
126 lines
5.4 KiB
Markdown
# ONOS+P4 Tutorial
|
|
|
|
This directory contains source code and instructions to run the ONOS+P4
|
|
tutorial exercises. Goal of the exercises is to learn how to use ONOS to control
|
|
P4-capable devices via P4Runtime, and how to write ONOS apps to control custom
|
|
data plane capabilities implemented in P4.
|
|
|
|
For help, please write to the mailing list
|
|
[brigade-p4@onosproject.org](mailto:brigade-p4@onosproject.org) or check the
|
|
[mailing list archives](https://groups.google.com/a/onosproject.org/forum/#!forum/brigade-p4).
|
|
|
|
## Tutorial VM
|
|
|
|
To complete the exercises, you will need to download and run the following VM
|
|
(in .ova format):
|
|
|
|
<http://onlab.vicci.org/onos/onos-p4-tutorial.ova>
|
|
|
|
To run the VM you can use any modern virtualization system, although we
|
|
recommend using VirtualBox. To download VirtualBox and import the VM use the
|
|
following links:
|
|
|
|
* <https://www.virtualbox.org/wiki/Downloads>
|
|
* <https://docs.oracle.com/cd/E26217_01/E26796/html/qs-import-vm.html>
|
|
|
|
For more information on the content of the VM and minimum system requirements,
|
|
[click here](/tools/dev/p4vm/README.md).
|
|
|
|
### VM credentials
|
|
|
|
The VM comes with one user with sudo privileges. Use these credentials to log in:
|
|
|
|
* Username: `sdn`
|
|
* Password: `rocks`
|
|
|
|
## Overview
|
|
|
|
### mytunnel.p4
|
|
|
|
These exercises are based on a simple P4 program called
|
|
[mytunnel.p4](./pipeconf/src/main/resources/mytunnel.p4) designed for this
|
|
tutorial.
|
|
|
|
To start, have a look a the P4 program. Even if this is the first time you
|
|
see P4 code, the program has been commented to provide an understanding of the
|
|
pipeline behavior to anyone with basic programming and networking background.
|
|
While checking the P4 program, try answering the following questions:
|
|
|
|
* Which protocol headers are being extracted from each packet?
|
|
* How can the parser distinguish a packet with MyTunnel encapsulation from one
|
|
without?
|
|
* How many match+action tables are defined in the P4 program?
|
|
* What is the first table in the pipeline applied to every packet?
|
|
* Which headers can be matched on table `t_l2_fwd`?
|
|
* Which type of match is applied to `t_l2_fwd`? E.g. exact match, ternary, or
|
|
longest-prefix match?
|
|
* Which actions can be executed on matched packets?
|
|
* Which action can be used to send a packet to the controller?
|
|
* What happens if a matching entry is not found in table `t_l2_fwd`? What's the
|
|
next table applied to the packet?
|
|
|
|
[Click here to see the solution to these questions](./questions.md)
|
|
|
|
### MyTunnel Pipeconf
|
|
|
|
The `mytunnel.p4` program is provided to ONOS as part of a "pipeconf".
|
|
|
|
The main class used to implement the pipeconf is
|
|
[PipeconfFactory.java](./pipeconf/src/main/java/org/onosproject/p4tutorial/pipeconf/PipeconfFactory.java).
|
|
This class is declared as an OSGi runtime component which is "activated" once
|
|
the pipeconf app is loaded in ONOS. The main purpose of this class is to
|
|
instantiate the Pipeconf object and register that with the corresponding service
|
|
in ONOS. This is where we associate ONOS driver behaviors with the pipeconf, and
|
|
also define the necessary pipeconf extensions to be able to deploy the P4
|
|
program to a device.
|
|
|
|
This pipeconf contains:
|
|
|
|
* [mytunnel.json](/apps/p4-tutorial/pipeconf/src/main/resources/mytunnel.json):
|
|
The JSON configuration used to execute the P4 program on BMv2. This is an output
|
|
of the P4 compiler for BMv2.
|
|
|
|
* [mytunnel.p4info](/apps/p4-tutorial/pipeconf/src/main/resources/mytunnel.p4info):
|
|
P4Info file obtained from the P4 compiler.
|
|
|
|
* [PipelineInterpreterImpl.java](./pipeconf/src/main/java/org/onosproject/p4tutorial/pipeconf/PipelineInterpreterImpl.java):
|
|
Implementation of the `PipelineInterpreter` ONOS driver behavior. The main
|
|
purpose of this class is to provide a mapping between ONOS constructs and P4
|
|
program-specific ones, for example methods to map ONOS well-known header fields
|
|
and packet forwarding/manipulation actions to those defined in the P4 program.
|
|
For a more detailed explanation of each method, check the
|
|
[PipelineInterpreter interface](./core/api/src/main/java/org/onosproject/net/pi/model/PiPipelineInterpreter.java).
|
|
|
|
* [PortStatisticsDiscoveryImpl.java](./pipeconf/src/main/java/org/onosproject/p4tutorial/pipeconf/PipelineInterpreterImpl.java):
|
|
Implementation of the `PortStatisticsDiscovery` ONOS driver behavior. As the
|
|
name suggests, this behavior is used to report statistics on the switch ports to
|
|
ONOS, e.g. number of packets/bytes received and transmitted for each port. This
|
|
implementation works by reading the value of two P4 counters defined in
|
|
`mytunnel.p4`, `tx_port_counter` and `rx_port_counter`.
|
|
|
|
### MyTunnel App
|
|
|
|
This app is used to provide connectivity between each pair of hosts via the
|
|
MyTunnel protocol, a non-standard tunneling protocol created for this exercise.
|
|
The implementation of this app can be found
|
|
[here](./mytunnel/src/main/java/org/onosproject/p4tutorial/mytunnel/MyTunnelApp.java),
|
|
and it will be discussed in more details on Exercise 2.
|
|
|
|
## Tutorial exercises
|
|
|
|
### Exercise 1
|
|
|
|
[Click here to go to this exercise instructions](./exercise-1.md)
|
|
|
|
This exercise shows how to start ONOS and Mininet with BMv2, it also
|
|
demonstrates connectivity between hosts using the pipeline-agnostic app
|
|
Reactive Forwarding, in combination with other well known ONOS services such as
|
|
Proxy ARP, Host Location Provider, and LLDP Link Discovery.
|
|
|
|
### Exercise 2
|
|
|
|
[Click here to go to this exercise instructions](./exercise-2.md)
|
|
|
|
Similar to exercise 1, but here connectivity between hosts is demonstrated using
|
|
pipeline-specific app "MyTunnel".
|