sensors

Documentation

Overview

SPDX-License-Identifier: Apache-2.0 Copyright Authors of Tetragon

SPDX-License-Identifier: Apache-2.0 Copyright Authors of Tetragon

SPDX-License-Identifier: Apache-2.0 Copyright Authors of Tetragon

Index

• Constants
• Variables
• func LoadConfig(ctx context.Context, bpfDir, mapDir, ciliumDir string, sens []*Sensor) error
• func PathJoin(elem ...string) string
• func RegisterProbeType(probeType string, s probeLoader)
• func RegisterSpecHandlerAtInit(name string, s specHandler)
• func UnloadAll(bpfDir string)
• func UpdateStatsMap(m *ebpf.Map, val int64) error
• type LoadArg
• type LoadProbeArgs
• type Manager
  • func StartSensorManager(bpfDir, mapDir, ciliumDir string) (*Manager, error)
  • func (h *Manager) AddSensor(ctx context.Context, name string, sensor *Sensor) error
  • func (h *Manager) AddTracingPolicy(ctx context.Context, name string, tp TracingPolicy) error
  • func (h *Manager) DelTracingPolicy(ctx context.Context, name string) error
  • func (h *Manager) DisableSensor(ctx context.Context, name string) error
  • func (h *Manager) EnableSensor(ctx context.Context, name string) error
  • func (h *Manager) GetSensorConfig(ctx context.Context, name string, cfgkey string) (string, error)
  • func (h *Manager) ListSensors(ctx context.Context) (*[]SensorStatus, error)
  • func (h *Manager) LogSensorsAndProbes(ctx context.Context)
  • func (h *Manager) RemoveSensor(ctx context.Context, sensorName string) error
  • func (h *Manager) SetSensorConfig(ctx context.Context, name string, cfgkey string, cfgval string) error
  • func (h *Manager) StopSensorManager(ctx context.Context) error
• type Operations
• type Sensor
  • func GetMergedSensorFromParserPolicy(name string, policy interface{}) (*Sensor, error)
  • func GetSensorsFromParserPolicy(spec interface{}) ([]*Sensor, error)
  • func SensorBuilder(name string, p []*program.Program, m []*program.Map) *Sensor
  • func SensorCombine(name string, sensors ...*Sensor) *Sensor
  • func (s *Sensor) FindPrograms(ctx context.Context) error
  • func (s *Sensor) Load(stopCtx context.Context, bpfDir, mapDir, ciliumDir string) error
  • func (s *Sensor) Unload() error
• type SensorStatus
• type SensorUnloadHook
• type TracingPolicy
• type UnloadArg

Constants

const (
	BPF_PROG_TYPE_UNSPEC                  = 0
	BPF_PROG_TYPE_SOCKET_FILTER           = 1
	BPF_PROG_TYPE_KPROBE                  = 2
	BPF_PROG_TYPE_SCHED_CLS               = 3
	BPF_PROG_TYPE_SCHED_ACT               = 4
	BPF_PROG_TYPE_TRACEPOINT              = 5
	BPF_PROG_TYPE_XDP                     = 6
	BPF_PROG_TYPE_PERF_EVENT              = 7
	BPF_PROG_TYPE_CGROUP_SKB              = 8
	BPF_PROG_TYPE_CGROUP_SOCK             = 9
	BPF_PROG_TYPE_LWT_IN                  = 10
	BPF_PROG_TYPE_LWT_OUT                 = 11
	BPF_PROG_TYPE_LWT_XMIT                = 12
	BPF_PROG_TYPE_SOCK_OPS                = 13
	BPF_PROG_TYPE_SK_SKB                  = 14
	BPF_PROG_TYPE_CGROUP_DEVICE           = 15
	BPF_PROG_TYPE_SK_MSG                  = 16
	BPF_PROG_TYPE_RAW_TRACEPOINT          = 17
	BPF_PROG_TYPE_CGROUP_SOCK_ADDR        = 18
	BPF_PROG_TYPE_LWT_SEG6LOCAL           = 19
	BPF_PROG_TYPE_LIRC_MODE2              = 20
	BPF_PROG_TYPE_SK_REUSEPORT            = 21
	BPF_PROG_TYPE_FLOW_DISSECTOR          = 22
	BPF_PROG_TYPE_CGROUP_SYSCTL           = 23
	BPF_PROG_TYPE_RAW_TRACEPOINT_WRITABLE = 24
	BPF_PROG_TYPE_CGROUP_SOCKOPT          = 25
	BPF_PROG_TYPE_TRACING                 = 26
	BPF_PROG_TYPE_STRUCT_OPS              = 27
	BPF_PROG_TYPE_EXT                     = 28
	BPF_PROG_TYPE_LSM                     = 29
)

Variables

var (
	// AllPrograms are all the loaded programs. For use with Unload().
	AllPrograms = []*program.Program{}
	// AllMaps are all the loaded programs. For use with Unload().
	AllMaps = []*program.Map{}
)

Functions

func LoadConfig

func LoadConfig(ctx context.Context, bpfDir, mapDir, ciliumDir string, sens []*Sensor) error

LoadConfig loads the default sensor, including any from the configuration file.

func PathJoin

func PathJoin(elem ...string) string

PathJoin creates a path meant for sensor filenames in /sys/fs/bpf.

At some point, we would like to have a file hierarchy under /sys/fs/bpf for each sensor. see: https://github.com/go-faster/tetragon/issues/408

Unfortunately, this requires changes, for properly creating and deleting these directories requires. As an intermediate step, we use this function that uses dashes instead of / to create unique files in flat hierarchy, without needeing to manage directories.

func RegisterProbeType

func RegisterProbeType(probeType string, s probeLoader)

RegisterProbeType registers a handler for a probe type string

This function is meant to be called in an init() by sensors that need extra logic when loading a specific probe type.

func RegisterSpecHandlerAtInit

func RegisterSpecHandlerAtInit(name string, s specHandler)

RegisterSpecHandlerAtInit registers a handler for Tracing policy.

This function is meant to be called in an init(). This will register a CRD or config file handler so that the config file or CRDs will be passed to the handler to be parsed.

func UnloadAll

func UnloadAll(bpfDir string)

func UpdateStatsMap

func UpdateStatsMap(m *ebpf.Map, val int64) error

Types

type LoadArg

type LoadArg struct {
	STTManagerHandle sttManager.Handle
}

type LoadProbeArgs

type LoadProbeArgs struct {
	BPFDir, MapDir, CiliumDir string
	Load                      *program.Program
	Version, Verbose          int
}

LoadProbeArgs are the args to the LoadProbe function.

type Manager

type Manager struct {
	STTManager sttManager.Handle
	// contains filtered or unexported fields
}

Manager handles dynamic sensor management, such as adding / removing sensors at runtime.

func StartSensorManager

func StartSensorManager(bpfDir, mapDir, ciliumDir string) (*Manager, error)

StartSensorManager initializes the sensorCtlHandle by spawning a sensor controller goroutine.

The purpose of this goroutine is to serialize loading and unloading of sensors as requested from different goroutines (e.g., different GRPC clients).

func (*Manager) AddSensor

func (h *Manager) AddSensor(ctx context.Context, name string, sensor *Sensor) error

AddSensor adds a sensor

func (*Manager) AddTracingPolicy

func (h *Manager) AddTracingPolicy(ctx context.Context, name string, tp TracingPolicy) error

AddTracingPolicy adds a new sensor based on a tracing policy

func (*Manager) DelTracingPolicy

func (h *Manager) DelTracingPolicy(ctx context.Context, name string) error

DelTracingPolicy deletes a new sensor based on a tracing policy

func (*Manager) DisableSensor

func (h *Manager) DisableSensor(ctx context.Context, name string) error

DisableSensor disables a sensor by name

func (*Manager) EnableSensor

func (h *Manager) EnableSensor(ctx context.Context, name string) error

EnableSensor enables a sensor by name

func (*Manager) GetSensorConfig

func (h *Manager) GetSensorConfig(ctx context.Context, name string, cfgkey string) (string, error)

func (*Manager) ListSensors

func (h *Manager) ListSensors(ctx context.Context) (*[]SensorStatus, error)

func (*Manager) LogSensorsAndProbes

func (h *Manager) LogSensorsAndProbes(ctx context.Context)

func (*Manager) RemoveSensor

func (h *Manager) RemoveSensor(ctx context.Context, sensorName string) error

func (*Manager) SetSensorConfig

func (h *Manager) SetSensorConfig(ctx context.Context, name string, cfgkey string, cfgval string) error

func (*Manager) StopSensorManager

func (h *Manager) StopSensorManager(ctx context.Context) error

type Operations

type Operations interface {
	Loaded(arg LoadArg)
	Unloaded(arg UnloadArg)

	GetConfig(cfg string) (string, error)
	SetConfig(cfg string, val string) error
}

Operations is the interface to the underlying sensor implementations.

type Sensor

type Sensor struct {
	// Name is a human-readbale description.
	Name string
	// Progs are all the BPF programs that exist on the filesystem.
	Progs []*program.Program
	// Maps are all the BPF Maps that the progs use.
	Maps []*program.Map
	// Loaded indicates whether the sensor has been Loaded.
	Loaded bool
	// Ops contains an implementation to perform on this sensor.
	Ops Operations
	// UnloadHook can optionally contain a pointer to a function to be
	// called during sensor unloading, prior to the programs and maps being
	// unloaded.
	UnloadHook SensorUnloadHook
}

Sensor is a set of BPF programs and maps that are managed as a unit.

NB: We need to rethink the Ops field. See manager main loop for some discussion on this. If we decide to keep them, we should merge them with the UnloadHook since the two are similar: ops.Unloaded is called when a sensor is successfully unloaded, while UnloadHook is called during unloading.

func GetMergedSensorFromParserPolicy

func GetMergedSensorFromParserPolicy(name string, policy interface{}) (*Sensor, error)

func GetSensorsFromParserPolicy

func GetSensorsFromParserPolicy(spec interface{}) ([]*Sensor, error)

func SensorBuilder

func SensorBuilder(name string, p []*program.Program, m []*program.Map) *Sensor

func SensorCombine

func SensorCombine(name string, sensors ...*Sensor) *Sensor

func (*Sensor) FindPrograms

func (s *Sensor) FindPrograms(ctx context.Context) error

FindPrograms finds all the BPF programs in the sensor on the filesytem.

func (*Sensor) Load

func (s *Sensor) Load(stopCtx context.Context, bpfDir, mapDir, ciliumDir string) error

Load loads the sensor, by loading all the BPF programs and maps.

func (*Sensor) Unload

func (s *Sensor) Unload() error

type SensorStatus

type SensorStatus struct {
	Name    string
	Enabled bool
}

type SensorUnloadHook

type SensorUnloadHook func() error

SensorUnloadHook is the function signature for an optional function that can be called during sensor unloading.

type TracingPolicy

type TracingPolicy interface {
	TpSpec() *v1alpha1.TracingPolicySpec
	TpInfo() string
}

TracingPolicy is an interface for a tracing policy This is implemented by v1alpha1.types.TracingPolicy and config.GenericTracingConf. The former is what is the k8s API server uses, and the latter is used when we load files directly (e.g., via the cli).

type UnloadArg

type UnloadArg = LoadArg