p4lang/p4runtime-sh

p4runtime-sh：P4Runtime的交互式Shell

镜像概述和主要用途

p4runtime-sh是一个基于IPython的https://github.com/p4lang/p4runtime%E4%BA%A4%E4%BA%92%E5%BC%8FPython shell。它提供便捷的命令行界面，用于与P4Runtime服务器交互，支持转发管道配置的检索与推送，以及运行时实体（如流表项、计数器、meter等）的编程操作。

核心功能和特性

• 交互式IPython shell，支持命令自动补全和帮助查询（命令+?）
• 检索和推送P4Runtime服务器的转发管道配置
• 查询P4Info对象信息（tables、actions、action_profiles等）
• 编程运行时实体（table_entry、counter_entry、meter_entry等）
• 数据包IO操作（packet_in、packet_out）
• 支持从文件读取并发送WriteRequest消息
• 可集成到Python脚本中作为P4Runtime客户端库使用
• 提供Docker镜像和包装脚本，简化部署和使用流程

使用场景和适用范围

• P4Runtime服务器的日常管理与配置
• P4程序转发管道的部署与验证
• 运行时实体（流表、计数器等）的动态编程
• P4相关自动化测试和脚本开发
• 支持P4.org Bmv2和Barefoot Tofino等目标设备

详细使用方法和配置说明

使用Docker运行

构建镜像

推荐使用预构建Docker镜像（约142MB），也可手动构建：

bash
git clone https://github.com/p4lang/p4runtime-shell
cd p4runtime-shell
docker build -t p4lang/p4runtime-sh .

基本运行命令

bash
[sudo] docker run -ti p4lang/p4runtime-sh \
  --grpc-addr <server IP>:<server port> \
  --device-id 0 --election-id 0,1

此命令从P4Runtime服务器检索转发管道配置。

推送转发管道配置

如需推送配置，需挂载包含P4Info和二进制设备配置文件的目录：

bash
[sudo] docker run -ti -v /tmp/:/tmp/ p4lang/p4runtime-sh \
  --grpc-addr <server IP>:<server port> \
  --device-id 0 --election-id 0,1 --config /tmp/p4info.txt,/tmp/bmv2.json

假设P4Info文件（p4info.txt）和二进制设备配置文件（bmv2.json）位于/tmp/目录。

使用包装脚本

提供包装脚本简化操作（自动处理文件挂载）：

bash
[sudo] ./p4runtime-sh-docker --grpc-addr <server IP>:<server port> \
  --device-id 0 --election-id 0,1 \
  --config <path to p4info>,<path to binary config>

注意事项：

• Linux用户可参考指南配置免sudo运行Docker
• 连接本地服务器时，不可使用localhost或127.0.0.1，需使用Docker桥接IP（默认docker0）或本地网络接口IP（如eth0），且服务器需监听0.0.0.0

不使用Docker运行

通过pip3安装并直接运行：

bash
# （可选）创建虚拟环境
python3 -m venv venv
source venv/bin/activate

# 安装并运行
pip3 install p4runtime-shell
python3 -m p4runtime_sh --grpc-addr <server IP>:<server port> \
  --device-id 0 --election-id 0,1 --config <p4info.txt>,<pipeline config>

可用命令

查询P4Info对象

• tables、actions、action_profiles、counters、direct_counters、meters、direct_meters：查询对应P4Info对象信息（名称对应P4Info消息字段）

运行时实体编程

• table_entry、action_profile_member、action_profile_group、counter_entry、direct_counter_entry、meter_entry、direct_meter_entry：编程对应P4Runtime Entity（名称对应P4Runtime Entity字段）
• multicast_group_entry、clone_session_entry：组播组和克隆会话编程

数据包IO

• packet_in、packet_out：数据包输入输出操作，详见使用说明

Write命令

从文件读取并发送WriteRequest消息（仅支持Protobuf文本格式）：

text
Write <path to file encoding WriteRequest message in text format>

获取命令帮助

输入命令名+?查看帮助，如table_entry?

字节字符串的规范表示

P4Runtime规范定义了字节字符串的规范表示，所有P4Runtime服务器必须支持。对于不兼容的旧服务器，可切换为字节填充格式：

python
P4Runtime sh >>> global_options["canonical_bytestrings"] = False

示例用法

以下为与ONF https://github.com/opennetworkinglab/onos/blob/master/pipelines/fabric/impl/src/main/resources/fabric.p4%E4%BA%A4%E4%BA%92%E7%9A%84%E7%A4%BA%E4%BE%8B%EF%BC%9A

python
 Welcome to the IPython shell for P4Runtime 
P4Runtime sh >>> tables
FabricEgress.egress_next.egress_vlan
FabricIngress.acl.acl
FabricIngress.filtering.fwd_classifier
FabricIngress.filtering.ingress_port_vlan
FabricIngress.forwarding.bridging
FabricIngress.forwarding.mpls
FabricIngress.forwarding.routing_v4
FabricIngress.next.hashed
FabricIngress.next.multicast
FabricIngress.next.next_vlan
FabricIngress.next.xconnect

# 查看表信息
P4Runtime sh >>> tables["FabricIngress.forwarding.routing_v4"]
Out[2]:
preamble {
  id: 33562650
  name: "FabricIngress.forwarding.routing_v4"
  alias: "routing_v4"
}
match_fields {
  id: 1
  name: "ipv4_dst"
  bitwidth: 32
  match_type: LPM
}
...

# 创建表项
P4Runtime sh >>> te = table_entry["FabricIngress.forwarding.routing_v4"](action="set_next_id_routing_v4")

# 设置匹配字段
P4Runtime sh >>> te.match["ipv4_dst"] = "10.0.0.0/16"

# 设置动作参数
P4Runtime sh >>> te.action["next_id"] = "10"

# 插入表项
P4Runtime sh >>> te.insert

# 读取表项
P4Runtime sh >>> for te in table_entry["FabricIngress.forwarding.routing_v4"].read():
            ...:     print(te)
            ...:
table_id: 33562650 ("FabricIngress.forwarding.routing_v4")
match {
  field_id: 1 ("ipv4_dst")
  lpm {
    value: "\\x0a\\x00\\x00\\x00"
    prefix_len: 16
  }
}
action {
  action {
    action_id: 16777434 ("FabricIngress.forwarding.set_next_id_routing_v4")
    params {
      param_id: 1 ("next_id")
      value: "\\x00\\x00\\x00\\x0a"
    }
  }
}

# 删除表项
P4Runtime sh >>> table_entry["FabricIngress.forwarding.routing_v4"].read(lambda te: te.delete())

在脚本中使用p4runtime-shell

可作为P4Runtime客户端库集成到Python脚本：

python
import p4runtime_sh.shell as sh

# 设置连接（如交换机已配置正确P4数据平面，可省略config参数）
sh.setup(
    device_id=1,
    grpc_addr='localhost:9559',
    election_id=(0, 1),  # (high, low)
    config=sh.FwdPipeConfig('config/p4info.pb.txt', 'config/device_config.bin')
)

# 创建并插入表项
te = sh.TableEntry('<table_name>')(action='<action_name>')
te.match['<name>'] = '<value>'
te.action['<name>'] = '<value>'
te.insert()

# ...其他操作...

# 关闭连接
sh.teardown()

注意：当前仅支持单个P4Runtime连接（全局客户端对象）

目标特定支持

P4.org Bmv2

直接使用https://github.com/p4lang/p4c%E7%94%9F%E6%88%90%E7%9A%84bmv2 JSON文件作为二进制设备配置。

Barefoot Tofino

使用专用脚本打包Barefoot p4c输出为二进制配置：

bash
./config_builders/tofino.py --ctx-json <path to context JSON> \
  --tofino-bin <path to tofino.bin> -p <program name> -o out.bin

使用打包后的文件：

bash
[sudo] ./p4runtime-sh-docker --grpc-addr <server IP>:<server port> \
  --device-id 0 --election-id 0,1 \
  --config <path to p4info>,out.bin