ouroboros

package
v0.1.5 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 28, 2025 License: MIT Imports: 16 Imported by: 0

Documentation

Overview

Package ouroboros provides a Go SDK for managing multiple eBPF programs.

This package allows you to programmatically interact with Ouroboros projects, manage eBPF programs, and perform operations like building, loading, and attaching programs without using the CLI.

Example usage: 

import "github.com/PacketStream-LLC/ouroboros/pkg/ouroboros"

// Load an existing project
o, err := ouroboros.New()
if err != nil {
    log.Fatal(err)
}

// Add a new program
prog := ouroboros.Program{
    Name: "myprogram",
}
if err := o.AddProgram(prog); err != nil {
    log.Fatal(err)
}

// Save configuration
if err := o.SaveConfig(); err != nil {
    log.Fatal(err)
}

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func CalculateMapMemlock 

func CalculateMapMemlock(mapInfo *MapInfo) uint64

CalculateMapMemlock estimates the memory locked by a map. This is an approximation of kernel memory usage.

func MapTypeToString 

func MapTypeToString(mapType ebpf.MapType) string

MapTypeToString converts a map type to its string representation.

func SetLogLevel added in v0.1.5 

func SetLogLevel(level LogLevel)

SetLogLevel sets the global log level for the Ouroboros SDK. This affects all logging output from the SDK.

func SetLogLevelString added in v0.1.5 

func SetLogLevelString(level string)

SetLogLevelString sets the global log level from a string. Valid values are: "debug", "info", "warn", "error". Invalid values default to "info".

func SetSilent added in v0.1.5 

func SetSilent(silent bool)

SetSilent disables all logging output from the SDK. Useful when using the SDK as a library where you want to handle logging yourself or suppress all output.

func SetVerbose added in v0.1.5 

func SetVerbose(verbose bool)

SetVerbose enables or disables verbose (debug) logging. This is a convenience function equivalent to SetLogLevel(LogLevelDebug).

Types

type AttachMode 

type AttachMode int

AttachMode specifies how to attach an XDP program. 

const (
	// AttachModeGeneric uses generic XDP (slower but works everywhere)
	AttachModeGeneric AttachMode = iota
	// AttachModeNative uses native XDP (faster, driver support required)
	AttachModeNative
	// AttachModeOffload uses hardware offload (fastest, hardware support required)
	AttachModeOffload
)

type AttachOptions 

type AttachOptions struct {
	// Mode specifies the XDP attach mode
	Mode AttachMode
	// Replace allows replacing an existing attached program
	Replace bool
}

AttachOptions contains options for attaching programs.

type AttachedProgram 

type AttachedProgram struct {
	Program   *LoadedProgram
	Interface string
	Link      link.Link
}

AttachedProgram represents a program attached to an interface.

type BuildOptions 

type BuildOptions struct {
	// Stdout is where to write build output (optional, defaults to discard)
	Stdout io.Writer
	// Stderr is where to write build errors (optional, defaults to discard)
	Stderr io.Writer
	// AdditionalArgs are additional arguments to pass to clang
	AdditionalArgs []string
}

BuildOptions contains options for building eBPF programs.

type Config 

type Config struct {
	Programs      []Program `json:"programs"`
	CompileArgs   []string  `json:"compile_args"`
	ProgramMap    string    `json:"program_map,omitempty"`
	ProgramPrefix string    `json:"program_prefix,omitempty"`
	BpfBaseDir    string    `json:"bpf_base_dir,omitempty"`
}

Config represents the Ouroboros project configuration.

type LoadOptions 

type LoadOptions struct {
	// PinPath is the directory where programs and maps should be pinned
	PinPath string
	// ReplaceMaps allows replacing existing pinned maps
	ReplaceMaps bool
	// RecreateProgramMap automatically recreates program maps if incompatible
	RecreateProgramMap bool
}

LoadOptions contains options for loading eBPF programs.

type LoadedProgram 

type LoadedProgram struct {
	Name       string
	ID         int
	Program    *ebpf.Program
	Collection *ebpf.Collection
}

LoadedProgram represents a program that has been loaded into the kernel.

type LogLevel added in v0.1.5 

type LogLevel int

LogLevel represents a logging level 

const (
	LogLevelDebug LogLevel = LogLevel(slog.LevelDebug)
	LogLevelInfo  LogLevel = LogLevel(slog.LevelInfo)
	LogLevelWarn  LogLevel = LogLevel(slog.LevelWarn)
	LogLevelError LogLevel = LogLevel(slog.LevelError)
)

type MapAnalysis 

type MapAnalysis struct {
	TotalMaps    int
	SharedMaps   []string
	UniqueMaps   []string
	MapsByType   map[ebpf.MapType][]string
	Dependencies map[string][]string // map name -> programs using it
}

MapAnalysis contains analysis results for maps and their relationships.

type MapInfo 

type MapInfo struct {
	Name       string
	Type       ebpf.MapType
	KeySize    uint32
	ValueSize  uint32
	MaxEntries uint32
	DependsBy  []string // DependsBy that use this map
	ID         uint32   // Kernel ID if loaded
	Pinned     bool     // Whether the map is pinned
}

MapInfo represents an eBPF map with its metadata and relationships.

type Ouroboros 

type Ouroboros struct {
	// contains filtered or unexported fields
}

Ouroboros represents the main SDK instance for managing eBPF programs. It encapsulates the project configuration and provides methods for program management, building, loading, and other operations.

func InitializeProject 

func InitializeProject(mainProgName string) (*Ouroboros, error)

InitializeProject creates a new Ouroboros project structure with the given main program name. It creates the necessary directories (src, target, src/_ouroboros) and a default configuration.

func InitializeProjectWithMap 

func InitializeProjectWithMap(mainProgName, programMapName string) (*Ouroboros, error)

InitializeProjectWithMap creates a new Ouroboros project structure with custom program map name. It creates the necessary directories (src, target, src/_ouroboros) and a default configuration. If programMapName is empty, no custom program map name will be set.

func New 

func New() (*Ouroboros, error)

New creates a new Ouroboros SDK instance by loading the configuration from the current directory. Returns an error if the configuration file doesn't exist or is invalid.

func NewFromPath added in v0.1.3 

func NewFromPath(path string) (*Ouroboros, error)

NewFromPath creates a new Ouroboros SDK instance by loading the configuration from the specified path. The path can be either a directory containing ouroboros.json or the path to the ouroboros.json file itself.

func NewWithConfig 

func NewWithConfig(cfg *Config) *Ouroboros

NewWithConfig creates a new Ouroboros SDK instance with the provided configuration. This is useful for creating projects programmatically or for testing.

func NewWithProjectConfig added in v0.1.3 

func NewWithProjectConfig(cfg *Config, workingDir string) *Ouroboros

NewWithProjectConfig creates a new Ouroboros SDK instance with the provided configuration, with specified project working directory. This is useful for creating projects programmatically or for testing.

func (*Ouroboros) AddNewProgram 

func (o *Ouroboros) AddNewProgram(progName string, mainCTemplate string) error

AddNewProgram is a high-level operation that adds a program with all necessary setup. It creates the program directory, generates the main.c file from the template, assigns an ID, and saves the configuration.

func (*Ouroboros) AddProgram 

func (o *Ouroboros) AddProgram(prog Program) error

AddProgram adds a new program to the configuration. If the program ID is 0, it will be automatically assigned. Returns an error if a program with the same name already exists.

func (*Ouroboros) AnalyzeMaps 

func (o *Ouroboros) AnalyzeMaps() (*MapAnalysis, error)

AnalyzeMaps performs comprehensive analysis of all maps.

func (*Ouroboros) AttachMainProgram 

func (o *Ouroboros) AttachMainProgram(ifaceName string, opts *AttachOptions) (*AttachedProgram, error)

AttachMainProgram is a convenience method to attach the main program to an interface. This loads ALL programs in the project (to populate the program map for tail calls) and then attaches the main program to the specified interface.

func (*Ouroboros) AttachToInterface 

func (o *Ouroboros) AttachToInterface(loaded *LoadedProgram, ifaceName string, opts *AttachOptions) (*AttachedProgram, error)

AttachToInterface attaches a loaded XDP program to a network interface. The program must be loaded before calling this method.

func (*Ouroboros) BuildAll 

func (o *Ouroboros) BuildAll(opts *BuildOptions) map[string]error

BuildAll compiles all eBPF programs in the project. Returns a map of program names to errors (nil if successful).

func (*Ouroboros) BuildAllOrFail 

func (o *Ouroboros) BuildAllOrFail(opts *BuildOptions) error

BuildAllOrFail compiles all eBPF programs and returns an error if any fail.

func (*Ouroboros) BuildProgram 

func (o *Ouroboros) BuildProgram(progName string, opts *BuildOptions) error

BuildProgram compiles a single eBPF program. It runs clang with the appropriate flags to compile the program's main.c into an eBPF object file in the target directory.

func (*Ouroboros) CleanBuildArtifacts 

func (o *Ouroboros) CleanBuildArtifacts() error

CleanBuildArtifacts removes all build artifacts including the target directory and the global ouroboros directory.

func (*Ouroboros) CleanProgram 

func (o *Ouroboros) CleanProgram(progName string) error

CleanProgram removes the compiled object for a specific program.

func (*Ouroboros) CompileToLLVMIR 

func (o *Ouroboros) CompileToLLVMIR(progName string, opts *BuildOptions) error

CompileToLLVMIR compiles a program to LLVM IR (.ll file) instead of object code. This is useful for analysis and optimization.

func (*Ouroboros) Config 

func (o *Ouroboros) Config() *Config

Config returns a copy of the current configuration.

func (*Ouroboros) CreateProgramFromTemplate 

func (o *Ouroboros) CreateProgramFromTemplate(progName string, tmpl string) error

CreateProgramFromTemplate creates a new program directory and main.c from template. The template should use {{.ProgramName}} for the program name placeholder.

func (*Ouroboros) DetachByName 

func (o *Ouroboros) DetachByName(ifaceName string) error

DetachByName detaches a program from an interface by name. This is useful when you don't have the AttachedProgram handle. This method loads the pinned link and uses it to detach.

func (*Ouroboros) DetachFromInterface 

func (o *Ouroboros) DetachFromInterface(attached *AttachedProgram) error

DetachFromInterface detaches a program from an interface.

func (*Ouroboros) EnsureGlobalDirectory 

func (o *Ouroboros) EnsureGlobalDirectory() error

EnsureGlobalDirectory creates the global ouroboros directory if it doesn't exist.

func (*Ouroboros) EnsureProgramDirectory 

func (o *Ouroboros) EnsureProgramDirectory(progName string) error

EnsureProgramDirectory creates a program's source directory if it doesn't exist.

func (*Ouroboros) EnsureTargetDirectory 

func (o *Ouroboros) EnsureTargetDirectory() error

EnsureTargetDirectory creates the target directory if it doesn't exist.

func (*Ouroboros) GenerateGitignore 

func (o *Ouroboros) GenerateGitignore() error

GenerateGitignore creates a .gitignore file for the project.

func (*Ouroboros) GenerateMakefile 

func (o *Ouroboros) GenerateMakefile() error

GenerateMakefile generates a basic Makefile for building the project.

func (*Ouroboros) GenerateProgramsHeader 

func (o *Ouroboros) GenerateProgramsHeader() error

GenerateProgramsHeader generates the programs.h header file in src/_ouroboros/. This header contains #define constants for each program's ID, making it easy to reference programs in C code (especially for tail calls).

func (*Ouroboros) GetAttachedProgramID 

func (o *Ouroboros) GetAttachedProgramID(ifaceName string) (uint32, error)

GetAttachedProgramID returns the ID of the program attached to an interface. Returns 0 if no program is attached. Note: This requires additional kernel support and is currently not fully implemented.

func (*Ouroboros) GetBpfBaseDir 

func (o *Ouroboros) GetBpfBaseDir() string

GetBpfBaseDir returns the BPF filesystem base directory.

func (*Ouroboros) GetCompileArgs 

func (o *Ouroboros) GetCompileArgs() []string

GetCompileArgs returns the compile arguments from configuration.

func (*Ouroboros) GetLoadedProgram 

func (o *Ouroboros) GetLoadedProgram(progName string) (*ebpf.Program, error)

GetLoadedProgram retrieves a handle to a loaded (pinned) program.

func (*Ouroboros) GetMainProgram 

func (o *Ouroboros) GetMainProgram() *Program

GetMainProgram returns the main program, or nil if no main program is set.

func (*Ouroboros) GetMap 

func (o *Ouroboros) GetMap(mapName string) (*ebpf.Map, error)

func (*Ouroboros) GetMapInfo added in v0.1.4 

func (o *Ouroboros) GetMapInfo(mapName string) (*MapInfo, error)

GetMapInfo returns information about a specific map by name.

func (*Ouroboros) GetMapInfosByProgram added in v0.1.4 

func (o *Ouroboros) GetMapInfosByProgram(progName string) (map[string]*MapInfo, error)

GetMapInfosByProgram returns all maps used by a specific program.

func (*Ouroboros) GetMapOptions 

func (o *Ouroboros) GetMapOptions() ebpf.MapOptions

GetMapOptions returns eBPF map options with the configured pin path.

func (*Ouroboros) GetNextProgramID 

func (o *Ouroboros) GetNextProgramID() int

GetNextProgramID returns the next available program ID.

func (*Ouroboros) GetOuroborosGlobalDir 

func (o *Ouroboros) GetOuroborosGlobalDir() (string, error)

GetOuroborosGlobalDir returns the absolute path to the _ouroboros directory.

func (*Ouroboros) GetProgram 

func (o *Ouroboros) GetProgram(name string) *Program

GetProgram finds a program by name. Returns nil if not found.

func (*Ouroboros) GetProgramByID 

func (o *Ouroboros) GetProgramByID(id int) *Program

GetProgramByID finds a program by ID. Returns nil if not found.

func (*Ouroboros) GetProgramLLPath 

func (o *Ouroboros) GetProgramLLPath(progName string) string

GetProgramLLPath returns the path to a program's LLVM IR file.

func (*Ouroboros) GetProgramMainFile 

func (o *Ouroboros) GetProgramMainFile(progName string) string

GetProgramMainFile returns the path to a program's main.c file.

func (*Ouroboros) GetProgramMap 

func (o *Ouroboros) GetProgramMap() string

GetProgramMap returns the configured program map name.

func (*Ouroboros) GetProgramObjectPath 

func (o *Ouroboros) GetProgramObjectPath(progName string) string

GetProgramObjectPath returns the path to a compiled program object file.

func (*Ouroboros) GetProgramPath 

func (o *Ouroboros) GetProgramPath(progName string) string

GetProgramPath returns the filesystem path for a program's source directory.

func (*Ouroboros) GetProgramSize 

func (o *Ouroboros) GetProgramSize(progName string) int64

GetProgramSize returns the size of a compiled program object in bytes. Returns 0 if the program hasn't been built.

func (*Ouroboros) GetProgramsByMap 

func (o *Ouroboros) GetProgramsByMap(mapName string) ([]string, error)

GetProgramsByMap returns all programs that use a specific map.

func (*Ouroboros) GetProjectRoot 

func (o *Ouroboros) GetProjectRoot() (string, error)

GetProjectRoot returns the project root directory (where ouroboros.json is located).

func (*Ouroboros) GetSrcDir 

func (o *Ouroboros) GetSrcDir() (string, error)

GetSrcDir returns the absolute path to the src directory.

func (*Ouroboros) GetTargetDir 

func (o *Ouroboros) GetTargetDir() (string, error)

GetTargetDir returns the absolute path to the target directory.

func (*Ouroboros) IsAttached 

func (o *Ouroboros) IsAttached(ifaceName string) (bool, error)

IsAttached checks if any XDP program is attached to an interface. This checks for a pinned link in the BPF filesystem.

func (*Ouroboros) IsMapShared 

func (o *Ouroboros) IsMapShared(mapName string) (bool, error)

IsMapShared returns true if a map is used by multiple programs.

func (*Ouroboros) IsProgramBuilt 

func (o *Ouroboros) IsProgramBuilt(progName string) bool

IsProgramBuilt checks if a program has been built (object file exists).

func (*Ouroboros) IsProgramLoaded 

func (o *Ouroboros) IsProgramLoaded(progName string) bool

IsProgramLoaded checks if a program is currently loaded (pinned) in the kernel.

func (*Ouroboros) ListInterfaces 

func (o *Ouroboros) ListInterfaces() ([]string, error)

ListInterfaces returns all available network interfaces.

func (*Ouroboros) ListMapInfos added in v0.1.4 

func (o *Ouroboros) ListMapInfos() (map[string]*MapInfo, error)

ListMapInfos discovers all maps from compiled programs. It analyzes the object files to extract map specifications.

func (*Ouroboros) ListPrograms 

func (o *Ouroboros) ListPrograms() []Program

ListPrograms returns all programs in the configuration.

func (*Ouroboros) LoadAllPrograms 

func (o *Ouroboros) LoadAllPrograms(opts *LoadOptions) (map[string]*LoadedProgram, map[string]error)

LoadAllPrograms loads all programs in the project into the kernel. Returns a map of program names to loaded programs or errors.

func (*Ouroboros) LoadPinnedMap 

func (o *Ouroboros) LoadPinnedMap(mapName string) (*ebpf.Map, error)

LoadPinnedMap loads a pinned map by name and returns the handle.

func (*Ouroboros) LoadProgram 

func (o *Ouroboros) LoadProgram(progName string, opts *LoadOptions) (*LoadedProgram, error)

LoadProgram loads a single eBPF program into the kernel. It loads the compiled object file, pins it to the BPF filesystem, and returns a handle to the loaded program.

func (*Ouroboros) LoadProgramMap 

func (o *Ouroboros) LoadProgramMap(recreate bool) (*ebpf.Map, error)

LoadProgramMap loads or creates the program array map used for tail calls.

func (*Ouroboros) PinProgram 

func (o *Ouroboros) PinProgram(loaded *LoadedProgram) error

PinProgram pins a loaded program to the BPF filesystem. This allows the program to persist after the loading process exits.

func (*Ouroboros) RebuildProgram 

func (o *Ouroboros) RebuildProgram(progName string, opts *BuildOptions) error

RebuildProgram removes old build artifacts and rebuilds a program.

func (*Ouroboros) ReloadConfig 

func (o *Ouroboros) ReloadConfig() error

ReloadConfig reloads the configuration from disk.

func (*Ouroboros) RemoveProgram 

func (o *Ouroboros) RemoveProgram(name string) error

RemoveProgram removes a program from the configuration by name.

func (*Ouroboros) SaveConfig 

func (o *Ouroboros) SaveConfig() error

SaveConfig writes the current configuration to disk.

func (*Ouroboros) SetCompileArgs 

func (o *Ouroboros) SetCompileArgs(args []string)

SetCompileArgs sets the compile arguments.

func (*Ouroboros) UnloadAllPrograms 

func (o *Ouroboros) UnloadAllPrograms() map[string]error

UnloadAllPrograms unloads all loaded programs.

func (*Ouroboros) UnloadProgram 

func (o *Ouroboros) UnloadProgram(loaded *LoadedProgram) error

UnloadProgram unloads a program from the kernel and closes its resources.

func (*Ouroboros) UnpinProgram 

func (o *Ouroboros) UnpinProgram(progName string) error

UnpinProgram unpins a program from the BPF filesystem.

func (*Ouroboros) UpdateProgramMap 

func (o *Ouroboros) UpdateProgramMap(progMap *ebpf.Map, loaded *LoadedProgram) error

UpdateProgramMap updates the program array map with a loaded program. This is used for tail call support.

type Program 

type Program struct {
	Name       string           `json:"name"`
	ID         int              `json:"id"`
	IsMain     bool             `json:"is_main,omitempty"`
	Metadata   *ProgramMetadata `json:"metadata,omitempty"`
	Entrypoint string           `json:"entrypoint,omitempty"`
}

Program represents an eBPF program in the project.

type ProgramMetadata 

type ProgramMetadata struct {
	HiddenOnFlow bool `json:"hidden_on_flow,omitempty"`
}

ProgramMetadata contains additional program metadata.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.