[{"_1":2,"_185":-5,"_186":-5},"loaderData",{"_3":4,"_18":19,"_25":26,"_164":165},"root",{"_5":-5,"_6":-7,"_7":8,"_9":-7,"_10":11,"_12":-7,"_13":14,"_15":16,"_17":11},"currentUser","primaryEmail","siteVerification","6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI","toast","enableDev",false,"incidentStatus","theme","system","contrast","normal","dockerRebrandTour","routes/_layout",{"_20":-5,"_21":22,"_23":11,"_24":22},"username","isAskGordonEnabled",true,"showMinimalLanding","showHoneypotTrap","routes/_layout.r.$namespace.$reponame",{"_27":28,"_29":-5,"_30":11,"_31":11,"_32":33,"_34":35,"_36":-5,"_37":11,"_38":39,"_89":90,"_111":112,"_152":-5,"_153":11,"_154":22,"_155":11,"_156":11,"_157":-5,"_158":11,"_159":-5,"_160":161,"_162":113,"_163":-7},"canonicalUrl","https://hub.docker.com/r/p4lang/p4runtime-sh/tags","mcpServer","canSeeDockerfile","canSeeAutobuilds","namespace","p4lang","reponame","p4runtime-sh","cloudBuildSource","isAutobuildsAvailable","repo",{"_40":41,"_42":43,"_45":46,"_47":48,"_49":11,"_50":51,"_52":53,"_54":55,"_57":35,"_32":33,"_58":59,"_60":44,"_61":62,"_63":64,"_65":66,"_67":-5,"_68":69,"_70":71,"_72":11,"_73":33,"_74":75,"_80":11,"_81":82,"_86":33,"_87":88},"categories",[],"content_types",[44],"image","date_registered","2019-04-16T02:08:26.301663Z","description","An interactive Python shell for P4Runtime","is_private","last_updated","2026-10-12T02:17:07.012274Z","last_modified","2024-10-16T13:48:34.145251Z","media_types",[56],"application/vnd.oci.image.index.v1+json","name","pull_count",18248,"repository_type","star_count",3,"status",1,"status_description","active","source","collaborator_count",0,"full_description","# A shell for P4Runtime\n\n[![Build Status](https://travis-ci.org/p4lang/p4runtime-shell.svg?branch=main)](https://travis-ci.org/p4lang/p4runtime-shell)\n\n**This is still a work in progress. Feedback is welcome.**\n\np4runtime-sh is an interactive Python shell for\n[P4Runtime](https://github.com/p4lang/p4runtime) based on\n[IPython](https://ipython.org/).\n\n## Using the shell\n\n### Run with Docker\n\nWe recommend that you download the Docker image (~142MB) and use it, but you can\nalso build the image directly with:\n\n```bash\ngit clone https://github.com/p4lang/p4runtime-shell\ncd p4runtime-shell\ndocker build -t p4lang/p4runtime-sh .\n```\n\nRun the shell as follows:\n\n```bash\n[sudo] docker run -ti p4lang/p4runtime-sh \\\n --grpc-addr : \\\n --device-id 0 --election-id 0,1\n```\n\nThe above command will retrieve the forwarding pipeline configuration from the\nP4Runtime server. You can also push a forwarding pipeline configuration with the\nshell (you will need to mount the directory containing the P4Info and binary\ndevice config in the docker):\n\n```bash\n[sudo] docker run -ti -v /tmp/:/tmp/ p4lang/p4runtime-sh \\\n --grpc-addr : \\\n --device-id 0 --election-id 0,1 --config /tmp/p4info.txt,/tmp/bmv2.json\n```\n\nThe above command assumes that the P4Info (p4info.txt) and the binary device\nconfig (bmv2.json) are under /tmp/.\n\nTo make the process more convenient, we provide a wrapper script, which takes\ncare of running the docker (including mounting the P4Info and binary device\nconfig files in the docker if needed):\n\n```bash\n[sudo] ./p4runtime-sh-docker --grpc-addr : \\\n --device-id 0 --election-id 0,1 \\\n --config ,\n```\n\n*If you are a Linux user, you can follow this\n [guide](https://docs.docker.com/install/linux/linux-postinstall/) to run Docker\n commands without `sudo`. You will be able to use `p4runtime-sh-docker` as a\n non-privileged user.*\n\n*If you are using the Docker image to run p4runtime-shell and you are trying to\n connect to a P4Runtime server running natively on the same system and listening\n on the localhost interface, you will not be able to connect to the server using\n `--grpc-addr localhost:` or `--grpc-addr 127.0.0.1:`. Instead, you\n should have your P4Runtime server listen on all interfaces (`0.0.0.0`) and you\n will need to use the IP address assigned to the Docker bridge (`docker0` by\n default) or the IP address assigned to the local network management interface\n (e.g. `eth0`).*\n\n### Run without Docker\n\nYou can also install P4Runtime shell via `pip3` and run it directly.\n\n```bash\n# (optional) Set up virtual environment\npython3 -m venv venv\nsource venv/bin/activate\n\n# Install p4runtime-shell package and run it\npip3 install p4runtime-shell\npython3 -m p4runtime_sh --grpc-addr : \\\n --device-id 0 --election-id 0,1 --config ,\n```\n\n## Available commands\n\n`tables`, `actions`, `action_profiles`, `counters`, `direct_counters`, `meters`,\n`direct_meters` (named after the P4Info message fields) to query information\nabout P4Info objects.\n\n`table_entry`, `action_profile_member`, `action_profile_group`, `counter_entry`,\n`direct_counter_entry`, `meter_entry`, `direct_meter_entry` (named after the\nP4Runtime `Entity` fields), along with `multicast_group_entry` and\n`clone_session_entry`, for runtime entity programming.\n\n`packet_in` and `packet_out` are commands for packet IO, see the [usage](usage/packet_io.md) for more information.\n\nThe `Write` command can be used to read a `WriteRequest` message from a file\n(for now, Protobuf text format only) and send it to a server:\n\n```text\nWrite \n```\n\nType the command name followed by `?` for information on each command,\ne.g. `table_entry?`.\n\n## Canonical representation of bytestrings\n\nThe [P4Runtime\nspecification](https://p4.org/p4runtime/spec/v1.3.0/P4Runtime-Spec.html#sec-bytestrings)\ndefines a canonical representation for binary strings, which all P4Runtime\nservers must support. This representation can be used to format all binary\nstrings (match fields, action parameters, ...) in P4Runtime messages exchanged\nbetween the client and the server. For legacy reasons, some P4Runtime servers do\nnot support the canonical representation and require binary strings to be\nbyte-padded according to the bitwidth specified in the P4Info message. While all\nP4Runtime-conformant servers must also accept this legacy format, it can lead to\nread-write asymmetry for P4Runtime entities. For example a client may insert a\nTableEntry using the legacy format for match fields, but when reading the same\nTableEntry back, the server may return a message with match field values in the\ncanonical representation. When a client uses the canonical representation,\nread-write symmetry is always guaranteed.\n\nIf you are dealing with a legacy server which rejects binary strings formatted\nusing the canonical representation (making this server non conformant to the\nspecification), you can revert to the byte-padded format by typing the following\ncommand in the shell:\n\n```python\nP4Runtime sh >>> global_options[\"canonical_bytestrings\"] = False\n```\n\n## Example usage\n\nHere is some of what you can do when using p4runtime-sh with ONF's\n[fabric.p4](https://github.com/opennetworkinglab/onos/blob/master/pipelines/fabric/impl/src/main/resources/fabric.p4).\n\nMore examples of usage can be found in the [usage/ folder](usage/).\n\n```python\n*** Welcome to the IPython shell for P4Runtime ***\nP4Runtime sh >>> tables\nFabricEgress.egress_next.egress_vlan\nFabricIngress.acl.acl\nFabricIngress.filtering.fwd_classifier\nFabricIngress.filtering.ingress_port_vlan\nFabricIngress.forwarding.bridging\nFabricIngress.forwarding.mpls\nFabricIngress.forwarding.routing_v4\nFabricIngress.next.hashed\nFabricIngress.next.multicast\nFabricIngress.next.next_vlan\nFabricIngress.next.xconnect\n\nP4Runtime sh >>> tables[\"FabricIngress.forwarding.routing_v4\"]\nOut[2]:\npreamble {\n id: 33562650\n name: \"FabricIngress.forwarding.routing_v4\"\n alias: \"routing_v4\"\n}\nmatch_fields {\n id: 1\n name: \"ipv4_dst\"\n bitwidth: 32\n match_type: LPM\n}\naction_refs {\n id: 16777434 (\"FabricIngress.forwarding.set_next_id_routing_v4\")\n}\naction_refs {\n id: 16804187 (\"FabricIngress.forwarding.nop_routing_v4\")\n}\naction_refs {\n id: 16819938 (\"nop\")\n annotations: \"@defaultonly\"\n scope: DEFAULT_ONLY\n}\nconst_default_action_id: 16819938 (\"nop\")\ndirect_resource_ids: 318811107 (\"FabricIngress.forwarding.routing_v4_counter\")\nsize: 1024\n\n\nP4Runtime sh >>> te = table_entry[\"FabricIngress.forwarding.routing_v4\"](action=\"set_next_id_routing_v4\")\n\nP4Runtime sh >>> te?\nSignature: te(**kwargs)\nType: TableEntry\nString form:\ntable_id: 33562650 (\"FabricIngress.forwarding.routing_v4\")\naction {\n action {\n action_id: 16777434 (\"FabricIngress.forwarding.set_next_id_routing_v4\")\n }\n}\nFile: /p4runtime-sh/p4runtime_sh/shell.py\nDocstring:\nAn entry for table 'FabricIngress.forwarding.routing_v4'\n\nUse .info to display the P4Info entry for this table.\n\nTo set the match key, use .match[''] = .\nType .match? for more details.\n\nTo set the action specification .action = .\nTo set the value of action parameters, use .action[''] = .\nType .action? for more details.\n\nTo set the priority, use .priority = .\n\nTo mark the entry as default, use .is_default = True.\n\nTypical usage to insert a table entry:\nt = table_entry[''](action='')\nt.match[''] = ...\n...\nt.match[''] = ...\n# OR t.match.set(f1=..., ..., fN=...)\nt.action[''] = ...\n...\nt.action[''] = ...\n# OR t.action.set(p1=..., ..., pM=...)\nt.insert\n\nTypical usage to set the default entry:\nt = table_entry[''](is_default=True)\nt.action[''] = ...\n...\nt.action[''] = ...\n# OR t.action.set(p1=..., ..., pM=...)\nt.modify\n\nFor information about how to read table entries, use .read?\n\nP4Runtime sh >>> te.match?\nType: MatchKey\nFile: /p4runtime-sh/p4runtime_sh/shell.py\nDocstring:\nMatch key fields for table 'FabricIngress.forwarding.routing_v4':\n\nid: 1\nname: \"ipv4_dst\"\nbitwidth: 32\nmatch_type: LPM\n\nSet a field value with [''] = '...'\n * For exact match: [''] = ''\n * For ternary match: [''] = '&&&'\n * For LPM match: [''] = '/'\n * For range match: [''] = '..'\n * For optional match: [''] = ''\n\nIf it's inconvenient to use the whole field name, you can use a unique suffix.\n\nYou may also use .set(='')\n ( must not include a '.' in this case, but remember that you can use a unique suffix)\n\nP4Runtime sh >>> te.match[\"ipv4_dst\"] = \"10.0.0.0/16\"\nfield_id: 1\nlpm {\n value: \"\\n\\000\\000\\000\"\n prefix_len: 16\n}\n\n\nP4Runtime sh >>> te.action?\nType: Action\nFile: /p4runtime-sh/p4runtime_sh/shell.py\nDocstring:\nAction parameters for action 'set_next_id_routing_v4':\n\nid: 1\nname: \"next_id\"\nbitwidth: 32\n\n\nSet a param value with [''] = ''\nYou may also use .set(='')\n\nP4Runtime sh >>> te.action[\"next_id\"] = \"10\"\nparam_id: 1\nvalue: \"\\000\\000\\000\\n\"\n\n\nP4Runtime sh >>> te.insert\n\nP4Runtime sh >>> for te in table_entry[\"FabricIngress.forwarding.routing_v4\"].read():\n ...: print(te)\n ...:\ntable_id: 33562650 (\"FabricIngress.forwarding.routing_v4\")\nmatch {\n field_id: 1 (\"ipv4_dst\")\n lpm {\n value: \"\\\\x0a\\\\x00\\\\x00\\\\x00\"\n prefix_len: 16\n }\n}\naction {\n action {\n action_id: 16777434 (\"FabricIngress.forwarding.set_next_id_routing_v4\")\n params {\n param_id: 1 (\"next_id\")\n value: \"\\\\x00\\\\x00\\\\x00\\\\x0a\"\n }\n }\n}\n\n\nP4Runtime sh >>> table_entry[\"FabricIngress.forwarding.routing_v4\"].read(lambda te: te.delete())\n\nP4Runtime sh >>> table_entry[\"FabricIngress.forwarding.routing_v4\"].read(lambda te: print(te))\n\nP4Runtime sh >>>\n```\n\n## Using p4runtime-shell in scripts\n\nYou can also leverage this project as a convenient P4Runtime wrapper to\nprogrammatically program switches using Pyhton scripts:\n\n```python\nimport p4runtime_sh.shell as sh\n\n# you can omit the config argument if the switch is already configured with the\n# correct P4 dataplane.\nsh.setup(\n device_id=1,\n grpc_addr='localhost:9559',\n election_id=(0, 1), # (high, low)\n config=sh.FwdPipeConfig('config/p4info.pb.txt', 'config/device_config.bin')\n)\n\n# see p4runtime_sh/test.py for more examples\nte = sh.TableEntry('')(action='')\nte.match[''] = ''\nte.action[''] = ''\nte.insert()\n\n# ...\n\nsh.teardown()\n```\n\nNote that at the moment the P4Runtime client object is a global variable, which\nmeans that we only support one P4Runtime connection to a single switch.\n\n## Target-specific support\n\n### P4.org Bmv2\n\nJust use the bmv2 JSON file generated by the\n[compiler](https://github.com/p4lang/p4c) as the binary device config.\n\n### Barefoot Tofino\n\nWe provide a script which can be used to \"pack\" the Barefoot p4c compiler output\n(part of the Barefoot SDE) into one binary file, to be used as the binary device\nconfig.\n```bash\n./config_builders/tofino.py --ctx-json \\\n --tofino-bin -p -o out.bin\n```\n\nYou can then use `out.bin` when invoking `p4runtime-sh-docker`:\n```bash\n[sudo] ./p4runtime-sh-docker --grpc-addr : \\\n --device-id 0 --election-id 0,1 \\\n --config ,out.bin\n```\n","has_starred","hub_user","immutable_tags_settings",{"_76":11,"_77":78},"enabled","rules",[79],".*","is_automated","permissions",{"_83":22,"_84":11,"_85":11},"read","write","admin","user","storage_size",3855526582,"orgData",{"_91":92,"_93":94,"_95":96,"_97":33,"_98":99,"_100":99,"_101":102,"_103":104,"_105":106,"_107":99,"_108":99,"_109":99,"_110":22},"id","c498798f9e4e413c96ec10c7b7ab7164","uuid","c498798f-9e4e-413c-96ec-10c7b7ab7164","type","organization","orgname","full_name","","location","company","P4.org","profile_url","http://p4.org","date_joined","2017-01-27T02:36:37.836355Z","gravatar_url","gravatar_email","badge","is_active","recentTags",[113],{"_114":44,"_115":116,"_117":118,"_119":120,"_91":121,"_122":123,"_50":139,"_140":141,"_142":143,"_144":56,"_57":145,"_146":147,"_148":130,"_149":139,"_150":66,"_151":22},"content_type","creator",1423874,"digest","sha256:16550aef1664041e91b5501e25402d125e0d24c767dbaf8523feb8e187334708","full_size",61970176,52820927,"images",[124],{"_125":126,"_117":127,"_128":99,"_129":130,"_131":132,"_133":134,"_135":99,"_136":-5,"_137":120,"_63":66,"_138":-5},"architecture","amd64","sha256:e47512e10be292c7573cf96f38c2c60f3e03de18da13917ea2fccc675fb444b0","features","last_pulled","2026-10-30T19:03:56.904732536Z","last_pushed","2026-10-12T02:17:05.403212245Z","os","linux","os_features","os_version","size","variant","2026-10-12T02:17:06.389328Z","last_updater",1423870,"last_updater_username","antoninbas","media_type","latest","repository",6983377,"tag_last_pulled","tag_last_pushed","tag_status","v2","sbxKitMetadata","isPotentialSpam","isHubSbxKitsEnabled","showSbxRunInCloud","showSbxLogoOverride","sbxTrademarkText","displaySecurityMetadata","tagAttestations","tagsHaveAttestations",[],"selectedTag","attestationsUrl","routes/_layout.r.$namespace.$reponame.tags",{"_38":166,"_173":174,"_160":183,"_184":11},{"_40":167,"_42":168,"_45":46,"_47":48,"_49":11,"_50":51,"_52":53,"_54":169,"_57":35,"_32":33,"_58":59,"_60":44,"_61":62,"_63":64,"_65":66,"_67":-5,"_68":69,"_70":71,"_72":11,"_73":33,"_74":170,"_80":11,"_81":172,"_86":33,"_87":88},[],[44],[56],{"_76":11,"_77":171},[79],{"_83":22,"_84":11,"_85":11},"tags",{"_175":64,"_176":-5,"_177":-5,"_178":179},"count","next","previous","results",[180],{"_114":44,"_115":116,"_117":118,"_119":120,"_91":121,"_122":181,"_50":139,"_140":141,"_142":143,"_144":56,"_57":145,"_146":147,"_148":130,"_149":139,"_150":66,"_151":22},[182],{"_125":126,"_117":127,"_128":99,"_129":130,"_131":132,"_133":134,"_135":99,"_136":-5,"_137":120,"_63":66,"_138":-5},[],"canDeleteTags","actionData","errors"]

p4lang/p4runtime-sh

Tags for p4lang/p4runtime-sh