How to use the p4lang/p4app Docker image

本文参考 孙勇峰博客 和 p4app README 以及 p4app Dockerfile 结合自己的理解做一些记录，有错误或不足之处欢迎批评指正。

简介

p4app是一个可以构建、运行、调试和测试P4程序的工具，p4app背后蕴含的哲学是“简单的事情应尽可能简单”，旨在使小而简单的P4程序易于编写、易于与他人分享。

p4lang/p4app的镜像结构

Docker 镜像是分层结构以Ubuntu 16.04为base镜像依次构建，p4app为最顶层.
对于如何构建这些镜像，有兴趣的可以看p4app的Dockerfile.

• p4app
• p4c
• pi
• bmv2
• third-party
• Ubuntu 16.04

安装p4app

• 下载github的p4app源码

  $ git clone https://github.com/p4lang/p4app

• 为了方便可将p4app脚本拷贝到PATH路径

  $ sudo cp p4app /usr/local/bin

• 安装docker

以下两种均可

1. docker安装教程

2. 一键安装

   $ wget -qO- https://get.docker.com/ | sh

如何使用

p4app运行p4app程序包. p4app程序包是一个以.p4app为后缀的目录，例如你用P4写了一个路由器程序，将其放在router.p4app目录文件夹下. 该目录应当包括你的P4程序、其他与你的程序相关联的文件和一个p4app.json文件. p4app.json指定如何执行你的p4程序(自定义执行动作).

在p4app/examples中包含多个样例，具体如下：

• broadcast.p4app
• compile_only.p4app
• customtopo.p4app
• multi_iface.p4app
• multiswitch.p4app
• paxos_acceptor.p4app
• simple_counter.p4app
• simple_router.p4app
• source_routing.p4app

例如，你要执行simple_router.p4app程序包

$ p4app run p4app/examples/simple_router.p4app

当你执行这条命令，最终会进入mininet命令行界面.

那么执行这条命令后具体发生了什么？我们先来看看p4app这个可执行脚本在做什么

• Ps：对于脚本感兴趣的可以查看p4app脚本源码

p4app可执行脚本详解

p4app命令参数

• p4app run
  • 运行p4app程序包
• p4app run
  • 运行p4app程序包并指定target
• p4app build
  • 构建p4app程序包并输出json文件
• p4app pack
  • 将p4app程序包压缩为单个文件，替换当前目录下的p4app程序包，使用gzip压缩
• p4app unpack
  • 解压上述压缩包
• p4app update
  • 更新到最新版本的p4app的docker镜像
• p4app exec
  • 在最新运行的p4app容器实例中执行一条命令

p4app run 内部具体执行流程

以simple_router.p4app为例

1. 执行run-comman函数

   • 传入参数为目录

     //如simple_router.p4app
     $ run-p4app /tem/p4app.tar.gz.XXXXXX

   • 传入参数为文件

     $ run-p4app 文件的绝对路径

     简单理解，如果是文件夹就压缩打包后传入其路径，是文件就传入绝对路径.

2. 执行run-p4app函数

   重点来了，运行p4app容器实例

   $ docker run --privileged --interactive --tty --rm \
       --name "p4app_$RANDOM" \
       -v $1:/tmp/app.tar.gz \
       -v "P4APP_LOGDIR":/tmp/p4app_logs \
       $P4APP_IMAGE /tmp/p4app.tar.gz "${@:2}"

   #docker run 
   # --tty 分配tty设备 可支持终端登录
   # --interactive 打开STDIN 用于控制台交互
   # 上面两个是-it
   # --name 随机取了一个名字
   # -v 将主机上/tmp/p4app.tar.gz.XXXXXX 挂载到容器的 /tmp/app.tar.gz 中
   #  如果只是文件 将文件绝对路径挂载到容器的 /tem/app.tar.gz中
   # -v 将主机的log目录挂载到容器的/tmp/p4app_logs 中
   #  $P4APP_IMAGE $APP_TO_RUN "${@:2}"
   #  指定 镜像 文件 其他参数(指定target)

3. 进入容器实例

   p4app容器实例启动后执行的是p4apprunner.py脚本

   p4apprunner.py参数

   • 必要参数
     • app
       • p4app程序包路径
     • target
       • compile-bmv2 编译成bmv2目标
       • mininet 单P4交换机测试
       • multiswitch 多P4交换机测试
       • stf 进行stf测试
       • custom
   • 可选参数
     • –buid-dir
       • 构建目录，默认为/tmp
     • –quiet
       • 不显示log消息
     • –build-only
       • 仅编译不运行
     • –json
       • Use this compiled JSON file instead of compiling
     • –manifest
       • manifest 清单文件路径，默认为./p4app.json

   p4apprunner.py解析流程

   1. 解压提取p4app程序包
   2. 根据p4app程序包中的p4app.json解析
   3. 根据其中的target执行相应函数

p4app build 具体执行流程

1. 执行build-command函数

   $ run-command --build-only "${@:3}"

2. 执行run-command函数（同上）
3. 执行run-p4app函数（同上）
4. 进入容器实例（同上）

5. copy容器中$P4APP_LOGDIR/program.json到host本地目录下

总结，添加–build-only选项，仅编译p4app程序输出json文件

p4app运行流程小结

1. 第一次运行p4app时会自动下载docker镜像p4lang/p4app:latest
   • 该镜像中包括P4编译器、mininet、抓包工具tshark、发包工具scapy、net-tools和nmap套件等工具
2. 启动一个p4app容器实例，并在容器中执行p4apprunner.py脚本
3. 根据传入的p4app.json执行相应操作

p4app.json解析

p4app程序包最终如何运行，由manifest指定的p4app.json文件配置.

例如：simple_router.p4app的p4app.json如下

{
  "program": "simple_router.p4",
  "language": "p4-16",
  "targets": {
    "mininet": {
      "num-hosts": 2,
      "switch-config": "simple_router.config"
    }
  }
}

当有多个target时，需要指定一个默认的target，否则p4app运行其中的第一个target.
(Ps：纠正孙勇峰博客中说的随机运行其中一个)

{
  "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" },
  }
}

注意其中的”use”字段，若没有指定”use”字段则默认为”use”:”前面的targets名”

targets字段详解

1. compile-bmv2

   将p4程序编译成bmv2目标，例如：样例compile_only.p4app

   {
     "program": "compile_only.p4",
     "language": "p4-14",
     "targets": {
       "compile-bmv2": {
         "compiler-flags": ["-v", "--p4runtime-file out.bin", "--p4runtime-format json"],
         "run-after-compile": ["cat out.bin"]
       }
     }
   }

2. mininet

   编译一个P4程序，并加载到一个BMV2 simple_switch中，然后创建一个mininet实验环境.

   支持以下可选的配置

   "mininet": {
     "num-hosts": 2,
     "switch-config": "file.config"
   }

   mininet将创建一个星型网络拓扑，包含num-hosts个host并通过不同端口连接到你的P4模拟交换机.

   你可以通过switch-config文件指定P4模拟交换机的启动配置，配置文件中是一系列 BMV2 simple_switch_CLI 命令.

3. multiswitch
   multiswitch与mininet类似，编译P4程序并运行在mininet环境. multiswitch顾名思义可支持配置多个交换机、自定义拓扑并自定义在host上执行命令. 这些交换机默认自动配置L2/L3转发规则，用于所有host之间的互通. （前提是P4程序中包含ipv4_lpm、send_frame、forwar table）

   例如：multiswitch.p4app

{
  "program": "simple_router.p4",
  "language": "p4-16",
  "targets": {
      "multiswitch": {
      "auto-control-plane": true,
      "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"
      }
    }
  }
}

该配置创建如下拓扑：

h1 <---> s1 <---> s2 <---> h2

其中 s2-h2 链路人工配置了50ms的时延. 而host的可选配置选项如下：

• cmd
  • 在host上运行的可执行命令
• wait
  • 如果配置为true，表示等待此命令执行结束；配置为false，表示在后台运行此命令.
• startup_sleep
  • 启动命令执行完成后必须等待的时间（单位为秒）
• latency
  • 主机与交换机之间的时延. 可配置为纯数字（默认单位为秒）或具有时间单位的字符串（例如50ms或1s）. 该配置将覆盖link对象中设置的时延.

限制：目前每个host只能连一个switch

1. stf （simple test framework）

编译P4程序并运行一个stf测试用例. stf是一种模拟网络测试框架，可以测试你的P4程序以确保达到预期行为.

例如：simple_counter.p4app

//json文件
"stf": {
      "test": "simple_counter.stf"
    }

//stf文件
add test1 data.f1:0x01010101 c1_2(val1:0x01, val2:0x02)
add test1 data.f1:0x02020202 c1_2(val1:0x10, val2:0x20)
add test2 data.f2:0x03030303 c3_4(val3:0x03, val4:0x04, port:1)
add test2 data.f2:0x04040404 c3_4(val3:0x30, val4:0x40, port:2)
expect 1 01010101 03030303 01 02 03 04
packet 0 01010101 03030303 55 66 77 88
expect 2 01010101 04040404 01 02 30 40
packet 0 01010101 04040404 55 66 77 88
expect 1 02020202 03030303 10 20 03 04
packet 0 02020202 03030303 99 88 77 66
expect 2 02020202 04040404 10 20 30 40
packet 0 02020202 04040404 14 25 36 47

“test”字段指定的配置文件必须使用stf格式编写. 但是目前还没有该格式的说明文档

1. custom

这是第三种编译P4程序并运行mininet实验环境的方法.

允许使用者在“program”字段指定自定义python程序. 可通过mininet的python api指定网络拓扑和配置.

例如：simple_routing.p4app

{
  "program": "source_routing.p4",
  "language": "p4-14",
  "targets": {
      "custom": {
           "program": "topo.py"
      }
  }
}

在运行topo.py时，将默认执行以下操作：

PYTHONPATH=$PYTHONPATH:/scripts/mininet/ python2 topo.py \
                        --behavioral-exe simple_switch \
                        --json SOME_FILE \
                        --cli simple_switch_CLI

同时可以指定其他参数传递给自定义拓扑程序，方法是将它们包含在 program 定义中，如下所示：

{
  "program": "source_routing.p4",
  "language": "p4-14",
  "targets": {
      "custom": {
           "program": "topo.py --num-hosts 2 --switch-config simple_router.config"
      }
  }
}

可以通过python获取docker容器ID

import os
container = os.environ['HOSTNAME']
print 'Run the switch CLI as follows:'
print '  docker exec -t -i %s %s' % (container, args.cli)

高级功能

• 使用自定义的Docker image
  如果你热衷于研究P4工具链和P4app脚本，你可以自己构建docker镜像来代替标准的p4lang images. 只需要通过P4APP_IMAGE环境变量配置docker镜像即可. 例如：

  P4APP_IMAGE=me/my_p4app_image:latest p4app run p4app/examples/sinmple_router.p4app

• 指定manifest文件
  默认情况下，p4app使用p4app程序包中的p4app.json的manifest文件. 如果你的manifest文件名称不是p4app，可以通过–manifest指定. 例如：

  p4app run myapp.p4app --manifest testing.json
  p4app run myapp.p4app --manifest testing.p4app

• 指定log目录
  默认情况下，p4app挂载host的/tmp/p4app_logs目录到docker容器实例的/tmp/p4app_logs中. bmv2或其他任何程序输出都保存到该目录. 可通过P4APP_LOGDIR环境变量指定其他目录为log目录. 例如：

  P4APP_LOGDIR=./out p4app run myapp.p4app