Session

Tutorial: Using Packetdrill to Write Automated Tests for the Linux Networking Stack

Session Type: Tutorial (instructor-led)

Duration: 60 minutes

Label: nuts and bolts

Title: Tutorial: Using Packetdrill to Write Automated Tests for the Linux Networking Stack

Abstract:

This tutorial will provide a hands-on introduction to Packetdrill. The Packetdrill open-source scripting tool enables quick, precise, reproducible, automated unit tests for entire TCP/UDP/IPv4/IPv6 network stacks, from the system call layer down to the NIC hardware. Packetdrill works on Linux, FreeBSD, OpenBSD, and NetBSD. It can test network stack behavior over physical NICs on a LAN, or (for speed and ease of use) on a single machine using a tun virtual network device. This tutorial aims to introduce Packetdrill and explain how to use it for network stack development, troubleshooting, and automated regression testing.

This tutorial will cover the following topics:

• Introduction to Packetdrill:
  • What is Packetdrill?
  • What are the goals of Packetdrill? What is it useful for? What is it not useful for?
  • How does Packetdrill work? An overview of Packetdrill’s architecture, implementation, and key features.
  • Understanding the Packetdrill scripting language, including syntax and semantics.
• Hands-on Packetdrill Basics:
  • Downloading, installing, and building Packetdrill and Packetdrill test suites
  • How to write a Packetdrill test
  • How to run a Packetdrill test (in local mode for single-machine testing)
  • How to interpret Packetdrill test failures
  • Testing different network protocols (e.g., TCP, UDP, ICMP)
• Advanced Packetdrill techniques:
  • Using local mode for single-machine testing and remote mode to test traffic between real NICs
  • Using Python embedded in Packetdrill scripts to print state and check assertions about state
  • How to troubleshoot unexpected test failures (with Packetdrill -v, tcpdump, ss, and other tools)
  • Working with sysctl values and dependencies
  • Working with network namespaces
  • Testing IPv4, IPv6, and IPv4-mapped-IPv6
  • Testing encapsulation, TOS/DSCP, ECN
  • Simulating network errors and edge cases (e.g., packet loss, reordering, fragmentation, ICMP errors)
  • Submitting patches for Packetdrill tests or changes to Packetdrill itself
  • Packetdrill forks for *BSD, SCTP, and QUIC
• Integrating Packetdrill into your development workflow:
  • Using Packetdrill for unit tests during network stack development, regression testing, bug reproduction, and documenting git commits for bug fixes or feature additions.
  • Automating Packetdrill tests in a CI/CD pipeline
  • Tips and best practices for effective Packetdrill usage

Target Audience:

This tutorial is targeted towards Linux kernel developers, network engineers, students learning about the TCP protocol, and anyone involved in developing or testing network stack implementations. Familiarity with basic networking concepts (e.g., TCP/IP, sockets) and the Linux command line is assumed.

Expected Outcomes:

The goal is for attendees to leave this tutorial with a solid understanding of Packetdrill’s capabilities, and how to use Packetdrill to aid kernel networking software development workflows.

Why this Tutorial is Important to the Netdev Community:

Packetdrill is a useful tool in the toolbox of a Linux kernel networking developer. By promoting its adoption, we can contribute to a more robust and reliable Linux network stack. This tutorial (the first Packetdrill tutorial at any conference since the open-sourcing of Packetdrill in 2013) will empower developers with a useful tool to catch bugs early, improve code quality, and ultimately deliver a better networking experience for all users.

Packetrill test scripts or snippets are increasingly being used on the Linux netdev mailing list and in Linux git commit messages (by developers from different companies and universities) to precisely describe buggy or correct/fixed network stack behavior.

In 2024 (Linux v6.12) Packetdrill tests were added to the self-test suite in tools/testing/selftests/net/Packetdrill/ and 66 Packetdrill tests (so far) are part of the set of automated tests the Linux networking community is using. The Packetdrill project on github has over 300 Linux Packetdrill tests that are being incrementally ported to the mainline Linux test suite, and Google has over 2,000 Packetdrill tests that are being incrementally open-sourced to github and mainline Linux.

We believe this tutorial will be a valuable addition to the Linux Netdev Conference and will contribute to the advancement of Linux network stack development. We look forward to your consideration.