Protocol Documentation

Table of Contents

• datapathplugins/datapathplugins.proto

  • AttachmentContext

  • AttachmentContext.Host

  • AttachmentContext.InterfaceInfo

  • AttachmentContext.LXC

  • AttachmentContext.Overlay

  • AttachmentContext.PodInfo

  • AttachmentContext.Socket

  • AttachmentContext.Wireguard

  • AttachmentContext.XDP

  • InstrumentCollectionRequest

  • InstrumentCollectionRequest.Collection

  • InstrumentCollectionRequest.Collection.Map

  • InstrumentCollectionRequest.Collection.MapsEntry

  • InstrumentCollectionRequest.Collection.Program

  • InstrumentCollectionRequest.Collection.ProgramsEntry

  • InstrumentCollectionRequest.Hook

  • InstrumentCollectionRequest.Hook.AttachTarget

  • InstrumentCollectionResponse

  • PrepareCollectionRequest

  • PrepareCollectionRequest.CollectionSpec

  • PrepareCollectionRequest.CollectionSpec.MapSpec

  • PrepareCollectionRequest.CollectionSpec.MapsEntry

  • PrepareCollectionRequest.CollectionSpec.ProgramSpec

  • PrepareCollectionRequest.CollectionSpec.ProgramsEntry

  • PrepareCollectionResponse

  • PrepareCollectionResponse.HookSpec

  • PrepareCollectionResponse.HookSpec.OrderingConstraint

  • HookType

  • PrepareCollectionResponse.HookSpec.OrderingConstraint.Order

  • DatapathPlugin

• Scalar Value Types

Top

datapathplugins/datapathplugins.proto

AttachmentContext

AttachmentContext contains the context about the attachment point in question. It may carry endpoint-specific information used to determine which hooks to load or how to configure them.

Field	Type	Label	Description
host	AttachmentContext.Host
lxc	AttachmentContext.LXC
overlay	AttachmentContext.Overlay
socket	AttachmentContext.Socket
wireguard	AttachmentContext.Wireguard
xdp	AttachmentContext.XDP

AttachmentContext.Host

attachment context for bpf_host (netdev, cilium_host, cilium_net).

Field	Type	Label	Description
iface	AttachmentContext.InterfaceInfo		interface that is being configured.

AttachmentContext.InterfaceInfo

InterfaceInfo contains information about a network interface.

Field	Type	Label	Description
name	string		name of the network interface.

AttachmentContext.LXC

attachment context for bpf_lxc (containers).

Field	Type	Label	Description
iface	AttachmentContext.InterfaceInfo		interface that is being configured.
pod_info	AttachmentContext.PodInfo		pod that is being configured.

AttachmentContext.Overlay

attachment context for bpf_overlay (vxlan/geneve).

Field	Type	Label	Description
iface	AttachmentContext.InterfaceInfo		interface that is being configured.

AttachmentContext.PodInfo

PodInfo contains information about a pod.

Field	Type	Label	Description
namespace	string		pod namespace.
name	string		pod name.
container_name	string		container name.

AttachmentContext.Socket

attachment context for bpf_sock (connect4,bind4,…)

AttachmentContext.Wireguard

attachment context for bpf_wireguard (cilium_wg)

Field	Type	Label	Description
iface	AttachmentContext.InterfaceInfo		interface that is being configured.

AttachmentContext.XDP

attachment context for bpf_xdp (netdev)

Field	Type	Label	Description
iface	AttachmentContext.InterfaceInfo		interface that is being configured.

InstrumentCollectionRequest

Phase 2: Cilium has constructed and loaded the collection along with any dispatcher programs that are meant to replace existing entrypoints in the collection. Cilium sends a round of requests to any plugins that wanted to inject hooks in the prepare phase.

Field	Type	Label	Description
collection	InstrumentCollectionRequest.Collection
attachment_context	AttachmentContext
config	google.protobuf.Any		config contains datapath configuration for this collection.
hooks	InstrumentCollectionRequest.Hook	repeated	list of hooks corresponding with those specified by the plugin in its PrepareHooks response.
pins	string		an ephemeral per-request bpffs directory where a plugin can pin an arbitrary set of objects. The lifecycle of these pins will be bound to that of the attachment context. This is useful especially in cases where the plugin loads its own set of tail call programs accessible from the entrypoint hook program and want to make sure a PROG_ARRAY and the programs it contains remain intact even after the InstrumentCollection request returns.
cookie	string		cookie matches the cookie provided in the plugin’s PrepareHooks response.

InstrumentCollectionRequest.Collection

Program and map IDs in the collection

Field	Type	Label	Description
programs	InstrumentCollectionRequest.Collection.ProgramsEntry	repeated	program details for each programs in the collection.
maps	InstrumentCollectionRequest.Collection.MapsEntry	repeated	map details for each map in the collection.

InstrumentCollectionRequest.Collection.Map

Field	Type	Label	Description
id	uint32

InstrumentCollectionRequest.Collection.MapsEntry

Field	Type	Label	Description
key	string
value	InstrumentCollectionRequest.Collection.Map

InstrumentCollectionRequest.Collection.Program

Field	Type	Label	Description
id	uint32

InstrumentCollectionRequest.Collection.ProgramsEntry

Field	Type	Label	Description
key	string
value	InstrumentCollectionRequest.Collection.Program

InstrumentCollectionRequest.Hook

Field	Type	Label	Description
type	HookType		position of the hook relative to the target program.
target	string		name of the program that should be instrumented.
attach_target	InstrumentCollectionRequest.Hook.AttachTarget		info necessary for loading freplace programs.
pin_path	string		plugin must pin the hook program to this pin path before responding to Cilium.

InstrumentCollectionRequest.Hook.AttachTarget

Field	Type	Label	Description
program_id	uint32		id of the target program.
subprog_name	string		name of the hook’s subprogram inside the target program.

InstrumentCollectionResponse

PrepareCollectionRequest

Phase 1: As Cilium loads and prepares a collection for a particular attachment point, it sends a PrepareHooksRequest to each plugin with context about the attachment point, collection, and its configuration. The plugin decides which hooks it would like to insert, where it would like to insert them, and informs Cilium in the PrepareHooksResponse.

Field	Type	Label	Description
collection	PrepareCollectionRequest.CollectionSpec
attachment_context	AttachmentContext
config	google.protobuf.Any		config contains datapath configuration for this collection.

PrepareCollectionRequest.CollectionSpec

Field	Type	Label	Description
programs	PrepareCollectionRequest.CollectionSpec.ProgramsEntry	repeated	program details for each programs in the collection.
maps	PrepareCollectionRequest.CollectionSpec.MapsEntry	repeated	map details for each map in the collection.

PrepareCollectionRequest.CollectionSpec.MapSpec

Field	Type	Label	Description
type	uint32
key_size	uint32
value_size	uint32
max_entries	uint32
flags	uint32
pin_type	uint32

PrepareCollectionRequest.CollectionSpec.MapsEntry

Field	Type	Label	Description
key	string
value	PrepareCollectionRequest.CollectionSpec.MapSpec

PrepareCollectionRequest.CollectionSpec.ProgramSpec

Field	Type	Label	Description
type	uint32
attach_type	uint32
section_name	string
license	string

PrepareCollectionRequest.CollectionSpec.ProgramsEntry

Field	Type	Label	Description
key	string
value	PrepareCollectionRequest.CollectionSpec.ProgramSpec

PrepareCollectionResponse

Field	Type	Label	Description
hooks	PrepareCollectionResponse.HookSpec	repeated	list of hooks that should be added to the collection.
cookie	string		cookie is an opaque string that will be passed in the subsequent InstrumentCollectionRequest related to this PrepareCollectionRequest. It may be used by plugins to associate the two requests or carry metadata between them.

PrepareCollectionResponse.HookSpec

Field	Type	Label	Description
type	HookType		position of the hook relative to the target program.
target	string		name of the program that should be instrumented.
constraints	PrepareCollectionResponse.HookSpec.OrderingConstraint	repeated	constraints is a list of ordering constraints for this hook. If other plugins want to place a hook at this same hook point, hooks from various plugins will be arranged in an order that respects all ordering constraints.

PrepareCollectionResponse.HookSpec.OrderingConstraint

An OrderingConstraint is a constraint about where this hook should go at this hook point relative to other plugins’ hooks.

Field	Type	Label	Description
order	PrepareCollectionResponse.HookSpec.OrderingConstraint.Order
plugin	string

HookType

Name	Number	Description
UNKNOWN	0
PRE	1	pre hooks run before the main Cilium program.
POST	2	post hooks run after the main Cilium program.

PrepareCollectionResponse.HookSpec.OrderingConstraint.Order

Name	Number	Description
UNKNOWN	0
BEFORE	1
AFTER	2

DatapathPlugin

A DatapathPlugin interacts with Cilium’s loader to augment or modify BPF collections as they are prepared for an attachment point.

Method Name	Request Type	Response Type	Description
PrepareCollection	PrepareCollectionRequest	PrepareCollectionResponse	PrepareCollection happens before the BPF collection is loaded into the kernel. Cilium passes BPF collection details to the plugin and the plugin tells Cilium how it would like to modify the collection.
InstrumentCollection	InstrumentCollectionRequest	InstrumentCollectionResponse	InstrumentCollection happens after the BPF collection is loaded into the kernel. Cilium passes BPF collection details to the plugin along with details about hook attachment points it created in the prepare phase. The plugin loads its BPF programs and passes them back to Cilium to be attached to these hook points.

Scalar Value Types

.proto Type	Notes	C++	Java	Python	Go	C#	PHP	Ruby
double		double	double	float	float64	double	float	Float
float		float	float	float	float32	float	float	Float
int32	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
int64	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.	int64	long	int/long	int64	long	integer/string	Bignum
uint32	Uses variable-length encoding.	uint32	int	int/long	uint32	uint	integer	Bignum or Fixnum (as required)
uint64	Uses variable-length encoding.	uint64	long	int/long	uint64	ulong	integer/string	Bignum or Fixnum (as required)
sint32	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sint64	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.	int64	long	int/long	int64	long	integer/string	Bignum
fixed32	Always four bytes. More efficient than uint32 if values are often greater than 2^28.	uint32	int	int	uint32	uint	integer	Bignum or Fixnum (as required)
fixed64	Always eight bytes. More efficient than uint64 if values are often greater than 2^56.	uint64	long	int/long	uint64	ulong	integer/string	Bignum
sfixed32	Always four bytes.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sfixed64	Always eight bytes.	int64	long	int/long	int64	long	integer/string	Bignum
bool		bool	boolean	boolean	bool	bool	boolean	TrueClass/FalseClass
string	A string must always contain UTF-8 encoded or 7-bit ASCII text.	string	String	str/unicode	string	string	string	String (UTF-8)
bytes	May contain any arbitrary sequence of bytes.	string	ByteString	str	[]byte	ByteString	string	String (ASCII-8BIT)