[P4基础]p4app的Docker镜像仓使用详解

作者: sstriver | 来源:发表于2017-12-14 10:20 被阅读0次

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

以下两种均可

docker安装教程
一键安装

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

p4app run 内部具体执行流程

以simple_router.p4app为例

执行run-comman函数
- 传入参数为目录
```
//如simple_router.p4app
$ run-p4app /tem/p4app.tar.gz.XXXXXX
```
- 传入参数为文件
```
$ run-p4app 文件的绝对路径
```
简单理解，如果是文件夹就压缩打包后传入其路径，是文件就传入绝对路径.

执行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)

进入容器实例

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 具体执行流程

执行build-command函数
```
$ run-command --build-only "${@:3}"
```
执行run-command函数（同上）
执行run-p4app函数（同上）
进入容器实例（同上）
copy容器中$P4APP_LOGDIR/program.json到host本地目录下

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

p4app运行流程小结

第一次运行p4app时会自动下载docker镜像p4lang/p4app:latest
- 该镜像中包括P4编译器、mininet、抓包工具tshark、发包工具scapy、net-tools和nmap套件等工具
启动一个p4app容器实例，并在容器中执行p4apprunner.py脚本
根据传入的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字段详解

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"]
    }
  }
}

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 命令.
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

此外，mulitswitch还支持以下配置

指定每个交换机的表项

路由表（ipv4_lpm，send_frame 和 forward）在本 target 中会自动下发. 另外，使用者可根据自己的需要下发表项到每个交换机中，形式为包含一个命令文件或命令数组。这些自定义的表项优先级比路由表的自动生成的高. 例如：

"multiswitch": {
  "links": [ ... ],
  "hosts": { ... },
  "switches": {
    "s1": {
      "entries": "s1_commands.txt"
    },
    "s2": {
      "entries": [
        "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"
      ]
    }
  }
}

如果上述 s2 表项与自动生成的表项一样（例如自动生成的表项 set_nhop 10.0.1.10 / 32），这些自定义表项将具有更高的优先权，在下发表项时将警告表项重复。

自定义拓扑

可以通过topo_module选项指定自己的mininet Topo类. 例如：

"multiswitch": {
  ...
  "topo_module": "mytopo"
  ...
}

将mytopo.py与manifest文件（p4app.json）放置在同一目录下，同时实现CustomAppTopo类. 可扩展默认的apptopo.AppTopo类. 例如样例customtopo.p4app：

# mytopo.py
from apptopo import AppTopo

class CustomAppTopo(AppTopo):

    def __init__(self, *args, **kwargs):
        # Initialize the top topo
        AppTopo.__init__(self, *args, **kwargs)

        manifest, target = kwargs['manifest'], kwargs['target']

        print "Using target:", manifest['targets'][target]

        # Update a link's latency
        for link in self.iterLinks(withInfo=True):
            n1, n2, info = link
            if n1 == 's1' and n2 == 's2':
                info['delay'] = '123ms'

        print self.links(withInfo=True)

自定义控制器

类似topo_module选项，可通过controller_module选项自定义控制器. 该选项必须自己实现一个CustomAppController类的python脚本. 默认的控制器类为appcontroller.AppController，可直接对该类进行扩展. 详见样例customtopo.p4appmycontroller.py.

自定义mininet host运行程序

AppProRunner类是负责执行每个mininet host中的程序，通过指定controller_module选项，你可以重写登录和关闭host的默认行为，该模块也必须自己实现CustomAppController类. 默认的控制器类为appprocrunner.AppProcRunner，可直接对该类进行扩展. 详见样例customtopo.p4appmyprocrunner.py.

logging日志

当运行multiswitch时，host上的临时目录 /tmp/p4app_log 将挂载到容器实例的 /tmp/p4app_log . 运行p4app后， host 上保存有所有的log. 来着host 命令的stdout标准输出也将保存到该目录，如果你需要保存某个命令的输出 log，可以将其输出到该目录.

设置"bmv2_log":true，保存P4交换机的调试log.
设置"pcap_dump":true，抓取所有交换机的报文，保存为PCAP格式.

以上文件将保存到host的P4APP_LOGDIR目录中. 详见样例broadcast.p4app

Cleanup命令

在运行target后，mininet stop之前，如果需要在docker容器实例内执行命令，可使用after选项，且必须包含cmd，可以是一个或多个命令，例如：

"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"
    ]
  }
}

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格式编写. 但是目前还没有该格式的说明文档

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
```