gont

package
v2.11.2 Latest Latest
Warning

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

 Go to latest Published: Dec 16, 2024 License: Apache-2.0 Imports: 50 Imported by: 2

Documentation

Index

Constants

View Source 
const (
	LinkTypeUser0 = 147
	LinkTypeTrace = LinkTypeUser0
)
View Source 
const (
	WithQdiscNetem = (1 << iota)
	WithQdiscTbf   = (1 << iota)
)
View Source 
const CGoPCAP = true

Variables

View Source 
var (
	DefaultIPv4Mask = net.IPNet{
		IP:   net.IPv4zero,
		Mask: net.CIDRMask(0, net.IPv4len*8),
	}

	DefaultIPv6Mask = net.IPNet{
		IP:   net.IPv6zero,
		Mask: net.CIDRMask(0, net.IPv6len*8),
	}
)
View Source 
var DefaultPreserveEnvVars = []string{
	"PATH",
}
View Source 
var ErrInvalidName = errors.New("invalid name")
View Source 
var ErrNameReserved = errors.New("name 'host' is reserved")
View Source 
var GlobalOptions []Option //nolint:gochecknoglobals
View Source 
var IPv4loopback = net.IPv4(127, 0, 0, 1) //nolint:gochecknoglobals

IPv4loopback is the IPv4 loopback address (127.0.0.1)

View Source 
var Names = []string{}/* 226 elements not displayed */

Names is a list of well known persons in information theory / networking From:

Functions

func CheckCaps 

func CheckCaps() error

CheckCaps checks if the current process has the required privileges to run Gont

func Exec 

func Exec(network, node string, args []string) error

func GenerateNetworkName 

func GenerateNetworkName() string

func Identify 

func Identify() (string, string, error)

Identify returns the network and node name if the current process is running in a network netspace created by Gont

func NetworkCGroups added in v2.10.0 

func NetworkCGroups() []string

func NetworkNames 

func NetworkNames() []string

func NodeNames 

func NodeNames(network string) []string

func RandomName added in v2.10.0 

func RandomName() string

func RandomNames added in v2.10.0 

func RandomNames(yield func(string) bool)

func SerializePacket 

func SerializePacket(t *trace.Event) (data []byte, ci gopacket.CaptureInfo, err error)

func TeardownNetwork 

func TeardownNetwork(ctx context.Context, c *dbus.Conn, network string) error

func TeardownNode 

func TeardownNode(ctx context.Context, c *dbus.Conn, network, node string) error

func TeardownStaleCgroups added in v2.10.0 

func TeardownStaleCgroups(ctx context.Context, c *dbus.Conn) ([]string, error)

TeardownStaleCgroups deletes all stale CGroup slices for which no corresponding Gont network exists.

func TestConnectivity 

func TestConnectivity(hosts ...*Host) error

TestConnectivity performs ICMP ping tests between all pairs of nodes in the network

func Unshare 

func Unshare(network, node string) error

Types

type BaseNode 

type BaseNode struct {
	*Namespace
	*CGroup

	VarPath string

	Interfaces []*Interface

	// Options
	ConfiguredInterfaces     []*Interface
	Tracer                   *Tracer
	Debugger                 *Debugger
	ExistingNetworkNamespace string
	ExistingDockerContainer  string
	Slice                    string
	RedirectToLog            bool
	EmptyDirs                []string
	Captures                 []*Capture
	// contains filtered or unexported fields
}

func (*BaseNode) AddDefaultRoute 

func (n *BaseNode) AddDefaultRoute(gw net.IP) error

AddDefaultRoute adds a default route for this node by providing a default gateway.

func (*BaseNode) AddInterface 

func (n *BaseNode) AddInterface(i *Interface)

AddInterface adds an interface to the list of configured interfaces

func (*BaseNode) AddRoute 

func (n *BaseNode) AddRoute(r *nl.Route) error

AddRoute adds a route to the node.

func (*BaseNode) BuildGo 

func (n *BaseNode) BuildGo(fileOrPkg string, args ...any) (*os.File, error)

func (*BaseNode) Close 

func (n *BaseNode) Close() error

func (*BaseNode) Command 

func (n *BaseNode) Command(name string, args ...any) *Cmd

func (*BaseNode) ConfigureInterface 

func (n *BaseNode) ConfigureInterface(i *Interface) error

func (*BaseNode) EnableForwarding 

func (n *BaseNode) EnableForwarding() error

EnableForwarding enables forwarding for both IPv4 and IPv6 protocols in the kernel for all interfaces

func (*BaseNode) Interface 

func (n *BaseNode) Interface(name string) *Interface

func (*BaseNode) Name 

func (n *BaseNode) Name() string

func (*BaseNode) NetNSHandle 

func (n *BaseNode) NetNSHandle() netns.NsHandle

func (*BaseNode) NetlinkHandle 

func (n *BaseNode) NetlinkHandle() *nl.Handle

func (*BaseNode) Network 

func (n *BaseNode) Network() *Network

Network returns the network to which this node belongs

func (*BaseNode) NftConn 

func (n *BaseNode) NftConn() *nft.Conn

func (*BaseNode) Run 

func (n *BaseNode) Run(cmd string, args ...any) (*Cmd, error)

func (*BaseNode) RunGo 

func (n *BaseNode) RunGo(fileOrPkg string, args ...any) (*Cmd, error)

func (*BaseNode) Start 

func (n *BaseNode) Start(cmd string, args ...any) (*Cmd, error)

func (*BaseNode) StartGo 

func (n *BaseNode) StartGo(fileOrPkg string, args ...any) (*Cmd, error)

func (*BaseNode) String 

func (n *BaseNode) String() string

func (*BaseNode) Teardown 

func (n *BaseNode) Teardown() error

func (*BaseNode) WriteProcFS 

func (n *BaseNode) WriteProcFS(path, value string) error

WriteProcFS write a value to a path within the ProcFS by entering the namespace of this node.

type BaseNodeOption 

type BaseNodeOption interface {
	ApplyBaseNode(n *BaseNode)
}

type BridgeOption 

type BridgeOption interface {
	ApplyBridge(br *nl.Bridge)
}

type CGroup added in v2.10.0 

type CGroup struct {
	Name       string
	Type       string
	Properties []dbus.Property
	// contains filtered or unexported fields
}

func NewCGroup added in v2.10.0 

func NewCGroup(c *dbus.Conn, typ, name string, opts ...Option) (g *CGroup, err error)

func (*CGroup) Freeze added in v2.10.0 

func (g *CGroup) Freeze() error

Freeze suspends execution of all processes in the control group.

func (*CGroup) SetProperties added in v2.10.0 

func (g *CGroup) SetProperties(opts ...CGroupOption) error

SetProperties sets transient systemd CGroup properties of the unit. See: https://systemd.io/TRANSIENT-SETTINGS/

func (*CGroup) Start added in v2.10.0 

func (g *CGroup) Start() error

Start creates the CGroup

func (*CGroup) Stop added in v2.10.0 

func (g *CGroup) Stop() error

Stop stops the CGroup and kills all contained processes

func (*CGroup) Thaw added in v2.10.0 

func (g *CGroup) Thaw() error

Thaw resumes execution of all processes in the control group.

func (*CGroup) Unit added in v2.10.0 

func (g *CGroup) Unit() string

type CGroupOption added in v2.10.0 

type CGroupOption interface {
	ApplyCGroup(s *CGroup)
}

type Callback 

type Callback func() error

type Capture 

type Capture struct {
	// Options
	SnapshotLength int
	Promiscuous    bool
	Comment        string
	Timeout        time.Duration
	LogKeys        bool
	FlushEach      uint64

	// Filter options
	FilterInterface    CaptureFilterInterfaceFunc
	FilterPackets      CaptureFilterPacketFunc
	FilterExpression   string
	FilterInstructions []bpf.Instruction

	// Output options
	Files       []*os.File
	Filenames   []string
	Channels    []chan CapturePacket
	Callbacks   []CaptureCallbackFunc
	Pipenames   []string
	ListenAddrs []string
	// contains filtered or unexported fields
}

func NewCapture 

func NewCapture(opts ...CaptureOption) *Capture

func (*Capture) ApplyBaseNode 

func (c *Capture) ApplyBaseNode(n *BaseNode)

func (*Capture) ApplyInterface 

func (c *Capture) ApplyInterface(i *Interface)

func (*Capture) ApplyNetwork 

func (c *Capture) ApplyNetwork(n *Network)

func (*Capture) ApplyTracer 

func (c *Capture) ApplyTracer(n *Tracer)

func (*Capture) Close 

func (c *Capture) Close() error

func (*Capture) Count 

func (c *Capture) Count() uint64

Count returns the total number of captured packets

func (*Capture) Flush 

func (c *Capture) Flush() error

type CaptureCallbackFunc 

type CaptureCallbackFunc func(pkt CapturePacket)

type CaptureFilterInterfaceFunc 

type CaptureFilterInterfaceFunc func(i *Interface) bool

type CaptureFilterPacketFunc 

type CaptureFilterPacketFunc func(p *CapturePacket) bool

type CaptureOption 

type CaptureOption interface {
	ApplyCapture(n *Capture)
}

type CapturePacket 

type CapturePacket struct {
	gopacket.CaptureInfo
	Data []byte

	Interface *captureInterface
}

func (CapturePacket) Decode 

func (p CapturePacket) Decode(dOpts gopacket.DecodeOptions) gopacket.Packet

type Cmd 

type Cmd struct {
	*CGroup
	*exec.Cmd

	// Options
	Tracer          *Tracer
	Debugger        *Debugger
	RedirectToLog   bool
	DisableASLR     bool
	Context         context.Context
	PreserveEnvVars []string
	Slice           string
	Scope           string
	CGroupOptions   []Option

	StdoutWriters []io.Writer
	StderrWriters []io.Writer
	// contains filtered or unexported fields
}

func (*Cmd) CombinedOutput 

func (c *Cmd) CombinedOutput() ([]byte, error)

CombinedOutput runs the command and returns its combined standard output and standard error.

func (*Cmd) Run 

func (c *Cmd) Run() error

func (*Cmd) Start 

func (c *Cmd) Start() (err error)

func (*Cmd) StderrPipe 

func (c *Cmd) StderrPipe() (io.ReadCloser, error)

func (*Cmd) StdoutPipe 

func (c *Cmd) StdoutPipe() (io.ReadCloser, error)

func (*Cmd) Wait 

func (c *Cmd) Wait() error

type CmdOption 

type CmdOption interface {
	ApplyCmd(*Cmd)
}

type Debugger 

type Debugger struct {
	// Options
	BreakOnEntry         bool
	DetachOnExit         bool
	Tracepoints          []Tracepoint
	Tracers              []*Tracer
	ListenAddr           string
	DebugInfoDirectories []string
	// contains filtered or unexported fields
}

func NewDebugger 

func NewDebugger(opts ...DebuggerOption) *Debugger

func (*Debugger) ApplyBaseNode 

func (d *Debugger) ApplyBaseNode(n *BaseNode)

func (*Debugger) ApplyCmd 

func (d *Debugger) ApplyCmd(c *Cmd)

func (*Debugger) ApplyNetwork 

func (d *Debugger) ApplyNetwork(n *Network)

func (*Debugger) Close 

func (d *Debugger) Close() error

func (*Debugger) WriteVSCodeConfigs 

func (d *Debugger) WriteVSCodeConfigs(dir string, _ bool) error

WriteVSCodeConfigs generates Visual Studio Code Launch and Task configuration files (tasks.json, launch.json) in the given workspace directory. The launch configuration is dynamically generated from the current active Delve debugger instances If an empty dir is passed, we attempt to find the workspace directory by searching for a parent directory which contains either a .vscode, go.mod or .git

type DebuggerOption 

type DebuggerOption interface {
	ApplyDebugger(*Debugger)
}

type DeviceGroup 

type DeviceGroup uint32
const (
	DeviceGroupDefault    DeviceGroup = 0
	DeviceGroupSouthBound DeviceGroup = 1000
	DeviceGroupNorthBound DeviceGroup = 1001
)

type ExecCmdOption 

type ExecCmdOption interface {
	ApplyExecCmd(*exec.Cmd)
}

type Filter 

type Filter struct {
	Family nft.TableFamily
	Table  *nft.Table

	Input   *nft.Chain
	Output  *nft.Chain
	Forward *nft.Chain
	// contains filtered or unexported fields
}

func NewFilter 

func NewFilter(c *nft.Conn) (*Filter, error)

func (*Filter) AddRule 

func (f *Filter) AddRule(h FilterHook, exprs ...expr.Any)

func (*Filter) Flush 

func (f *Filter) Flush() error

type FilterHook 

type FilterHook int
const (
	FilterInput FilterHook = iota
	FilterOutput
	FilterForward
)

type FilterRule 

type FilterRule struct {
	Exprs []expr.Any

	Hook FilterHook
}

func (FilterRule) ApplyHost 

func (fr FilterRule) ApplyHost(h *Host)

type GoBuildFlags 

type GoBuildFlags []string

type GoBuildFlagsOption 

type GoBuildFlagsOption interface {
	ApplyGoBuildFlags(*GoBuildFlags)
}

type Host 

type Host struct {
	*BaseNode

	Filter *Filter

	// Options
	FilterRules []*FilterRule
	Routes      []*nl.Route
}

func (*Host) ApplyInterface 

func (h *Host) ApplyInterface(i *Interface)

Options

func (*Host) ConfigureInterface 

func (h *Host) ConfigureInterface(i *Interface) error
func (h *Host) ConfigureLinks() error

ConfigureLinks adds links to other nodes which have been configured by functional options

func (*Host) LookupAddress 

func (h *Host) LookupAddress(n string) *net.IPAddr

func (*Host) Ping 

func (h *Host) Ping(o *Host) (*probing.Statistics, error)

func (*Host) PingWithNetwork 

func (h *Host) PingWithNetwork(o *Host, net string) (*probing.Statistics, error)

func (*Host) PingWithOptions 

func (h *Host) PingWithOptions(o *Host, net string, count int, timeout time.Duration, intv time.Duration, output bool) (*probing.Statistics, error)

func (*Host) Traceroute 

func (h *Host) Traceroute(o *Host, opts ...any) error

type HostOption 

type HostOption interface {
	ApplyHost(h *Host)
}

type Interface 

type Interface struct {
	Name string
	Node Node

	Link  nl.Link
	Flags int

	// Options
	Netem     nl.NetemQdiscAttrs
	Tbf       nl.Tbf
	EnableDAD bool
	LinkAttrs nl.LinkAttrs
	Addresses []net.IPNet
	Captures  []*Capture
}

func NewInterface 

func NewInterface(name string, opts ...Option) *Interface

func (*Interface) AddAddress 

func (i *Interface) AddAddress(a *net.IPNet) error

func (*Interface) ApplyBaseNode 

func (i *Interface) ApplyBaseNode(n *BaseNode)

func (*Interface) Close 

func (i *Interface) Close() error

func (*Interface) DeleteAddress 

func (i *Interface) DeleteAddress(a *net.IPNet) error

func (Interface) IsLoopback 

func (i Interface) IsLoopback() bool

func (*Interface) SetDown 

func (i *Interface) SetDown() error

func (*Interface) SetUp 

func (i *Interface) SetUp() error

func (Interface) String 

func (i Interface) String() string

type InterfaceOption 

type InterfaceOption interface {
	ApplyInterface(n *Interface)
}

type LinkOption 

type LinkOption interface {
	ApplyLink(a *nl.LinkAttrs)
}

type NAT 

type NAT struct {
	*Router

	Table       *nft.Table
	Input       *nft.Chain
	Forward     *nft.Chain
	PostRouting *nft.Chain

	// Options
	Persistent    bool
	Random        bool
	FullyRandom   bool
	SourcePortMin int
	SourcePortMax int
}

func (*NAT) ApplyInterface 

func (n *NAT) ApplyInterface(i *Interface)

type NATOption 

type NATOption interface {
	ApplyNAT(n *NAT)
}

type Namespace 

type Namespace struct {
	netns.NsHandle

	Name string
	// contains filtered or unexported fields
}

func HostNamespace added in v2.10.0 

func HostNamespace() (ns *Namespace, err error)

HostNamespace creates

func NewNamespace 

func NewNamespace(name string) (ns *Namespace, err error)

NewNamespace creates a new named network namespace.

func (*Namespace) Close 

func (ns *Namespace) Close() error

Close releases the network namespace.

func (*Namespace) Enter 

func (ns *Namespace) Enter() (func(), error)

Enter locks the current Goroutine to an OS thread by calling runtime.LockOSThread(). and afterwards attaches the calling Goroutines thread to the namespace. The returned function should be called to move the thread back to the original namespace and unlock the Goroutine from the OS thread.

func (*Namespace) IsHost added in v2.10.0 

func (ns *Namespace) IsHost() bool

IsHost returns true if the namespace is representing the hosts default network namespace.

func (*Namespace) MustClose added in v2.10.0 

func (ns *Namespace) MustClose()

MustClose closes the namespace like Close() but panics if an error occurs.

func (*Namespace) RunFunc 

func (ns *Namespace) RunFunc(cb Callback) error

RunFunc runs a Go function within the namespace. Note, that Goroutines started from within the passed function are not guaranteed to run inside the same namespace! This function calls runtime.{Lock|Unlock}OSThread().

type Network 

type Network struct {
	*CGroup

	Name    string
	VarPath string
	TmpPath string // For storing temporart Go build artifacts (see RunGo())

	// Options
	Persistent    bool
	Captures      []*Capture
	Debugger      *Debugger
	Tracer        *Tracer
	RedirectToLog bool
	Slice         string
	// contains filtered or unexported fields
}

func NewNetwork 

func NewNetwork(name string, opts ...Option) (n *Network, err error)

func (*Network) AddHost 

func (n *Network) AddHost(name string, opts ...Option) (h *Host, err error)
func (n *Network) AddLink(l, r *Interface, opts ...Option) error

func (*Network) AddNAT 

func (n *Network) AddNAT(name string, opts ...Option) (*NAT, error)

func (*Network) AddNode 

func (n *Network) AddNode(name string, opts ...Option) (node *BaseNode, err error)

func (*Network) AddRouter 

func (n *Network) AddRouter(name string, opts ...Option) (*Router, error)

func (*Network) AddSwitch 

func (n *Network) AddSwitch(name string, opts ...Option) (*Switch, error)

AddSwitch adds a new Linux virtual bridge in a dedicated namespace

func (*Network) Close 

func (n *Network) Close() error

func (*Network) ForEachHost 

func (n *Network) ForEachHost(cb func(h *Host))

func (*Network) Hosts 

func (n *Network) Hosts() []*Host

func (*Network) KeyLogPipe 

func (n *Network) KeyLogPipe(secretsType uint32) (*os.File, error)

func (*Network) MustClose added in v2.10.0 

func (n *Network) MustClose()

MustClose closes the network like Close() but panics if an error occurs.

func (*Network) Nodes 

func (n *Network) Nodes() []Node

func (*Network) Register 

func (n *Network) Register(m Node)

func (*Network) Routers 

func (n *Network) Routers() []*Router

func (*Network) String 

func (n *Network) String() string

func (*Network) Switches 

func (n *Network) Switches() []*Switch

func (*Network) Teardown 

func (n *Network) Teardown() error

func (*Network) WriteHostsFile 

func (n *Network) WriteHostsFile(f io.Writer) error

type NetworkOption 

type NetworkOption interface {
	ApplyNetwork(n *Network)
}

type Node 

type Node interface {
	Close() error
	Teardown() error

	// Getters
	Name() string
	String() string
	Network() *Network
	Interface(name string) *Interface
	NetNSHandle() netns.NsHandle
	NetlinkHandle() *nl.Handle

	RunFunc(cb Callback) error
	ConfigureInterface(i *Interface) error
}

type Option 

type Option any

Option is the base type for all functional options.

type Router 

type Router struct {
	*Host
}

func (*Router) ApplyInterface 

func (h *Router) ApplyInterface(i *Interface)

type RouterOption 

type RouterOption interface {
	ApplyRouter(r *Router)
}

type Switch 

type Switch struct {
	*BaseNode
}

Switch is an abstraction for a Linux virtual bridge

func (*Switch) ApplyInterface 

func (sw *Switch) ApplyInterface(i *Interface)

func (*Switch) ConfigureInterface 

func (sw *Switch) ConfigureInterface(i *Interface) error

ConfigureInterface attaches an existing interface to a bridge interface

type SwitchOption 

type SwitchOption interface {
	ApplySwitch(sw *Switch)
}

type TraceOption 

type TraceOption interface {
	ApplyTracer(t *Tracer)
}

type Tracepoint 

type Tracepoint struct {
	// Options
	api.Breakpoint
	Location string
	Message  string
}

func NewTracepoint 

func NewTracepoint(opts ...TracepointOption) Tracepoint

func (Tracepoint) ApplyDebugger 

func (tp Tracepoint) ApplyDebugger(d *Debugger)

func (*Tracepoint) IsWatchpoint 

func (tp *Tracepoint) IsWatchpoint() bool

type TracepointOption 

type TracepointOption interface {
	ApplyTracepoint(*Tracepoint)
}

type Tracer 

type Tracer struct {
	// Output options
	Files     []*os.File
	Filenames []string
	Channels  []chan trace.Event
	Callbacks []trace.EventCallback
	Captures  []*Capture
	// contains filtered or unexported fields
}

func NewTracer 

func NewTracer(opts ...TraceOption) *Tracer

func (*Tracer) ApplyBaseNode 

func (t *Tracer) ApplyBaseNode(n *BaseNode)

func (*Tracer) ApplyCmd 

func (t *Tracer) ApplyCmd(c *Cmd)

func (*Tracer) ApplyDebugger 

func (t *Tracer) ApplyDebugger(d *Debugger)

func (*Tracer) ApplyNetwork 

func (t *Tracer) ApplyNetwork(n *Network)

func (*Tracer) Close 

func (t *Tracer) Close() error

func (*Tracer) Flush 

func (t *Tracer) Flush() error

func (*Tracer) Pipe 

func (t *Tracer) Pipe() (*os.File, error)

func (*Tracer) Start 

func (t *Tracer) Start() error

type VethOption 

type VethOption interface {
	ApplyVeth(ve *nl.Veth)
}

Source Files

View all Source files

Directories

Path Synopsis
capture
Package capture contains the options to configure to packet capturing
 Package capture contains the options to configure to packet capturing
cmd
debug
filters
Package filters contains the options for configuring NFTables filtering
 Package filters contains the options for configuring NFTables filtering
systemd
tc
Package tc contains the options for configuring per-interface Traffic Control (TC) queuing disciplines
 Package tc contains the options for configuring per-interface Traffic Control (TC) queuing disciplines
trace

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.