UDP Mux

UDP multiplexing for sharing a single UDP port across multiple ICE connections

Overview

UDP Mux allows multiple ICE connections to share a single UDP port by demultiplexing packets based on the username fragment (ufrag) from STUN messages. This enables efficient port usage and is particularly useful when you need to handle multiple concurrent WebRTC connections.

UDPMux Interface

The UDPMux interface defines the contract for UDP multiplexing implementations.

type UDPMux interface {
    io.Closer
    GetConn(ufrag string, addr net.Addr) (net.PacketConn, error)
    RemoveConnByUfrag(ufrag string)
    GetListenAddresses() []net.Addr
}

Methods

GetConn · func(ufrag string, addr net.Addr) (net.PacketConn, error)

Returns a PacketConn for the given username fragment and address. Creates a new connection if one doesn’t exist for the specified ufrag.

Parameters:

• ufrag - The username fragment from the ICE credentials
• addr - The network address to bind to

Returns: A net.PacketConn or an error if the connection cannot be created

RemoveConnByUfrag · func(ufrag string)

Stops and removes the muxed packet connection associated with the given username fragment.

Parameters:

• ufrag - The username fragment identifying the connection to remove

GetListenAddresses · func() []net.Addr

Returns the list of addresses that this mux is listening on.

Returns: A slice of net.Addr representing all listening addresses

Close · func() error

Closes the mux and all associated connections. No further connections can be created after closing.

Returns: An error if the close operation fails

UDPMuxDefault

UDPMuxDefault is the default implementation of the UDPMux interface.

Creating a UDPMuxDefault

func NewUDPMuxDefault(params UDPMuxParams) *UDPMuxDefault

Creates a new UDP mux with the specified parameters.

UDPMuxParams

Logger · logging.LeveledLogger

Logger instance for the mux. If nil, a default logger will be created.

UDPConn · net.PacketConn · required

The UDP connection to multiplex. This should be bound to a specific address.

Net · transport.Net

Network transport interface. Required when the UDPConn binds to an unspecified address.

Example: Basic UDP Mux

Basic Usage

package main

import (
    "net"
    "github.com/pion/ice/v4"
)

func main() {
    // Create a UDP connection
    udpAddr := &net.UDPAddr{
        IP:   net.ParseIP("0.0.0.0"),
        Port: 8443,
    }
    
    conn, err := net.ListenUDP("udp", udpAddr)
    if err != nil {
        panic(err)
    }
    
    // Create UDP mux
    mux := ice.NewUDPMuxDefault(ice.UDPMuxParams{
        UDPConn: conn,
    })
    defer mux.Close()
    
    // Get a connection for a specific ufrag
    packetConn, err := mux.GetConn("myufrag", conn.LocalAddr())
    if err != nil {
        panic(err)
    }
    
    // Use packetConn for ICE agent...
}

When using an unspecified address (0.0.0.0 or ::), the mux will automatically detect all local interfaces. However, it’s recommended to use NewMultiUDPMuxFromPort instead for better control.

MultiUDPMuxDefault

MultiUDPMuxDefault allows multiple UDPMux instances to be used together, enabling listening on multiple ports or addresses simultaneously.

Creating a MultiUDPMuxDefault

func NewMultiUDPMuxDefault(muxes ...UDPMux) *MultiUDPMuxDefault

Creates a multi-mux from existing UDPMux instances.

func NewMultiUDPMuxFromPort(port int, opts ...UDPMuxFromPortOption) (*MultiUDPMuxDefault, error)

Creates a multi-mux that listens on all network interfaces on the specified port.

Configuration Options

UDPMuxFromPortWithInterfaceFilter · func(string) bool

Filter to determine which network interfaces should be used.

ice.UDPMuxFromPortWithInterfaceFilter(func(iface string) bool {
    return iface != "docker0" // Exclude docker interface
})

UDPMuxFromPortWithIPFilter · func(net.IP) bool

Filter to determine which IP addresses should be used.

ice.UDPMuxFromPortWithIPFilter(func(ip net.IP) bool {
    return !ip.IsLoopback() // Exclude loopback addresses
})

UDPMuxFromPortWithNetworks · ...NetworkType

Specify which network types to use (IPv4, IPv6, or both).

ice.UDPMuxFromPortWithNetworks(ice.NetworkTypeUDP4)

UDPMuxFromPortWithReadBufferSize · int

Set the UDP connection read buffer size in bytes.

ice.UDPMuxFromPortWithReadBufferSize(8 * 1024 * 1024) // 8MB

UDPMuxFromPortWithWriteBufferSize · int

Set the UDP connection write buffer size in bytes.

ice.UDPMuxFromPortWithWriteBufferSize(8 * 1024 * 1024) // 8MB

UDPMuxFromPortWithLogger · logging.LeveledLogger

Set a custom logger for the mux.

UDPMuxFromPortWithLoopback · bool

Include loopback interfaces in the mux.

ice.UDPMuxFromPortWithLoopback()

UDPMuxFromPortWithNet · transport.Net

Set a custom network transport implementation.

Example: Multi-Interface UDP Mux

All Interfaces

package main

import (
    "github.com/pion/ice/v4"
)

func main() {
    // Listen on all interfaces on port 8443
    mux, err := ice.NewMultiUDPMuxFromPort(8443)
    if err != nil {
        panic(err)
    }
    defer mux.Close()
    
    // Get all listening addresses
    addrs := mux.GetListenAddresses()
    for _, addr := range addrs {
        println("Listening on:", addr.String())
    }
}

Port Sharing Concepts

How It Works

1. Packet Demultiplexing: When a packet arrives on the shared UDP port, the mux examines it to determine which connection it belongs to.

2. STUN Username: For STUN packets, the mux extracts the username attribute and uses the first part (before the colon) as the ufrag to route the packet.

3. Address Mapping: After the first STUN packet, the mux remembers the remote address and can route subsequent packets (including media) based on the source address.

4. Connection Lifecycle: Each muxed connection is independent and can be closed without affecting others sharing the same port.

Benefits

• Reduced Port Usage: Handle multiple WebRTC connections on a single UDP port
• NAT Traversal: Simplified firewall configuration with fewer ports to open
• Scalability: Better resource utilization for applications with many concurrent connections
• IPv4 and IPv6: Separate connection tracking for IPv4 and IPv6 traffic

Limitations

• The first packet from each remote peer must be a STUN message with a USERNAME attribute
• Each ufrag should be unique across all connections using the mux
• Performance may be impacted with very high numbers of concurrent connections (thousands)

Best Practices

1. Use Specific Addresses: When possible, bind to specific IP addresses rather than 0.0.0.0 for better security and predictability.

2. Buffer Sizes: For high-throughput applications, configure appropriate read and write buffer sizes:

   mux, _ := ice.NewMultiUDPMuxFromPort(
       8443,
       ice.UDPMuxFromPortWithReadBufferSize(8 * 1024 * 1024),
       ice.UDPMuxFromPortWithWriteBufferSize(8 * 1024 * 1024),
   )
   

3. Cleanup: Always defer Close() to ensure proper cleanup of resources:

   mux := ice.NewUDPMuxDefault(params)
   defer mux.Close()
   

4. Interface Filtering: In containerized environments, filter out virtual interfaces:

   ice.UDPMuxFromPortWithInterfaceFilter(func(iface string) bool {
       return !strings.HasPrefix(iface, "veth")
   })
   

Related

• TCP Mux - TCP connection multiplexing
• Universal Mux - Combined UDP mux with STUN/TURN support
• Agent Options - Using muxes with ICE agents