ifplugo

README

ifplugo

ifplugo delivers network interface link information and link changes. It does this (on Linux) by querying kernel ioctls to gather the necessary status information, then emits a status summary on a given channel. This summary (LinkStatusSample) is emitted on the first invocation and each time the state changes for at least one monitored interface.

type LinkStatusSample struct {
    Ifaces  map[string]InterfaceStatus
}

where InterfaceStatus can be:

const (
    // InterfaceUnknown represents an interface with no assigned state.
    InterfaceUnknown InterfaceStatus = iota
    // InterfaceUp represents an interface with a cable connected.
    InterfaceUp
    // InterfaceDown represents an interface with no cable connected.
    InterfaceDown
    // InterfaceErr represents an interface with errors querying its status.
    InterfaceErr
)

These summaries can then easily be consumed (example):

outchan := make(chan ifplugo.LinkStatusSample)
mon := ifplugo.MakeLinkStatusMonitor(2 * time.Second, []string{"eth0"}, outchan)
go func() {
    for v := range outchan {
        for k, v := range v.Ifaces {
            fmt.Printf("%s: %s\n", k, v)
        }
    }
}()
mon.Run()

It is also possible to determine the status of an interface from whether any data is flowing or not. This can be useful if, for example, the interesting interface is only connected to one way of the physical connection (RX or TX) or for other reasons can not complete autonegotiation. Use CheckIncomingDelta() in this case, it allows to also mark an interface as 'up' and seeing traffic if a certain threshold of received bytes is exceeded during one polling period. Example:

mon.CheckIncomingDelta(true, 1000)

This would, for example, also mark an interface as up if more than 1000 bytes are received during the polling period, and mark the interface as down if there are ever less than 1000 bytes received in a polling period.

Platform restrictions

Obviously, this works on Linux only.

Example

See the source code of the simple command line tools in cmd/* for more simple examples of how to use ifplugo.

$ ifplugo-watch eth0,eth1,eth2,eth3
eth0: link
eth1: link
eth2: link
eth3: no link
^C
$

Authors

Sascha Steinbiss <sascha (at) steinbiss (dot) name>.

License

MIT

Documentation

Index

• type InterfaceStatus
  • func GetLinkStatus(iface string) (InterfaceStatus, error)
  • func (s InterfaceStatus) String() string
• type LinkStatusMonitor
  • func MakeLinkStatusMonitor(pollPeriod time.Duration, ifaces []string, outChan chan LinkStatusSample) *LinkStatusMonitor
  • func (a *LinkStatusMonitor) CheckIncomingDelta(val bool, threshold uint64)
  • func (a *LinkStatusMonitor) Run()
  • func (a *LinkStatusMonitor) Stop()
• type LinkStatusSample

Types

type InterfaceStatus

type InterfaceStatus int

InterfaceStatus represents the link status of an interface.

const (
	// InterfaceUnknown represents an interface with no assigned state.
	InterfaceUnknown InterfaceStatus = iota
	// InterfaceUp represents an interface with a cable connected.
	InterfaceUp
	// InterfaceDown represents an interface with no cable connected.
	InterfaceDown
	// InterfaceErr represents an interface with errors querying its status.
	InterfaceErr
)

func GetLinkStatus

func GetLinkStatus(iface string) (InterfaceStatus, error)

GetLinkStatus returns, for a given interface, the corresponding status code at the time of the call. If any error was encountered (e.g. invalid interface, etc.) we simply return ifplugo.InterfaceErr.

func (InterfaceStatus) String

func (s InterfaceStatus) String() string

type LinkStatusMonitor

type LinkStatusMonitor struct {
	PollPeriod time.Duration
	LastStatus map[string]InterfaceStatus
	LastStats  map[string]net.IOCountersStat

	OutChan    chan LinkStatusSample
	CloseChan  chan bool
	ClosedChan chan bool
	Ifaces     []string
	// contains filtered or unexported fields
}

LinkStatusMonitor represents a concurrent software component that periodically checks a list of given interfaces and returns their link status via a specified channel.

func MakeLinkStatusMonitor

func MakeLinkStatusMonitor(pollPeriod time.Duration, ifaces []string,
	outChan chan LinkStatusSample) *LinkStatusMonitor

MakeLinkStatusMonitor creates a new LinkStatusMonitor, polling each interval given in pollPeriod for the status information of the interfaces given in ifaces and outputting results as a map of interface->status pairs in the channel outChan.

func (*LinkStatusMonitor) CheckIncomingDelta

func (a *LinkStatusMonitor) CheckIncomingDelta(val bool, threshold uint64)

CheckIncomingDelta allows to enable the optional behaviour to also consider an interface as 'up' if traffic is received on it. This is, for example, necessary in passive monitoring setups where there is no physical link detected (e.g. using taps that only provide RX lines).

func (*LinkStatusMonitor) Run

func (a *LinkStatusMonitor) Run()

Run starts watching interfaces in the background.

func (*LinkStatusMonitor) Stop

func (a *LinkStatusMonitor) Stop()

Stop causes the monitor to cease monitoring interfaces.

type LinkStatusSample

type LinkStatusSample struct {
	Ifaces map[string]InterfaceStatus
}

LinkStatusSample is a single description of the link status at a given time. Changed is set to true if the state is different than the previously emitted one.