multicast

README

multicast

A small Go helper library for UDP multicast with multi-interface support.

:::note This library is not thoroughly tested. Please test it carefully in your environment and verify it behaves as expected before using it in production. Bug reports and pull requests are welcome. :::

This package provides a thin wrapper to simplify IPv4/IPv6 multicast send/receive. It supports joining multicast groups on multiple network interfaces, setting TTL/HopLimit, controlling multicast loopback, and sending a packet from all joined interfaces.

Features

• Supports udp4 and udp6
• Automatically discovers multicast-capable interfaces
• Dynamically add interfaces to a multicast group
• Set multicast TTL (IPv4) / hop limit (IPv6)
• Control multicast loopback
• Send a packet on all joined interfaces (WriteToMulticast)

Installation

go get github.com/oosawy/multicast

Usage (quick example)

An example that sends an mDNS query and listens for responses is available in examples/mdns.

Build and run the example (fish shell):

cd examples/mdns
go build -o mdns-example
./mdns-example my-host.local

Core usage example (excerpt):

addr := &net.UDPAddr{IP: net.IPv4zero, Port: 0}
conn, err := multicast.ListenMulticastUDPIfaces("udp4", nil, addr)
if err != nil {
    log.Fatal(err)
}
defer conn.Close()

gaddr := &net.UDPAddr{IP: net.IPv4(224, 0, 0, 251), Port: 5353}
if err := conn.JoinMulticastGroup(nil, gaddr); err != nil {
    log.Printf("warning: failed to join some interfaces: %v", err)
}

_ = conn.SetMulticastTTL(255)
_ = conn.SetMulticastLoopback(true)
_ = conn.ReuseAddrPort()

// Send
buf := []byte("...")
_ = conn.WriteToMulticast(buf, gaddr)

// Receive
b := make([]byte, 65536)
n, _, err := conn.ReadFrom(b)
if err != nil {
    log.Printf("read error: %v", err)
}

API summary

• ListenMulticastUDPIfaces(network string, ifaces []net.Interface, addr *net.UDPAddr) (*UDPConn, error)

  • Creates a socket bound to addr and joins the multicast group on the provided interfaces. If ifaces is nil, the package will enumerate multicast-capable interfaces.
  • network must be either "udp4" or "udp6".

• (*UDPConn) JoinMulticastGroup(ifaces []net.Interface, gaddr *net.UDPAddr) error

  • Join additional multicast group on the interfaces. If ifaces is nil, the connection's current interfaces are used.

• (*UDPConn) SetMulticastTTL(ttl int) error

  • Set IPv4 TTL or IPv6 hop limit for outgoing multicast packets.

• (*UDPConn) SetMulticastHopLimit(hopLimit int) error

  • Set IPv6 hop limit for outgoing multicast packets. This is an alias to SetMulticastTTL for API symmetry to IPv6.

• (*UDPConn) SetMulticastLoopback(on bool) error

  • Enable or disable loopback of multicast packets to local sockets.

• (*UDPConn) ReuseAddrPort() error

  • Try to set SO_REUSEADDR/PORT on the underlying socket (platform dependent).

• (*UDPConn) WriteToMulticast(buf []byte, addr *net.UDPAddr) error

  • Send buf to addr using all joined interfaces. Errors per-interface are aggregated and returned.

• (*UDPConn) Interfaces() []net.Interface / (*UDPConn) Network() string

Notes

• Multicast and low-level socket behavior varies between OS. On some systems (notably macOS and some Linux distributions) additional permissions or sysctl settings may be required.
• Behavior of ReuseAddrPort is OS-dependent.
• When attempting to join multiple interfaces at ListenMulticastUDPIfaces or JoinMulticastGroup, if some (but not all) interfaces fail to join, the library logs a warning via the slog package describing the partial failure. The connection will still be returned if at least one interface succeeded.

Acknowledgements

This library's multicast sending logic was partly inspired by grandcat/zeroconf; thanks to its maintainers and contributors for their work.

License

This repository follows the terms in the LICENSE file.

Contributing

Bug reports and pull requests are welcome. Please open an issue first for larger changes.

Documentation

Index

• type UDPConn
  • func ListenMulticastUDPIfaces(network string, ifaces []net.Interface, addr *net.UDPAddr) (*UDPConn, error)
  • func (c *UDPConn) Close() error
  • func (c *UDPConn) Interfaces() []net.Interface
  • func (c *UDPConn) JoinMulticastGroup(ifaces []net.Interface, gaddr *net.UDPAddr) error
  • func (c *UDPConn) Network() string
  • func (c *UDPConn) ReuseAddrPort() error
  • func (c *UDPConn) SetMulticastHopLimit(hoplim int) error
  • func (c *UDPConn) SetMulticastLoopback(on bool) error
  • func (c *UDPConn) SetMulticastTTL(ttl int) error
  • func (c *UDPConn) WriteToMulticast(buf []byte, addr *net.UDPAddr) error

Types

type UDPConn

type UDPConn struct {
	net.UDPConn
	// contains filtered or unexported fields
}

UDPConn is a UDP connection configured for multicast communication. It embeds net.UDPConn and provides convenience methods for multicast reads/writes.

func ListenMulticastUDPIfaces

func ListenMulticastUDPIfaces(network string, ifaces []net.Interface, addr *net.UDPAddr) (*UDPConn, error)

ListenMulticastUDPIfaces listens for multicast on the provided address and joins multicast groups on the given network interfaces.

It accepts "udp4" or "udp6" for the network argument. If ifaces is nil, it will use all multicast-capable interfaces. The addr argument specifies the socket to bind to. It returns a *UDPConn ready for multicast reads/writes.

func (*UDPConn) Close

func (c *UDPConn) Close() error

Close closes the underlying connection.

func (*UDPConn) Interfaces

func (c *UDPConn) Interfaces() []net.Interface

Interfaces returns a copy of the interfaces that have joined the multicast group.

func (*UDPConn) JoinMulticastGroup

func (c *UDPConn) JoinMulticastGroup(ifaces []net.Interface, gaddr *net.UDPAddr) error

JoinMulticastGroup joins the multicast group gaddr on iface. This allows adding additional interfaces to the multicast group dynamically.

Example:

addr := &net.UDPAddr{IP: net.IPv4zero, Port: 0}
conn, err := multicast.ListenMulticastUDPIfaces("udp4", nil, addr)
gaddr := &net.UDPAddr{IP: net.IPv4(224, 0, 0, 251), Port: 5353}
err := conn.JoinMulticastGroup(iface, gaddr)

func (*UDPConn) Network

func (c *UDPConn) Network() string

Network returns the network type ("udp4" or "udp6") of the connection.

func (*UDPConn) ReuseAddrPort

func (c *UDPConn) ReuseAddrPort() error

func (*UDPConn) SetMulticastHopLimit

func (c *UDPConn) SetMulticastHopLimit(hoplim int) error

SetMulticastHopLimit is an alias to SetMulticastTTL for API symmetry for IPv6.

func (*UDPConn) SetMulticastLoopback

func (c *UDPConn) SetMulticastLoopback(on bool) error

SetMulticastLoopback sets whether multicast packets sent from this socket should be looped back to the local sockets.

func (*UDPConn) SetMulticastTTL

func (c *UDPConn) SetMulticastTTL(ttl int) error

SetMulticastTTL sets the multicast TTL (IPv4) or hop limit (IPv6) used for outbound multicast packets.

func (*UDPConn) WriteToMulticast

func (c *UDPConn) WriteToMulticast(buf []byte, addr *net.UDPAddr) error

WriteToMulticast sends buf to the multicast address addr using all joined interfaces. Any errors encountered during transmission on each interface are aggregated and returned as a joined error.