Protocol 48 of 81Layer 7FrameAssembly v3.1.2
llms-full.txt
grpcgRPC Remote Procedure Calls over HTTP/2

Microservice RPCs & Router gNMI Telemetry (caller <-> svc grpc TCP 50051)

Default Port / Protocol
TCP 50051
Host Endpoint Rule
Dual-Stack IPv4/IPv6
Wireshark Display Filter
grpc || http2
Standards & Specs
gRPC over HTTP/2, RFC 9113
Wire Stack:Ethernet II[802.1Q / QinQ / MPLS]IPv4 / IPv6TCP 50051gRPC

What It Does on the Wire

Whether it is Kubernetes east-west microservices or Arista/Cisco gnmi.gNMI/Subscribe streaming telemetry on TCP 50051, grpc builds the length-prefixed Protobuf envelope and grpc-status trailers.

gRPC (grpc) runs Remote Procedure Calls over HTTP/2 on TCP port 50051 (and network telemetry ports such as 57400/9339 for gNMI). On the wire, a gRPC call encodes :path /<service>/<method> with content-type: application/grpc inside HTTP/2 HEADERS, followed by a 5-byte length-prefixed gRPC DATA frame (1-byte compressed flag + 4-byte message length + Protobuf payload), and finishes with an HTTP/2 trailer carrying grpc-status.

FrameAssembly builds valid HTTP/2 + gRPC request frames from service and method names, or emits a gRPC response trailer when you specify grpcstatus (0 OK, 7 PERMISSION_DENIED, 14 UNAVAILABLE).

Kubernetes Service Mesh & Envoy gRPC Routing Tests

Test path-based routing rules matching /payments.Ledger/Authorize and verify alerting on grpcstatus 14 (UNAVAILABLE) or grpcstatus 4 (DEADLINE_EXCEEDED).

gNMI Streaming Network Telemetry Firewall Checks

Override dstport 9339 with service "gnmi.gNMI" method "Subscribe" to verify firewall policies between routers and telemetry collectors.

API Gateway Zero-Trust Authorization Audits

Capture grpcstatus 7 (PERMISSION_DENIED) and grpcstatus 16 (UNAUTHENTICATED) responses for security regression suites.

Minimal Quickstart (grpc_quickstart.frasm)

Hit Preview Packets to compile in-browser and eyeball timestamps + wire byte lengths, or ship it straight to the Playground.

grpc_quickstart.frasm7 lines
Open in Playground
host caller { ip 10.42.0.15 }
host backend { ip 10.42.0.50 }
compile {
caller -> backend grpc service "inventory.StockService" method "CheckItem" wait 2ms
caller <- backend grpc grpcstatus 0
}

What the Compiler Calculates So You Don't Have To

  • Defaults to TCP destination port 50051 (psh ack) and formats HTTP/2 HEADERS (:method POST, :path /<service>/<method>, content-type: application/grpc).
  • Wraps request payloads in the 5-byte gRPC Length-Prefixed-Message header (Compressed-Flag = 0 + 32-bit big-endian message length).
  • Emits an HTTP/2 END_STREAM | END_HEADERS trailer frame carrying grpc-status: <code_num> whenever grpcstatus is set.
Multi-Frame Lab · Ready to Compile

gNMI Router Telemetry Subscription + Backend UNAVAILABLE Failover

Opens a TCP 50051 connection, invokes a telemetry.Collector/Export RPC succeeding with grpcstatus 0, and captures a second call returning grpcstatus 14 (UNAVAILABLE).

grpc_service_mesh_lab.frasm14 lines
Open in Playground
host edge_agent { ip 172.16.40.12 }
host mesh_gw { ip 172.16.40.50 }
compile {
edge_agent -> mesh_gw tcp syn srcport 55051 dstport 50051 win 65535 mss 1460 wait 1ms
edge_agent <- mesh_gw tcp syn ack win 65535 mss 1460 wait 1ms
edge_agent -> mesh_gw tcp ack wait 1ms
// 1. Healthy gRPC Export call -> OK (0)
edge_agent -> mesh_gw grpc service "telemetry.Collector" method "Export" wait 2ms
edge_agent <- mesh_gw grpc grpcstatus 0 wait 4ms
// 2. Upstream maintenance -> UNAVAILABLE (14)
edge_agent -> mesh_gw grpc service "auth.TokenVerifier" method "Validate" wait 2ms
edge_agent <- mesh_gw grpc grpcstatus 14
}
Terminal Commands (FrameAssembly CLI v3.1.2)
# 1. Eyeball relative timestamps, ports & wire lengths in your terminal
frameassembly show grpc_service_mesh_lab.frasm

# 2. Compile .frasm -> classic .pcap (tcpdump/tcpreplay/Suricata) or nanosecond .pcapng
frameassembly grpc_service_mesh_lab.frasm grpc_service_mesh_lab.pcap
frameassembly grpc_service_mesh_lab.frasm grpc_service_mesh_lab.pcapng

# 3. Round-trip .pcap <-> .frasm whenever you want to scrub or tweak an existing capture
frameassembly reverse grpc_service_mesh_lab.pcap grpc_service_mesh_lab_edited.frasm

All grpc Keywords & Header Options

Every sub-keyword and header option is lowercase [a-z0-9]+ with zero underscores — mix and match them in any order after grpc:

src_host -> dst_host grpc [service "<text>"] [method "<text>"] [grpcstatus <number>]
Keyword / OptionAccepted ValueDefaultEffect on Packet
service "<text>"Package-qualified gRPC service name"helloworld.Greeter"Sets the service prefix in the HTTP/2 :path pseudo-header (/<service>/<method>).
method "<text>"gRPC RPC method name"SayHello"Sets the method suffix in the HTTP/2 :path pseudo-header.
grpcstatus <number>gRPC status code (0 OK, 3 INVALID_ARGUMENT, 7 PERMISSION_DENIED, 14 UNAVAILABLE, 16 UNAUTHENTICATED)Omitted on requestsSwitches the packet to a gRPC Trailers response frame carrying grpc-status.

Cross-Layer Wrappers Valid with grpc

802.1Q VLAN / QinQ / MPLS tags, IPv4/IPv6 QoS & TTL fields, wait gaps, and transport overrides allowed on this protocol

11 options
OptionRange / FormatDefaultEffect on Packet
wait <number><ns|us|ms|s|m>Time gap (ns, us, ms, s, m)10msAdvances the packet timestamp clock after sending this packet and before the next packet (wait 0ns sends back-to-back).
payload "<text>" | hexpayload "<hex>"Quoted text or hex bytes (choose one)OmittedAppends or overrides raw payload bytes ("deadbeef" or "de:ad:be:ef") and updates packet lengths and checksums.
srcmac <mac> | dstmac <mac>Colon, hyphen, or Cisco dot MACHost MAC / RFC multicast MACOverrides the 14-byte Ethernet II source or destination MAC address for this single packet.
vlan <0..4095> [pcp <0..7>] [dei <0|1>]VLAN ID 0..4095, PCP 0..7, DEI 0..1UntaggedWraps the packet in an IEEE 802.1Q VLAN tag (0x8100) with optional 802.1p QoS priority.
qinq <0..4095> [innervlan <0..4095>]Outer S-VLAN 0..4095, Inner C-VLAN 0..4095Untagged (innervlan 1 when qinq is set)Double-tags the packet with outer IEEE 802.1ad S-Tag (0x88a8) plus inner IEEE 802.1Q C-Tag (0x8100).
mpls <0..1048575> [exp|tc <0..7>] [bos <0|1>] [mplsttl <0..255>]Label 0..1048575, exp/tc 0..7, bos 0..1, ttl 0..255Unlabeled (at most 1 mpls tag per packet)Inserts a 32-bit MPLS label header (0x8847) ahead of the Layer 3 header.
ttl <0..255> [dscp <0..63>] [ecn <0..3>]TTL/Hop Limit 0..255, DSCP 0..63, ECN 0..3ttl 64, dscp 0, ecn 0Sets IPv4 TTL or IPv6 Hop Limit plus DiffServ (DSCP) and ECN QoS markings.
ipid <0..65535> [df] [mf] [fragoffset <0..8191>]IPv4 ID, DF/MF flags, fragment offset 0..8191ipid 1, flags 0, fragoffset 0Sets IPv4 Identification, Do-Not-Fragment (df), More-Fragments (mf), and fragment offset (ignored over IPv6).
flowlabel <0..1048575>20-bit IPv6 Flow Label (0..1048575)0Sets the 20-bit IPv6 Flow Label for ECMP routing tests (ignored when running over IPv4 hosts).
srcport <0..65535> | dstport <0..65535>Port number 0..65535srcport 49152 (remembered), TCP 50051Overrides source or destination port and remembers the port pair automatically on <- replies.
seq <number> | acknum <number> | win <0..65535> | syn | ack | psh | fin | rstTCP sequence/ack numbers, window size, flags & RFC 7323 optionspsh ack, win 65535, automatic TCP seq/acknumOverrides automatic TCP sequence tracking, flags, or RFC 7323 options (mss, wscale, sackperm, tsval, tsecr).

Gotchas & Quick Fixes

Use grpcstatus (Not status) for gRPC Status Codes

Avoid
caller <- backend grpc status 14
Valid v3.1.2 Syntax
caller <- backend grpc grpcstatus 14

gRPC reports RPC completion codes in the grpc-status trailer (0..16) rather than HTTP status 200, so the modifier is named grpcstatus.

Do Not Include Leading Slashes in service or method

Avoid
caller -> backend grpc service "/helloworld.Greeter" method "/SayHello"
Valid v3.1.2 Syntax
caller -> backend grpc service "helloworld.Greeter" method "SayHello"

FrameAssembly automatically joins service and method into /:service/:method—pass plain names without extra / slashes.

Field Guide 03
Poke Stateful Firewalls, Suricata, Zeek & OT Conduits