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

[P4基础]p4app的Docker镜像仓使用详解
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 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为例
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

此外，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"
    ]
  }
}
```
<4>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格式编写. 但是目前还没有该格式的说明文档

<5>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
```
相关阅读:
style实例
 背景小实例
 html表单与输入实例
 列表小知识
 表格的使用
 框架的奥秘
 链接那档子事
 判断网络是否连通
 Python3编码规范
 CentOS 7 安装 Docker-Compose
原文地址：https://www.cnblogs.com/spjy/p/8027787.html

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

How to use the p4lang/p4app Docker image

简介

p4lang/p4app的镜像结构

安装p4app

如何使用

p4app可执行脚本详解

p4app命令参数

p4app run 内部具体执行流程

p4app build 具体执行流程

p4app运行流程小结

p4app.json解析

targets字段详解

<1>compile-bmv2

<2>mininet

<3>multiswitch

指定每个交换机的表项

自定义拓扑

自定义控制器

自定义mininet host运行程序

logging日志

Cleanup命令

<4>stf （simple test framework）

<5>custom

高级功能