P4 Tutorial

• Introduction
• Presentation
• P4 Documentation
• Obtaining required software
  • To build the virtual machine
  • Accessing the VM
  • To install P4 development tools on an existing system
• How to Contribute
• Older tutorials

If you are reading this while not attending a live P4 tutorial class, see below for links to information about recently given live classes.

Introduction

Welcome to the P4 Tutorial! We've prepared a set of exercises to help you get started with P4 programming, organized into several modules:

1. Introduction and Language Basics

   • Basic Forwarding
     In this exercise, you'll learn to implement basic IPv4 packet forwarding using P4. By extending the provided basic.p4 skeleton, you'll develop logic for updating MAC addresses, decrementing TTL values, and forwarding packets based on predefined rules. Through practical implementation and testing on a fat-tree topology in Mininet, you'll gain insights into designing and deploying data plane logic for network switches.

   • Basic Tunneling
     In this exercise, you enhance an IP router implemented in P4 by adding basic tunneling support, enabling encapsulation of IP packets for customized forwarding. By introducing a new tunnel header type, you modify the switch code to handle encapsulated packets and define forwarding rules based on destination IDs. Through static control plane entries, the switch routes encapsulated packets, showcasing P4's versatility in customizing packet processing and network functionality.

2. P4Runtime and the Control Plane

   • P4Runtime
     This exercise involves implementing a control plane using P4Runtime to send flow entries to switches for tunneling traffic between hosts. Students modify the provided P4 program and controller script to establish connections, push P4 programs, install tunnel ingress rules, and read tunnel counters, enhancing their understanding of P4Runtime and network forwarding logic.

3. Monitoring and Debugging

   • Explicit Congestion Notification
     In this tutorial, you'll enhance a basic L3 forwarding P4 program with Explicit Congestion Notification (ECN) support, enabling end-to-end notification of network congestion without packet drops. By modifying the ecn.p4 file, you'll implement ECN logic such as updating the ECN flag based on queue length thresholds and configuring static rules for proper ECN handling, followed by testing the solution in Mininet to verify packet forwarding and ECN flag manipulation.

   • Multi-Hop Route Inspection
     This tutorial aims to augment basic L3 forwarding with a simplified version of In-Band Network Telemetry (INT) called Multi-Hop Route Inspection (MRI). It guides users through extending a skeleton P4 program, mri.p4, to append an ID and queue length to the header stack of every packet, enabling tracking of the packet's path and queue lengths.

4. Advanced Behavior

   • Source Routing
     This exercise aims to implement source routing, where the source host specifies the route for each packet through a stack of output ports. After configuring the P4 program, source_routing.p4, packets should be routed according to the specified port numbers in the stack, enabling end-to-end delivery based on the predetermined path.

   • Calculator
     This tutorial guides you through implementing a basic calculator using a custom protocol header in P4. The P4 program, calc.p4, parses incoming calculator packets, performs the specified operation on the operands, and returns the result to the sender, enabling basic arithmetic calculations in a network switch.

   • Load Balancing
     This exercise guides you in implementing load balancing using Equal-Cost Multipath Forwarding in a P4 program named load_balance.p4. It utilizes a hash function to distribute packets between two destination hosts based on a 5-tuple hash, enabling efficient traffic distribution across the network.

   • Quality of Service
     This tutorial focuses on implementing Quality of Service (QoS) using Differentiated Services (Diffserv) in a P4 program named qos.p4. It extends basic L3 forwarding to classify and manage network traffic, providing QoS on modern IP networks by setting DiffServ flags based on traffic classes and priority.

   • Multicasting
     This exercise involves writing a P4 program to enable a network switch to multicast packets to multiple output ports based on the destination MAC address. It requires the implementation of logic to handle multicast packets, including defining actions for packet forwarding and configuring the control plane to manage packet processing rules. Through practical implementation and testing in a Mininet environment, participants learn to enhance network traffic management and efficiency through multicast communication.

5. Stateful Packet Processing

   • Firewall
     This exercise focuses on implementing a basic stateful firewall using a P4 program named firewall.p4. The firewall is designed to allow communication between internal and external hosts based on predefined rules, utilizing a bloom filter for stateful packet inspection and filtering.

   • Link Monitoring
     This exercise focuses on implementing link monitoring within a network using P4 programming. By extending the basic IPv4 forwarding exercise, the program enables the measurement of link utilization by processing source-routed probe packets. Through the manipulation of probe packet headers and the maintenance of register arrays, the solution facilitates accurate monitoring of link utilization, which can be invaluable for network management and optimization.

Presentation

The slides are available online and in the P4_tutorial.pdf in the tutorial directory.

A P4 Cheat Sheet is also available online which contains various examples that you can refer to.

P4 Documentation

The documentation for P4_16 and P4Runtime is available here

All exercises in this repository use the v1model architecture, the documentation for which is available at:

1. The BMv2 Simple Switch target document accessible here talks mainly about the v1model architecture.
2. The include file v1model.p4 has extensive comments and can be accessed here.

Obtaining required software

If you are starting this tutorial at one of the proctored tutorial events, then we've already provided you with a virtual machine that has all of the required software installed. Ask an instructor for a USB stick with the VM image.

Otherwise, to complete the exercises, you will need to do one of the following:

• Download and run a virtual machine with the P4 development tools already installed.
• Build a virtual machine, compiling and installing the P4 development tools within it.
• Install the P4 development tools on an existing system with a supported version of Ubuntu Linux.

Download a virtual machine with the P4 development tools already installed

You will need a system with a 64-bit Intel/AMD processor architecture, with VirtualBox installed on it. See the table here for a list of virtual machine images that you can download, then use VirtualBox's File->Import Appliance menu item to add the virtual machine to those on your system.

To build a virtual machine with the P4 development tools.

Requirements

• Vagrant
• VirtualBox
• At least 12 GB of free disk space, otherwise the installation can fail in unpredictable ways.

Installation Steps

1. Install Vagrant and VirtualBox on your system.
2. Clone the repository

   git clone https://github.com/p4lang/tutorials.git
   

3. Navigate to the cloned directory :

   cd vm-ubuntu-24.04
   

4. Start the virtual machine using Vagrant:

   vagrant up dev
   

   Note : The time for this step depends on your computer and Internet speed. On a 2019 Intel MacBook Pro with a 1 Gbps download speed, it took approximately 2 hours. Ensure a stable Internet connection throughout the process.

Accessing the VM

• There are two user accounts:
  • Username: vagrant | Password: vagrant (This is the default account)
  • Username: p4 | Password: p4 (Usage of this account is expected)

Note: Before running the vagrant up command, make sure you have enabled virtualization in your environment; otherwise you may get a "VT-x is disabled in the BIOS for both all CPU modes" error. Check this for enabling it in virtualbox and/or BIOS for different system configurations.

You will need the script to execute to completion before you can see the p4 login on your virtual machine's GUI. In some cases, the vagrant up command brings up only the default vagrant login with the password vagrant. Dependencies may or may not have been installed for you to proceed with running P4 programs. Please refer the existing issues to help fix your problem or create a new one if your specific problem isn't addressed there.

To install P4 development tools on an existing system

There are instructions and scripts in another Github repository that can, starting from a freshly installed Ubuntu 20.04, 22.04, or 24.04 Linux system with enough RAM and free disk space, install all of the necessary P4 development tools to run the exercises in this repository. You can find those instructions and scripts here (note that you must clone a copy of that entire repository in order for its install scripts to work).

How to Contribute

We value and welcome new contributions. To get started, kindly look at our Contribution Guidelines.

Older tutorials

Multiple live tutorial classes have been given using the example code in this repository for hands-on exercises. For example, there is one each April or May at the P4 workshop at Stanford University in California, and there have been several at networking conferences such as ACM SIGCOMM.

Please create an issue for this tutorials repository if you know a public link for classroom video recordings and/or pre-built VM images that currently do not have such a link.

ACM SIGCOMM August 2019 Tutorial on Programming the Network Data Plane

You can find more information about the ACM SIGCOMM August 2019 Tutorial on Programming the Network Data Plane here

The page linked above has a link to download a pre-built VM image used for this class, as well as instructions to build one yourself from a particular branch of this repository.

P4 Developer Day, April 2019

You can find more information about the P4 Developer Day held in April 2019 here

Both a beginner and advanced class were taught at this event. The page linked above contains instructions to download and install a pre-built Linux VM that was used during the classes.

P4 Developer Day, November 2017

This link plays the first welcome video of a series of 6 videos of tutorials given at this event.

More information about this event can be found here.