p4app is a tool that can build, run, debug, and test P4 programs. The philosophy behind p4app is "easy things should be easy" - p4app is designed to make small, simple P4 programs easy to write and easy to share with others.
-
Install docker if you don't already have it.
-
If you want, put the
p4appscript somewhere in your path. For example:cp p4app /usr/local/bin
That's it! You're done.
p4app runs p4app packages. p4app packages are just directories with a .p4app
extension - for example, if you wrote a router in P4, you might place it in
router.p4app. Inside the directory, you'd place your P4 program, any
supporting files, and a p4app.json file that tells p4app how to run it.
This repository comes with an example p4app called simple_router.p4app. Here's
how you can run it:
p4app run examples/simple_router.p4app
If you run this command, you'll find yourself at a Mininet command prompt. p4app
will automatically download a Docker image containing the P4 compiler and tools,
compile simpler_router.p4, and set up a container with a simulated network you
can use to experiment. In addition to Mininet itself, you can use tshark,
scapy, and the net-tools and nmap suites right out of the box.
Mininet isn't the only backend that p4app supports, though. Here's another example p4app:
p4app run examples/simple_counter.p4app
If you run this command, p4app will automatically compile simple_counter.p4,
feed it a sequence of input packets defined in simple_counter.stf, and make
sure it gets the output packets it expects. This example uses the "simple
testing framework", which can help you test small P4 programs and ensure they
behave the way you expect.
A p4app package contains one program, but it can contain multiple "targets" - for example, a p4app might include several different network configurations for Mininet, an entire suite of STF tests, or a mix of the two. p4app runs the default target, well, by default, but you can specify a target by name this way:
p4app run examples/simple_router.p4app mininet
That's pretty much it! There's one more useful command, though. p4app caches the P4 compiler and tools locally, so you don't have to redownload them every time, but from time to time you may want to update to the latest versions. When that time comes, run:
p4app update
A p4app package has a directory structure that looks like this:
my_program.p4app
|
|- p4app.json
|
|- my_program.p4
|
|- ...other files...
The p4app.json file is a package manifest that tells p4app how to build and
run a P4 program; it's comparable to a Makefile. Here's one looks:
{
"program": "my_program.p4",
"language": "p4-14",
"targets": {
"mininet": {
"num-hosts": 2,
"switch-config": "my_program.config"
}
}
}
This manifest tells p4app that it should run my_program.p4, which is written
in p4-14 - that's the current version of the P4 language, though you can also
use p4-16 to use the P4-16 draft revision. It defines one target, mininet,
and it provides some Mininet configuration options: there will be two hosts on
the network, and the simulated switch will be configured using the file
my_program.config. When you reference an external file in p4app.json like
this, just place that file in the package, and p4app will make sure that the
appropriate tools can find it.
If there are multiple targets and the user doesn't specify one by name, p4app
will run one of the targets, chosen arbitrarily. You can set the default target
to be run using the default-target option. Here's an example with several
targets:
{
"program": "my_program.p4",
"language": "p4-14",
"default-target": "debug",
"targets": {
"debug": { "use": "mininet", "num-hosts": 2 },
"test1": { "use": "stf", "test": "test1.stf" },
"test2": { "use": "stf", "test": "test2.stf" },
}
}
This defines one Mininet target, "debug", and two STF targets, "test1" and
"test2". The use field specifies which backend a target uses; if you don't
provide it, the target name is also used as the backend name. That's why, in
the previous example, we didn't have to specify "use": "mininet" - the
target's name is mininet, and that's enough for p4app to know what you mean.
That's really all there is to it. There's one final tip: if you want to share a
p4app package with someone else, you can run p4app pack my-program.p4app, and
p4app will compress the package into a single file. p4app can run compressed
packages transparently, so the person you send it to won't even have to
decompress it. If they want to take a look at the files it contains, though,
they can just run p4app unpack my-program.p4app, and p4app will turn the
package back into a directory.
This backend compiles a P4 program, loads it into a BMV2 simple_switch, and creates a Mininet environment that lets you experiment with it.
The following configuration values are supported:
"mininet": {
"num-hosts": 2,
"switch-config": "file.config"
}
All are optional.
The Mininet network will use a star topology, with num-hosts hosts each
connected to your switch via a separate interface.
You can load a configuration into your switch at startup using switch-config;
the file format is just a sequence of commands for the BMV2
simple_switch_CLI.
During startup, messages will be displayed telling you information about the network configuration and about how to access logging and debugging facilities. The BMV2 debugger is especially handy; you can read up on how to use it here.
This target also supports the configuration values for the compile-bvm2 target.
Like mininet, this target compiles a P4 program and runs it in a Mininet
environment. Moreover, this target allows you to run multiple switches with a
custom topology and execute arbitrary commands on the hosts. The switches are
automatically configured with l2 and l3 rules for routing traffic to all hosts
(this assumes that the P4 programs have the ipv4_lpm, send_frame and
forward tables). For example:
"multiswitch": {
"links": [
["h1", "s1"],
["s1", "s2"],
["s2", "h2", 50]
],
"hosts": {
"h1": {
"cmd": "python echo_server.py $port",
"startup_sleep": 0.2,
"wait": false
},
"h2": {
"cmd": "python echo_client.py h1 $port $echo_msg",
"wait": true
}
},
"parameters": {
"port": 8000,
"echo_msg": "foobar"
}
}
This configuration will create a topology like this:
h1 <---> s1 <---> s2 <---> h2
where the s2-h2 link has a 50ms artificial delay. The hosts can be configured
with the following options:
cmd- the command to be executed on the host.wait- wait for the command to complete before continuing. By setting it to false, you can start a process on the host in the background, like a daemon/server.startup_sleep- the amount of time (in seconds) that should be waited after starting the command.latency- the latency between this host and the switch. This can either be a number (interpreted as seconds) or a string with time units (e.g.50msor1s). This overrides the latency set in thelinksobject.
The command is formatted by replacing the hostnames (e.g. h1) with the
corresponding IP address. The parameters specified in the target will be
available to the command as environment variables (i.e. $ followed by the
variable name). For an example, have a look at the
manifest for the multiswitch example
app.
Currently, each host can be connected to at most one switch.
The routing tables (ipv4_lpm, send_frame and forward) are automatically
populated with this target. Additionally, you can specify custom commands to be
run on each switch. You can either include a commands file, or an array of
commands. These custom commands will be sent before the automatically
generated ones for the routing tables. For example:
"multiswitch": {
"links": [ ... ],
"hosts": { ... },
"switches": {
"s1": {
"commands": "s1_commands.txt"
},
"s2": {
"commands": [
"table_add ipv4_lpm set_nhop 10.0.1.10/32 => 10.0.1.10 1",
"table_add ipv4_lpm set_nhop 10.0.2.10/32 => 10.0.2.10 2"
]
}
}
}
If the commands for s2 above overlap with the automatically generated commands
(e.g. there is an automatic entry for set_nhop 10.0.1.10/32), these custom
commands will have precedence and you will see a warning about a duplicate entry
while the tables are being populated.
Instead of letting this target create the mininet Topo class, you can use your
own. Specify the name of your module with the topo_module option. For example:
"multiswitch": {
...
"topo_module": "mytopo"
...
}
This will import the mytopo module, mytopo.py, which should be in the same
directory as the manifest file (p4app.json). The module should implement the
class CustomAppTopo. It can extend the default topo class,
apptopo.AppTopo. For example:
# mytopo.py
from apptopo import AppTopo
class CustomAppTopo(AppTopo):
def __init__(self, *args, **kwargs):
AppTopo.__init__(self, *args, **kwargs)
print self.links()
See the customtopo.p4app working example.
Similarly to the topo_module option, you can specify a controller with the
controller_module option. This module should implement the class
CustomAppController. The default controller class is
appcontroller.AppController. You can
extend this class, as shown in the
customtopo.p4app example.
The AppProcRunner class is responsible for executing programs in each of the
mininet hosts. By specifying the controller_module option, you can override
the default behaviour for launching and killing programs on the hosts. This
module should implement the class CustomAppProcRunner. The default controller
class is
appprocrunner.AppProcRunner. You can
extend this class, as shown in the
customtopo.p4app example.
When this target is run, a temporary directory on the host, /tmp/p4app_log,
is mounted on the guest at /tmp/p4app_log. All data in this directory is
persisted to the host after running the p4app. The stdout from the hosts'
commands is stored in this location. If you need to save the output (e.g. logs)
of a command, you can also put that in this directory.
To save the debug logs from the P4 switches, set "bmv2_log": true in the
target. To capture PCAPs from all switches, set "pcap_dump": true. These
files will be saved to /tmp/p4app_log. For example usage, see the
manifest for the broadcast example app.
If you need to execute commands in the docker container after running the
target (and before Mininet is stopped), you can use after. after should
contain cmd, which can either be a command or a list of commands. For
example:
"multiswitch": {
"links": [ ... ],
"hosts": { ... },
"after": {
"cmd": [
"echo register_read my_register 1 | simple_switch_CLI --json p4src/my_router.p4.json",
"echo register_read my_register 2 | simple_switch_CLI --json p4src/my_router.p4.json"
]
}
}
This is a third method for compiling a P4 program to run in a Mininet
environment. This target allows you to specify a Python program that
uses Mininet's Python API to specify the network topology and configuration.
For example:
{
"program": "source_routing.p4",
"language": "p4-14",
"targets": {
"custom": {
"program": "topo.py"
}
}
}
This target will invoke the python script topo.py to start Mininet.
The program will be called with the following arguments:
| Argument | Description |
|---|---|
| --behavioral-exe | Value will be the switch executable |
| --json | Value will be the P4 compiler output |
| --cli | Value will be the switch command line interface program |
Example invocation:
PYTHONPATH=$PYTHONPATH:/scripts/mininet/ python2 topo.py \
--behavioral-exe simple_switch \
--json SOME_FILE \
--cli simple_switch_CLI
You can specify additional arguments to pass to your custom topology program by
including them in your program definition as follows:
{
"program": "source_routing.p4",
"language": "p4-14",
"targets": {
"custom": {
"program": "topo.py --num-hosts 2 --switch-config simple_router.config"
}
}
}
The program can find the docker container ID in the HOSTNAME environment
variable so that it can output useful commands for copy/paste:
import os
container = os.environ['HOSTNAME']
print 'Run the switch CLI as follows:'
print ' docker exec -t -i %s %s' % (container, args.cli)This target compiles the provided P4 program and run a test against it written for the STF testing framework.
There is one configuration value, which is required:
"stf": {
"test": "file.stf"
}
You must write the file specified by test in the STF format, which is
unfortunately currently undocumented. (If you'd like to reverse engineer it and
provide some documentation, please submit a PR!) You can take a look at the
example p4apps included in this repo to get a sense of the basics.
This target also supports the configuration values for the compile-bvm2 target.
This is a simple backend that just attempts to compile the provided P4 program for the BMV2 architecture.
The following optional configuration values are supported:
"compile-bmv2": {
"compiler-flags": ["-v", "-E"],
"run-before-compile": ["date"],
"run-after-compile": ["date"]
}
If you're hacking on the P4 toolchain or p4app itself, you may want to use a
modified Docker image instead of the standard p4lang one. That's easy to do;
just set the P4APP_IMAGE environment variable to the Docker image you'd like
to use. For example:
P4APP_IMAGE=me/my_p4app_image:latest p4app run examples/simple_router.p4app
By default, p4app will use the manifest file called p4app.json in the app's
directory. If your manifest file is not called p4app.json, you can use the
--manifest option to specify the name of the manifest. For example:
p4app run myapp.p4app --manifest testing.p4app
By default, p4app will mount the directory /tmp/p4app_logs on the host to
/tmp/p4app_logs on the docker container guest. The output from bmv2, as well
as any output from your programs, will be saved to this directory. Instead of
using the default directory (/tmp/p4app_logs), you can specify another
directory with the $P4APP_LOGDIR environment variable. For example, if you
run:
P4APP_LOGDIR=./out p4app run myapp.p4app
all the log files will be stored to ./out.
To run commands interactively on a currently running p4app, you can use
p4app exec command arg1 arg2 ...
This will run a command in a currently running p4app instance. If there are multiple instances running, the command will be executed on the most recently started p4app.
To run a command on a Mininet host, you can use the Mininet m utility script,
which is included in p4app. For example, run ping on Mininet host h1:
p4app exec m h1 ping 10.0.2.101
You can also run tcpdump on the Mininet host to see packets in realtime with
Wireshark:
p4app exec m h1 tcpdump -Uw - | wireshark -ki -