Protocol Documentation

Table of Contents

• recorder/recorder.proto

  • FileSinkConfiguration

  • FileSinkResult

  • Filter

  • RecordRequest

  • RecordResponse

  • RecordingRunningResponse

  • RecordingStatistics

  • RecordingStoppedResponse

  • StartRecording

  • StopCondition

  • StopRecording

  • Protocol

  • Recorder

• Scalar Value Types

Top

recorder/recorder.proto

FileSinkConfiguration

FileSinkConfiguration configures the file output. Possible future additions might be the selection of the output volume. The initial implementation will only support a single volume which is configured as a cilium-agent CLI flag.

Field	Type	Label	Description
file_prefix	string		file_prefix is an optional prefix for the file name. Defaults to hubble if empty. Must match the following regex if not empty: ^[a-z][a-z0-9]{0,19}$ The generated filename will be of format <file_prefix><unixtime><unique_random>_<node_name>.pcap

FileSinkResult

Field	Type	Label	Description
file_path	string		file_path is the absolute path to the captured pcap file

Filter

Field	Type	Label	Description
source_cidr	string		source_cidr. Must not be empty. Set to 0.0.0.0/0 to match any IPv4 source address (::/0 for IPv6).
source_port	uint32		source_port. Matches any source port if empty.
destination_cidr	string		destination_cidr. Must not be empty. Set to 0.0.0.0/0 to match any IPv4 destination address (::/0 for IPv6).
destination_port	uint32		destination_port. Matches any destination port if empty.
protocol	Protocol		protocol. Matches any protocol if empty.

RecordRequest

Field	Type	Label	Description
start	StartRecording		start starts a new recording with the given parameters.
stop	StopRecording		stop stops the running recording.

RecordResponse

Field	Type	Label	Description
node_name	string		name of the node where this recording is happening
time	google.protobuf.Timestamp		time at which this event was observed on the above node
running	RecordingRunningResponse		running means that the recording is capturing packets. This is emitted in regular intervals
stopped	RecordingStoppedResponse		stopped means the recording has stopped

RecordingRunningResponse

Field	Type	Label	Description
stats	RecordingStatistics		stats for the running recording

RecordingStatistics

Field	Type	Label	Description
bytes_captured	uint64		bytes_captured is the total amount of bytes captured in the recording
packets_captured	uint64		packets_captured is the total amount of packets captured the recording
packets_lost	uint64		packets_lost is the total amount of packets matching the filter during the recording, but never written to the sink because it was overloaded.
bytes_lost	uint64		bytes_lost is the total amount of bytes matching the filter during the recording, but never written to the sink because it was overloaded.

RecordingStoppedResponse

Field	Type	Label	Description
stats	RecordingStatistics		stats for the recording
filesink	FileSinkResult		filesink contains the path to the captured file

StartRecording

Field	Type	Label	Description
filesink	FileSinkConfiguration		filesink configures the outfile of this recording Future alternative sink configurations may be added as a backwards-compatible change by moving this field into a oneof.
include	Filter	repeated	include list for this recording. Packets matching any of the provided filters will be recorded.
max_capture_length	uint32		max_capture_length specifies the maximum packet length. Full packet length will be captured if absent/zero.
stop_condition	StopCondition		stop_condition defines conditions which will cause the recording to stop early after any of the stop conditions has been hit

StopCondition

StopCondition defines one or more conditions which cause the recording to stop after they have been hit. Stop conditions are ignored if they are absent or zero-valued. If multiple conditions are defined, the recording stops after the first one is hit.

Field	Type	Label	Description
bytes_captured_count	uint64		bytes_captured_count stops the recording after at least this many bytes have been captured. Note: The resulting file might be slightly larger due to added pcap headers.
packets_captured_count	uint64		packets_captured_count stops the recording after at least this many packets have been captured.
time_elapsed	google.protobuf.Duration		time_elapsed stops the recording after this duration has elapsed.

StopRecording

Protocol

Protocol is a one of the supported protocols for packet capture

Name	Number	Description
PROTOCOL_ANY	0
PROTOCOL_TCP	6
PROTOCOL_UDP	17
PROTOCOL_SCTP	132

Recorder

Recorder implements the Hubble module for capturing network packets

Method Name	Request Type	Response Type	Description
Record	RecordRequest stream	RecordResponse stream	Record can start and stop a single recording. The recording is automatically stopped if the client aborts this rpc call.

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)