netmonitor.go

// Copyright (c) 2022 Zededa, Inc.
// SPDX-License-Identifier: Apache-2.0

package netmonitor

import (
	"context"
	"net"

	"github.com/lf-edge/eve/pkg/pillar/types"
	"github.com/lf-edge/eve/pkg/pillar/utils/netutils"
)

// NetworkMonitor should allow to:
// - list (and possibly cache) network interfaces
// - obtain (and possibly cache) interface index
// - obtain (and possibly cache) interface attributes, addresses, DNS info, etc.
// - allow to watch for interface/address/route changes
// There should be one implementation for every supported network stack.
// NetworkMonitor should be thread-safe.
type NetworkMonitor interface {
	// ListInterfaces returns all available network interfaces.
	ListInterfaces() (ifNames []string, err error)
	// GetInterfaceIndex : get interface index. Both name and index are unique
	// interface identifiers, but while name is usually used in user-facing
	// contexts, index is preferred in APIs (may vary between different network stacks).
	// At least within NetworkMonitor, index is the preferred identifier and can be used
	// with the methods below to obtain interface attributes, assigned addresses, etc.
	// Do not keep the index for too long however, the mapping between the name and
	// the index may change as interfaces are added/deleted.
	GetInterfaceIndex(ifName string) (ifIndex int, exists bool, err error)
	// GetInterfaceAttrs : get interface attributes (not including assigned addresses).
	GetInterfaceAttrs(ifIndex int) (IfAttrs, error)
	// GetInterfaceAddrs : get MAC address and a list of IP addresses assigned
	// to the given interface.
	GetInterfaceAddrs(ifIndex int) ([]*net.IPNet, net.HardwareAddr, error)
	// GetInterfaceDNSInfo : get DNS information associated with the given interface.
	// Function returns one entry for every resolv.conf file generated for the interface.
	GetInterfaceDNSInfo(ifIndex int) ([]DNSInfo, error)
	// GetInterfaceDHCPInfo : get DHCP + DHCPv6 information associated with the given interface.
	// This information should be retrieved from the DHCP(v6) client.
	GetInterfaceDHCPInfo(ifIndex int) (DHCPInfo, error)
	// GetInterfaceDefaultGWs : return a list of IP addresses of default gateways
	// used by the given interface. Includes both statically configured GWs as well as
	// those assigned by DHCP.
	// Returns both IPv4 and IPv6 gateways.
	GetInterfaceDefaultGWs(ifIndex int) ([]net.IP, error)
	// ListRoutes returns routes currently present in the routing tables.
	// The set of routes to list can be filtered.
	// Returns both IPv4 and IPv6 routes.
	ListRoutes(filters RouteFilters) ([]Route, error)
	// GetPNACStatus returns the current PNAC (Port Network Access Control) status
	// for the specified interface.
	// The exact 802.1x supplicant state and any associated error condition are obtained
	// by querying `wpa_cli status`. The per-interface PNAC state file (see PNACStateDir)
	// is used only to determine the timestamp of the last successful 802.1X authentication.
	GetPNACStatus(ifIndex int) (types.PNACStatus, error)
	// GetPNACMetrics returns IEEE 802.1X PNAC (Port-Based Network Access Control)
	// metrics for the specified interface.
	GetPNACMetrics(ifIndex int) (types.PNACMetrics, error)
	// GetBondStatus : retrieve runtime status of a bond interface.
	// Returns an error if the interface is not a bond or does not exist.
	GetBondStatus(ifIndex int) (BondStatus, error)
	// GetBondMetrics : retrieve metrics for a bond interface and its members.
	// Returns an error if the interface is not a bond or does not exist.
	// Note: BondMetrics.LogicalLabel and BondMemberMetrics.LogicalLabel are
	// returned unset (NetworkMonitor does not work with logical labels).
	GetBondMetrics(ifIndex int) (types.BondMetrics, error)
	// ClearCache : clear cached mappings between interface names, interface indexes,
	// attributes, assigned addresses, DNS info, DHCP info and default GWs.
	// It is reasonable to do this once in a while because the monitor can miss some
	// notification from the network stack and therefore the cache can get out-of-date
	// over time.
	ClearCache()
	// WatchEvents : subscribe to watch for changes happening inside the network stack
	// related to interfaces, routes, DNS, etc.
	// The returned channel should be reasonably buffered.
	WatchEvents(ctx context.Context, subName string) <-chan Event
}

// Event received from the network stack.
type Event interface {
	isNetworkEvent()
}

// Route : IP route.
type Route struct {
	IfIndex int
	Dst     *net.IPNet
	Gw      net.IP
	Table   int
	// Network-stack specific data.
	Data interface{}
}

// IsDefaultRoute returns true if this is a default route, i.e. matches all destinations.
func (r Route) IsDefaultRoute() bool {
	if r.Dst == nil {
		return true
	}
	ones, _ := r.Dst.Mask.Size()
	return r.Dst.IP.IsUnspecified() && ones == 0
}

// RouteChange : a route was added or removed.
type RouteChange struct {
	Route
	Added   bool
	Deleted bool
}

// RouteFilters : used by ListRoutes() to limit the set of routes to list.
type RouteFilters struct {
	// Enable to retrieve routes only from the given table.
	FilterByTable bool
	Table         int

	// Enable to retrieve only those routes which are associated
	// with the given interface.
	FilterByIf bool
	IfIndex    int
}

func (e RouteChange) isNetworkEvent() {}

// AddrChange : IP address was (un)assigned from/to interface.
type AddrChange struct {
	IfIndex   int
	IfAddress *net.IPNet
	Deleted   bool
}

func (e AddrChange) isNetworkEvent() {}

// IfChange : interface (dis)appeared or attributes changed.
type IfChange struct {
	Attrs IfAttrs
	// True if this is a newly added interface.
	Added bool
	// True if interface was removed.
	Deleted bool
}

func (e IfChange) isNetworkEvent() {}

// Equal allows to compare two IfChange events for equality.
func (e IfChange) Equal(e2 IfChange) bool {
	return e.Added == e2.Added &&
		e.Deleted == e2.Deleted &&
		e.Attrs.Equal(e2.Attrs)
}

// DNSInfoChange : DNS information for interface has changed.
type DNSInfoChange struct {
	IfIndex int
	Info    []DNSInfo
}

func (e DNSInfoChange) isNetworkEvent() {}

// IfAttrs : interface attributes.
type IfAttrs struct {
	// Index of the interface
	IfIndex int
	// Name of the interface.
	IfName string
	// IfType should be one of the link types as defined in ip-link(8).
	IfType string
	// True if interface is a loopback interface.
	IsLoopback bool
	// True if interface supports broadcast access capability.
	WithBroadcast bool
	// True if interface is administratively enabled.
	AdminUp bool
	// True if interface is ready to transmit data at the L1 layer.
	LowerUp bool
	// True if interface is a slave of another interface (e.g. a sub-interface).
	Enslaved bool
	// If interface is enslaved, this should contain index of the master interface.
	MasterIfIndex int
	// Maximum Transmission Unit configured on the interface.
	MTU uint16
	// Index of the VLAN parent interface (only set for VLAN sub-interfaces).
	VlanParentIfIndex int
	// VLAN ID assigned to this subinterface (only set for VLAN sub-interfaces).
	VlanID uint16
}

// Equal allows to compare two sets of interface attributes for equality.
func (a IfAttrs) Equal(a2 IfAttrs) bool {
	return a.IfIndex == a2.IfIndex &&
		a.IfName == a2.IfName &&
		a.IfType == a2.IfType &&
		a.IsLoopback == a2.IsLoopback &&
		a.WithBroadcast == a2.WithBroadcast &&
		a.AdminUp == a2.AdminUp &&
		a.LowerUp == a2.LowerUp &&
		a.Enslaved == a2.Enslaved &&
		a.MasterIfIndex == a2.MasterIfIndex &&
		a.MTU == a2.MTU &&
		a.VlanParentIfIndex == a2.VlanParentIfIndex &&
		a.VlanID == a2.VlanID
}

// DNSInfo : DNS information associated with an interface.
type DNSInfo struct {
	ResolvConfPath string
	Domains        []string
	DNSServers     []net.IP
	ForIPv6        bool
}

// DHCPInfo : DHCP information associated with an interface.
type DHCPInfo struct {
	IPv4Subnet     *net.IPNet
	IPv6Subnets    []*net.IPNet
	IPv4NtpServers []netutils.HostnameOrIP
	IPv6NtpServers []netutils.HostnameOrIP
}

// PNACEvent represents a change in port authentication state.
// Only reports transitions between non-authenticated and fully authenticated.
// Does not capture intermediate EAP states; intended to trigger network
// configuration changes that depend on port auth (e.g., acquiring (new) DHCP lease).
type PNACEvent struct {
	IfName          string
	IsAuthenticated bool
}

func (e PNACEvent) isNetworkEvent() {}

// BondStatus : runtime status of a bond interface as reported by the kernel.
type BondStatus struct {
	// Mode is the bonding mode as reported by the kernel.
	Mode types.BondMode
	// ActiveMemberIfIndex is the ifindex of the currently active member.
	// Applicable for active-backup, balance-tlb and balance-alb modes.
	// Zero if there is no active member.
	ActiveMemberIfIndex int
	// Monitoring parameters.
	Miimon                uint32
	UpDelay               uint32
	DownDelay             uint32
	ArpInterval           uint32
	ArpIPTargets          []net.IP
	PeerNotificationDelay uint32
	ArpMissedMax          uint32
	// LACPInfo contains 802.3ad aggregator info.
	// Only set when bond mode is 802.3ad.
	LACPInfo *BondLACPInfo
	// Members contains per-member status.
	Members []BondMemberStatus
}

// BondMemberStatus : per-member status within a bond.
type BondMemberStatus struct {
	// IfIndex of the member interface.
	IfIndex int
	// MIIUp indicates whether the member's MII link is up.
	MIIUp bool
	// AggregatorID the member belongs to (802.3ad only).
	AggregatorID uint16
	// ActorChurnState (802.3ad only).
	ActorChurnState types.BondLACPChurnState
	// PartnerChurnState (802.3ad only).
	PartnerChurnState types.BondLACPChurnState
}

// BondLACPInfo : 802.3ad aggregator info for a bond.
type BondLACPInfo struct {
	AggregatorID uint16
	ActorKey     uint16
	PartnerKey   uint16
	PartnerMAC   net.HardwareAddr
}

// BondActiveMemberChange : the active member of a bond has changed.
type BondActiveMemberChange struct {
	// BondIfIndex is the ifindex of the bond master interface.
	BondIfIndex int
	// ActiveMemberIfIndex is the ifindex of the new active member.
	// Zero if there is no active member.
	ActiveMemberIfIndex int
}

func (e BondActiveMemberChange) isNetworkEvent() {}